Audio

🔊 Audio system for real-time audio capture and playback More...

Files
file	analysis.c
	Audio Analysis Implementation.
file	analysis.h
	Audio Analysis and Debugging Interface.
file	audio.c
	🔊 Audio capture and playback using PortAudio with buffer management
file	audio.h
	🔊 Audio Capture and Playback Interface for ascii-chat
file	client_audio_pipeline.h
	Unified client-side audio processing pipeline.
file	mixer.c
	🎚️ Real-time audio mixer with ducking, gain control, and multi-stream blending
file	mixer.h
	Multi-Source Audio Mixing and Processing System.
file	opus_codec.c
	Opus audio codec implementation.
file	opus_codec.h
	Opus audio codec wrapper for real-time encoding/decoding.

Data Structures
struct	audio_context_t
	Audio context for full-duplex capture and playback. More...
struct	audio_device_info_t
	Audio device information structure. More...
struct	audio_batch_info_t
	Parsed audio batch packet header information. More...
struct	compressor_t
	Dynamic range compressor settings and state. More...
struct	noise_gate_t
	Noise gate settings and state. More...
struct	highpass_filter_t
	High-pass filter settings and state. More...
struct	lowpass_filter_t
	Low-pass filter state. More...
struct	ducking_t
	Ducking system settings and state. More...
struct	mixer_t
	Main mixer structure for multi-source audio processing. More...
struct	opus_codec_t
	Opus codec context for encoding or decoding. More...

Macros
#define	AUDIO_SAMPLE_RATE   48000
	Audio sample rate (48kHz professional quality, Opus-compatible)
#define	AUDIO_FRAMES_PER_BUFFER   480
	Audio frames per buffer (480 = 10ms at 48kHz, matches WebRTC AEC3 frame size)
#define	AUDIO_CHANNELS   1
	Number of audio channels (1 = mono)
#define	AUDIO_BUFFER_SIZE   (AUDIO_FRAMES_PER_BUFFER * AUDIO_CHANNELS)
	Total audio buffer size (frames × channels)

Typedefs
typedef struct OpusEncoder	OpusEncoder
typedef struct OpusDecoder	OpusDecoder

Enumerations
enum	opus_application_t { OPUS_APPLICATION_VOIP = 2048 , OPUS_APPLICATION_AUDIO = 2049 , OPUS_APPLICATION_RESTRICTED_LOWDELAY = 2051 }
	Application mode for opus encoder. More...

Functions
asciichat_error_t	audio_init (audio_context_t *ctx)
	Initialize audio context and PortAudio.
void	audio_destroy (audio_context_t *ctx)
	Destroy audio context and clean up resources.
void	audio_set_pipeline (audio_context_t *ctx, void *pipeline)
	Set audio pipeline for echo cancellation.
asciichat_error_t	audio_start_duplex (audio_context_t *ctx)
	Start full-duplex audio (simultaneous capture and playback)
asciichat_error_t	audio_stop_duplex (audio_context_t *ctx)
	Stop full-duplex audio.
asciichat_error_t	audio_read_samples (audio_context_t *ctx, float *buffer, int num_samples)
	Read captured audio samples from capture buffer.
asciichat_error_t	audio_write_samples (audio_context_t *ctx, const float *buffer, int num_samples)
	Write audio samples to playback buffer.
asciichat_error_t	audio_set_realtime_priority (void)
	Request real-time priority for current thread.
asciichat_error_t	audio_list_input_devices (audio_device_info_t **out_devices, unsigned int *out_count)
	List available audio input devices (microphones)
asciichat_error_t	audio_list_output_devices (audio_device_info_t **out_devices, unsigned int *out_count)
	List available audio output devices (speakers)
void	audio_free_device_list (audio_device_info_t *devices)
	Free device list allocated by audio_list_input_devices/audio_list_output_devices.
asciichat_error_t	audio_dequantize_samples (const uint8_t *samples_ptr, uint32_t total_samples, float *out_samples)
	Dequantize network audio samples from int32 to float.
audio_ring_buffer_t *	audio_ring_buffer_create (void)
	Create a new audio ring buffer (for playback with jitter buffering)
audio_ring_buffer_t *	audio_ring_buffer_create_for_capture (void)
	Create a new audio ring buffer for capture (without jitter buffering)
void	audio_ring_buffer_destroy (audio_ring_buffer_t *rb)
	Destroy an audio ring buffer.
void	audio_ring_buffer_clear (audio_ring_buffer_t *rb)
	Clear all audio samples from ring buffer.
asciichat_error_t	audio_ring_buffer_write (audio_ring_buffer_t *rb, const float *data, int samples)
	Write audio samples to ring buffer.
size_t	audio_ring_buffer_read (audio_ring_buffer_t *rb, float *data, size_t samples)
	Read audio samples from ring buffer.
size_t	audio_ring_buffer_peek (audio_ring_buffer_t *rb, float *data, size_t samples)
	Peek at available samples without consuming them (for AEC3 render signal)
size_t	audio_ring_buffer_available_read (audio_ring_buffer_t *rb)
	Get number of samples available for reading.
size_t	audio_ring_buffer_available_write (audio_ring_buffer_t *rb)
	Get number of sample slots available for writing.
void	resample_linear (const float *src, size_t src_samples, float *dst, size_t dst_samples, double src_rate, double dst_rate)
	Resample audio using linear interpolation.
asciichat_error_t	audio_parse_batch_header (const void *data, size_t len, audio_batch_info_t *out_batch)
	Parse an audio batch packet header from raw packet data.
asciichat_error_t	audio_validate_batch_params (const audio_batch_info_t *batch)
	Validate audio batch parameters for sanity.
bool	audio_is_supported_sample_rate (uint32_t sample_rate)
	Check if a sample rate is a standard/supported rate.
opus_codec_t *	opus_codec_create_encoder (opus_application_t application, int sample_rate, int bitrate)
	Create an Opus encoder.
opus_codec_t *	opus_codec_create_decoder (int sample_rate)
	Create an Opus decoder.
size_t	opus_codec_encode (opus_codec_t *codec, const float *samples, int num_samples, uint8_t *out_data, size_t out_size)
	Encode audio frame with Opus.
int	opus_codec_decode (opus_codec_t *codec, const uint8_t *data, size_t data_len, float *out_samples, int out_num_samples)
	Decode Opus audio frame.
asciichat_error_t	opus_codec_set_bitrate (opus_codec_t *codec, int bitrate)
	Set encoder bitrate.
int	opus_codec_get_bitrate (opus_codec_t *codec)
	Get current encoder bitrate.
asciichat_error_t	opus_codec_set_dtx (opus_codec_t *codec, int enable)
	Enable/disable DTX (Discontinuous Transmission)
void	opus_codec_destroy (opus_codec_t *codec)
	Destroy an Opus codec instance.

Variables
float	compressor_t::threshold_dB
	Compression threshold in dB (e.g., -10.0)
float	compressor_t::knee_dB
	Knee width in dB for soft knee (e.g., 2.0)
float	compressor_t::ratio
	Compression ratio (e.g., 4.0 for 4:1 compression)
float	compressor_t::attack_ms
	Attack time in milliseconds (how fast compression kicks in)
float	compressor_t::release_ms
	Release time in milliseconds (how fast compression releases)
float	compressor_t::makeup_dB
	Makeup gain in dB (compensates for gain reduction)
float	compressor_t::sample_rate
	Sample rate in Hz (set during initialization)
float	compressor_t::envelope
	Current envelope follower state (linear, 0-1)
float	compressor_t::gain_lin
	Current gain multiplier (linear, calculated from envelope)
float	compressor_t::attack_coeff
	Attack coefficient (converted from attack_ms)
float	compressor_t::release_coeff
	Release coefficient (converted from release_ms)
float	noise_gate_t::threshold
	Gate threshold in linear units (e.g., 0.01f for -40dB)
float	noise_gate_t::attack_ms
	Attack time in milliseconds (how fast gate opens)
float	noise_gate_t::release_ms
	Release time in milliseconds (how fast gate closes)
float	noise_gate_t::hysteresis
	Hysteresis factor (0-1, prevents gate chatter)
float	noise_gate_t::sample_rate
	Sample rate in Hz (set during initialization)
float	noise_gate_t::envelope
	Current envelope follower state (linear, 0-1)
float	noise_gate_t::attack_coeff
	Attack coefficient (converted from attack_ms)
float	noise_gate_t::release_coeff
	Release coefficient (converted from release_ms)
bool	noise_gate_t::gate_open
	True if gate is currently open (allowing audio through)
float	highpass_filter_t::cutoff_hz
	Cutoff frequency in Hz (frequencies below this are attenuated)
float	highpass_filter_t::sample_rate
	Sample rate in Hz (set during initialization)
float	highpass_filter_t::alpha
	Filter coefficient alpha (calculated from cutoff_hz)
float	highpass_filter_t::prev_input
	Previous input sample (filter state)
float	highpass_filter_t::prev_output
	Previous output sample (filter state)
float	lowpass_filter_t::cutoff_hz
	Cutoff frequency in Hz (frequencies above this are attenuated)
float	lowpass_filter_t::sample_rate
	Sample rate in Hz (set during initialization)
float	lowpass_filter_t::alpha
	Filter coefficient alpha (calculated from cutoff_hz)
float	lowpass_filter_t::prev_output
	Previous output sample (filter state)
float	ducking_t::threshold_dB
	Speaking threshold in dB (sources below this are not "speaking")
float	ducking_t::leader_margin_dB
	Leader margin in dB (sources within this of loudest are leaders)
float	ducking_t::atten_dB
	Attenuation in dB for non-leader sources.
float	ducking_t::attack_ms
	Ducking attack time in milliseconds.
float	ducking_t::release_ms
	Ducking release time in milliseconds.
float	ducking_t::attack_coeff
	Attack coefficient (converted from attack_ms)
float	ducking_t::release_coeff
	Release coefficient (converted from release_ms)
float *	ducking_t::envelope
	Per-source envelope follower state (linear, allocated per source)
float *	ducking_t::gain
	Per-source ducking gain (linear, calculated from envelope)
int	mixer_t::num_sources
	Current number of active audio sources.
int	mixer_t::max_sources
	Maximum number of sources (allocated array sizes)
int	mixer_t::sample_rate
	Sample rate in Hz (e.g., 44100)
audio_ring_buffer_t **	mixer_t::source_buffers
	Array of pointers to client audio ring buffers.
uint32_t *	mixer_t::source_ids
	Array of client IDs (one per source slot)
bool *	mixer_t::source_active
	Array of active flags (true if source is active)
uint64_t	mixer_t::active_sources_mask
	Bitset of active sources (bit i = source i is active, O(1) iteration)
uint8_t	mixer_t::source_id_to_index [256]
	Hash table mapping client_id → mixer source index (uses hash function for 32-bit IDs)
uint32_t	mixer_t::source_id_at_hash [256]
	Client IDs stored at each hash index for collision detection.
rwlock_t	mixer_t::source_lock
	Reader-writer lock protecting source arrays and bitset.
float	mixer_t::crowd_alpha
	Crowd scaling exponent (typically 0.5 for sqrt scaling)
float	mixer_t::base_gain
	Base gain before crowd scaling is applied.
ducking_t	mixer_t::ducking
	Ducking system (active speaker detection and attenuation)
compressor_t	mixer_t::compressor
	Compressor (dynamic range compression)
float *	mixer_t::mix_buffer
	Temporary buffer for mixing operations (pre-allocated)

Mixer Lifecycle Functions
mixer_t *	mixer_create (int max_sources, int sample_rate)
	Create a new audio mixer.
void	mixer_destroy (mixer_t *mixer)
	Destroy a mixer and free all resources.

Source Management Functions
int	mixer_add_source (mixer_t *mixer, uint32_t client_id, audio_ring_buffer_t *buffer)
	Add an audio source to the mixer.
void	mixer_remove_source (mixer_t *mixer, uint32_t client_id)
	Remove an audio source from the mixer.
void	mixer_set_source_active (mixer_t *mixer, uint32_t client_id, bool active)
	Set whether a source is active (receiving audio)

Audio Processing Functions
int	mixer_process (mixer_t *mixer, float *output, int num_samples)
	Process audio from all active sources.
int	mixer_process_excluding_source (mixer_t *mixer, float *output, int num_samples, uint32_t exclude_client_id)
	Process audio from all sources except one (for per-client output)

Utility Functions
float	db_to_linear (float db)
	Convert decibels to linear gain.
float	linear_to_db (float linear)
	Convert linear gain to decibels.
float	clamp_float (float value, float min, float max)
	Clamp a float value to a range.

Compressor Functions
void	compressor_init (compressor_t *comp, float sample_rate)
	Initialize a compressor.
void	compressor_set_params (compressor_t *comp, float threshold_dB, float ratio, float attack_ms, float release_ms, float makeup_dB)
	Set compressor parameters.
float	compressor_process_sample (compressor_t *comp, float sidechain)
	Process a single sample through compressor.

Ducking Functions
int	ducking_init (ducking_t *duck, int num_sources, float sample_rate)
	Initialize ducking system.
void	ducking_free (ducking_t *duck)
	Free ducking system resources.
void	ducking_set_params (ducking_t *duck, float threshold_dB, float leader_margin_dB, float atten_dB, float attack_ms, float release_ms)
	Set ducking parameters.
void	ducking_process_frame (ducking_t *duck, float *envelopes, float *gains, int num_sources)
	Process a frame of audio through ducking system.

Noise Gate Functions
void	noise_gate_init (noise_gate_t *gate, float sample_rate)
	Initialize a noise gate.
void	noise_gate_set_params (noise_gate_t *gate, float threshold, float attack_ms, float release_ms, float hysteresis)
	Set noise gate parameters.
float	noise_gate_process_sample (noise_gate_t *gate, float input, float peak_amplitude)
	Process a single sample through noise gate.
void	noise_gate_process_buffer (noise_gate_t *gate, float *buffer, int num_samples)
	Process a buffer of samples through noise gate.
bool	noise_gate_is_open (const noise_gate_t *gate)
	Check if noise gate is currently open.

High-Pass Filter Functions
void	highpass_filter_init (highpass_filter_t *filter, float cutoff_hz, float sample_rate)
	Initialize a high-pass filter.
void	highpass_filter_reset (highpass_filter_t *filter)
	Reset high-pass filter state.
float	highpass_filter_process_sample (highpass_filter_t *filter, float input)
	Process a single sample through high-pass filter.
void	highpass_filter_process_buffer (highpass_filter_t *filter, float *buffer, int num_samples)
	Process a buffer of samples through high-pass filter.

Low-Pass Filter Functions
void	lowpass_filter_init (lowpass_filter_t *filter, float cutoff_hz, float sample_rate)
	Initialize a low-pass filter.
void	lowpass_filter_reset (lowpass_filter_t *filter)
	Reset low-pass filter state.
float	lowpass_filter_process_sample (lowpass_filter_t *filter, float input)
	Process a single sample through low-pass filter.
void	lowpass_filter_process_buffer (lowpass_filter_t *filter, float *buffer, int num_samples)
	Process a buffer of samples through low-pass filter.

Buffer Utility Functions
float	smoothstep (float t)
	Compute smoothstep interpolation.
int16_t	float_to_int16 (float sample)
	Convert float sample to int16 (WebRTC format)
float	int16_to_float (int16_t sample)
	Convert int16 sample to float.
void	buffer_float_to_int16 (const float *src, int16_t *dst, int count)
	Convert float buffer to int16 buffer.
void	buffer_int16_to_float (const int16_t *src, float *dst, int count)
	Convert int16 buffer to float buffer.
float	buffer_peak (const float *buffer, int count)
	Find peak absolute value in buffer.
void	apply_gain_buffer (float *buffer, int count, float gain)
	Apply gain to buffer in-place.
void	fade_buffer (float *buffer, int count, float start_gain, float end_gain)
	Apply linear fade to buffer in-place.
void	fade_buffer_smooth (float *buffer, int count, bool fade_in)
	Apply smoothstep fade to buffer in-place.
void	copy_buffer_with_gain (const float *src, float *dst, int count, float gain)
	Copy buffer with gain scaling.

Soft Clipping Functions
float	soft_clip (float sample, float threshold, float steepness)
	Apply soft clipping to a sample.
void	soft_clip_buffer (float *buffer, int num_samples, float threshold, float steepness)
	Apply soft clipping to a buffer.

Audio Mixing Configuration
#define	MIXER_MAX_SOURCES   32
	Maximum number of simultaneous audio sources.
#define	MIXER_FRAME_SIZE   256
	Number of samples processed per audio frame.

Detailed Description

🔊 Audio system for real-time audio capture and playback

This header provides audio capture and playback functionality using PortAudio, enabling real-time audio streaming for ascii-chat video chat sessions.

CORE FEATURES:

• Real-time audio capture from microphone/input devices
• Real-time audio playback to speakers/output devices
• Thread-safe ring buffers for audio data
• Low-latency audio processing
• Platform-specific real-time priority scheduling
• Configurable audio parameters (sample rate, buffer size)

AUDIO ARCHITECTURE:

The audio system uses PortAudio for cross-platform audio I/O:

• Single full-duplex stream for simultaneous capture and playback
• Single callback receives both render and capture at EXACT same instant
• Perfect timing for WebRTC AEC3 echo cancellation (no ring buffer delay)
• Ring buffers only for network I/O (playback from jitter buffer, capture to encoder)
• Automatic device enumeration and selection

AUDIO PARAMETERS:

• Sample Rate: 48kHz (professional quality, Opus-compatible)
• Channels: Mono (1 channel)
• Buffer Size: 256 frames per buffer (low latency)
• Format: 32-bit floating point samples

THREAD SAFETY:

• Audio context state protected by mutex
• Ring buffers provide thread-safe audio data transfer
• Real-time priority scheduling on supported platforms

PLATFORM SUPPORT:

• Windows: DirectSound, WASAPI, or ASIO backends
• Linux: ALSA backend only (JACK explicitly disabled)
• macOS: CoreAudio backend

Note

Audio capture and playback can be started/stopped independently.

The audio system uses ring buffers to smooth out timing variations between capture/playback threads and network I/O.

Real-time priority is automatically requested on supported platforms to minimize audio glitches and latency.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

This header provides professional-quality audio mixing for ascii-chat's multi-client audio chat functionality. The mixer combines audio from multiple clients with advanced processing including compression, ducking, noise gating, and high-pass filtering.

CORE FEATURES:

• Multi-source audio mixing (up to 10 simultaneous sources)
• Active speaker detection and ducking
• Dynamic range compression
• Noise gate with hysteresis
• High-pass filtering for noise reduction
• Crowd scaling (automatic volume adjustment based on participant count)
• Optimized O(1) source exclusion using bitsets
• Reader-writer lock synchronization for concurrent access

AUDIO PROCESSING PIPELINE:

The mixer processes audio through the following stages:

1. Source Reading: Reads samples from client audio ring buffers
2. Ducking: Identifies active speaker and attenuates background sources
3. Mixing: Combines all active sources with crowd scaling
4. Compression: Applies dynamic range compression to prevent clipping
5. Noise Gate: Suppresses background noise below threshold
6. High-Pass Filter: Removes low-frequency noise and rumble
7. Soft Clipping: Prevents hard clipping artifacts

DUCKING SYSTEM:

The ducking system automatically:

• Detects the loudest active speaker
• Identifies sources within a margin of the loudest (also considered active)
• Attenuates non-active sources to prevent echo and feedback
• Uses smooth attack/release curves for natural transitions

COMPRESSION:

The compressor provides:

• Threshold-based compression (acts above threshold)
• Configurable compression ratio (e.g., 4:1)
• Soft knee for smooth compression curves
• Independent attack and release times
• Automatic makeup gain compensation

OPTIMIZATIONS:

• Bitset-based active source tracking (O(1) exclusion vs O(n))
• Hash table for client ID to mixer index mapping
• Reader-writer locks for concurrent source management
• Pre-allocated mix buffer to avoid allocations in hot path

THREAD SAFETY:

• Source arrays protected by reader-writer locks
• Bitset operations are atomic
• Mix processing is thread-safe once sources are locked

Note

The mixer processes audio in fixed-size frames (256 samples) for consistent latency and processing behavior.

Ducking parameters should be tuned based on room acoustics and expected participant count for optimal performance.

Crowd scaling automatically reduces per-source volume as more participants join, preventing audio overload.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

Provides high-level interface to libopus for encoding and decoding audio frames with configurable bitrate and frame sizes.

OPUS CODEC FEATURES:

• Real-time audio compression with minimal latency
• Flexible bitrate from 6 kbps (voice) to 128+ kbps (music)
• Adaptive frame sizes (10ms, 20ms, 40ms, 60ms)
• Automatic detection of voice vs music content
• Graceful handling of packet loss

USAGE EXAMPLE:

// Create encoder for voice at 24 kbps
opus_codec_t *encoder = opus_codec_create_encoder(OPUS_APPLICATION_VOIP, 44100, 24000);
 
// Encode audio (882 samples = 20ms at 44.1kHz)
float samples[882];
uint8_t compressed[250];
size_t encoded_bytes = opus_codec_encode(encoder, samples, 882, compressed, 250);
 
// Send over network...
 
// Create decoder
opus_codec_t *decoder = opus_codec_create_decoder(44100);
 
// Decode received audio
float decoded[882];
int decoded_samples = opus_codec_decode(decoder, compressed, encoded_bytes, decoded, 882);
 
// Cleanup
opus_codec_destroy(encoder);
opus_codec_destroy(decoder);

Note

Thread-safety: Each codec instance must not be accessed from multiple threads simultaneously. Create separate encoder and decoder instances per thread if needed.

Frame sizes: Opus works with fixed frame sizes. Recommended:

• 20ms (882 samples @ 44.1kHz) for voice
• 40ms (1764 samples @ 44.1kHz) for low-latency music

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

December 2025

Audio README

Overview

Welcome to the Audio System! This is where all the audio magic happens—capturing your voice from the microphone, playing back audio from other participants, and making sure everything runs smoothly in real-time. We use PortAudio for cross-platform audio I/O, which means everything works the same way on Linux, macOS, and Windows.

What does the audio system do?

The Audio System provides real-time audio capture and playback functionality for ascii-chat video chat sessions. Here's what it gives you:

• Real-time audio capture from microphone/input devices (so your voice is captured as you speak)
• Real-time audio playback to speakers/output devices (so you hear others in real-time)
• Thread-safe ring buffers for audio data (so capture and playback can run in parallel without conflicts)
• Low-latency audio processing (so there's minimal delay between speaking and hearing)
• Platform-specific real-time priority scheduling (so audio threads get priority and don't get interrupted by other tasks)
• Configurable audio parameters (sample rate, buffer size) so you can tune for your needs
• Automatic device enumeration and selection (so it just works with your audio devices)

Implementation: lib/audio.h

Architecture

The audio system is built around a few key concepts: PortAudio for cross-platform audio I/O, ring buffers for efficient data transfer, and thread-safe operations so everything can run in parallel. Let's walk through how everything fits together.

How does PortAudio work?

We use PortAudio for cross-platform audio I/O because it handles all the platform-specific details for us—we write the same code and it works on Linux, macOS, and Windows. PortAudio provides:

Audio Streams:

• Separate input and output streams for full-duplex audio (you can capture and play back at the same time)
• Independent capture and playback threads (so capture doesn't block playback and vice versa)
• Automatic stream management and lifecycle (PortAudio handles starting, stopping, and cleaning up streams)

What about ring buffers?

Ring Buffers:

• Efficient producer-consumer audio data transfer: Ring buffers let one thread (the producer) write data while another thread (the consumer) reads data, without blocking each other
• Lock-free or mutex-protected buffers depending on platform (we use the most efficient approach for each platform)
• Jitter buffering to smooth out network timing variations (network latency can vary, so we buffer a bit to smooth it out)
• Configurable buffer sizes for latency/quality trade-offs (bigger buffers = smoother playback but higher latency, smaller buffers = lower latency but might stutter)

How do we handle threading?

Thread Safety:

• Audio context state protected by mutex: When multiple threads access the audio context, they're protected by a mutex so there are no race conditions
• Ring buffers provide thread-safe audio data transfer: The ring buffers themselves are thread-safe, so capture and playback can run in parallel
• Real-time priority scheduling on supported platforms: Audio threads get real-time priority, so they don't get interrupted by other tasks (critical for smooth audio playback)

Audio Parameters

Audio parameters control the quality and latency of audio. The defaults are tuned for good quality with low latency, but you can adjust them for your needs.

What are the defaults?

Default Configuration:

• Sample Rate: 44.1kHz (CD quality)—this gives you excellent audio quality while keeping bandwidth reasonable. If you need even higher quality, you can go up to 48kHz or even 192kHz
• Channels: Mono (1 channel)—this keeps bandwidth low. If you want stereo (2 channels), you can enable it, but it doubles the bandwidth
• Buffer Size: 256 frames per buffer (low latency)—this gives you low latency (~5.8ms at 44.1kHz). If you have audio stuttering, you might want to increase this
• Format: 32-bit floating point samples—this gives you the best quality and is what PortAudio recommends

What can I configure?

Configurable Options:

• Custom sample rates: You can use any sample rate from 8kHz (for low bandwidth) up to 192kHz (for high quality), but 44.1kHz and 48kHz are the most common
• Stereo support: You can enable stereo (2 channels) if you want spatial audio, but it doubles the bandwidth
• Variable buffer sizes: You can adjust buffer sizes from 128 frames (ultra-low latency but might stutter) to 1024 frames (smooth but higher latency)
• Device selection: You can choose which input/output device to use if you have multiple audio devices

Operations

Initialization

Create Audio Context:

audio_context_t audio_ctx;
asciichat_error_t err = audio_init(&audio_ctx);
if (err != ASCIICHAT_OK) {
    log_error("Failed to initialize audio: %d", err);
    return err;
}

Configure Audio Parameters:

// Set custom sample rate and buffer size
audio_ctx.sample_rate = 48000;
audio_ctx.buffer_size = 512;
audio_ctx.channels = 1; // Mono

Audio Capture

Start Capture:

err = audio_start_capture(&audio_ctx);
if (err != ASCIICHAT_OK) {
    log_error("Failed to start audio capture");
    return err;
}

Read Captured Samples:

float samples[256];
asciichat_error_t err = audio_read_samples(&audio_ctx, samples, 256);
if (err == ASCIICHAT_OK) {
    // Send samples to network
    send_audio_packet(sockfd, samples, 256);
}

Audio Playback

Start Playback:

err = audio_start_playback(&audio_ctx);
if (err != ASCIICHAT_OK) {
    log_error("Failed to start audio playback");
    return err;
}

Write Playback Samples:

float samples[256];
// Receive samples from network
receive_audio_packet(sockfd, samples, 256);
 
// Write to playback buffer
asciichat_error_t err = audio_write_samples(&audio_ctx, samples, 256);
if (err != ASCIICHAT_OK) {
    log_warn("Failed to write audio samples");
}

Cleanup

Stop Audio:

audio_stop_capture(&audio_ctx);
audio_stop_playback(&audio_ctx);

Destroy Audio Context:

audio_destroy(&audio_ctx);

Platform Support

Windows:

• DirectSound backend (legacy)
• WASAPI backend (modern, recommended)
• ASIO backend (low-latency professional audio)

Linux:

• ALSA backend (standard Linux audio)
• JACK backend (professional audio, low latency)
• PulseAudio support via ALSA

macOS:

• CoreAudio backend (native macOS audio)
• Automatic device selection
• Low-latency support

Performance

Audio performance is all about balancing latency, CPU usage, and bandwidth. We've tuned the defaults for good performance across all three dimensions, but let's look at what you can expect:

How much latency do we have?

Latency:

• Buffer size: 256 frames @ 44.1kHz = ~5.8ms latency (this is the latency from the audio buffer itself)
• Network jitter buffering: +46ms (8 packets) (this is extra buffering to smooth out network timing variations)
• Total end-to-end latency: ~50-60ms (this is the total time from when someone speaks to when you hear it)

50-60ms is quite good for networked audio—it's comparable to phone calls and way better than most video conferencing software. The jitter buffering helps smooth out network hiccups, so you get smooth audio even when the network is a bit flaky.

How much CPU does audio use?

CPU Usage:

• Audio capture: ~1-2% CPU (single thread) (capturing audio is pretty lightweight)
• Audio playback: ~1-2% CPU (single thread) (playback is also lightweight)
• Total audio overhead: ~2-4% CPU (so audio adds about 2-4% CPU overhead total)

Audio is pretty lightweight—you probably won't even notice the CPU usage unless you're monitoring it closely.

How much bandwidth does audio use?

Bandwidth:

• 44.1kHz mono: ~176 KB/s (about 176 kilobytes per second)
• 48kHz mono: ~192 KB/s (about 192 kilobytes per second)
• 48kHz stereo: ~384 KB/s (about 384 kilobytes per second, double because stereo is two channels)

Audio bandwidth is pretty reasonable—even stereo at 48kHz is only about 384 KB/s, which is much less than video. You could stream audio over a decent cellular connection without any problems.

Ring Buffers

The audio system uses ring buffers for efficient producer-consumer audio transfer:

Capture Ring Buffer:

• Producer: PortAudio capture callback
• Consumer: Network send thread
• Size: 8192 samples (~186ms @ 44.1kHz)
• Thread-safe: Mutex-protected on all platforms

Playback Ring Buffer:

• Producer: Network receive thread
• Consumer: PortAudio playback callback
• Size: 8192 samples (~186ms @ 44.1kHz)
• Jitter buffer threshold: 2048 samples (~46ms)
• Thread-safe: Mutex-protected on all platforms

Threading

Audio Threads:

• Capture thread: PortAudio callback (real-time priority)
• Playback thread: PortAudio callback (real-time priority)
• Network threads: User threads (normal priority)

Priority Scheduling:

• Windows: THREAD_PRIORITY_TIME_CRITICAL for audio threads
• Linux: SCHED_FIFO with priority 50 (requires capabilities)
• macOS: Real-time thread priority

Integration

Network Integration:

• Audio samples sent via PACKET_TYPE_AUDIO_BATCH
• Compression enabled for large batches
• Encryption via crypto context (if enabled)

Ring Buffer Integration:

• Uses specialized audio ring buffer (audio_ring_buffer_t)
• Jitter buffering for network latency compensation
• Thread-safe operations with mutex protection

See also

audio.h

ringbuffer.h

network/av.h

Mixer README

Overview

Welcome to the audio mixer—where all the magic happens when multiple people are talking at once!

Picture yourself in a group video call. Person A is talking, Person B laughs, Person C asks a question—all happening simultaneously. Your speakers don't have three separate outputs (well, most don't). So how does your computer play all three audio streams at once? That's where the mixer comes in!

The mixer takes multiple audio streams (one from each client) and combines them into a single output stream that gets sent to everyone. It's like a real mixing board at a concert—each microphone is a separate input, and the mixer blends them into one cohesive sound that goes to the speakers.

But here's the cool part: when lots of people are talking at once, the mixer automatically applies "ducking" (volume reduction) so the combined audio doesn't clip or distort. It's like how a good sound engineer knows to turn down each microphone a bit when everyone's singing together—the mix stays clear and balanced.

Implementation: lib/mixer.h

What makes the mixer special?

• Real-time mixing: Combines multiple audio streams on the fly
• Dynamic source management: Sources can join or leave without disrupting the mix
• Active speaker detection: Automatically identifies who's talking loudest
• Automatic ducking: Attenuates background sources when someone is speaking
• Dynamic range compression: Prevents clipping with professional compressor
• Noise gate: Suppresses background noise below threshold with hysteresis
• High-pass filtering: Removes low-frequency rumble and noise
• Soft clipping: Prevents harsh digital clipping artifacts
• Crowd scaling: Automatically adjusts volume based on participant count
• Thread-safe: Reader-writer locks for concurrent access
• Low latency: Fixed 256-sample frame processing
• O(1) source exclusion: Bitset-based tracking for echo cancellation

Architecture

Mixer Design:

• Single mixer instance per server
• Per-client audio input buffers
• Shared output buffer for mixed audio
• Thread-safe operation with mutex protection

Audio Flow:

Client 1 Audio → Input Buffer 1 ──┐
Client 2 Audio → Input Buffer 2 ──┤
Client 3 Audio → Input Buffer 3 ──┼→ Mixer → Mixed Output → All Clients
...                               ─┘

Operations

Initialization

Create Mixer:

// mixer_create returns a pointer to a new mixer (NULL on failure)
mixer_t *mixer = mixer_create(MIXER_MAX_SOURCES, 48000);
if (!mixer) {
    log_error("Failed to create mixer");
    return ASCIICHAT_ERROR_MEMORY;
}

Source Management

Add Audio Source (client with audio ring buffer):

uint32_t client_id = 12345;
audio_ring_buffer_t *client_audio_buffer = ...; // Client's audio ring buffer
 
int result = mixer_add_source(mixer, client_id, client_audio_buffer);
if (result < 0) {
    log_error("Failed to add client %u to mixer", client_id);
    return ASCIICHAT_ERROR_FULL;
}
log_info("Client %u added to mixer at index %d", client_id, result);

Remove Audio Source:

mixer_remove_source(mixer, client_id);
log_info("Client %u removed from mixer", client_id);

Audio Processing

The mixer reads audio directly from each client's audio ring buffer. Clients write their audio samples to their ring buffer, and the mixer reads and mixes them during processing.

Mix Audio (reads from all source ring buffers):

float mixed_output[MIXER_FRAME_SIZE];
int samples_mixed = mixer_process(mixer, mixed_output, MIXER_FRAME_SIZE);
 
if (samples_mixed > 0) {
    // Send mixed audio to all clients
    send_audio_to_all_clients(mixed_output, samples_mixed);
}

Mix Audio Excluding a Source (for echo cancellation):

// Mix all sources except the client we're sending to (prevents echo)
float output_for_client[MIXER_FRAME_SIZE];
int samples = mixer_process_excluding_source(mixer, output_for_client,
                                              MIXER_FRAME_SIZE, client_id);
send_audio_to_client(client_id, output_for_client, samples);

Cleanup

Destroy Mixer:

mixer_destroy(mixer);  // Pass pointer, not address-of

Active Speaker Detection & Ducking

The ducking system automatically identifies who's speaking and attenuates background sources to improve clarity. This is more sophisticated than simple volume scaling.

How It Works:

• Leader Detection: The loudest source(s) above threshold_dB are identified
• Margin Tracking: Sources within leader_margin_dB of the loudest are also "leaders"
• Attenuation: Non-leader sources are attenuated by atten_dB
• Smooth Transitions: Attack/release curves prevent jarring volume changes

The ducking uses dB-based audio analysis:

// Ducking parameters (in dB and milliseconds)
typedef struct {
    float threshold_dB;    // Speaking threshold (-40dB typical)
    float leader_margin_dB; // Margin to be considered a leader (6dB typical)
    float atten_dB;        // Attenuation for non-leaders (-12dB typical)
    float attack_ms;       // How fast ducking engages (10ms typical)
    float release_ms;      // How fast ducking releases (100ms typical)
} ducking_t;

Practical Example:

• Person A speaks at -20dB (loud)
• Person B speaks at -25dB (within 6dB margin of A)
• Person C has background noise at -50dB (below threshold)
• Result: A and B are heard at full volume, C is attenuated by 12dB

This allows multiple people to have a natural conversation while suppressing background noise from inactive participants.

Thread Safety

Reader-Writer Lock Protection:

• Source array protected by reader-writer locks (rwlock)
• Multiple readers can process audio concurrently
• Writers (add/remove source) get exclusive access
• Bitset operations are atomic for source exclusion

Thread Model:

// Network receive thread - writes to client's ring buffer
void* client_receive_thread(void *arg) {
    client_t *client = (client_t *)arg;
    while (running) {
        float samples[256];
        receive_audio_packet(client->id, samples, 256);
        // Write directly to client's audio ring buffer
        audio_ring_buffer_write(client->audio_buffer, samples, 256);
    }
    return NULL;
}
 
// Audio processing thread - reads from all ring buffers via mixer
void* audio_mix_thread(void *arg) {
    mixer_t *mixer = (mixer_t *)arg;
    while (running) {
        float mixed[MIXER_FRAME_SIZE];
        int samples = mixer_process(mixer, mixed, MIXER_FRAME_SIZE);
        if (samples > 0) {
            send_to_all_clients(mixed, samples);
        }
    }
    return NULL;
}

Performance

Mixing Algorithm:

• Simple additive mixing with ducking
• SIMD optimization where available
• Minimal memory allocations
• Cache-friendly data layout

CPU Usage:

• 2 clients: ~1% CPU
• 4 clients: ~2% CPU
• 8 clients: ~3% CPU
• 16 clients: ~5% CPU

Latency:

• Mixing latency: <1ms
• Total audio latency: ~50-60ms (includes network)

Buffer Management

Per-Client Buffers:

• Fixed-size circular buffers
• Automatic overflow handling
• Underrun detection and handling

Buffer Configuration:

mixer.buffer_size = 8192;  // Samples per client buffer
mixer.min_frames = 256;    // Minimum frames for mixing

Overflow Handling:

• Drop oldest frames when buffer full
• Log warning message
• Continue operation without crash

Underrun Handling:

• Output silence when insufficient data
• Log debug message
• Wait for more data

Integration Example

Complete Server Integration:

// Initialize mixer
mixer_t mixer;
mixer_init(&mixer, MAX_CLIENTS);
 
// When client connects
void on_client_connect(uint32_t client_id) {
    mixer_add_client(&mixer, client_id);
    log_info("Client %u added to audio mixer", client_id);
}
 
// When client disconnects
void on_client_disconnect(uint32_t client_id) {
    mixer_remove_client(&mixer, client_id);
    log_info("Client %u removed from audio mixer", client_id);
}
 
// When audio packet arrives
void on_audio_packet(uint32_t client_id, float *samples, size_t num_frames) {
    mixer_submit_audio(&mixer, client_id, samples, num_frames);
}
 
// Audio mixing thread
void* audio_thread(void *arg) {
    float mixed[256];
 
    while (running) {
        size_t frames = mixer_process(&mixer, mixed, 256);
        if (frames > 0) {
            broadcast_audio_to_all_clients(mixed, frames);
        }
        usleep(5000);  // ~5ms sleep for 44.1kHz
    }
 
    return NULL;
}
 
// Cleanup
mixer_destroy(&mixer);

Best Practices

DO:

• Enable ducking for 4+ clients
• Monitor buffer overflows/underruns
• Use consistent sample rates across clients
• Remove clients from mixer on disconnect
• Use dedicated audio mixing thread

DON'T:

• Don't mix audio on network thread
• Don't forget to remove disconnected clients
• Don't use different sample rates per client
• Don't disable ducking with many clients
• Don't mix audio without mutex protection

See also

mixer.h

audio.h

ringbuffer.h

Macro Definition Documentation

AUDIO_BUFFER_SIZE

#define AUDIO_BUFFER_SIZE   (AUDIO_FRAMES_PER_BUFFER * AUDIO_CHANNELS)

#include <audio.h>

Total audio buffer size (frames × channels)

Definition at line 93 of file lib/audio/audio.h.

AUDIO_CHANNELS

#define AUDIO_CHANNELS   1

#include <audio.h>

Number of audio channels (1 = mono)

Definition at line 91 of file lib/audio/audio.h.

AUDIO_FRAMES_PER_BUFFER

#define AUDIO_FRAMES_PER_BUFFER   480

#include <audio.h>

Audio frames per buffer (480 = 10ms at 48kHz, matches WebRTC AEC3 frame size)

Definition at line 89 of file lib/audio/audio.h.

AUDIO_SAMPLE_RATE

#define AUDIO_SAMPLE_RATE   48000

#include <audio.h>

Audio sample rate (48kHz professional quality, Opus-compatible)

Definition at line 87 of file lib/audio/audio.h.

MIXER_FRAME_SIZE

#define MIXER_FRAME_SIZE   256

#include <mixer.h>

Number of samples processed per audio frame.

Fixed frame size for consistent latency and processing behavior. 256 samples at 48kHz = ~5.3ms per frame.

Definition at line 114 of file mixer.h.

MIXER_MAX_SOURCES

#define MIXER_MAX_SOURCES   32

#include <mixer.h>

Maximum number of simultaneous audio sources.

Limits the maximum number of clients that can provide audio simultaneously. Each client requires one source slot in the mixer.

Definition at line 104 of file mixer.h.

Typedef Documentation

OpusDecoder

typedef struct OpusDecoder OpusDecoder

#include <opus_codec.h>

Definition at line 66 of file opus_codec.h.

OpusEncoder

typedef struct OpusEncoder OpusEncoder

#include <opus_codec.h>

Definition at line 65 of file opus_codec.h.

Enumeration Type Documentation

opus_application_t

enum opus_application_t

#include <opus_codec.h>

Application mode for opus encoder.

Enumerator
OPUS_APPLICATION_VOIP	Voice over IP (optimized for speech)
OPUS_APPLICATION_AUDIO	General audio (optimized for music)
OPUS_APPLICATION_RESTRICTED_LOWDELAY	Low-latency mode.

Definition at line 76 of file opus_codec.h.

             {
  OPUS_APPLICATION_VOIP = 2048,               
  OPUS_APPLICATION_AUDIO = 2049,              
  OPUS_APPLICATION_RESTRICTED_LOWDELAY = 2051 
} opus_application_t;

Function Documentation

apply_gain_buffer()

void apply_gain_buffer	(	float *	buffer,
		int	count,
		float	gain
	)

#include <mixer.h>

Apply gain to buffer in-place.

Parameters

buffer	Audio buffer (modified in-place)
count	Number of samples
gain	Gain multiplier to apply

Multiplies all samples by gain factor.

Definition at line 1096 of file mixer.c.

                                                             {
  if (!buffer || count <= 0)
    return;
 
  for (int i = 0; i < count; i++) {
    buffer[i] *= gain;
  }
}

audio_dequantize_samples()

asciichat_error_t audio_dequantize_samples	(	const uint8_t *	samples_ptr,
		uint32_t	total_samples,
		float *	out_samples
	)

#include <audio.h>

Dequantize network audio samples from int32 to float.

Parameters

samples_ptr	Pointer to quantized samples (network byte order uint32_t values)
total_samples	Number of samples to convert
out_samples	Output buffer for float samples (must be pre-allocated)

Returns

ASCIICHAT_OK on success, error code on failure

Converts quantized audio samples from network byte order (uint32_t) to floating point format. Performs the following transformation:

• Read uint32_t in network byte order
• Convert to int32_t via ntohl()
• Scale to float range [-1.0, 1.0] by dividing by 2147483647.0

This helper eliminates code duplication between server and client handlers.

Note

out_samples must be pre-allocated by caller with space for total_samples floats

samples_ptr should point to total_samples * sizeof(uint32_t) bytes

Definition at line 1359 of file lib/audio/audio.c.

                                                                                                                   {
  if (!samples_ptr || !out_samples || total_samples == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for audio dequantization");
  }
 
  for (uint32_t i = 0; i < total_samples; i++) {
    uint32_t network_sample;
    // Use memcpy to safely handle potential misalignment from packet header
    memcpy(&network_sample, samples_ptr + i * sizeof(uint32_t), sizeof(uint32_t));
    int32_t scaled = (int32_t)NET_TO_HOST_U32(network_sample);
    out_samples[i] = (float)scaled / 2147483647.0f;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, NET_TO_HOST_U32, and SET_ERRNO.

Referenced by handle_audio_batch_packet().

audio_destroy()

void audio_destroy

(

audio_context_t *

ctx

)

#include <audio.h>

Destroy audio context and clean up resources.

Parameters

ctx	Audio context to destroy (can be NULL)

Stops all audio streams, destroys ring buffers, and cleans up PortAudio resources. Safe to call multiple times or with NULL pointer.

Note

Automatically stops capture and playback if active.

Ring buffers are destroyed and all data is lost.

PortAudio is terminated after last context is destroyed.

Definition at line 894 of file lib/audio/audio.c.

                                         {
  if (!ctx || !ctx->initialized) {
    return;
  }
 
  // Stop duplex stream if running
  if (ctx->running) {
    audio_stop_duplex(ctx);
  }
 
  mutex_lock(&ctx->state_mutex);
 
  audio_ring_buffer_destroy(ctx->capture_buffer);
  audio_ring_buffer_destroy(ctx->playback_buffer);
 
  // Terminate PortAudio only when last context is destroyed
  static_mutex_lock(&g_pa_refcount_mutex);
  if (g_pa_init_refcount > 0) {
    g_pa_init_refcount--;
    if (g_pa_init_refcount == 0) {
      Pa_Terminate();
    }
  }
  static_mutex_unlock(&g_pa_refcount_mutex);
 
  ctx->initialized = false;
 
  mutex_unlock(&ctx->state_mutex);
  mutex_destroy(&ctx->state_mutex);
 
  log_info("Audio system destroyed");
}

References audio_ring_buffer_destroy(), audio_stop_duplex(), audio_context_t::capture_buffer, audio_context_t::initialized, log_info, mutex_destroy(), mutex_lock, mutex_unlock, audio_context_t::playback_buffer, audio_context_t::running, and audio_context_t::state_mutex.

Referenced by audio_cleanup(), and audio_client_init().

audio_free_device_list()

void audio_free_device_list

(

audio_device_info_t *

devices

)

#include <audio.h>

Free device list allocated by audio_list_input_devices/audio_list_output_devices.

Parameters

devices

Device array to free (can be NULL)

Frees the device array allocated by audio_list_input_devices() or audio_list_output_devices(). Safe to call with NULL.

Definition at line 1355 of file lib/audio/audio.c.

                                                          {
  SAFE_FREE(devices);
}

References SAFE_FREE.

Referenced by action_list_microphones(), and action_list_speakers().

audio_init()

asciichat_error_t audio_init

(

audio_context_t *

ctx

)

#include <audio.h>

Initialize audio context and PortAudio.

Parameters

ctx	Audio context to initialize (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Initializes the audio context and PortAudio library. Creates ring buffers for capture and playback but does not start streams. Must be called before any other audio functions.

Note

PortAudio initialization is idempotent and thread-safe.

Ring buffers are created but empty after initialization.

Use audio_start_duplex() to begin full-duplex audio I/O.

Warning

Must call audio_destroy() to clean up resources when done.

Definition at line 773 of file lib/audio/audio.c.

                                                   {
  if (!ctx) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx is NULL");
  }
 
  SAFE_MEMSET(ctx, sizeof(audio_context_t), 0, sizeof(audio_context_t));
 
  if (mutex_init(&ctx->state_mutex) != 0) {
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize audio context mutex");
  }
 
  // Initialize PortAudio with reference counting
  static_mutex_lock(&g_pa_refcount_mutex);
  if (g_pa_init_refcount == 0) {
    // Suppress PortAudio backend probe errors (ALSA/JACK/OSS warnings)
    // These are harmless - PortAudio tries multiple backends until one works
    int stderr_fd_backup = -1;
    int devnull_fd = -1;
#ifndef _WIN32
    stderr_fd_backup = dup(STDERR_FILENO);
    devnull_fd = platform_open("/dev/null", O_WRONLY, 0);
    if (stderr_fd_backup >= 0 && devnull_fd >= 0) {
      dup2(devnull_fd, STDERR_FILENO);
    }
#endif
 
    PaError err = Pa_Initialize();
 
    // Restore stderr IMMEDIATELY so real errors are visible
#ifndef _WIN32
    if (stderr_fd_backup >= 0) {
      dup2(stderr_fd_backup, STDERR_FILENO);
      close(stderr_fd_backup);
    }
    if (devnull_fd >= 0) {
      close(devnull_fd);
    }
#endif
 
    if (err != paNoError) {
      static_mutex_unlock(&g_pa_refcount_mutex);
      mutex_destroy(&ctx->state_mutex);
      // stderr is restored, so this error will be visible
      return SET_ERRNO(ERROR_AUDIO, "Failed to initialize PortAudio: %s", Pa_GetErrorText(err));
    }
 
    log_debug("PortAudio initialized successfully (probe warnings suppressed)");
  }
  g_pa_init_refcount++;
  static_mutex_unlock(&g_pa_refcount_mutex);
 
  // Enumerate all audio devices for debugging
  int numDevices = Pa_GetDeviceCount();
  const size_t max_device_info_size = 4096; // Limit total device info size
  char device_names[max_device_info_size];
  int offset = 0;
  for (int i = 0; i < numDevices && offset < (int)sizeof(device_names) - 256; i++) {
    const PaDeviceInfo *deviceInfo = Pa_GetDeviceInfo(i);
    if (deviceInfo && deviceInfo->name) {
      int remaining = sizeof(device_names) - offset;
      if (remaining < 256)
        break;
 
      int len = snprintf(&device_names[offset], remaining,
                         "\n  Device %d: %s (inputs=%d, outputs=%d, sample_rate=%.0f Hz)%s%s", i, deviceInfo->name,
                         deviceInfo->maxInputChannels, deviceInfo->maxOutputChannels, deviceInfo->defaultSampleRate,
                         (i == Pa_GetDefaultInputDevice()) ? " [DEFAULT INPUT]" : "",
                         (i == Pa_GetDefaultOutputDevice()) ? " [DEFAULT OUTPUT]" : "");
      if (len > 0 && len < remaining) {
        offset += len;
      } else {
        // Buffer full or error - stop here
        break;
      }
    }
  }
  device_names[offset] = '\0';
  if (offset > 0) {
    log_debug("PortAudio found %d audio devices:%s", numDevices, device_names);
  } else {
    log_warn("PortAudio found no audio devices");
  }
 
  // Create capture buffer WITHOUT jitter buffering (PortAudio writes directly from microphone)
  ctx->capture_buffer = audio_ring_buffer_create_for_capture();
  if (!ctx->capture_buffer) {
    // Decrement refcount and terminate if this was the only context
    static_mutex_lock(&g_pa_refcount_mutex);
    if (g_pa_init_refcount > 0) {
      g_pa_init_refcount--;
      if (g_pa_init_refcount == 0) {
        Pa_Terminate();
      }
    }
    static_mutex_unlock(&g_pa_refcount_mutex);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create capture buffer");
  }
 
  ctx->playback_buffer = audio_ring_buffer_create();
  if (!ctx->playback_buffer) {
    audio_ring_buffer_destroy(ctx->capture_buffer);
    // Decrement refcount and terminate if this was the only context
    static_mutex_lock(&g_pa_refcount_mutex);
    if (g_pa_init_refcount > 0) {
      g_pa_init_refcount--;
      if (g_pa_init_refcount == 0) {
        Pa_Terminate();
      }
    }
    static_mutex_unlock(&g_pa_refcount_mutex);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create playback buffer");
  }
 
  ctx->initialized = true;
  atomic_store(&ctx->shutting_down, false);
  log_info("Audio system initialized successfully");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, audio_ring_buffer_create(), audio_ring_buffer_create_for_capture(), audio_ring_buffer_destroy(), audio_context_t::capture_buffer, ERROR_AUDIO, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_THREAD, audio_context_t::initialized, log_debug, log_info, log_warn, mutex_destroy(), mutex_init(), platform_open(), audio_context_t::playback_buffer, SAFE_MEMSET, SET_ERRNO, audio_context_t::shutting_down, and audio_context_t::state_mutex.

Referenced by audio_client_init().

audio_is_supported_sample_rate()

bool audio_is_supported_sample_rate

(

uint32_t

sample_rate

)

#include <audio.h>

Check if a sample rate is a standard/supported rate.

Supported rates: 8000, 16000, 24000, 32000, 44100, 48000, 96000, 192000

Parameters

sample_rate

Sample rate in Hz

Returns

true if the sample rate is supported, false otherwise

Usage:

if (!audio_is_supported_sample_rate(batch.sample_rate)) {
    log_error("Unsupported sample rate: %u", batch.sample_rate);
    return;
}

Definition at line 1455 of file lib/audio/audio.c.

                                                          {
  // List of commonly supported audio sample rates
  static const uint32_t supported_rates[] = {
      8000,   // Telephone quality
      16000,  // Wideband telephony
      24000,  // High quality speech
      32000,  // Good for video
      44100,  // CD quality (less common in VoIP)
      48000,  // Standard professional
      96000,  // High-end professional
      192000, // Ultra-high-end mastering
  };
 
  const size_t rate_count = sizeof(supported_rates) / sizeof(supported_rates[0]);
  for (size_t i = 0; i < rate_count; i++) {
    if (sample_rate == supported_rates[i]) {
      return true;
    }
  }
 
  return false;
}

Referenced by audio_validate_batch_params().

audio_list_input_devices()

asciichat_error_t audio_list_input_devices	(	audio_device_info_t **	out_devices,
		unsigned int *	out_count
	)

#include <audio.h>

List available audio input devices (microphones)

Parameters

out_devices	Pointer to store allocated array of devices (must not be NULL)
out_count	Pointer to store device count (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Enumerates all audio input devices (microphones) available on the system. The caller is responsible for freeing the returned array with audio_free_device_list().

Note

This function initializes PortAudio temporarily if not already initialized.

Devices with maxInputChannels > 0 are included.

Warning

Must call audio_free_device_list() to free the returned array.

Definition at line 1347 of file lib/audio/audio.c.

                                                                                                       {
  return audio_list_devices_internal(out_devices, out_count, true);
}

Referenced by action_list_microphones().

audio_list_output_devices()

asciichat_error_t audio_list_output_devices	(	audio_device_info_t **	out_devices,
		unsigned int *	out_count
	)

#include <audio.h>

List available audio output devices (speakers)

Parameters

out_devices	Pointer to store allocated array of devices (must not be NULL)
out_count	Pointer to store device count (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Enumerates all audio output devices (speakers/headphones) available on the system. The caller is responsible for freeing the returned array with audio_free_device_list().

Note

This function initializes PortAudio temporarily if not already initialized.

Devices with maxOutputChannels > 0 are included.

Warning

Must call audio_free_device_list() to free the returned array.

Definition at line 1351 of file lib/audio/audio.c.

                                                                                                        {
  return audio_list_devices_internal(out_devices, out_count, false);
}

Referenced by action_list_speakers().

audio_parse_batch_header()

asciichat_error_t audio_parse_batch_header	(	const void *	data,
		size_t	len,
		audio_batch_info_t *	out_batch
	)

#include <audio.h>

Parse an audio batch packet header from raw packet data.

Performs the following validations:

1. Checks that the data pointer is not NULL
2. Checks that len is at least sizeof(audio_batch_header_t)
3. Verifies that batch_count and channels are within reasonable bounds
4. Unpacks all 32-bit values from network byte order to host byte order

Parameters

	data	Pointer to packet data (must not be NULL)
	len	Length of packet data in bytes
[out]	out_batch	Pointer to audio_batch_info_t struct to fill with parsed data

Returns

ASCIICHAT_OK if parsing succeeded

ERROR_INVALID_PARAM if data is NULL or out_batch is NULL

ERROR_INVALID_PARAM if len is too small for the header

Usage:

audio_batch_info_t batch;
asciichat_error_t result = audio_parse_batch_header(packet_data, packet_len, &batch);
if (result != ASCIICHAT_OK) {
    log_error("Failed to parse audio batch: %d", result);
    return;
}
 
// Now batch.batch_count, batch.sample_rate, etc. are ready to use
log_debug("Audio batch: %u frames at %u Hz, %u channels",
          batch.batch_count, batch.sample_rate, batch.channels);

Definition at line 1389 of file lib/audio/audio.c.

                                                                                                        {
  if (!data) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch header data pointer is NULL");
  }
 
  if (!out_batch) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch info output pointer is NULL");
  }
 
  if (len < sizeof(audio_batch_packet_t)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch header too small (len=%zu, expected=%zu)", len,
                     sizeof(audio_batch_packet_t));
  }
 
  const audio_batch_packet_t *batch_header = (const audio_batch_packet_t *)data;
 
  // Unpack network byte order values to host byte order
  out_batch->batch_count = ntohl(batch_header->batch_count);
  out_batch->total_samples = ntohl(batch_header->total_samples);
  out_batch->sample_rate = ntohl(batch_header->sample_rate);
  out_batch->channels = ntohl(batch_header->channels);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, audio_batch_info_t::batch_count, audio_batch_packet_t::batch_count, audio_batch_info_t::channels, audio_batch_packet_t::channels, ERROR_INVALID_PARAM, audio_batch_info_t::sample_rate, audio_batch_packet_t::sample_rate, SET_ERRNO, audio_batch_info_t::total_samples, and audio_batch_packet_t::total_samples.

Referenced by handle_audio_batch_packet().

audio_read_samples()

asciichat_error_t audio_read_samples	(	audio_context_t *	ctx,
		float *	buffer,
		int	num_samples
	)

#include <audio.h>

Read captured audio samples from capture buffer.

Parameters

ctx	Audio context (must not be NULL)
buffer	Output buffer for audio samples (must not be NULL)
num_samples	Number of samples to read (must be > 0)

Returns

ASCIICHAT_OK on success, error code on failure

Reads audio samples from the capture ring buffer. Samples are in floating point format (-1.0 to 1.0 range). This function is non-blocking and returns whatever samples are available up to num_samples.

Note

Actual number of samples read may be less than num_samples if buffer doesn't contain enough samples.

Samples are removed from the buffer after reading.

Thread-safe: Can be called from any thread.

Warning

Buffer must be large enough to hold num_samples float values.

Definition at line 1156 of file lib/audio/audio.c.

                                                                                           {
  if (!ctx || !ctx->initialized || !buffer || num_samples <= 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, buffer=%p, num_samples=%d", ctx, buffer,
                     num_samples);
  }
 
  // audio_ring_buffer_read now returns number of samples read, not error code
  int samples_read = audio_ring_buffer_read(ctx->capture_buffer, buffer, num_samples);
  return (samples_read >= 0) ? ASCIICHAT_OK : ERROR_AUDIO;
}

References ASCIICHAT_OK, audio_ring_buffer_read(), audio_context_t::capture_buffer, ERROR_AUDIO, ERROR_INVALID_PARAM, audio_context_t::initialized, and SET_ERRNO.

audio_ring_buffer_available_read()

size_t audio_ring_buffer_available_read

(

audio_ring_buffer_t *

rb

)

#include <audio.h>

Get number of samples available for reading.

Parameters

rb	Audio ring buffer (must not be NULL)

Returns

Number of samples available to read

Returns the current number of samples available in the ring buffer for reading. Useful for determining if enough samples are available before calling audio_ring_buffer_read().

Note

Thread-safe: Can be called from any thread.

Value may change immediately after return due to concurrent writes.

Definition at line 747 of file lib/audio/audio.c.

                                                                 {
  if (!rb)
    return 0;
 
  // LOCK-FREE: Load indices with proper memory ordering
  // Use acquire for write_index to see writer's updates
  // Use relaxed for read_index (our own index)
  unsigned int write_idx = atomic_load_explicit(&rb->write_index, memory_order_acquire);
  unsigned int read_idx = atomic_load_explicit(&rb->read_index, memory_order_relaxed);
 
  if (write_idx >= read_idx) {
    return write_idx - read_idx;
  }
 
  return AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
}

References AUDIO_RING_BUFFER_SIZE, audio_ring_buffer::read_index, and audio_ring_buffer::write_index.

Referenced by audio_process_received_samples(), audio_ring_buffer_available_write(), client_audio_render_thread(), and mixer_process_excluding_source().

audio_ring_buffer_available_write()

size_t audio_ring_buffer_available_write

(

audio_ring_buffer_t *

rb

)

#include <audio.h>

Get number of sample slots available for writing.

Parameters

rb	Audio ring buffer (must not be NULL)

Returns

Number of sample slots available for writing

Returns the current number of sample slots available in the ring buffer for writing. Useful for determining if enough space is available before calling audio_ring_buffer_write().

Note

Thread-safe: Can be called from any thread.

Value may change immediately after return due to concurrent reads.

Definition at line 764 of file lib/audio/audio.c.

                                                                  {
  if (!rb) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb is NULL");
    return 0;
  }
 
  return AUDIO_RING_BUFFER_SIZE - audio_ring_buffer_available_read(rb) - 1;
}

References audio_ring_buffer_available_read(), AUDIO_RING_BUFFER_SIZE, ERROR_INVALID_PARAM, and SET_ERRNO.

audio_ring_buffer_clear()

void audio_ring_buffer_clear

(

audio_ring_buffer_t *

rb

)

#include <audio.h>

Clear all audio samples from ring buffer.

Parameters

rb	Audio ring buffer (must not be NULL)

Resets the ring buffer to empty state, clearing all samples. Used during shutdown to prevent stale audio from playing.

Definition at line 447 of file lib/audio/audio.c.

                                                      {
  if (!rb)
    return;
 
  mutex_lock(&rb->mutex);
  // Reset buffer to empty state (no audio to play = silence at shutdown)
  rb->write_index = 0;
  rb->read_index = 0;
  rb->last_sample = 0.0f;
  // Clear the actual data to zeros to prevent any stale audio
  SAFE_MEMSET(rb->data, sizeof(rb->data), 0, sizeof(rb->data));
  mutex_unlock(&rb->mutex);
}

References audio_ring_buffer::data, audio_ring_buffer::last_sample, audio_ring_buffer::mutex, mutex_lock, mutex_unlock, audio_ring_buffer::read_index, SAFE_MEMSET, and audio_ring_buffer::write_index.

Referenced by audio_stop_duplex().

audio_ring_buffer_create()

audio_ring_buffer_t * audio_ring_buffer_create

(

void

)

#include <audio.h>

Create a new audio ring buffer (for playback with jitter buffering)

Returns

Pointer to newly created audio ring buffer, or NULL on failure

Creates a new audio ring buffer for storing audio samples. The buffer has a fixed size defined by AUDIO_RING_BUFFER_SIZE and is optimized for real-time audio streaming with jitter buffering support (enabled by default).

Note

The ring buffer is thread-safe and can be used concurrently by capture and playback threads.

Ring buffer includes jitter buffer threshold for network latency compensation.

Use audio_ring_buffer_create_for_capture() for capture buffers.

Warning

Must call audio_ring_buffer_destroy() to free resources.

Definition at line 431 of file lib/audio/audio.c.

                                                    {
  return audio_ring_buffer_create_internal(true); // Default: enable jitter buffering for playback
}

Referenced by audio_init().

audio_ring_buffer_create_for_capture()

audio_ring_buffer_t * audio_ring_buffer_create_for_capture

(

void

)

#include <audio.h>

Create a new audio ring buffer for capture (without jitter buffering)

Returns

Pointer to newly created audio ring buffer, or NULL on failure

Creates an audio ring buffer optimized for direct microphone input from PortAudio. Unlike playback buffers, capture buffers disable jitter buffering since PortAudio writes directly from the microphone with no network latency.

Note

The ring buffer is thread-safe and can be used concurrently by capture and playback threads.

Jitter buffering is disabled for capture buffers.

Warning

Must call audio_ring_buffer_destroy() to free resources.

Definition at line 435 of file lib/audio/audio.c.

                                                                {
  return audio_ring_buffer_create_internal(false); // Disable jitter buffering for capture
}

Referenced by audio_init(), and audio_start_duplex().

audio_ring_buffer_destroy()

void audio_ring_buffer_destroy

(

audio_ring_buffer_t *

rb

)

#include <audio.h>

Destroy an audio ring buffer.

Parameters

rb	Audio ring buffer to destroy (can be NULL)

Destroys an audio ring buffer and frees all associated resources. Safe to call multiple times or with NULL pointer.

Note

All samples in the buffer are discarded.

Definition at line 439 of file lib/audio/audio.c.

                                                        {
  if (!rb)
    return;
 
  mutex_destroy(&rb->mutex);
  buffer_pool_free(NULL, rb, sizeof(audio_ring_buffer_t));
}

References buffer_pool_free(), audio_ring_buffer::mutex, and mutex_destroy().

Referenced by audio_destroy(), audio_init(), audio_start_duplex(), audio_stop_duplex(), and cleanup_client_media_buffers().

audio_ring_buffer_peek()

size_t audio_ring_buffer_peek	(	audio_ring_buffer_t *	rb,
		float *	data,
		size_t	samples
	)

#include <audio.h>

Peek at available samples without consuming them (for AEC3 render signal)

This function reads samples from the jitter buffer WITHOUT advancing the read_index. Used to feed audio to AEC3 for echo cancellation even during jitter buffer fill period.

Parameters

rb	Ring buffer to peek from
data	Output buffer for samples
samples	Number of samples to peek

Returns

Number of samples actually peeked (may be less than requested)

Definition at line 710 of file lib/audio/audio.c.

                                                                                    {
  if (!rb || !data || samples <= 0) {
    return 0;
  }
 
  // LOCK-FREE: Load indices with proper memory ordering
  unsigned int write_idx = atomic_load_explicit(&rb->write_index, memory_order_acquire);
  unsigned int read_idx = atomic_load_explicit(&rb->read_index, memory_order_relaxed);
 
  // Calculate available samples
  size_t available;
  if (write_idx >= read_idx) {
    available = write_idx - read_idx;
  } else {
    available = AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
  }
 
  size_t to_peek = (samples > available) ? available : samples;
 
  if (to_peek == 0) {
    return 0;
  }
 
  // Copy samples in chunks (handle wraparound)
  size_t first_chunk = (read_idx + to_peek <= AUDIO_RING_BUFFER_SIZE) ? to_peek : (AUDIO_RING_BUFFER_SIZE - read_idx);
 
  SAFE_MEMCPY(data, first_chunk * sizeof(float), rb->data + read_idx, first_chunk * sizeof(float));
 
  if (first_chunk < to_peek) {
    // Wraparound: copy second chunk from beginning of buffer
    size_t second_chunk = to_peek - first_chunk;
    SAFE_MEMCPY(data + first_chunk, second_chunk * sizeof(float), rb->data, second_chunk * sizeof(float));
  }
 
  return to_peek;
}

References AUDIO_RING_BUFFER_SIZE, audio_ring_buffer::data, audio_ring_buffer::read_index, SAFE_MEMCPY, and audio_ring_buffer::write_index.

audio_ring_buffer_read()

size_t audio_ring_buffer_read	(	audio_ring_buffer_t *	rb,
		float *	data,
		size_t	samples
	)

#include <audio.h>

Read audio samples from ring buffer.

Parameters

rb	Audio ring buffer (must not be NULL)
data	Output buffer for audio samples (must not be NULL)
samples	Maximum number of samples to read

Returns

Number of samples actually read (may be less than requested)

Reads audio samples from the ring buffer. Samples are in floating point format (-1.0 to 1.0 range). This function is non-blocking and returns whatever samples are available up to the requested count.

Note

Actual number of samples read may be less than samples if buffer doesn't contain enough samples.

Samples are removed from the buffer after reading.

Thread-safe: Can be called from multiple threads simultaneously.

Warning

Data buffer must be large enough to hold samples float values.

Definition at line 549 of file lib/audio/audio.c.

                                                                                    {
  if (!rb || !data || samples <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb=%p, data=%p, samples=%d", rb, data, samples);
    return 0; // Return 0 samples read on error
  }
 
  // LOCK-FREE: Load indices with proper memory ordering
  // - Load writer's write_index with acquire (see writer's data updates)
  // - Load our own read_index with relaxed (no sync needed with ourselves)
  unsigned int write_idx = atomic_load_explicit(&rb->write_index, memory_order_acquire);
  unsigned int read_idx = atomic_load_explicit(&rb->read_index, memory_order_relaxed);
 
  // Calculate available samples
  size_t available;
  if (write_idx >= read_idx) {
    available = write_idx - read_idx;
  } else {
    available = AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
  }
 
  // LOCK-FREE: Load jitter buffer state with acquire ordering
  bool jitter_filled = atomic_load_explicit(&rb->jitter_buffer_filled, memory_order_acquire);
  int crossfade_remaining = atomic_load_explicit(&rb->crossfade_samples_remaining, memory_order_acquire);
  bool fade_in = atomic_load_explicit(&rb->crossfade_fade_in, memory_order_acquire);
 
  // Jitter buffer: don't read until initial fill threshold is reached
  // (only for playback buffers - capture buffers have jitter_buffer_enabled = false)
  if (!jitter_filled && rb->jitter_buffer_enabled) {
    // First, check if we're in the middle of a fade-out that needs to continue
    // This happens when fade-out spans multiple buffer reads
    if (!fade_in && crossfade_remaining > 0) {
      // Continue fade-out from where we left off
      int fade_start = AUDIO_CROSSFADE_SAMPLES - crossfade_remaining;
      size_t fade_samples = (samples < (size_t)crossfade_remaining) ? samples : (size_t)crossfade_remaining;
      float last = rb->last_sample; // NOT atomic - only written by reader
      for (size_t i = 0; i < fade_samples; i++) {
        float fade_factor = 1.0f - ((float)(fade_start + (int)i) / (float)AUDIO_CROSSFADE_SAMPLES);
        data[i] = last * fade_factor;
      }
      // Fill rest with silence
      for (size_t i = fade_samples; i < samples; i++) {
        data[i] = 0.0f;
      }
      // Update crossfade state atomically
      atomic_store_explicit(&rb->crossfade_samples_remaining, crossfade_remaining - (int)fade_samples,
                            memory_order_release);
      if (crossfade_remaining - (int)fade_samples <= 0) {
        rb->last_sample = 0.0f;
      }
 
      return samples; // Return full buffer (with continued fade-out)
    }
 
    // Check if we've accumulated enough samples to start playback
    if (available >= AUDIO_JITTER_BUFFER_THRESHOLD) {
      atomic_store_explicit(&rb->jitter_buffer_filled, true, memory_order_release);
      atomic_store_explicit(&rb->crossfade_samples_remaining, AUDIO_CROSSFADE_SAMPLES, memory_order_release);
      atomic_store_explicit(&rb->crossfade_fade_in, true, memory_order_release);
      log_info("Jitter buffer filled (%zu samples), starting playback with fade-in", available);
      // Reload state for processing below
      jitter_filled = true;
      crossfade_remaining = AUDIO_CROSSFADE_SAMPLES;
      fade_in = true;
    } else {
      // Log buffer fill progress every second
      log_debug_every(1000000, "Jitter buffer filling: %zu/%d samples (%.1f%%)", available,
                      AUDIO_JITTER_BUFFER_THRESHOLD, (100.0f * available) / AUDIO_JITTER_BUFFER_THRESHOLD);
      return 0; // Return silence until buffer is filled
    }
  }
 
  // Periodic buffer health logging (every 5 seconds when healthy)
  static unsigned int health_log_counter = 0;
  if (++health_log_counter % 250 == 0) { // ~5 seconds at 50Hz callback rate
    unsigned int underruns = atomic_load_explicit(&rb->underrun_count, memory_order_relaxed);
    log_debug("Buffer health: %zu/%d samples (%.1f%%), underruns=%u", available, AUDIO_RING_BUFFER_SIZE,
              (100.0f * available) / AUDIO_RING_BUFFER_SIZE, underruns);
  }
 
  // Low buffer handling: DON'T pause playback - continue reading what's available
  // and fill the rest with silence. Pausing causes a feedback loop where:
  // 1. Underrun -> pause reading -> buffer overflows from incoming samples
  // 2. Threshold reached -> resume reading -> drains too fast -> underrun again
  //
  // Instead: always consume samples to prevent overflow, use silence for missing data
  if (rb->jitter_buffer_enabled && available < AUDIO_JITTER_LOW_WATER_MARK) {
    unsigned int underrun_count = atomic_fetch_add_explicit(&rb->underrun_count, 1, memory_order_relaxed) + 1;
    log_warn_every(LOG_RATE_FAST,
                   "Audio buffer low #%u: only %zu samples available (low water mark: %d), padding with silence",
                   underrun_count, available, AUDIO_JITTER_LOW_WATER_MARK);
    // Don't set jitter_buffer_filled = false - keep reading to prevent overflow
  }
 
  size_t to_read = (samples > available) ? available : samples;
 
  // Optimize: copy in chunks instead of one sample at a time
  size_t remaining = AUDIO_RING_BUFFER_SIZE - read_idx;
 
  if (to_read <= remaining) {
    // Can copy in one chunk
    SAFE_MEMCPY(data, to_read * sizeof(float), &rb->data[read_idx], to_read * sizeof(float));
  } else {
    // Need to wrap around - copy in two chunks
    SAFE_MEMCPY(data, remaining * sizeof(float), &rb->data[read_idx], remaining * sizeof(float));
    SAFE_MEMCPY(&data[remaining], (to_read - remaining) * sizeof(float), &rb->data[0],
                (to_read - remaining) * sizeof(float));
  }
 
  // LOCK-FREE: Store new read_index with release ordering
  // This ensures all data reads above complete before the index update
  unsigned int new_read_idx = (read_idx + (unsigned int)to_read) % AUDIO_RING_BUFFER_SIZE;
  atomic_store_explicit(&rb->read_index, new_read_idx, memory_order_release);
 
  // Apply fade-in if recovering from underrun
  if (fade_in && crossfade_remaining > 0) {
    int fade_start = AUDIO_CROSSFADE_SAMPLES - crossfade_remaining;
    size_t fade_samples = (to_read < (size_t)crossfade_remaining) ? to_read : (size_t)crossfade_remaining;
 
    for (size_t i = 0; i < fade_samples; i++) {
      float fade_factor = (float)(fade_start + (int)i + 1) / (float)AUDIO_CROSSFADE_SAMPLES;
      data[i] *= fade_factor;
    }
 
    int new_crossfade_remaining = crossfade_remaining - (int)fade_samples;
    atomic_store_explicit(&rb->crossfade_samples_remaining, new_crossfade_remaining, memory_order_release);
    if (new_crossfade_remaining <= 0) {
      atomic_store_explicit(&rb->crossfade_fade_in, false, memory_order_release);
      log_debug("Audio fade-in complete");
    }
  }
 
  // Save last sample for potential fade-out
  // Note: only update if we actually read some data
  // This is NOT atomic - only the reader thread writes this
  if (to_read > 0) {
    rb->last_sample = data[to_read - 1];
  }
 
  // Fill any remaining samples with pure silence if we couldn't read enough
  // NOTE: Previous code applied fade-out from last sample, but this created
  // audible "little extra sounds in the gaps" during frequent underruns.
  // Pure silence is less disruptive than artificial fade artifacts.
  if (to_read < samples) {
    size_t silence_samples = samples - to_read;
    SAFE_MEMSET(data + to_read, silence_samples * sizeof(float), 0, silence_samples * sizeof(float));
  }
 
  return samples; // Always return full buffer (with silence padding if needed)
}

References AUDIO_CROSSFADE_SAMPLES, AUDIO_JITTER_BUFFER_THRESHOLD, AUDIO_JITTER_LOW_WATER_MARK, AUDIO_RING_BUFFER_SIZE, audio_ring_buffer::crossfade_fade_in, audio_ring_buffer::crossfade_samples_remaining, audio_ring_buffer::data, ERROR_INVALID_PARAM, audio_ring_buffer::jitter_buffer_enabled, audio_ring_buffer::jitter_buffer_filled, audio_ring_buffer::last_sample, log_debug, log_debug_every, log_info, LOG_RATE_FAST, log_warn_every, audio_ring_buffer::read_index, SAFE_MEMCPY, SAFE_MEMSET, SET_ERRNO, audio_ring_buffer::underrun_count, and audio_ring_buffer::write_index.

Referenced by audio_read_samples(), client_audio_render_thread(), mixer_process(), and mixer_process_excluding_source().

audio_ring_buffer_write()

asciichat_error_t audio_ring_buffer_write	(	audio_ring_buffer_t *	rb,
		const float *	data,
		int	samples
	)

#include <audio.h>

Write audio samples to ring buffer.

Parameters

rb	Audio ring buffer (must not be NULL)
data	Audio samples to write (must not be NULL)
samples	Number of samples to write

Returns

ASCIICHAT_OK on success, error code on failure

Writes audio samples to the ring buffer. Samples should be in floating point format (-1.0 to 1.0 range). This function is non-blocking and writes as many samples as buffer space allows.

Note

Actual number of samples written may be less than requested if buffer is full or nearly full.

Thread-safe: Can be called from multiple threads simultaneously.

Warning

Data must contain at least samples float values.

Definition at line 461 of file lib/audio/audio.c.

                                                                                                   {
  if (!rb || !data || samples <= 0)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb=%p, data=%p, samples=%d", rb, data, samples);
 
  // Validate samples doesn't exceed our buffer size
  if (samples > AUDIO_RING_BUFFER_SIZE) {
    return SET_ERRNO(ERROR_BUFFER, "Attempted to write %d samples, but buffer size is only %d", samples,
                     AUDIO_RING_BUFFER_SIZE);
  }
 
  // LOCK-FREE: Load indices with proper memory ordering
  // - Load our own write_index with relaxed (no sync needed with ourselves)
  // - Load reader's read_index with acquire (see reader's updates to free space)
  unsigned int write_idx = atomic_load_explicit(&rb->write_index, memory_order_relaxed);
  unsigned int read_idx = atomic_load_explicit(&rb->read_index, memory_order_acquire);
 
  // Calculate current buffer level (how many samples are buffered)
  int buffer_level;
  if (write_idx >= read_idx) {
    buffer_level = (int)(write_idx - read_idx);
  } else {
    buffer_level = AUDIO_RING_BUFFER_SIZE - (int)(read_idx - write_idx);
  }
  int available = AUDIO_RING_BUFFER_SIZE - buffer_level;
 
  // HIGH WATER MARK: Drop OLD samples to prevent latency accumulation
  // This is critical for real-time audio - we always want the NEWEST data
  // ALWAYS apply high-water-mark on write, regardless of jitter_buffer_enabled
  // jitter_buffer_enabled only controls READ side (whether to wait for threshold)
  // On WRITE side, we ALWAYS want to drop old samples to bound latency
  if (buffer_level + samples > AUDIO_JITTER_HIGH_WATER_MARK) {
    // Calculate how many old samples to drop to bring buffer to target level
    int excess = (buffer_level + samples) - AUDIO_JITTER_TARGET_LEVEL;
    if (excess > 0) {
      // Advance read_index to drop old samples
      // Note: This is safe because the reader checks for underrun and handles it gracefully
      unsigned int new_read_idx = (read_idx + (unsigned int)excess) % AUDIO_RING_BUFFER_SIZE;
      atomic_store_explicit(&rb->read_index, new_read_idx, memory_order_release);
 
      log_warn_every(LOG_RATE_FAST,
                     "Audio buffer high water mark exceeded: dropping %d OLD samples to reduce latency "
                     "(buffer was %d, target %d)",
                     excess, buffer_level, AUDIO_JITTER_TARGET_LEVEL);
 
      // Recalculate available space after dropping old samples
      read_idx = new_read_idx;
      buffer_level = AUDIO_JITTER_TARGET_LEVEL - samples;
      if (buffer_level < 0)
        buffer_level = 0;
      available = AUDIO_RING_BUFFER_SIZE - buffer_level;
    }
  }
 
  // Now write the new samples - should always have enough space after above
  int samples_to_write = samples;
  if (samples > available) {
    // This should rarely happen after the high water mark logic above
    int samples_dropped = samples - available;
    samples_to_write = available;
    log_warn_every(LOG_RATE_FAST, "Audio buffer overflow: dropping %d of %d incoming samples (buffer_used=%d/%d)",
                   samples_dropped, samples, AUDIO_RING_BUFFER_SIZE - available, AUDIO_RING_BUFFER_SIZE);
  }
 
  // Write only the samples that fit (preserves existing data integrity)
  if (samples_to_write > 0) {
    int remaining = AUDIO_RING_BUFFER_SIZE - (int)write_idx;
 
    if (samples_to_write <= remaining) {
      // Can copy in one chunk
      SAFE_MEMCPY(&rb->data[write_idx], samples_to_write * sizeof(float), data, samples_to_write * sizeof(float));
    } else {
      // Need to wrap around - copy in two chunks
      SAFE_MEMCPY(&rb->data[write_idx], remaining * sizeof(float), data, remaining * sizeof(float));
      SAFE_MEMCPY(&rb->data[0], (samples_to_write - remaining) * sizeof(float), &data[remaining],
                  (samples_to_write - remaining) * sizeof(float));
    }
 
    // LOCK-FREE: Store new write_index with release ordering
    // This ensures all data writes above are visible before the index update
    unsigned int new_write_idx = (write_idx + (unsigned int)samples_to_write) % AUDIO_RING_BUFFER_SIZE;
    atomic_store_explicit(&rb->write_index, new_write_idx, memory_order_release);
  }
 
  // Note: jitter buffer fill check is now done in read function for better control
 
  return ASCIICHAT_OK; // Success
}

References ASCIICHAT_OK, AUDIO_JITTER_HIGH_WATER_MARK, AUDIO_JITTER_TARGET_LEVEL, AUDIO_RING_BUFFER_SIZE, audio_ring_buffer::data, ERROR_BUFFER, ERROR_INVALID_PARAM, LOG_RATE_FAST, log_warn_every, audio_ring_buffer::read_index, SAFE_MEMCPY, SET_ERRNO, and audio_ring_buffer::write_index.

Referenced by audio_write_samples(), handle_audio_batch_packet(), handle_audio_opus_batch_packet(), handle_audio_opus_packet(), and handle_audio_packet().

audio_set_pipeline()

void audio_set_pipeline	(	audio_context_t *	ctx,
		void *	pipeline
	)

#include <audio.h>

Set audio pipeline for echo cancellation.

Parameters

ctx	Audio context (must not be NULL)
pipeline	Client audio pipeline pointer (opaque, can be NULL)

Associates an audio pipeline with the context for echo cancellation. The pipeline is fed playback samples from the output callback, allowing AEC3 to properly synchronize render and capture signals.

Note

Safe to call at any time, including before/after audio streams are started.

Pass NULL to disable pipeline integration.

Definition at line 927 of file lib/audio/audio.c.

                                                              {
  if (!ctx)
    return;
  ctx->audio_pipeline = pipeline;
}

References audio_context_t::audio_pipeline.

Referenced by audio_cleanup(), and audio_client_init().

audio_set_realtime_priority()

asciichat_error_t audio_set_realtime_priority

(

void

)

#include <audio.h>

Request real-time priority for current thread.

Returns

ASCIICHAT_OK on success, error code on failure

Requests real-time priority scheduling for the current thread. This reduces audio latency and glitches by ensuring audio threads get scheduled promptly. Platform-specific implementation (SCHED_FIFO on Linux, thread priority on Windows/macOS).

Note

This function should be called from audio capture/playback threads.

On some platforms, real-time priority requires appropriate permissions.

If real-time priority cannot be obtained, the function may succeed but use a lower priority level.

Warning

Real-time priority can cause system instability if misused. Only use in audio threads that process data quickly.

LIMITATION: This function only affects the calling thread. When used with PortAudio, the audio callbacks run in PortAudio's internal threads, not the thread that calls audio_start_duplex. Some PortAudio backends (WASAPI, CoreAudio) automatically use real-time priority for their callback threads. For other backends, this function has limited effect when called from the main thread.

Definition at line 1375 of file lib/audio/audio.c.

                                                    {
  // Delegate to platform abstraction layer
  asciichat_error_t result = asciichat_thread_set_realtime_priority();
  if (result == ASCIICHAT_OK) {
    log_info("✓ Audio thread real-time priority set successfully");
  }
  return result;
}

References ASCIICHAT_OK, asciichat_thread_set_realtime_priority(), and log_info.

Referenced by audio_start_duplex().

audio_start_duplex()

asciichat_error_t audio_start_duplex

(

audio_context_t *

ctx

)

#include <audio.h>

Start full-duplex audio (simultaneous capture and playback)

Parameters

ctx	Audio context (must not be NULL, must be initialized)

Returns

ASCIICHAT_OK on success, error code on failure

Opens a single PortAudio stream that handles BOTH input (microphone) and output (speakers) simultaneously. This is CRITICAL for proper AEC3 echo cancellation because:

• Single callback receives both render and capture samples at the EXACT same instant
• No timing mismatch between input/output callbacks
• No ring buffer delay for AEC3 reference signal
• Perfect synchronization for echo cancellation

The duplex callback:

1. Reads from playback_buffer → outputs to speakers
2. Processes capture through AEC3 (using render as reference)
3. Writes processed capture to capture_buffer for encoder thread

Note

Real-time priority is automatically requested for callback thread.

If already running, this function has no effect.

Warning

Both input and output devices must be available.

Definition at line 933 of file lib/audio/audio.c.

                                                           {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
  }
 
  mutex_lock(&ctx->state_mutex);
 
  // Already running?
  if (ctx->duplex_stream || ctx->input_stream || ctx->output_stream) {
    mutex_unlock(&ctx->state_mutex);
    return ASCIICHAT_OK;
  }
 
  // Setup input parameters
  PaStreamParameters inputParams;
  if (GET_OPTION(microphone_index) >= 0) {
    inputParams.device = GET_OPTION(microphone_index);
  } else {
    inputParams.device = Pa_GetDefaultInputDevice();
  }
 
  if (inputParams.device == paNoDevice) {
    mutex_unlock(&ctx->state_mutex);
    return SET_ERRNO(ERROR_AUDIO, "No input device available");
  }
 
  const PaDeviceInfo *inputInfo = Pa_GetDeviceInfo(inputParams.device);
  if (!inputInfo) {
    mutex_unlock(&ctx->state_mutex);
    return SET_ERRNO(ERROR_AUDIO, "Input device info not found");
  }
 
  inputParams.channelCount = AUDIO_CHANNELS;
  inputParams.sampleFormat = paFloat32;
  inputParams.suggestedLatency = inputInfo->defaultLowInputLatency;
  inputParams.hostApiSpecificStreamInfo = NULL;
 
  // Setup output parameters
  PaStreamParameters outputParams;
  if (GET_OPTION(speakers_index) >= 0) {
    outputParams.device = GET_OPTION(speakers_index);
  } else {
    outputParams.device = Pa_GetDefaultOutputDevice();
  }
 
  if (outputParams.device == paNoDevice) {
    mutex_unlock(&ctx->state_mutex);
    return SET_ERRNO(ERROR_AUDIO, "No output device available");
  }
 
  const PaDeviceInfo *outputInfo = Pa_GetDeviceInfo(outputParams.device);
  if (!outputInfo) {
    mutex_unlock(&ctx->state_mutex);
    return SET_ERRNO(ERROR_AUDIO, "Output device info not found");
  }
 
  outputParams.channelCount = AUDIO_CHANNELS;
  outputParams.sampleFormat = paFloat32;
  outputParams.suggestedLatency = outputInfo->defaultLowOutputLatency;
  outputParams.hostApiSpecificStreamInfo = NULL;
 
  // Store device rates for diagnostics
  ctx->input_device_rate = inputInfo->defaultSampleRate;
  ctx->output_device_rate = outputInfo->defaultSampleRate;
 
  log_info("Opening audio:");
  log_info("  Input:  %s (%.0f Hz)", inputInfo->name, inputInfo->defaultSampleRate);
  log_info("  Output: %s (%.0f Hz)", outputInfo->name, outputInfo->defaultSampleRate);
 
  // Check if sample rates differ - ALSA full-duplex doesn't handle this well
  bool rates_differ = (inputInfo->defaultSampleRate != outputInfo->defaultSampleRate);
  bool try_separate = rates_differ;
  PaError err = paNoError;
 
  if (!try_separate) {
    // Try full-duplex first (preferred - perfect AEC3 timing)
    err = Pa_OpenStream(&ctx->duplex_stream, &inputParams, &outputParams, AUDIO_SAMPLE_RATE, AUDIO_FRAMES_PER_BUFFER,
                        paClipOff, duplex_callback, ctx);
 
    if (err == paNoError) {
      err = Pa_StartStream(ctx->duplex_stream);
      if (err != paNoError) {
        Pa_CloseStream(ctx->duplex_stream);
        ctx->duplex_stream = NULL;
        log_warn("Full-duplex stream failed to start: %s", Pa_GetErrorText(err));
        try_separate = true;
      }
    } else {
      log_warn("Full-duplex stream failed to open: %s", Pa_GetErrorText(err));
      try_separate = true;
    }
  }
 
  if (try_separate) {
    // Fall back to separate streams (needed when sample rates differ)
    log_info("Using separate input/output streams (sample rates differ: %.0f vs %.0f Hz)", inputInfo->defaultSampleRate,
             outputInfo->defaultSampleRate);
    log_info("  Will resample: buffer at %.0f Hz → output at %.0f Hz", (double)AUDIO_SAMPLE_RATE,
             outputInfo->defaultSampleRate);
 
    // Store the internal sample rate (buffer rate)
    ctx->sample_rate = AUDIO_SAMPLE_RATE;
 
    // Create render buffer for AEC3 reference synchronization
    ctx->render_buffer = audio_ring_buffer_create_for_capture();
    if (!ctx->render_buffer) {
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_MEMORY, "Failed to create render buffer");
    }
 
    // Open output stream at NATIVE device rate - we'll resample from 48kHz buffer in callback
    err = Pa_OpenStream(&ctx->output_stream, NULL, &outputParams, outputInfo->defaultSampleRate,
                        AUDIO_FRAMES_PER_BUFFER, paClipOff, output_callback, ctx);
    if (err != paNoError) {
      audio_ring_buffer_destroy(ctx->render_buffer);
      ctx->render_buffer = NULL;
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_AUDIO, "Failed to open output stream: %s", Pa_GetErrorText(err));
    }
 
    // Open input stream at PIPELINE rate (48kHz) - let PortAudio resample from device if needed
    // This ensures input matches sample_rate for AEC3, avoiding resampling in our callback
    err = Pa_OpenStream(&ctx->input_stream, &inputParams, NULL, AUDIO_SAMPLE_RATE, AUDIO_FRAMES_PER_BUFFER, paClipOff,
                        input_callback, ctx);
    if (err != paNoError) {
      Pa_CloseStream(ctx->output_stream);
      ctx->output_stream = NULL;
      audio_ring_buffer_destroy(ctx->render_buffer);
      ctx->render_buffer = NULL;
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_AUDIO, "Failed to open input stream: %s", Pa_GetErrorText(err));
    }
 
    // Start both streams
    err = Pa_StartStream(ctx->output_stream);
    if (err != paNoError) {
      Pa_CloseStream(ctx->input_stream);
      Pa_CloseStream(ctx->output_stream);
      ctx->input_stream = NULL;
      ctx->output_stream = NULL;
      audio_ring_buffer_destroy(ctx->render_buffer);
      ctx->render_buffer = NULL;
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_AUDIO, "Failed to start output stream: %s", Pa_GetErrorText(err));
    }
 
    err = Pa_StartStream(ctx->input_stream);
    if (err != paNoError) {
      Pa_StopStream(ctx->output_stream);
      Pa_CloseStream(ctx->input_stream);
      Pa_CloseStream(ctx->output_stream);
      ctx->input_stream = NULL;
      ctx->output_stream = NULL;
      audio_ring_buffer_destroy(ctx->render_buffer);
      ctx->render_buffer = NULL;
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_AUDIO, "Failed to start input stream: %s", Pa_GetErrorText(err));
    }
 
    ctx->separate_streams = true;
    log_info("Separate streams started successfully");
  } else {
    ctx->separate_streams = false;
    log_info("Full-duplex stream started (single callback, perfect AEC3 timing)");
  }
 
  audio_set_realtime_priority();
 
  ctx->running = true;
  ctx->sample_rate = AUDIO_SAMPLE_RATE;
  mutex_unlock(&ctx->state_mutex);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, AUDIO_CHANNELS, AUDIO_FRAMES_PER_BUFFER, audio_ring_buffer_create_for_capture(), audio_ring_buffer_destroy(), AUDIO_SAMPLE_RATE, audio_set_realtime_priority(), audio_context_t::duplex_stream, ERROR_AUDIO, ERROR_INVALID_STATE, ERROR_MEMORY, GET_OPTION, audio_context_t::initialized, audio_context_t::input_device_rate, audio_context_t::input_stream, log_info, log_warn, mutex_lock, mutex_unlock, audio_context_t::output_device_rate, audio_context_t::output_stream, audio_context_t::render_buffer, audio_context_t::running, audio_context_t::sample_rate, audio_context_t::separate_streams, SET_ERRNO, and audio_context_t::state_mutex.

Referenced by audio_client_init().

audio_stop_duplex()

asciichat_error_t audio_stop_duplex

(

audio_context_t *

ctx

)

#include <audio.h>

Stop full-duplex audio.

Parameters

ctx	Audio context (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Stops the full-duplex audio stream and closes the stream.

Note

If not running, this function has no effect.

Buffers are not cleared by this function.

Definition at line 1108 of file lib/audio/audio.c.

                                                          {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
  }
 
  atomic_store(&ctx->shutting_down, true);
 
  if (ctx->playback_buffer) {
    audio_ring_buffer_clear(ctx->playback_buffer);
  }
 
  Pa_Sleep(50); // Let callbacks drain
 
  mutex_lock(&ctx->state_mutex);
 
  if (ctx->duplex_stream) {
    Pa_StopStream(ctx->duplex_stream);
    Pa_CloseStream(ctx->duplex_stream);
    ctx->duplex_stream = NULL;
  }
 
  // Stop separate streams if used
  if (ctx->input_stream) {
    Pa_StopStream(ctx->input_stream);
    Pa_CloseStream(ctx->input_stream);
    ctx->input_stream = NULL;
  }
 
  if (ctx->output_stream) {
    Pa_StopStream(ctx->output_stream);
    Pa_CloseStream(ctx->output_stream);
    ctx->output_stream = NULL;
  }
 
  // Cleanup render buffer
  if (ctx->render_buffer) {
    audio_ring_buffer_destroy(ctx->render_buffer);
    ctx->render_buffer = NULL;
  }
 
  ctx->running = false;
  ctx->separate_streams = false;
  mutex_unlock(&ctx->state_mutex);
 
  log_info("Audio stopped");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, audio_ring_buffer_clear(), audio_ring_buffer_destroy(), audio_context_t::duplex_stream, ERROR_INVALID_STATE, audio_context_t::initialized, audio_context_t::input_stream, log_info, mutex_lock, mutex_unlock, audio_context_t::output_stream, audio_context_t::playback_buffer, audio_context_t::render_buffer, audio_context_t::running, audio_context_t::separate_streams, SET_ERRNO, audio_context_t::shutting_down, and audio_context_t::state_mutex.

Referenced by audio_cleanup(), and audio_destroy().

audio_validate_batch_params()

asciichat_error_t audio_validate_batch_params

(

const audio_batch_info_t *

batch

)

#include <audio.h>

Validate audio batch parameters for sanity.

Checks that parsed batch parameters are within acceptable ranges. Performs these checks:

• batch_count > 0 and <= MAX_BATCH_SIZE
• sample_rate is a standard rate (8000, 16000, 24000, 48000, etc.)
• channels is 1 (mono) or 2 (stereo)
• total_samples is consistent with batch_count

Parameters

batch

Pointer to audio_batch_info_t struct to validate

Returns

ASCIICHAT_OK if batch parameters are valid

ERROR_INVALID_PARAM if any parameter is out of range

Usage:

audio_batch_info_t batch;
audio_parse_batch_header(data, len, &batch);
 
if (audio_validate_batch_params(&batch) != ASCIICHAT_OK) {
    log_error("Audio batch parameters invalid");
    return;
}

Definition at line 1414 of file lib/audio/audio.c.

                                                                               {
  if (!batch) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch info pointer is NULL");
  }
 
  // Validate batch_count
  if (batch->batch_count == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch count cannot be zero");
  }
 
  // Check for reasonable max (256 frames per batch is very generous)
  if (batch->batch_count > 256) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch count too large (batch_count=%u, max=256)", batch->batch_count);
  }
 
  // Validate channels (1=mono, 2=stereo, max 8 for multi-channel)
  if (batch->channels == 0 || batch->channels > 8) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid channel count (channels=%u, valid=1-8)", batch->channels);
  }
 
  // Validate sample rate
  if (!audio_is_supported_sample_rate(batch->sample_rate)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Unsupported sample rate (sample_rate=%u)", batch->sample_rate);
  }
 
  // Check for reasonable sample counts
  if (batch->total_samples == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch has zero samples");
  }
 
  // Each batch typically has samples_per_frame worth of samples
  // For 48kHz at 20ms per frame: 48000 * 0.02 = 960 samples per frame
  // With max 256 frames, that's up to ~245k samples per batch
  if (batch->total_samples > 1000000) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch sample count suspiciously large (total_samples=%u)",
                     batch->total_samples);
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, audio_is_supported_sample_rate(), audio_batch_info_t::batch_count, audio_batch_info_t::channels, ERROR_INVALID_PARAM, audio_batch_info_t::sample_rate, SET_ERRNO, and audio_batch_info_t::total_samples.

audio_write_samples()

asciichat_error_t audio_write_samples	(	audio_context_t *	ctx,
		const float *	buffer,
		int	num_samples
	)

#include <audio.h>

Write audio samples to playback buffer.

Parameters

ctx	Audio context (must not be NULL)
buffer	Input buffer of audio samples (must not be NULL)
num_samples	Number of samples to write (must be > 0)

Returns

ASCIICHAT_OK on success, error code on failure

Writes audio samples to the playback ring buffer for playback. Samples should be in floating point format (-1.0 to 1.0 range). This function is non-blocking and writes as many samples as buffer space allows.

Note

Actual number of samples written may be less than num_samples if buffer doesn't have enough space.

Samples are queued for playback by the playback thread.

Thread-safe: Can be called from any thread.

Warning

Buffer must contain at least num_samples float values.

Definition at line 1167 of file lib/audio/audio.c.

                                                                                                  {
  if (!ctx || !ctx->initialized || !buffer || num_samples <= 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, buffer=%p, num_samples=%d", ctx, buffer,
                     num_samples);
  }
 
  // Don't accept new audio data during shutdown - this prevents garbage/beeps
  if (atomic_load(&ctx->shutting_down)) {
    return ASCIICHAT_OK; // Silently discard
  }
 
  asciichat_error_t result = audio_ring_buffer_write(ctx->playback_buffer, buffer, num_samples);
 
  return result;
}

References ASCIICHAT_OK, audio_ring_buffer_write(), ERROR_INVALID_PARAM, audio_context_t::initialized, audio_context_t::playback_buffer, SET_ERRNO, and audio_context_t::shutting_down.

Referenced by audio_process_received_samples().

buffer_float_to_int16()

void buffer_float_to_int16	(	const float *	src,
		int16_t *	dst,
		int	count
	)

#include <mixer.h>

Convert float buffer to int16 buffer.

Parameters

src	Source float buffer
dst	Destination int16 buffer
count	Number of samples to convert

Batch converts float samples to int16 format for WebRTC.

Definition at line 1067 of file mixer.c.

                                                                      {
  if (!src || !dst || count <= 0)
    return;
  for (int i = 0; i < count; i++) {
    dst[i] = float_to_int16(src[i]);
  }
}

References float_to_int16().

buffer_int16_to_float()

void buffer_int16_to_float	(	const int16_t *	src,
		float *	dst,
		int	count
	)

#include <mixer.h>

Convert int16 buffer to float buffer.

Parameters

src	Source int16 buffer
dst	Destination float buffer
count	Number of samples to convert

Batch converts int16 samples to float format.

Definition at line 1075 of file mixer.c.

                                                                      {
  if (!src || !dst || count <= 0)
    return;
  for (int i = 0; i < count; i++) {
    dst[i] = int16_to_float(src[i]);
  }
}

References int16_to_float().

buffer_peak()

float buffer_peak	(	const float *	buffer,
		int	count
	)

#include <mixer.h>

Find peak absolute value in buffer.

Parameters

buffer	Audio buffer
count	Number of samples

Returns

Maximum absolute sample value (0.0 to 1.0+)

Scans buffer for the sample with highest absolute value. Useful for level metering and gain staging.

Definition at line 1083 of file mixer.c.

                                                  {
  if (!buffer || count <= 0)
    return 0.0f;
 
  float peak = 0.0f;
  for (int i = 0; i < count; i++) {
    float abs_sample = fabsf(buffer[i]);
    if (abs_sample > peak)
      peak = abs_sample;
  }
  return peak;
}

clamp_float()

float clamp_float	(	float	value,
		float	min,
		float	max
	)

#include <mixer.h>

Clamp a float value to a range.

Parameters

value	Value to clamp
min	Minimum value
max	Maximum value

Returns

Clamped value (min <= result <= max)

Clamps a float value to the specified range. Useful for preventing audio overflow and ensuring parameters stay within valid ranges.

Definition at line 31 of file mixer.c.

                                                     {
  if (value < min) {
    return min;
  }
  if (value > max) {
    return max;
  }
  return value;
}

compressor_init()

void compressor_init	(	compressor_t *	comp,
		float	sample_rate
	)

#include <mixer.h>

Initialize a compressor.

Parameters

comp	Compressor structure
sample_rate	Sample rate in Hz

Initializes compressor state and converts time-based parameters (attack_ms, release_ms) to coefficients for sample-by-sample processing.

Definition at line 42 of file mixer.c.

                                                            {
  comp->sample_rate = sample_rate;
  comp->envelope = 0.0f;
  comp->gain_lin = 1.0f;
 
  // Set default parameters with +6dB makeup gain
  // The client playback path now has proper soft clipping to handle any peaks
  // Server ducking (-6dB) + crowd scaling (-3dB) needs compensation
  compressor_set_params(comp, -10.0f, 4.0f, 10.0f, 100.0f, 6.0f);
}

References compressor_set_params(), compressor_t::envelope, compressor_t::gain_lin, and compressor_t::sample_rate.

Referenced by client_audio_pipeline_create(), and mixer_create().

compressor_process_sample()

float compressor_process_sample	(	compressor_t *	comp,
		float	sidechain
	)

#include <mixer.h>

Process a single sample through compressor.

Parameters

comp	Compressor structure
sidechain	Input level for gain reduction calculation

Returns

Compressed output level

Processes sidechain input through compressor to calculate gain reduction. Returns compressed output level (not actual audio sample - use for sidechain).

Note

This calculates gain reduction, not actual audio compression. Apply the gain to audio samples separately.

Definition at line 87 of file mixer.c.

                                                                     {
  float x = fabsf(sidechain);
 
  // Update envelope with attack/release
  if (x > comp->envelope)
    comp->envelope = comp->attack_coeff * comp->envelope + (1.0f - comp->attack_coeff) * x;
  else
    comp->envelope = comp->release_coeff * comp->envelope + (1.0f - comp->release_coeff) * x;
 
  // Calculate gain reduction
  float level_dB = linear_to_db(comp->envelope);
  float gr_dB = compressor_gain_reduction_db(comp, level_dB);
  float target_lin = db_to_linear(gr_dB + comp->makeup_dB);
 
  // Smooth gain changes
  if (target_lin < comp->gain_lin)
    comp->gain_lin = comp->attack_coeff * comp->gain_lin + (1.0f - comp->attack_coeff) * target_lin;
  else
    comp->gain_lin = comp->release_coeff * comp->gain_lin + (1.0f - comp->release_coeff) * target_lin;
 
  return comp->gain_lin;
}

References compressor_t::attack_coeff, db_to_linear(), compressor_t::envelope, compressor_t::gain_lin, linear_to_db(), compressor_t::makeup_dB, and compressor_t::release_coeff.

Referenced by client_audio_pipeline_process_duplex(), mixer_process(), and mixer_process_excluding_source().

compressor_set_params()

void compressor_set_params	(	compressor_t *	comp,
		float	threshold_dB,
		float	ratio,
		float	attack_ms,
		float	release_ms,
		float	makeup_dB
	)

#include <mixer.h>

Set compressor parameters.

Parameters

comp	Compressor structure
threshold_dB	Compression threshold in dB
ratio	Compression ratio (e.g., 4.0 for 4:1)
attack_ms	Attack time in milliseconds
release_ms	Release time in milliseconds
makeup_dB	Makeup gain in dB

Updates compressor parameters. Time-based parameters are converted to coefficients internally.

Definition at line 53 of file mixer.c.

                                            {
  comp->threshold_dB = threshold_dB;
  comp->ratio = ratio;
  comp->attack_ms = attack_ms;
  comp->release_ms = release_ms;
  comp->makeup_dB = makeup_dB;
  comp->knee_dB = 2.0f; // Fixed soft knee
 
  // Calculate time constants
  float attack_tau = attack_ms / 1000.0f;
  float release_tau = release_ms / 1000.0f;
  comp->attack_coeff = expf(-1.0f / (attack_tau * comp->sample_rate + 1e-12f));
  comp->release_coeff = expf(-1.0f / (release_tau * comp->sample_rate + 1e-12f));
}

References compressor_t::attack_coeff, compressor_t::attack_ms, compressor_t::knee_dB, compressor_t::makeup_dB, compressor_t::ratio, compressor_t::release_coeff, compressor_t::release_ms, compressor_t::sample_rate, and compressor_t::threshold_dB.

Referenced by client_audio_pipeline_create(), and compressor_init().

copy_buffer_with_gain()

void copy_buffer_with_gain	(	const float *	src,
		float *	dst,
		int	count,
		float	gain
	)

#include <mixer.h>

Copy buffer with gain scaling.

Parameters

src	Source buffer
dst	Destination buffer
count	Number of samples
gain	Gain multiplier to apply during copy

Copies samples from src to dst while applying gain. Useful for format conversion (e.g., scale by 32768 for WebRTC).

Definition at line 1128 of file mixer.c.

                                                                                {
  if (!src || !dst || count <= 0)
    return;
 
  for (int i = 0; i < count; i++) {
    dst[i] = src[i] * gain;
  }
}

Referenced by client_audio_pipeline_process_duplex().

db_to_linear()

float db_to_linear

(

float

db

)

#include <mixer.h>

Convert decibels to linear gain.

Parameters

db	Decibel value

Returns

Linear gain multiplier (10^(db/20))

Converts decibel value to linear gain multiplier for audio processing.

Definition at line 23 of file mixer.c.

                             {
  return powf(10.0f, db / 20.0f);
}

Referenced by compressor_process_sample(), ducking_process_frame(), mixer_process(), and mixer_process_excluding_source().

ducking_free()

void ducking_free

(

ducking_t *

duck

)

#include <mixer.h>

Free ducking system resources.

Parameters

duck	Ducking structure

Frees per-source arrays allocated by ducking_init().

Definition at line 166 of file mixer.c.

                                   {
  if (duck->envelope) {
    SAFE_FREE(duck->envelope);
  }
  if (duck->gain) {
    SAFE_FREE(duck->gain);
  }
}

References ducking_t::envelope, ducking_t::gain, and SAFE_FREE.

Referenced by mixer_destroy().

ducking_init()

int ducking_init	(	ducking_t *	duck,
		int	num_sources,
		float	sample_rate
	)

#include <mixer.h>

Initialize ducking system.

Parameters

duck	Ducking structure
num_sources	Number of sources to support
sample_rate	Sample rate in Hz

Allocates per-source arrays (envelope, gain) for ducking system. Time-based parameters are converted to coefficients.

Warning

Must be paired with ducking_free() to prevent memory leaks.

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 111 of file mixer.c.

                                                                      {
  if (!duck) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "ducking_init: duck is NULL");
  }
 
  // Set default parameters
  // threshold_dB: sources below this aren't considered "speaking"
  // leader_margin_dB: sources within this margin of loudest are all "leaders"
  // atten_dB: how much to attenuate non-leaders (was -12dB, too aggressive)
  duck->threshold_dB = -45.0f;   // More lenient threshold
  duck->leader_margin_dB = 6.0f; // Wider margin = more sources treated as leaders
  duck->atten_dB = -6.0f;        // Only -6dB attenuation (was -12dB)
  duck->attack_ms = 10.0f;       // Slower attack (was 5ms)
  duck->release_ms = 200.0f;     // Slower release (was 100ms)
  duck->envelope = NULL;
  duck->gain = NULL;
 
  // Calculate time constants
  float attack_tau = duck->attack_ms / 1000.0f;
  float release_tau = duck->release_ms / 1000.0f;
  duck->attack_coeff = expf(-1.0f / (attack_tau * sample_rate + 1e-12f));
  duck->release_coeff = expf(-1.0f / (release_tau * sample_rate + 1e-12f));
 
  // Allocate arrays with overflow checking
  size_t envelope_size = 0;
  if (checked_size_mul((size_t)num_sources, sizeof(float), &envelope_size) != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Ducking envelope array size overflow: %d sources", num_sources);
  }
  duck->envelope = SAFE_MALLOC(envelope_size, float *);
  if (!duck->envelope) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate ducking envelope array");
  }
 
  size_t gain_size = 0;
  if (checked_size_mul((size_t)num_sources, sizeof(float), &gain_size) != ASCIICHAT_OK) {
    SAFE_FREE(duck->envelope);
    duck->envelope = NULL;
    return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Ducking gain array size overflow: %d sources", num_sources);
  }
  duck->gain = SAFE_MALLOC(gain_size, float *);
  if (!duck->gain) {
    SAFE_FREE(duck->envelope);
    duck->envelope = NULL;
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate ducking gain array");
  }
 
  // Initialize
  SAFE_MEMSET(duck->envelope, (size_t)num_sources * sizeof(float), 0, (size_t)num_sources * sizeof(float));
  for (int i = 0; i < num_sources; i++) {
    duck->gain[i] = 1.0f;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ducking_t::attack_coeff, ducking_t::attack_ms, ducking_t::atten_dB, ducking_t::envelope, ERROR_BUFFER_OVERFLOW, ERROR_INVALID_PARAM, ERROR_MEMORY, ducking_t::gain, ducking_t::leader_margin_dB, ducking_t::release_coeff, ducking_t::release_ms, SAFE_FREE, SAFE_MALLOC, SAFE_MEMSET, SET_ERRNO, and ducking_t::threshold_dB.

Referenced by mixer_create().

ducking_process_frame()

void ducking_process_frame	(	ducking_t *	duck,
		float *	envelopes,
		float *	gains,
		int	num_sources
	)

#include <mixer.h>

Process a frame of audio through ducking system.

Parameters

duck	Ducking structure
envelopes	Array of per-source envelope levels (input)
gains	Array of per-source ducking gains (output)
num_sources	Number of sources to process

Calculates ducking gains for each source based on envelope levels. Outputs per-source gain multipliers to apply to audio samples.

Note

Gains are calculated from envelope levels, identifying leaders and applying attenuation to non-leaders.

Definition at line 184 of file mixer.c.

                                                                                             {
  // Find the loudest source
  float max_dB = -120.0f;
  float env_dB[MIXER_MAX_SOURCES];
 
  for (int i = 0; i < num_sources; i++) {
    env_dB[i] = linear_to_db(envelopes[i]);
    if (env_dB[i] > max_dB)
      max_dB = env_dB[i];
  }
 
  // Calculate ducking gain for each source
  float leader_cut = db_to_linear(duck->atten_dB);
 
  for (int i = 0; i < num_sources; i++) {
    bool is_speaking = env_dB[i] > duck->threshold_dB;
    bool is_leader = is_speaking && (env_dB[i] >= max_dB - duck->leader_margin_dB);
 
    float target;
    if (is_speaking && !is_leader) {
      target = leader_cut;
    } else {
      target = 1.0f;
    }
 
    // Smooth gain transitions
    if (target < gains[i])
      gains[i] = duck->attack_coeff * gains[i] + (1.0f - duck->attack_coeff) * target;
    else
      gains[i] = duck->release_coeff * gains[i] + (1.0f - duck->release_coeff) * target;
  }
}

References ducking_t::attack_coeff, ducking_t::atten_dB, db_to_linear(), ducking_t::leader_margin_dB, linear_to_db(), MIXER_MAX_SOURCES, ducking_t::release_coeff, and ducking_t::threshold_dB.

Referenced by mixer_process(), and mixer_process_excluding_source().

ducking_set_params()

void ducking_set_params	(	ducking_t *	duck,
		float	threshold_dB,
		float	leader_margin_dB,
		float	atten_dB,
		float	attack_ms,
		float	release_ms
	)

#include <mixer.h>

Set ducking parameters.

Parameters

duck	Ducking structure
threshold_dB	Speaking threshold in dB
leader_margin_dB	Leader margin in dB
atten_dB	Attenuation in dB for non-leaders
attack_ms	Attack time in milliseconds
release_ms	Release time in milliseconds

Updates ducking parameters. Time-based parameters are converted to coefficients internally.

Definition at line 175 of file mixer.c.

                                          {
  duck->threshold_dB = threshold_dB;
  duck->leader_margin_dB = leader_margin_dB;
  duck->atten_dB = atten_dB;
  duck->attack_ms = attack_ms;
  duck->release_ms = release_ms;
}

References ducking_t::attack_ms, ducking_t::atten_dB, ducking_t::leader_margin_dB, ducking_t::release_ms, and ducking_t::threshold_dB.

fade_buffer()

void fade_buffer	(	float *	buffer,
		int	count,
		float	start_gain,
		float	end_gain
	)

#include <mixer.h>

Apply linear fade to buffer in-place.

Parameters

buffer	Audio buffer (modified in-place)
count	Number of samples
start_gain	Gain at start of buffer
end_gain	Gain at end of buffer

Applies linear interpolation from start_gain to end_gain across buffer. Use start_gain=0, end_gain=1 for fade-in; start_gain=1, end_gain=0 for fade-out.

Definition at line 1105 of file mixer.c.

                                                                             {
  if (!buffer || count <= 0)
    return;
 
  float step = (end_gain - start_gain) / (float)count;
  float gain = start_gain;
  for (int i = 0; i < count; i++) {
    buffer[i] *= gain;
    gain += step;
  }
}

fade_buffer_smooth()

void fade_buffer_smooth	(	float *	buffer,
		int	count,
		bool	fade_in
	)

#include <mixer.h>

Apply smoothstep fade to buffer in-place.

Parameters

buffer	Audio buffer (modified in-place)
count	Number of samples
fade_in	If true, fade from 0 to 1; if false, fade from 1 to 0

Applies smoothstep curve for more natural-sounding fades.

Definition at line 1117 of file mixer.c.

                                                                {
  if (!buffer || count <= 0)
    return;
 
  for (int i = 0; i < count; i++) {
    float t = (float)i / (float)(count - 1);
    float gain = smoothstep(fade_in ? t : (1.0f - t));
    buffer[i] *= gain;
  }
}

References smoothstep().

float_to_int16()

int16_t float_to_int16

(

float

sample

)

#include <mixer.h>

Convert float sample to int16 (WebRTC format)

Parameters

sample

Float sample in [-1.0, 1.0] range

Returns

Scaled int16 sample in [-32768, 32767] range

Scales float audio sample to 16-bit integer format used by WebRTC. Values outside [-1.0, 1.0] are clamped before scaling.

Definition at line 1054 of file mixer.c.

                                     {
  // Clamp to [-1, 1] then scale to int16 range
  if (sample > 1.0f)
    sample = 1.0f;
  if (sample < -1.0f)
    sample = -1.0f;
  return (int16_t)(sample * 32767.0f);
}

Referenced by buffer_float_to_int16().

highpass_filter_init()

void highpass_filter_init	(	highpass_filter_t *	filter,
		float	cutoff_hz,
		float	sample_rate
	)

#include <mixer.h>

Initialize a high-pass filter.

Parameters

filter	High-pass filter structure
cutoff_hz	Cutoff frequency in Hz
sample_rate	Sample rate in Hz

Initializes filter state and calculates filter coefficient alpha from cutoff frequency.

Definition at line 920 of file mixer.c.

                                                                                         {
  if (!filter)
    return;
 
  filter->cutoff_hz = cutoff_hz;
  filter->sample_rate = sample_rate;
 
  // Calculate filter coefficient
  // alpha = 1 / (1 + 2*pi*fc/fs)
  filter->alpha = 1.0f / (1.0f + 2.0f * M_PI * cutoff_hz / sample_rate);
 
  highpass_filter_reset(filter);
}

References highpass_filter_t::alpha, highpass_filter_t::cutoff_hz, highpass_filter_reset(), M_PI, and highpass_filter_t::sample_rate.

Referenced by client_audio_pipeline_create().

highpass_filter_process_buffer()

void highpass_filter_process_buffer	(	highpass_filter_t *	filter,
		float *	buffer,
		int	num_samples
	)

#include <mixer.h>

Process a buffer of samples through high-pass filter.

Parameters

filter	High-pass filter structure
buffer	Audio buffer (modified in-place)
num_samples	Number of samples to process

Processes entire buffer through high-pass filter. Buffer is modified in-place.

Definition at line 956 of file mixer.c.

                                                                                               {
  if (!filter || !buffer || num_samples <= 0)
    return;
 
  for (int i = 0; i < num_samples; i++) {
    buffer[i] = highpass_filter_process_sample(filter, buffer[i]);
  }
}

References highpass_filter_process_sample().

Referenced by client_audio_pipeline_process_duplex().

highpass_filter_process_sample()

float highpass_filter_process_sample	(	highpass_filter_t *	filter,
		float	input
	)

#include <mixer.h>

Process a single sample through high-pass filter.

Parameters

filter	High-pass filter structure
input	Input sample value

Returns

Filtered output sample

Processes input sample through first-order IIR high-pass filter. Filter state is updated for next sample.

Definition at line 942 of file mixer.c.

                                                                             {
  if (!filter)
    return input;
 
  // First-order high-pass filter
  // y[n] = alpha * (y[n-1] + x[n] - x[n-1])
  float output = filter->alpha * (filter->prev_output + input - filter->prev_input);
 
  filter->prev_input = input;
  filter->prev_output = output;
 
  return output;
}

References highpass_filter_t::alpha, highpass_filter_t::prev_input, and highpass_filter_t::prev_output.

Referenced by highpass_filter_process_buffer().

highpass_filter_reset()

void highpass_filter_reset

(

highpass_filter_t *

filter

)

#include <mixer.h>

Reset high-pass filter state.

Parameters

filter

High-pass filter structure

Resets filter state (prev_input, prev_output) to zero. Useful for starting fresh processing or removing DC offset.

Definition at line 934 of file mixer.c.

                                                      {
  if (!filter)
    return;
 
  filter->prev_input = 0.0f;
  filter->prev_output = 0.0f;
}

References highpass_filter_t::prev_input, and highpass_filter_t::prev_output.

Referenced by highpass_filter_init().

int16_to_float()

float int16_to_float

(

int16_t

sample

)

#include <mixer.h>

Convert int16 sample to float.

Parameters

sample

Int16 sample in [-32768, 32767] range

Returns

Float sample in [-1.0, 1.0] range

Scales 16-bit integer audio sample to float format.

Definition at line 1063 of file mixer.c.

                                     {
  return (float)sample / 32768.0f;
}

Referenced by buffer_int16_to_float().

linear_to_db()

float linear_to_db

(

float

linear

)

#include <mixer.h>

Convert linear gain to decibels.

Parameters

linear

Linear gain multiplier

Returns

Decibel value (20*log10(linear))

Converts linear gain multiplier to decibel value for display/logging.

Definition at line 27 of file mixer.c.

                                 {
  return 20.0f * log10f(fmaxf(linear, 1e-12f));
}

Referenced by compressor_process_sample(), and ducking_process_frame().

lowpass_filter_init()

void lowpass_filter_init	(	lowpass_filter_t *	filter,
		float	cutoff_hz,
		float	sample_rate
	)

#include <mixer.h>

Initialize a low-pass filter.

Parameters

filter	Low-pass filter structure
cutoff_hz	Cutoff frequency in Hz
sample_rate	Sample rate in Hz

Initializes filter state and calculates filter coefficient alpha from cutoff frequency. Frequencies above cutoff are attenuated.

Definition at line 970 of file mixer.c.

                                                                                       {
  if (!filter)
    return;
 
  filter->cutoff_hz = cutoff_hz;
  filter->sample_rate = sample_rate;
 
  // Calculate filter coefficient using RC time constant formula
  // alpha = dt / (RC + dt) where RC = 1 / (2 * pi * fc)
  float dt = 1.0f / sample_rate;
  float rc = 1.0f / (2.0f * (float)M_PI * cutoff_hz);
  filter->alpha = dt / (rc + dt);
 
  lowpass_filter_reset(filter);
}

References lowpass_filter_t::alpha, lowpass_filter_t::cutoff_hz, lowpass_filter_reset(), M_PI, and lowpass_filter_t::sample_rate.

Referenced by client_audio_pipeline_create().

lowpass_filter_process_buffer()

void lowpass_filter_process_buffer	(	lowpass_filter_t *	filter,
		float *	buffer,
		int	num_samples
	)

#include <mixer.h>

Process a buffer of samples through low-pass filter.

Parameters

filter	Low-pass filter structure
buffer	Audio buffer (modified in-place)
num_samples	Number of samples to process

Processes entire buffer through low-pass filter. Buffer is modified in-place.

Definition at line 1005 of file mixer.c.

                                                                                             {
  if (!filter || !buffer || num_samples <= 0)
    return;
 
  for (int i = 0; i < num_samples; i++) {
    buffer[i] = lowpass_filter_process_sample(filter, buffer[i]);
  }
}

References lowpass_filter_process_sample().

Referenced by client_audio_pipeline_process_duplex().

lowpass_filter_process_sample()

float lowpass_filter_process_sample	(	lowpass_filter_t *	filter,
		float	input
	)

#include <mixer.h>

Process a single sample through low-pass filter.

Parameters

filter	Low-pass filter structure
input	Input sample value

Returns

Filtered output sample

Processes input sample through first-order IIR low-pass filter. Filter state is updated for next sample.

Definition at line 993 of file mixer.c.

                                                                           {
  if (!filter)
    return input;
 
  // First-order IIR low-pass filter: y[n] = alpha * x[n] + (1 - alpha) * y[n-1]
  float output = filter->alpha * input + (1.0f - filter->alpha) * filter->prev_output;
 
  filter->prev_output = output;
 
  return output;
}

References lowpass_filter_t::alpha, and lowpass_filter_t::prev_output.

Referenced by lowpass_filter_process_buffer().

lowpass_filter_reset()

void lowpass_filter_reset

(

lowpass_filter_t *

filter

)

#include <mixer.h>

Reset low-pass filter state.

Parameters

filter

Low-pass filter structure

Resets filter state (prev_output) to zero.

Definition at line 986 of file mixer.c.

                                                    {
  if (!filter)
    return;
 
  filter->prev_output = 0.0f;
}

References lowpass_filter_t::prev_output.

Referenced by lowpass_filter_init().

mixer_add_source()

int mixer_add_source	(	mixer_t *	mixer,
		uint32_t	client_id,
		audio_ring_buffer_t *	buffer
	)

#include <mixer.h>

Add an audio source to the mixer.

Parameters

mixer	Audio mixer
client_id	Client ID for this source
buffer	Pointer to client's audio ring buffer

Returns

Mixer source index on success, -1 on failure (max sources reached)

Adds a new audio source to the mixer. Client ID is mapped to a mixer source index for efficient lookup during processing.

Note

Thread-safe (acquires write lock internally).

If max_sources is reached, addition fails and -1 is returned.

Definition at line 363 of file mixer.c.

                                                                                      {
  if (!mixer || !buffer)
    return -1;
 
  // OPTIMIZATION 2: Acquire write lock for source modification
  rwlock_wrlock(&mixer->source_lock);
 
  // Find an empty slot
  int slot = -1;
  for (int i = 0; i < mixer->max_sources; i++) {
    if (mixer->source_ids[i] == 0) {
      slot = i;
      break;
    }
  }
 
  if (slot == -1) {
    rwlock_wrunlock(&mixer->source_lock);
    log_warn("Mixer: No available slots for client %u", client_id);
    return -1;
  }
 
  mixer->source_buffers[slot] = buffer;
  mixer->source_ids[slot] = client_id;
  mixer->source_active[slot] = true;
  mixer->num_sources++;
 
  // OPTIMIZATION 1: Update bitset optimization structures
  mixer->active_sources_mask |= (1ULL << slot);                // Set bit for this slot
  mixer->source_id_to_index[client_id & 0xFF] = (uint8_t)slot; // Hash table: client_id → slot
 
  rwlock_wrunlock(&mixer->source_lock);
 
  log_info("Mixer: Added source for client %u at slot %d", client_id, slot);
  return slot;
}

References mixer_t::active_sources_mask, log_info, log_warn, mixer_t::max_sources, mixer_t::num_sources, rwlock_wrlock, rwlock_wrunlock, mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_id_to_index, mixer_t::source_ids, and mixer_t::source_lock.

mixer_create()

mixer_t * mixer_create	(	int	max_sources,
		int	sample_rate
	)

#include <mixer.h>

Create a new audio mixer.

Parameters

max_sources	Maximum number of audio sources to support
sample_rate	Sample rate in Hz (e.g., 44100)

Returns

Pointer to new mixer, or NULL on failure

Creates a new mixer with pre-allocated source arrays and processing buffers. All audio processing components are initialized.

Note

max_sources should not exceed MIXER_MAX_SOURCES.

Definition at line 218 of file mixer.c.

                                                        {
  // Validate parameters
  if (max_sources <= 0 || max_sources > MIXER_MAX_SOURCES) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid max_sources: %d (must be 1-%d)", max_sources, MIXER_MAX_SOURCES);
    return NULL;
  }
 
  if (sample_rate <= 0 || sample_rate > 192000) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid sample_rate: %d (must be 1-192000)", sample_rate);
    return NULL;
  }
 
  mixer_t *mixer;
  mixer = SAFE_MALLOC(sizeof(mixer_t), mixer_t *);
  if (!mixer) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate mixer structure");
    return NULL;
  }
 
  mixer->num_sources = 0;
  mixer->max_sources = max_sources;
  mixer->sample_rate = sample_rate;
 
  // Allocate source management arrays with overflow checking
  size_t buffers_size = 0;
  if (checked_size_mul((size_t)max_sources, sizeof(audio_ring_buffer_t *), &buffers_size) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Mixer source buffers array overflow: %d sources", max_sources);
    SAFE_FREE(mixer);
    return NULL;
  }
  mixer->source_buffers = SAFE_MALLOC(buffers_size, audio_ring_buffer_t **);
  if (!mixer->source_buffers) {
    SAFE_FREE(mixer);
    return NULL;
  }
 
  size_t ids_size = 0;
  if (checked_size_mul((size_t)max_sources, sizeof(uint32_t), &ids_size) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Mixer source IDs array overflow: %d sources", max_sources);
    SAFE_FREE(mixer->source_buffers);
    SAFE_FREE(mixer);
    return NULL;
  }
  mixer->source_ids = SAFE_MALLOC(ids_size, uint32_t *);
  if (!mixer->source_ids) {
    SAFE_FREE(mixer->source_buffers);
    SAFE_FREE(mixer);
    return NULL;
  }
 
  size_t active_size = 0;
  if (checked_size_mul((size_t)max_sources, sizeof(bool), &active_size) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Mixer source active array overflow: %d sources", max_sources);
    SAFE_FREE(mixer->source_buffers);
    SAFE_FREE(mixer->source_ids);
    SAFE_FREE(mixer);
    return NULL;
  }
  mixer->source_active = SAFE_MALLOC(active_size, bool *);
  if (!mixer->source_active) {
    SAFE_FREE(mixer->source_buffers);
    SAFE_FREE(mixer->source_ids);
    SAFE_FREE(mixer);
    return NULL;
  }
 
  // Initialize arrays
  SAFE_MEMSET((void *)mixer->source_buffers, buffers_size, 0, buffers_size);
  SAFE_MEMSET(mixer->source_ids, ids_size, 0, ids_size);
  SAFE_MEMSET(mixer->source_active, active_size, 0, active_size);
 
  // OPTIMIZATION 1: Initialize bitset optimization structures
  mixer->active_sources_mask = 0ULL; // No sources active initially
  SAFE_MEMSET(mixer->source_id_to_index, sizeof(mixer->source_id_to_index), 0xFF,
              sizeof(mixer->source_id_to_index)); // 0xFF = invalid index
 
  // Allocate mix buffer BEFORE rwlock_init so cleanup path is correct
  size_t mix_buffer_size = 0;
  if (checked_size_mul(MIXER_FRAME_SIZE, sizeof(float), &mix_buffer_size) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Mixer mix buffer size overflow: %zu samples", (size_t)MIXER_FRAME_SIZE);
    SAFE_FREE(mixer->source_buffers);
    SAFE_FREE(mixer->source_ids);
    SAFE_FREE(mixer->source_active);
    SAFE_FREE(mixer);
    return NULL;
  }
  mixer->mix_buffer = SAFE_MALLOC(mix_buffer_size, float *);
  if (!mixer->mix_buffer) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate mix buffer");
    SAFE_FREE(mixer->source_buffers);
    SAFE_FREE(mixer->source_ids);
    SAFE_FREE(mixer->source_active);
    SAFE_FREE(mixer);
    return NULL;
  }
 
  // OPTIMIZATION 2: Initialize reader-writer lock
  if (rwlock_init(&mixer->source_lock) != 0) {
    SET_ERRNO(ERROR_THREAD, "Failed to initialize mixer source lock");
    SAFE_FREE(mixer->source_buffers);
    SAFE_FREE(mixer->source_ids);
    SAFE_FREE(mixer->source_active);
    SAFE_FREE(mixer->mix_buffer);
    SAFE_FREE(mixer);
    return NULL;
  }
 
  // Set crowd scaling parameters
  mixer->crowd_alpha = 0.5f; // Square root scaling
  mixer->base_gain = 1.0f;   // Unity gain - let compressor handle loudness, avoid clipping
 
  // Initialize processing
  if (ducking_init(&mixer->ducking, max_sources, (float)sample_rate) != ASCIICHAT_OK) {
    rwlock_destroy(&mixer->source_lock);
    SAFE_FREE(mixer->source_buffers);
    SAFE_FREE(mixer->source_ids);
    SAFE_FREE(mixer->source_active);
    SAFE_FREE(mixer->mix_buffer);
    SAFE_FREE(mixer);
    return NULL;
  }
  compressor_init(&mixer->compressor, (float)sample_rate);
 
  log_info("Audio mixer created: max_sources=%d, sample_rate=%d", max_sources, sample_rate);
 
  return mixer;
}

References mixer_t::active_sources_mask, ASCIICHAT_OK, mixer_t::base_gain, mixer_t::compressor, compressor_init(), mixer_t::crowd_alpha, mixer_t::ducking, ducking_init(), ERROR_BUFFER_OVERFLOW, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_THREAD, log_info, mixer_t::max_sources, mixer_t::mix_buffer, MIXER_FRAME_SIZE, MIXER_MAX_SOURCES, mixer_t::num_sources, rwlock_destroy(), rwlock_init(), SAFE_FREE, SAFE_MALLOC, SAFE_MEMSET, mixer_t::sample_rate, SET_ERRNO, mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_id_to_index, mixer_t::source_ids, and mixer_t::source_lock.

Referenced by server_main().

mixer_destroy()

void mixer_destroy

(

mixer_t *

mixer

)

#include <mixer.h>

Destroy a mixer and free all resources.

Parameters

mixer

Mixer to destroy (can be NULL)

Frees all allocated memory including source arrays, processing buffers, and ducking system allocations.

Warning

Mixer must not be in use by any threads when destroyed.

Definition at line 346 of file mixer.c.

                                   {
  if (!mixer)
    return;
 
  // OPTIMIZATION 2: Destroy reader-writer lock
  rwlock_destroy(&mixer->source_lock);
 
  ducking_free(&mixer->ducking);
 
  SAFE_FREE(mixer->source_buffers);
  SAFE_FREE(mixer->source_ids);
  SAFE_FREE(mixer->source_active);
  SAFE_FREE(mixer->mix_buffer);
  SAFE_FREE(mixer);
  log_info("Audio mixer destroyed");
}

References mixer_t::ducking, ducking_free(), log_info, mixer_t::mix_buffer, rwlock_destroy(), SAFE_FREE, mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_ids, and mixer_t::source_lock.

Referenced by server_main().

mixer_process()

int mixer_process	(	mixer_t *	mixer,
		float *	output,
		int	num_samples
	)

#include <mixer.h>

Process audio from all active sources.

Parameters

mixer	Audio mixer
output	Output buffer for mixed audio (must have num_samples elements)
num_samples	Number of samples to process

Returns

Number of samples processed on success, negative on error

Reads audio from all active sources, applies processing pipeline (ducking, mixing, compression, noise gate, high-pass filter), and writes mixed output to output buffer.

Note

Processing includes all stages: ducking, mixing, compression, noise gating, high-pass filtering, and soft clipping.

Thread-safe (acquires read lock for source access).

Warning

Output buffer must have at least num_samples float elements.

Definition at line 459 of file mixer.c.

                                                                  {
  if (!mixer || !output || num_samples <= 0)
    return -1;
 
  // THREAD SAFETY: Acquire read lock to protect against concurrent source add/remove
  // This prevents race conditions where source_buffers[i] could be set to NULL while we read it
  rwlock_rdlock(&mixer->source_lock);
 
  // Clear output buffer
  SAFE_MEMSET(output, num_samples * sizeof(float), 0, num_samples * sizeof(float));
 
  // Count active sources
  int active_count = 0;
  for (int i = 0; i < mixer->max_sources; i++) {
    if (mixer->source_ids[i] != 0 && mixer->source_active[i] && mixer->source_buffers[i]) {
      active_count++;
    }
  }
 
  if (active_count == 0) {
    // No active sources, output silence
    return 0;
  }
 
  // Process in frames for efficiency
  for (int frame_start = 0; frame_start < num_samples; frame_start += MIXER_FRAME_SIZE) {
    int frame_size = (frame_start + MIXER_FRAME_SIZE > num_samples) ? (num_samples - frame_start) : MIXER_FRAME_SIZE;
 
    // Clear mix buffer
    SAFE_MEMSET(mixer->mix_buffer, frame_size * sizeof(float), 0, frame_size * sizeof(float));
 
    // Temporary buffers for source audio
    float source_samples[MIXER_MAX_SOURCES][MIXER_FRAME_SIZE];
    int source_count = 0;
    int source_map[MIXER_MAX_SOURCES]; // Maps source index to slot
 
    // Read from each active source
    for (int i = 0; i < mixer->max_sources; i++) {
      if (mixer->source_ids[i] != 0 && mixer->source_active[i] && mixer->source_buffers[i]) {
        // Read samples from this source's ring buffer
        size_t samples_read_size =
            audio_ring_buffer_read(mixer->source_buffers[i], source_samples[source_count], frame_size);
        int samples_read = (int)samples_read_size;
 
        // Accept partial frames - pad with silence if needed
        // This prevents audio dropouts when ring buffers are temporarily under-filled
        if (samples_read > 0) {
          // Pad remaining samples with silence if we got a partial frame
          if (samples_read < frame_size) {
            SAFE_MEMSET(&source_samples[source_count][samples_read], (frame_size - samples_read) * sizeof(float), 0,
                        (frame_size - samples_read) * sizeof(float));
          }
 
          source_map[source_count] = i;
          source_count++;
 
          if (source_count >= MIXER_MAX_SOURCES)
            break;
        }
      }
    }
 
    // OPTIMIZATION: Batch envelope calculation per-frame instead of per-sample
    // Calculate peak amplitude for each source over the entire frame
    int speaking_count = 0;
 
    for (int i = 0; i < source_count; i++) {
      int slot = source_map[i];
      float peak = 0.0f;
 
      // Find peak amplitude in frame (much faster than per-sample envelope)
      for (int s = 0; s < frame_size; s++) {
        float abs_sample = fabsf(source_samples[i][s]);
        if (abs_sample > peak)
          peak = abs_sample;
      }
 
      // Update envelope using frame peak (one update per frame instead of per-sample)
      if (peak > mixer->ducking.envelope[slot]) {
        mixer->ducking.envelope[slot] =
            mixer->ducking.attack_coeff * mixer->ducking.envelope[slot] + (1.0f - mixer->ducking.attack_coeff) * peak;
      } else {
        mixer->ducking.envelope[slot] =
            mixer->ducking.release_coeff * mixer->ducking.envelope[slot] + (1.0f - mixer->ducking.release_coeff) * peak;
      }
 
      // Count speaking sources
      if (mixer->ducking.envelope[slot] > db_to_linear(-60.0f))
        speaking_count++;
    }
 
    // Apply ducking ONCE per frame (not per-sample)
    ducking_process_frame(&mixer->ducking, mixer->ducking.envelope, mixer->ducking.gain, mixer->max_sources);
 
    // Calculate crowd scaling ONCE per frame
    float crowd_gain = (speaking_count > 0) ? (1.0f / powf((float)speaking_count, mixer->crowd_alpha)) : 1.0f;
    float pre_bus = mixer->base_gain * crowd_gain;
 
    // Pre-calculate combined gains for each source (ducking * pre_bus)
    float combined_gains[MIXER_MAX_SOURCES];
    for (int i = 0; i < source_count; i++) {
      int slot = source_map[i];
      combined_gains[i] = mixer->ducking.gain[slot] * pre_bus;
    }
 
    // OPTIMIZATION: Fast mixing loop - simple multiply-add with pre-calculated gains
    // NO per-sample compressor to avoid expensive log/pow calls (480x per iteration)
    for (int s = 0; s < frame_size; s++) {
      float mix = 0.0f;
      for (int i = 0; i < source_count; i++) {
        mix += source_samples[i][s] * combined_gains[i];
      }
 
      // Store in mix buffer for frame-level compression below
      mixer->mix_buffer[s] = mix;
    }
 
    // OPTIMIZATION: Apply compression ONCE per frame instead of per-sample
    // This reduces expensive log10f/powf calls from 480x to 1x per iteration
    // Calculate frame peak for compressor sidechain
    float frame_peak = 0.0f;
    for (int s = 0; s < frame_size; s++) {
      float abs_val = fabsf(mixer->mix_buffer[s]);
      if (abs_val > frame_peak)
        frame_peak = abs_val;
    }
 
    // Process compressor with frame peak (1 call instead of 480)
    float comp_gain = compressor_process_sample(&mixer->compressor, frame_peak);
 
    // Apply compression gain and soft clipping to all samples
    for (int s = 0; s < frame_size; s++) {
      float mix = mixer->mix_buffer[s] * comp_gain;
 
      // Compressor provides +6dB makeup gain for better audibility
      // Soft clip threshold 1.0f allows full range without premature clipping
      // Steepness 3.0 for smoother clipping behavior
      output[frame_start + s] = soft_clip(mix, 1.0f, 3.0f);
    }
  }
 
  rwlock_rdunlock(&mixer->source_lock);
  return num_samples;
}

References ducking_t::attack_coeff, audio_ring_buffer_read(), mixer_t::base_gain, mixer_t::compressor, compressor_process_sample(), mixer_t::crowd_alpha, db_to_linear(), mixer_t::ducking, ducking_process_frame(), ducking_t::envelope, ducking_t::gain, mixer_t::max_sources, mixer_t::mix_buffer, MIXER_FRAME_SIZE, MIXER_MAX_SOURCES, ducking_t::release_coeff, rwlock_rdlock, rwlock_rdunlock, SAFE_MEMSET, soft_clip(), mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_ids, and mixer_t::source_lock.

mixer_process_excluding_source()

int mixer_process_excluding_source	(	mixer_t *	mixer,
		float *	output,
		int	num_samples,
		uint32_t	exclude_client_id
	)

#include <mixer.h>

Process audio from all sources except one (for per-client output)

Parameters

mixer	Audio mixer
output	Output buffer for mixed audio
num_samples	Number of samples to process
exclude_client_id	Client ID to exclude from mixing

Returns

Number of samples processed on success, negative on error

Same as mixer_process() but excludes one client's audio from the mix. Used to generate per-client output that doesn't include their own audio (prevents echo and feedback).

Note

Processing pipeline is identical to mixer_process().

Thread-safe (acquires read lock for source access).

Definition at line 604 of file mixer.c.

                                                                                                               {
  if (!mixer || !output || num_samples <= 0)
    return -1;
 
  // Only use timing in debug builds - snprintf + hashtable ops are expensive in hot path
#ifndef NDEBUG
  START_TIMER("mixer_total");
#endif
 
  // THREAD SAFETY: Acquire read lock to protect against concurrent source add/remove
  // This prevents race conditions where source_buffers[i] could be set to NULL while we read it
  rwlock_rdlock(&mixer->source_lock);
 
  // Clear output buffer
  SAFE_MEMSET(output, num_samples * sizeof(float), 0, num_samples * sizeof(float));
 
  // OPTIMIZATION 1: O(1) exclusion using bitset and hash table
  uint8_t exclude_index = mixer->source_id_to_index[exclude_client_id & 0xFF];
  uint64_t active_mask = mixer->active_sources_mask;
 
  // Validate exclude_index before using in bitshift
  // - exclude_index == 0xFF means "not found" (sentinel value from initialization)
  // - exclude_index >= MIXER_MAX_SOURCES would cause undefined behavior in bitshift
  // - Also verify hash table lookup actually matched the client_id (collision detection)
  bool valid_exclude = (exclude_index < MIXER_MAX_SOURCES && exclude_index != 0xFF &&
                        mixer->source_ids[exclude_index] == exclude_client_id);
 
  if (valid_exclude) {
    // Check if this is the ONLY active source - if so, drain it to prevent buffer overflow
    // With N>1 clients, other threads drain this buffer. With N=1, no one does.
    uint64_t mask_without_excluded = active_mask & ~(1ULL << exclude_index);
    if (mask_without_excluded == 0 && mixer->source_buffers[exclude_index]) {
      // Solo client: drain their buffer to prevent overflow (discard samples)
      // LOCK-FREE: Skip samples directly using atomic operations
      audio_ring_buffer_t *rb = mixer->source_buffers[exclude_index];
      if (rb) {
        size_t available = audio_ring_buffer_available_read(rb);
        size_t to_skip = ((size_t)num_samples < available) ? (size_t)num_samples : available;
 
        // LOCK-FREE: Atomically advance read_index with release ordering
        unsigned int old_read_idx = atomic_load_explicit(&rb->read_index, memory_order_relaxed);
        unsigned int new_read_idx = (old_read_idx + to_skip) % AUDIO_RING_BUFFER_SIZE;
        atomic_store_explicit(&rb->read_index, new_read_idx, memory_order_release);
 
        log_debug_every(LOG_RATE_DEFAULT, "Mixer: Drained %zu samples for solo client %u (lock-free skip)", to_skip,
                        exclude_client_id);
      }
    }
    active_mask = mask_without_excluded;
 
    // DIAGNOSTIC: Log which client was excluded and which remain active
    log_info_every(
        1000000,
        "MIXER EXCLUSION: exclude_client=%u, exclude_index=%u, active_mask_before=0x%llx, active_mask_after=0x%llx",
        exclude_client_id, exclude_index, (unsigned long long)(active_mask | (1ULL << exclude_index)),
        (unsigned long long)active_mask);
  } else {
    // DIAGNOSTIC: Failed to exclude - log why
    log_warn_every(1000000, "MIXER EXCLUSION FAILED: exclude_client=%u, exclude_index=%u (valid=%d), lookup_id=%u",
                   exclude_client_id, exclude_index, valid_exclude,
                   (exclude_index < MIXER_MAX_SOURCES && exclude_index != 0xFF) ? mixer->source_ids[exclude_index] : 0);
  }
 
  // Fast check: any sources to mix?
  if (active_mask == 0) {
    rwlock_rdunlock(&mixer->source_lock);
#ifndef NDEBUG
    STOP_TIMER("mixer_total");
#endif
    return 0; // No sources to mix (excluding the specified client), output silence
  }
 
  // Process in frames for efficiency
  for (int frame_start = 0; frame_start < num_samples; frame_start += MIXER_FRAME_SIZE) {
    int frame_size = (frame_start + MIXER_FRAME_SIZE > num_samples) ? (num_samples - frame_start) : MIXER_FRAME_SIZE;
 
    struct timespec read_start, read_end;
    (void)clock_gettime(CLOCK_MONOTONIC, &read_start);
 
    // Clear mix buffer
    SAFE_MEMSET(mixer->mix_buffer, frame_size * sizeof(float), 0, frame_size * sizeof(float));
 
    // Temporary buffers for source audio
    float source_samples[MIXER_MAX_SOURCES][MIXER_FRAME_SIZE];
    int source_count = 0;
    int source_map[MIXER_MAX_SOURCES]; // Maps source index to slot
 
    // OPTIMIZATION 1: Iterate only over active sources using bitset
    uint64_t current_mask = active_mask;
    while (current_mask && source_count < MIXER_MAX_SOURCES) {
      int i = find_first_set_bit(current_mask); // Portable: find first set bit
      current_mask &= current_mask - 1;         // Clear lowest set bit
 
      // Verify source is valid (defensive programming)
      if (i < mixer->max_sources && mixer->source_ids[i] != 0 && mixer->source_buffers[i]) {
        // Read samples from this source's ring buffer
        size_t samples_read_size =
            audio_ring_buffer_read(mixer->source_buffers[i], source_samples[source_count], frame_size);
        int samples_read = (int)samples_read_size;
 
        // Accept partial frames - pad with silence if needed
        // This prevents audio dropouts when ring buffers are temporarily under-filled
        if (samples_read > 0) {
          // Pad remaining samples with silence if we got a partial frame
          if (samples_read < frame_size) {
            SAFE_MEMSET(&source_samples[source_count][samples_read], (frame_size - samples_read) * sizeof(float), 0,
                        (frame_size - samples_read) * sizeof(float));
          }
 
          // DIAGNOSTIC: Calculate RMS of this source's audio
          float source_rms = 0.0f;
          if (frame_start == 0) { // Only log for first frame to reduce spam
            float sum_squares = 0.0f;
            for (int s = 0; s < samples_read; s++) {
              sum_squares += source_samples[source_count][s] * source_samples[source_count][s];
            }
            source_rms = sqrtf(sum_squares / (float)samples_read);
            log_info_every(1000000, "MIXER SOURCE READ: client_id=%u, slot=%d, samples_read=%d, RMS=%.6f",
                           mixer->source_ids[i], i, samples_read, source_rms);
          }
 
          source_map[source_count] = i;
          source_count++;
        }
      }
    }
 
    (void)clock_gettime(CLOCK_MONOTONIC, &read_end);
    uint64_t read_time_us = ((uint64_t)read_end.tv_sec * 1000000 + (uint64_t)read_end.tv_nsec / 1000) -
                            ((uint64_t)read_start.tv_sec * 1000000 + (uint64_t)read_start.tv_nsec / 1000);
 
    if (read_time_us > 10000) { // Log if reading sources takes > 10ms
      log_warn_every(LOG_RATE_DEFAULT, "Mixer: Slow source reading took %lluus (%.2fms) for %d sources", read_time_us,
                     (float)read_time_us / 1000.0f, source_count);
    }
 
    // OPTIMIZATION: Batch envelope calculation per-frame instead of per-sample
    // Calculate peak amplitude for each source over the entire frame
    int speaking_count = 0;
 
    for (int i = 0; i < source_count; i++) {
      int slot = source_map[i];
      float peak = 0.0f;
 
      // Find peak amplitude in frame (much faster than per-sample envelope)
      for (int s = 0; s < frame_size; s++) {
        float abs_sample = fabsf(source_samples[i][s]);
        if (abs_sample > peak)
          peak = abs_sample;
      }
 
      // Update envelope using frame peak (one update per frame instead of per-sample)
      if (peak > mixer->ducking.envelope[slot]) {
        mixer->ducking.envelope[slot] =
            mixer->ducking.attack_coeff * mixer->ducking.envelope[slot] + (1.0f - mixer->ducking.attack_coeff) * peak;
      } else {
        mixer->ducking.envelope[slot] =
            mixer->ducking.release_coeff * mixer->ducking.envelope[slot] + (1.0f - mixer->ducking.release_coeff) * peak;
      }
 
      // Count speaking sources
      if (mixer->ducking.envelope[slot] > db_to_linear(-60.0f))
        speaking_count++;
    }
 
    // Apply ducking ONCE per frame (not per-sample)
    ducking_process_frame(&mixer->ducking, mixer->ducking.envelope, mixer->ducking.gain, mixer->max_sources);
 
    // Calculate crowd scaling ONCE per frame
    float crowd_gain = (speaking_count > 0) ? (1.0f / powf((float)speaking_count, mixer->crowd_alpha)) : 1.0f;
    float pre_bus = mixer->base_gain * crowd_gain;
 
    // Pre-calculate combined gains for each source (ducking * pre_bus)
    float combined_gains[MIXER_MAX_SOURCES];
    for (int i = 0; i < source_count; i++) {
      int slot = source_map[i];
      combined_gains[i] = mixer->ducking.gain[slot] * pre_bus;
    }
 
    // OPTIMIZATION: Fast mixing loop - simple multiply-add with pre-calculated gains
    // NO per-sample compressor to avoid expensive log/pow calls (480x per iteration)
    for (int s = 0; s < frame_size; s++) {
      float mix = 0.0f;
      for (int i = 0; i < source_count; i++) {
        mix += source_samples[i][s] * combined_gains[i];
      }
 
      // Store in mix buffer for frame-level compression below
      mixer->mix_buffer[s] = mix;
    }
 
    // OPTIMIZATION: Apply compression ONCE per frame instead of per-sample
    // This reduces expensive log10f/powf calls from 480x to 1x per iteration
    // Calculate frame peak for compressor sidechain
    float frame_peak = 0.0f;
    for (int s = 0; s < frame_size; s++) {
      float abs_val = fabsf(mixer->mix_buffer[s]);
      if (abs_val > frame_peak)
        frame_peak = abs_val;
    }
 
    // Process compressor with frame peak (1 call instead of 480)
    float comp_gain = compressor_process_sample(&mixer->compressor, frame_peak);
 
    // Apply compression gain and soft clipping to all samples
    for (int s = 0; s < frame_size; s++) {
      float mix = mixer->mix_buffer[s] * comp_gain;
 
      // Compressor provides +6dB makeup gain for better audibility
      // Soft clip threshold 1.0f allows full range without premature clipping
      // Steepness 3.0 for smoother clipping behavior
      output[frame_start + s] = soft_clip(mix, 1.0f, 3.0f);
    }
  }
 
  rwlock_rdunlock(&mixer->source_lock);
 
#ifndef NDEBUG
  double total_ns = STOP_TIMER("mixer_total");
  if (total_ns > 2000000) { // > 2ms
    char duration_str[32];
    format_duration_ns(total_ns, duration_str, sizeof(duration_str));
    log_warn("Slow mixer: total=%s, num_samples=%d", duration_str, num_samples);
  }
#endif
 
  return num_samples;
}

References mixer_t::active_sources_mask, ducking_t::attack_coeff, audio_ring_buffer_available_read(), audio_ring_buffer_read(), AUDIO_RING_BUFFER_SIZE, mixer_t::base_gain, mixer_t::compressor, compressor_process_sample(), mixer_t::crowd_alpha, db_to_linear(), mixer_t::ducking, ducking_process_frame(), ducking_t::envelope, format_duration_ns(), ducking_t::gain, log_debug_every, log_info_every, LOG_RATE_DEFAULT, log_warn, log_warn_every, mixer_t::max_sources, mixer_t::mix_buffer, MIXER_FRAME_SIZE, MIXER_MAX_SOURCES, audio_ring_buffer::read_index, ducking_t::release_coeff, rwlock_rdlock, rwlock_rdunlock, SAFE_MEMSET, soft_clip(), mixer_t::source_buffers, mixer_t::source_id_to_index, mixer_t::source_ids, mixer_t::source_lock, START_TIMER, and STOP_TIMER.

Referenced by client_audio_render_thread().

mixer_remove_source()

void mixer_remove_source	(	mixer_t *	mixer,
		uint32_t	client_id
	)

#include <mixer.h>

Remove an audio source from the mixer.

Parameters

mixer	Audio mixer
client_id	Client ID to remove

Removes the audio source associated with the given client ID. Source slot is freed for reuse by another client.

Note

Thread-safe (acquires write lock internally).

If client_id is not found, operation has no effect.

Definition at line 400 of file mixer.c.

                                                             {
  if (!mixer)
    return;
 
  // OPTIMIZATION 2: Acquire write lock for source modification
  rwlock_wrlock(&mixer->source_lock);
 
  for (int i = 0; i < mixer->max_sources; i++) {
    if (mixer->source_ids[i] == client_id) {
      mixer->source_buffers[i] = NULL;
      mixer->source_ids[i] = 0;
      mixer->source_active[i] = false;
      mixer->num_sources--;
 
      // OPTIMIZATION 1: Update bitset optimization structures
      mixer->active_sources_mask &= ~(1ULL << i);         // Clear bit for this slot
      mixer->source_id_to_index[client_id & 0xFF] = 0xFF; // Mark as invalid in hash table
 
      // Reset ducking state for this source
      mixer->ducking.envelope[i] = 0.0f;
      mixer->ducking.gain[i] = 1.0f;
 
      rwlock_wrunlock(&mixer->source_lock);
 
      log_info("Mixer: Removed source for client %u from slot %d", client_id, i);
      return;
    }
  }
 
  rwlock_wrunlock(&mixer->source_lock);
}

References mixer_t::active_sources_mask, mixer_t::ducking, ducking_t::envelope, ducking_t::gain, log_info, mixer_t::max_sources, mixer_t::num_sources, rwlock_wrlock, rwlock_wrunlock, mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_id_to_index, mixer_t::source_ids, and mixer_t::source_lock.

mixer_set_source_active()

void mixer_set_source_active	(	mixer_t *	mixer,
		uint32_t	client_id,
		bool	active
	)

#include <mixer.h>

Set whether a source is active (receiving audio)

Parameters

mixer	Audio mixer
client_id	Client ID
active	true to mark source as active, false to mark inactive

Updates the active status of a source. Inactive sources are excluded from mixing operations for efficiency.

Note

Thread-safe (acquires write lock internally).

Source must exist (be added) before calling this function.

Definition at line 432 of file mixer.c.

                                                                              {
  if (!mixer)
    return;
 
  // OPTIMIZATION 2: Acquire write lock for source modification
  rwlock_wrlock(&mixer->source_lock);
 
  for (int i = 0; i < mixer->max_sources; i++) {
    if (mixer->source_ids[i] == client_id) {
      mixer->source_active[i] = active;
 
      // OPTIMIZATION 1: Update bitset for active state change
      if (active) {
        mixer->active_sources_mask |= (1ULL << i); // Set bit
      } else {
        mixer->active_sources_mask &= ~(1ULL << i); // Clear bit
      }
 
      rwlock_wrunlock(&mixer->source_lock);
      log_debug("Mixer: Set source %u active=%d", client_id, active);
      return;
    }
  }
 
  rwlock_wrunlock(&mixer->source_lock);
}

References mixer_t::active_sources_mask, log_debug, mixer_t::max_sources, rwlock_wrlock, rwlock_wrunlock, mixer_t::source_active, mixer_t::source_ids, and mixer_t::source_lock.

noise_gate_init()

void noise_gate_init	(	noise_gate_t *	gate,
		float	sample_rate
	)

#include <mixer.h>

Initialize a noise gate.

Parameters

gate	Noise gate structure
sample_rate	Sample rate in Hz

Initializes noise gate state and converts time-based parameters to coefficients.

Definition at line 838 of file mixer.c.

                                                            {
  if (!gate)
    return;
 
  gate->sample_rate = sample_rate;
  gate->envelope = 0.0f;
  gate->gate_open = false;
 
  // Default parameters
  // Slower attack (10ms) prevents clicking artifacts during gate transitions
  // threshold=0.01, attack=10ms, release=50ms, hysteresis=0.9
  noise_gate_set_params(gate, 0.01f, 10.0f, 50.0f, 0.9f);
}

References noise_gate_t::envelope, noise_gate_t::gate_open, noise_gate_set_params(), and noise_gate_t::sample_rate.

Referenced by client_audio_pipeline_create().

noise_gate_is_open()

bool noise_gate_is_open

(

const noise_gate_t *

gate

)

#include <mixer.h>

Check if noise gate is currently open.

Parameters

gate	Noise gate structure

Returns

true if gate is open, false if closed

Returns current gate state. Useful for debugging and monitoring.

Definition at line 911 of file mixer.c.

                                                  {
  return gate ? gate->gate_open : false;
}

References noise_gate_t::gate_open.

noise_gate_process_buffer()

void noise_gate_process_buffer	(	noise_gate_t *	gate,
		float *	buffer,
		int	num_samples
	)

#include <mixer.h>

Process a buffer of samples through noise gate.

Parameters

gate	Noise gate structure
buffer	Audio buffer (modified in-place)
num_samples	Number of samples to process

Processes entire buffer through noise gate. Buffer is modified in-place.

Note

Peak amplitude is calculated per sample for gate decision.

Definition at line 892 of file mixer.c.

                                                                                   {
  if (!gate || !buffer || num_samples <= 0)
    return;
 
  // First pass: find peak amplitude
  float peak = 0.0f;
  for (int i = 0; i < num_samples; i++) {
    float abs_sample = fabsf(buffer[i]);
    if (abs_sample > peak) {
      peak = abs_sample;
    }
  }
 
  // Second pass: apply gate
  for (int i = 0; i < num_samples; i++) {
    buffer[i] = noise_gate_process_sample(gate, buffer[i], peak);
  }
}

References noise_gate_process_sample().

Referenced by client_audio_pipeline_playback(), and client_audio_pipeline_process_duplex().

noise_gate_process_sample()

float noise_gate_process_sample	(	noise_gate_t *	gate,
		float	input,
		float	peak_amplitude
	)

#include <mixer.h>

Process a single sample through noise gate.

Parameters

gate	Noise gate structure
input	Input sample value
peak_amplitude	Peak amplitude for gate decision

Returns

Gated output sample (input if gate open, 0 if closed)

Processes input sample through noise gate. Gate opens/closes based on peak_amplitude compared to threshold (with hysteresis).

Note

peak_amplitude should be envelope follower output, not raw sample.

Definition at line 867 of file mixer.c.

                                                                                       {
  if (!gate)
    return input;
 
  // Determine target state with hysteresis
  float target;
  if (gate->gate_open) {
    // Gate is open - use lower threshold (hysteresis) to close
    target = (peak_amplitude > gate->threshold * gate->hysteresis) ? 1.0f : 0.0f;
  } else {
    // Gate is closed - use normal threshold to open
    target = (peak_amplitude > gate->threshold) ? 1.0f : 0.0f;
  }
 
  // Update gate state
  gate->gate_open = (target > 0.5f);
 
  // Update envelope with appropriate coefficient
  float coeff = (target > gate->envelope) ? gate->attack_coeff : gate->release_coeff;
  gate->envelope += coeff * (target - gate->envelope);
 
  // Apply gate
  return input * gate->envelope;
}

References noise_gate_t::attack_coeff, noise_gate_t::envelope, noise_gate_t::gate_open, noise_gate_t::hysteresis, noise_gate_t::release_coeff, and noise_gate_t::threshold.

Referenced by noise_gate_process_buffer().

noise_gate_set_params()

void noise_gate_set_params	(	noise_gate_t *	gate,
		float	threshold,
		float	attack_ms,
		float	release_ms,
		float	hysteresis
	)

#include <mixer.h>

Set noise gate parameters.

Parameters

gate	Noise gate structure
threshold	Gate threshold in linear units
attack_ms	Attack time in milliseconds
release_ms	Release time in milliseconds
hysteresis	Hysteresis factor (0-1) to prevent chatter

Updates noise gate parameters. Time-based parameters are converted to coefficients internally.

Definition at line 852 of file mixer.c.

                                                                                                                     {
  if (!gate)
    return;
 
  gate->threshold = threshold;
  gate->attack_ms = attack_ms;
  gate->release_ms = release_ms;
  gate->hysteresis = hysteresis;
 
  // Calculate coefficients for envelope follower
  // Using exponential moving average: coeff = 1 - exp(-1 / (time_ms * sample_rate / 1000))
  gate->attack_coeff = 1.0f - expf(-1.0f / (attack_ms * gate->sample_rate / 1000.0f));
  gate->release_coeff = 1.0f - expf(-1.0f / (release_ms * gate->sample_rate / 1000.0f));
}

References noise_gate_t::attack_coeff, noise_gate_t::attack_ms, noise_gate_t::hysteresis, noise_gate_t::release_coeff, noise_gate_t::release_ms, noise_gate_t::sample_rate, and noise_gate_t::threshold.

Referenced by client_audio_pipeline_create(), and noise_gate_init().

opus_codec_create_decoder()

opus_codec_t * opus_codec_create_decoder

(

int

sample_rate

)

#include <opus_codec.h>

Create an Opus decoder.

Parameters

sample_rate

Sample rate in Hz (must match encoder)

Returns

Pointer to new decoder, NULL on error

Creates a new Opus decoder instance for decompressing audio.

Warning

Returned pointer must be freed with opus_codec_destroy()

Definition at line 62 of file opus_codec.c.

                                                         {
  if (sample_rate <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid sample rate: %d", sample_rate);
    return NULL;
  }
 
  opus_codec_t *codec = SAFE_MALLOC(sizeof(opus_codec_t), opus_codec_t *);
  if (!codec) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate opus codec context");
    return NULL;
  }
 
  // Create decoder
  int error = OPUS_OK;
  codec->decoder = opus_decoder_create(sample_rate, 1, &error);
  if (error != OPUS_OK || !codec->decoder) {
    SET_ERRNO(ERROR_AUDIO, "Failed to create Opus decoder: %s", opus_strerror(error));
    SAFE_FREE(codec);
    return NULL;
  }
 
  codec->encoder = NULL;
  codec->sample_rate = sample_rate;
  codec->bitrate = 0; // N/A for decoder
  codec->tmp_buffer = NULL;
 
  log_debug("Opus decoder created: sample_rate=%d", sample_rate);
 
  return codec;
}

References opus_codec_t::bitrate, opus_codec_t::decoder, opus_codec_t::encoder, ERROR_AUDIO, ERROR_INVALID_PARAM, ERROR_MEMORY, log_debug, SAFE_FREE, SAFE_MALLOC, opus_codec_t::sample_rate, SET_ERRNO, and opus_codec_t::tmp_buffer.

Referenced by handle_stream_start_packet().

opus_codec_create_encoder()

opus_codec_t * opus_codec_create_encoder	(	opus_application_t	application,
		int	sample_rate,
		int	bitrate
	)

#include <opus_codec.h>

Create an Opus encoder.

Parameters

application	Application mode (OPUS_APPLICATION_VOIP for voice)
sample_rate	Sample rate in Hz (8000, 12000, 16000, 24000, or 48000)
bitrate	Target bitrate in bits per second (6000-128000 typical)

Returns

Pointer to new encoder, NULL on error

Creates a new Opus encoder instance for compressing audio.

Note

Common bitrates:

• 16 kbps: Good quality voice
• 24 kbps: Excellent quality voice
• 64 kbps: High quality audio

Warning

Returned pointer must be freed with opus_codec_destroy()

Definition at line 18 of file opus_codec.c.

                                                                                                      {
  if (sample_rate <= 0 || bitrate <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid codec parameters: sample_rate=%d, bitrate=%d", sample_rate, bitrate);
    return NULL;
  }
 
  opus_codec_t *codec = SAFE_MALLOC(sizeof(opus_codec_t), opus_codec_t *);
  if (!codec) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate opus codec context");
    return NULL;
  }
 
  // Create encoder
  int error = OPUS_OK;
  codec->encoder = opus_encoder_create(sample_rate, 1, (int)application, &error);
  if (error != OPUS_OK || !codec->encoder) {
    SET_ERRNO(ERROR_AUDIO, "Failed to create Opus encoder: %s", opus_strerror(error));
    SAFE_FREE(codec);
    return NULL;
  }
 
  // Set bitrate
  error = opus_encoder_ctl(codec->encoder, OPUS_SET_BITRATE(bitrate));
  if (error != OPUS_OK) {
    SET_ERRNO(ERROR_AUDIO, "Failed to set Opus bitrate: %s", opus_strerror(error));
    opus_encoder_destroy(codec->encoder);
    SAFE_FREE(codec);
    return NULL;
  }
 
  codec->decoder = NULL;
  codec->sample_rate = sample_rate;
  codec->bitrate = bitrate;
  codec->tmp_buffer = NULL;
 
  log_debug("Opus encoder created: sample_rate=%d, bitrate=%d bps", sample_rate, bitrate);
 
  return codec;
}

References opus_codec_t::bitrate, opus_codec_t::decoder, opus_codec_t::encoder, ERROR_AUDIO, ERROR_INVALID_PARAM, ERROR_MEMORY, log_debug, SAFE_FREE, SAFE_MALLOC, opus_codec_t::sample_rate, SET_ERRNO, and opus_codec_t::tmp_buffer.

Referenced by client_audio_render_thread().

opus_codec_decode()

int opus_codec_decode	(	opus_codec_t *	codec,
		const uint8_t *	data,
		size_t	data_len,
		float *	out_samples,
		int	out_num_samples
	)

#include <opus_codec.h>

Decode Opus audio frame.

Parameters

codec	Opus decoder (created with opus_codec_create_decoder)
data	Compressed audio data (or NULL for PLC)
data_len	Length of compressed data in bytes
out_samples	Output buffer for decoded samples (float)
out_num_samples	Maximum number of output samples

Returns

Number of samples decoded, negative on error

Decodes a compressed Opus frame back to PCM audio samples.

Note

To handle packet loss, pass NULL for data to enable PLC (Packet Loss Concealment)

Output will be exactly the frame size (typically 882 samples)

This function is NOT thread-safe for the same codec instance

Definition at line 128 of file opus_codec.c.

                                           {
  if (!codec || !codec->decoder || !out_samples || out_num_samples <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM,
              "Invalid decode parameters: codec=%p, decoder=%p, out_samples=%p, out_num_samples=%d", (void *)codec,
              (void *)(codec ? codec->decoder : NULL), (void *)out_samples, out_num_samples);
    return -1;
  }
 
  // If data is NULL, use PLC (Packet Loss Concealment)
  if (!data || data_len == 0) {
    log_debug_every(LOG_RATE_VERY_FAST, "Opus PLC (Packet Loss Concealment)");
    int samples = opus_decode_float(codec->decoder, NULL, 0, out_samples, out_num_samples, 0);
    if (samples < 0) {
      SET_ERRNO(ERROR_AUDIO, "Opus PLC failed: %s", opus_strerror(samples));
      return -1;
    }
    return samples;
  }
 
  // Decode frame
  int samples = opus_decode_float(codec->decoder, data, (opus_int32)data_len, out_samples, out_num_samples, 0);
 
  if (samples < 0) {
    SET_ERRNO(ERROR_AUDIO, "Opus decoding failed: %s", opus_strerror(samples));
    return -1;
  }
 
  return samples;
}

References opus_codec_t::decoder, ERROR_AUDIO, ERROR_INVALID_PARAM, log_debug_every, LOG_RATE_VERY_FAST, and SET_ERRNO.

Referenced by handle_audio_opus_batch_packet(), and handle_audio_opus_packet().

opus_codec_destroy()

void opus_codec_destroy

(

opus_codec_t *

codec

)

#include <opus_codec.h>

Destroy an Opus codec instance.

Parameters

codec

Codec to destroy (can be NULL)

Frees all resources associated with the codec. Safe to call multiple times or with NULL pointer.

Definition at line 215 of file opus_codec.c.

                                             {
  if (!codec) {
    return;
  }
 
  if (codec->encoder) {
    opus_encoder_destroy(codec->encoder);
    codec->encoder = NULL;
  }
 
  if (codec->decoder) {
    opus_decoder_destroy(codec->decoder);
    codec->decoder = NULL;
  }
 
  if (codec->tmp_buffer) {
    SAFE_FREE(codec->tmp_buffer);
    codec->tmp_buffer = NULL;
  }
 
  SAFE_FREE(codec);
}

References opus_codec_t::decoder, opus_codec_t::encoder, SAFE_FREE, and opus_codec_t::tmp_buffer.

Referenced by cleanup_client_media_buffers(), and client_audio_render_thread().

opus_codec_encode()

size_t opus_codec_encode	(	opus_codec_t *	codec,
		const float *	samples,
		int	num_samples,
		uint8_t *	out_data,
		size_t	out_size
	)

#include <opus_codec.h>

Encode audio frame with Opus.

Parameters

codec	Opus encoder (created with opus_codec_create_encoder)
samples	Input audio samples (float, -1.0 to 1.0 range)
num_samples	Number of input samples (882 for 20ms @ 44.1kHz)
out_data	Output buffer for compressed audio
out_size	Maximum output buffer size in bytes

Returns

Number of bytes written to out_data, negative on error

Encodes a frame of audio samples using Opus compression.

Note

Input must be exactly the correct frame size (typically 882 samples)

Output is typically 30-100 bytes depending on bitrate and content

This function is NOT thread-safe for the same codec instance

Definition at line 97 of file opus_codec.c.

                                          {
  if (!codec || !codec->encoder || !samples || num_samples <= 0 || !out_data || out_size == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM,
              "Invalid encode parameters: codec=%p, encoder=%p, samples=%p, num_samples=%d, out_data=%p, "
              "out_size=%zu",
              (void *)codec, (void *)(codec ? codec->encoder : NULL), (const void *)samples, num_samples,
              (void *)out_data, out_size);
    return 0;
  }
 
  // Encode frame
  opus_int32 encoded_bytes = opus_encode_float(codec->encoder, samples, num_samples, out_data, (opus_int32)out_size);
 
  if (encoded_bytes < 0) {
    SET_ERRNO(ERROR_AUDIO, "Opus encoding failed: %s", opus_strerror((int)encoded_bytes));
    return 0;
  }
 
  if (encoded_bytes == 0) {
    // DTX frame (silence) - encoder produced zero bytes
    log_debug_every(LOG_RATE_VERY_FAST, "Opus DTX frame (silence detected)");
  }
 
  return (size_t)encoded_bytes;
}

References opus_codec_t::encoder, ERROR_AUDIO, ERROR_INVALID_PARAM, log_debug_every, LOG_RATE_VERY_FAST, and SET_ERRNO.

Referenced by client_audio_render_thread().

opus_codec_get_bitrate()

int opus_codec_get_bitrate

(

opus_codec_t *

codec

)

#include <opus_codec.h>

Get current encoder bitrate.

Parameters

codec

Opus encoder

Returns

Bitrate in bits per second, negative on error

Definition at line 180 of file opus_codec.c.

                                                {
  if (!codec || !codec->encoder) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid codec for bitrate query");
    return -1;
  }
 
  opus_int32 bitrate = 0;
  int error = opus_encoder_ctl(codec->encoder, OPUS_GET_BITRATE(&bitrate));
  if (error != OPUS_OK) {
    SET_ERRNO(ERROR_AUDIO, "Failed to get Opus bitrate: %s", opus_strerror(error));
    return -1;
  }
 
  return (int)bitrate;
}

References opus_codec_t::encoder, ERROR_AUDIO, ERROR_INVALID_PARAM, and SET_ERRNO.

opus_codec_set_bitrate()

asciichat_error_t opus_codec_set_bitrate	(	opus_codec_t *	codec,
		int	bitrate
	)

#include <opus_codec.h>

Set encoder bitrate.

Parameters

codec	Opus encoder (created with opus_codec_create_encoder)
bitrate	New bitrate in bits per second

Returns

0 on success, negative on error

Changes the bitrate of an active encoder. This can be used to dynamically adjust quality based on network conditions.

Definition at line 163 of file opus_codec.c.

                                                                           {
  if (!codec || !codec->encoder || bitrate <= 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid bitrate parameters: codec=%p, encoder=%p, bitrate=%d", (void *)codec,
                     (void *)(codec ? codec->encoder : NULL), bitrate);
  }
 
  int error = opus_encoder_ctl(codec->encoder, OPUS_SET_BITRATE(bitrate));
  if (error != OPUS_OK) {
    return SET_ERRNO(ERROR_AUDIO, "Failed to set Opus bitrate: %s", opus_strerror(error));
  }
 
  codec->bitrate = bitrate;
  log_debug("Opus bitrate changed to %d bps", bitrate);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, opus_codec_t::bitrate, opus_codec_t::encoder, ERROR_AUDIO, ERROR_INVALID_PARAM, log_debug, and SET_ERRNO.

opus_codec_set_dtx()

asciichat_error_t opus_codec_set_dtx	(	opus_codec_t *	codec,
		int	enable
	)

#include <opus_codec.h>

Enable/disable DTX (Discontinuous Transmission)

Parameters

codec	Opus encoder
enable	1 to enable DTX, 0 to disable

Returns

0 on success, negative on error

DTX allows the encoder to produce zero-byte frames during silence, reducing bandwidth usage significantly for voice communication.

Definition at line 196 of file opus_codec.c.

                                                                      {
  if (!codec || !codec->encoder) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid codec for DTX configuration");
  }
 
  int error = opus_encoder_ctl(codec->encoder, OPUS_SET_DTX(enable ? 1 : 0));
  if (error != OPUS_OK) {
    return SET_ERRNO(ERROR_AUDIO, "Failed to set Opus DTX: %s", opus_strerror(error));
  }
 
  log_debug("Opus DTX %s", enable ? "enabled" : "disabled");
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, opus_codec_t::encoder, ERROR_AUDIO, ERROR_INVALID_PARAM, log_debug, and SET_ERRNO.

resample_linear()

void resample_linear	(	const float *	src,
		size_t	src_samples,
		float *	dst,
		size_t	dst_samples,
		double	src_rate,
		double	dst_rate
	)

#include <audio.h>

Resample audio using linear interpolation.

Parameters

src	Source samples at src_rate
src_samples	Number of source samples
dst	Destination buffer at dst_rate
dst_samples	Number of destination samples to produce
src_rate	Source sample rate (e.g., 48000)
dst_rate	Destination sample rate (e.g., 44100)

Performs simple linear interpolation resampling from one sample rate to another. Suitable for real-time audio where computational efficiency is more important than perfect audio quality. For higher quality, consider a polyphase resampler.

Example usage:

// Resample from 48kHz buffer to 44.1kHz output
size_t in_samples = 960;  // 20ms at 48kHz
size_t out_samples = 882; // 20ms at 44.1kHz
resample_linear(input, in_samples, output, out_samples, 48000, 44100);

Note

If src_samples or dst_samples is 0, dst is filled with silence.

Thread-safe: No shared state.

Simple linear interpolation resampler. Resamples from src_rate to dst_rate using linear interpolation.

Parameters

src	Source samples at src_rate
src_samples	Number of source samples
dst	Destination buffer at dst_rate
dst_samples	Number of destination samples to produce
src_rate	Source sample rate (e.g., 48000)
dst_rate	Destination sample rate (e.g., 44100)

Definition at line 165 of file lib/audio/audio.c.

                                      {
  if (src_samples == 0 || dst_samples == 0) {
    SAFE_MEMSET(dst, dst_samples * sizeof(float), 0, dst_samples * sizeof(float));
    return;
  }
 
  double ratio = src_rate / dst_rate;
 
  for (size_t i = 0; i < dst_samples; i++) {
    double src_pos = (double)i * ratio;
    size_t idx0 = (size_t)src_pos;
    size_t idx1 = idx0 + 1;
    double frac = src_pos - (double)idx0;
 
    // Clamp indices to valid range
    if (idx0 >= src_samples)
      idx0 = src_samples - 1;
    if (idx1 >= src_samples)
      idx1 = src_samples - 1;
 
    // Linear interpolation
    dst[i] = (float)((1.0 - frac) * src[idx0] + frac * src[idx1]);
  }
}

References SAFE_MEMSET.

smoothstep()

float smoothstep

(

float

t

)

#include <mixer.h>

Compute smoothstep interpolation.

Parameters

t	Input value (typically 0.0 to 1.0)

Returns

Smoothly interpolated value using 3t² - 2t³ curve

Standard smoothstep function providing smooth fade-in/fade-out curves. Output is clamped to [0, 1] range.

Definition at line 1046 of file mixer.c.

                          {
  if (t <= 0.0f)
    return 0.0f;
  if (t >= 1.0f)
    return 1.0f;
  return t * t * (3.0f - 2.0f * t);
}

Referenced by client_audio_pipeline_process_duplex(), and fade_buffer_smooth().

soft_clip()

float soft_clip	(	float	sample,
		float	threshold,
		float	steepness
	)

#include <mixer.h>

Apply soft clipping to a sample.

Parameters

sample	Input sample value
threshold	Clipping threshold (e.g., 0.7 for 3dB headroom)
steepness	How aggressively the curve bends (1.0 = gentle, 10.0 = sharp)

Returns

Soft-clipped output sample (always in [-1.0, 1.0] range)

Applies soft clipping using tanh curve. The formula is: output = threshold + (1.0 - threshold) * tanh((sample - threshold) * steepness)

This maps samples above threshold asymptotically toward 1.0, preventing hard clipping artifacts while maintaining perceptual loudness.

Common parameter combinations:

• threshold=0.7, steepness=3.0: Gentle limiting, 3dB headroom
• threshold=0.9, steepness=6.0: Moderate limiting, 1dB headroom
• threshold=0.95, steepness=10.0: Aggressive limiting, minimal headroom

Definition at line 1019 of file mixer.c.

                                                                {
  if (sample > threshold) {
    // Soft clip positive values using tanh curve
    // Maps samples above threshold asymptotically toward 1.0
    return threshold + (1.0f - threshold) * tanhf((sample - threshold) * steepness);
  }
  if (sample < -threshold) {
    // Soft clip negative values symmetrically
    return -threshold + (-1.0f + threshold) * tanhf((sample + threshold) * steepness);
  }
  return sample;
}

Referenced by client_audio_pipeline_process_duplex(), mixer_process(), mixer_process_excluding_source(), and soft_clip_buffer().

soft_clip_buffer()

void soft_clip_buffer	(	float *	buffer,
		int	num_samples,
		float	threshold,
		float	steepness
	)

#include <mixer.h>

Apply soft clipping to a buffer.

Parameters

buffer	Audio buffer (modified in-place)
num_samples	Number of samples to process
threshold	Clipping threshold (e.g., 0.7 for 3dB headroom)
steepness	How aggressively the curve bends

Processes entire buffer through soft_clip(). Buffer is modified in-place.

Definition at line 1032 of file mixer.c.

                                                                                        {
  if (!buffer || num_samples <= 0)
    return;
 
  for (int i = 0; i < num_samples; i++) {
    buffer[i] = soft_clip(buffer[i], threshold, steepness);
  }
}

References soft_clip().

Referenced by client_audio_pipeline_process_duplex().

Variable Documentation

active_sources_mask

uint64_t mixer_t::active_sources_mask

Bitset of active sources (bit i = source i is active, O(1) iteration)

Definition at line 341 of file mixer.h.

Referenced by mixer_add_source(), mixer_create(), mixer_process_excluding_source(), mixer_remove_source(), and mixer_set_source_active().

alpha [1/2]

float highpass_filter_t::alpha

Filter coefficient alpha (calculated from cutoff_hz)

Definition at line 225 of file mixer.h.

Referenced by highpass_filter_init(), and highpass_filter_process_sample().

alpha [2/2]

float lowpass_filter_t::alpha

Filter coefficient alpha (calculated from cutoff_hz)

Definition at line 248 of file mixer.h.

Referenced by lowpass_filter_init(), and lowpass_filter_process_sample().

attack_coeff [1/3]

float compressor_t::attack_coeff

Attack coefficient (converted from attack_ms)

Definition at line 158 of file mixer.h.

Referenced by compressor_process_sample(), and compressor_set_params().

attack_coeff [2/3]

float noise_gate_t::attack_coeff

Attack coefficient (converted from attack_ms)

Definition at line 195 of file mixer.h.

Referenced by noise_gate_process_sample(), and noise_gate_set_params().

attack_coeff [3/3]

float ducking_t::attack_coeff

Attack coefficient (converted from attack_ms)

Definition at line 284 of file mixer.h.

Referenced by ducking_init(), ducking_process_frame(), mixer_process(), and mixer_process_excluding_source().

attack_ms [1/3]

float compressor_t::attack_ms

Attack time in milliseconds (how fast compression kicks in)

Definition at line 145 of file mixer.h.

Referenced by compressor_set_params().

attack_ms [2/3]

float noise_gate_t::attack_ms

Attack time in milliseconds (how fast gate opens)

Definition at line 184 of file mixer.h.

Referenced by noise_gate_set_params().

attack_ms [3/3]

float ducking_t::attack_ms

Ducking attack time in milliseconds.

Definition at line 279 of file mixer.h.

Referenced by ducking_init(), and ducking_set_params().

atten_dB

float ducking_t::atten_dB

Attenuation in dB for non-leader sources.

Definition at line 277 of file mixer.h.

Referenced by ducking_init(), ducking_process_frame(), and ducking_set_params().

base_gain

float mixer_t::base_gain

Base gain before crowd scaling is applied.

Definition at line 353 of file mixer.h.

Referenced by mixer_create(), mixer_process(), and mixer_process_excluding_source().

compressor

compressor_t mixer_t::compressor

Compressor (dynamic range compression)

Definition at line 358 of file mixer.h.

Referenced by mixer_create(), mixer_process(), and mixer_process_excluding_source().

crowd_alpha

float mixer_t::crowd_alpha

Crowd scaling exponent (typically 0.5 for sqrt scaling)

Definition at line 351 of file mixer.h.

Referenced by mixer_create(), mixer_process(), and mixer_process_excluding_source().

cutoff_hz [1/2]

float highpass_filter_t::cutoff_hz

Cutoff frequency in Hz (frequencies below this are attenuated)

Definition at line 220 of file mixer.h.

Referenced by highpass_filter_init().

cutoff_hz [2/2]

float lowpass_filter_t::cutoff_hz

Cutoff frequency in Hz (frequencies above this are attenuated)

Definition at line 243 of file mixer.h.

Referenced by lowpass_filter_init().

ducking

ducking_t mixer_t::ducking

Ducking system (active speaker detection and attenuation)

Definition at line 356 of file mixer.h.

Referenced by mixer_create(), mixer_destroy(), mixer_process(), mixer_process_excluding_source(), and mixer_remove_source().

envelope [1/3]

float compressor_t::envelope

Current envelope follower state (linear, 0-1)

Definition at line 154 of file mixer.h.

Referenced by compressor_init(), and compressor_process_sample().

envelope [2/3]

float noise_gate_t::envelope

Current envelope follower state (linear, 0-1)

Definition at line 193 of file mixer.h.

Referenced by noise_gate_init(), and noise_gate_process_sample().

envelope [3/3]

float* ducking_t::envelope

Per-source envelope follower state (linear, allocated per source)

Definition at line 288 of file mixer.h.

Referenced by ducking_free(), ducking_init(), mixer_process(), mixer_process_excluding_source(), and mixer_remove_source().

gain

float* ducking_t::gain

Per-source ducking gain (linear, calculated from envelope)

Definition at line 290 of file mixer.h.

Referenced by ducking_free(), ducking_init(), mixer_process(), mixer_process_excluding_source(), and mixer_remove_source().

gain_lin

float compressor_t::gain_lin

Current gain multiplier (linear, calculated from envelope)

Definition at line 156 of file mixer.h.

Referenced by compressor_init(), and compressor_process_sample().

gate_open

bool noise_gate_t::gate_open

True if gate is currently open (allowing audio through)

Definition at line 199 of file mixer.h.

Referenced by noise_gate_init(), noise_gate_is_open(), and noise_gate_process_sample().

hysteresis

float noise_gate_t::hysteresis

Hysteresis factor (0-1, prevents gate chatter)

Definition at line 188 of file mixer.h.

Referenced by noise_gate_process_sample(), and noise_gate_set_params().

knee_dB

float compressor_t::knee_dB

Knee width in dB for soft knee (e.g., 2.0)

Definition at line 141 of file mixer.h.

Referenced by compressor_set_params().

leader_margin_dB

float ducking_t::leader_margin_dB

Leader margin in dB (sources within this of loudest are leaders)

Definition at line 275 of file mixer.h.

Referenced by ducking_init(), ducking_process_frame(), and ducking_set_params().

makeup_dB

float compressor_t::makeup_dB

Makeup gain in dB (compensates for gain reduction)

Definition at line 149 of file mixer.h.

Referenced by compressor_process_sample(), and compressor_set_params().

max_sources

int mixer_t::max_sources

Maximum number of sources (allocated array sizes)

Definition at line 329 of file mixer.h.

Referenced by client_audio_render_thread(), mixer_add_source(), mixer_create(), mixer_process(), mixer_process_excluding_source(), mixer_remove_source(), and mixer_set_source_active().

mix_buffer

float* mixer_t::mix_buffer

Temporary buffer for mixing operations (pre-allocated)

Definition at line 361 of file mixer.h.

Referenced by mixer_create(), mixer_destroy(), mixer_process(), and mixer_process_excluding_source().

num_sources

int mixer_t::num_sources

Current number of active audio sources.

Definition at line 327 of file mixer.h.

Referenced by mixer_add_source(), mixer_create(), and mixer_remove_source().

prev_input

float highpass_filter_t::prev_input

Previous input sample (filter state)

Definition at line 227 of file mixer.h.

Referenced by highpass_filter_process_sample(), and highpass_filter_reset().

prev_output [1/2]

float highpass_filter_t::prev_output

Previous output sample (filter state)

Definition at line 229 of file mixer.h.

Referenced by highpass_filter_process_sample(), and highpass_filter_reset().

prev_output [2/2]

float lowpass_filter_t::prev_output

Previous output sample (filter state)

Definition at line 250 of file mixer.h.

Referenced by lowpass_filter_process_sample(), and lowpass_filter_reset().

ratio

float compressor_t::ratio

Compression ratio (e.g., 4.0 for 4:1 compression)

Definition at line 143 of file mixer.h.

Referenced by compressor_set_params().

release_coeff [1/3]

float compressor_t::release_coeff

Release coefficient (converted from release_ms)

Definition at line 160 of file mixer.h.

Referenced by compressor_process_sample(), and compressor_set_params().

release_coeff [2/3]

float noise_gate_t::release_coeff

Release coefficient (converted from release_ms)

Definition at line 197 of file mixer.h.

Referenced by noise_gate_process_sample(), and noise_gate_set_params().

release_coeff [3/3]

float ducking_t::release_coeff

Release coefficient (converted from release_ms)

Definition at line 286 of file mixer.h.

Referenced by ducking_init(), ducking_process_frame(), mixer_process(), and mixer_process_excluding_source().

release_ms [1/3]

float compressor_t::release_ms

Release time in milliseconds (how fast compression releases)

Definition at line 147 of file mixer.h.

Referenced by compressor_set_params().

release_ms [2/3]

float noise_gate_t::release_ms

Release time in milliseconds (how fast gate closes)

Definition at line 186 of file mixer.h.

Referenced by noise_gate_set_params().

release_ms [3/3]

float ducking_t::release_ms

Ducking release time in milliseconds.

Definition at line 281 of file mixer.h.

Referenced by ducking_init(), and ducking_set_params().

sample_rate [1/5]

float compressor_t::sample_rate

Sample rate in Hz (set during initialization)

Definition at line 152 of file mixer.h.

Referenced by compressor_init(), and compressor_set_params().

sample_rate [2/5]

float noise_gate_t::sample_rate

Sample rate in Hz (set during initialization)

Definition at line 191 of file mixer.h.

Referenced by noise_gate_init(), and noise_gate_set_params().

sample_rate [3/5]

float highpass_filter_t::sample_rate

Sample rate in Hz (set during initialization)

Definition at line 222 of file mixer.h.

Referenced by highpass_filter_init().

sample_rate [4/5]

float lowpass_filter_t::sample_rate

Sample rate in Hz (set during initialization)

Definition at line 245 of file mixer.h.

Referenced by lowpass_filter_init().

sample_rate [5/5]

int mixer_t::sample_rate

Sample rate in Hz (e.g., 44100)

Definition at line 331 of file mixer.h.

Referenced by mixer_create().

source_active

bool* mixer_t::source_active

Array of active flags (true if source is active)

Definition at line 338 of file mixer.h.

Referenced by mixer_add_source(), mixer_create(), mixer_destroy(), mixer_process(), mixer_remove_source(), and mixer_set_source_active().

source_buffers

audio_ring_buffer_t** mixer_t::source_buffers

Array of pointers to client audio ring buffers.

Definition at line 334 of file mixer.h.

Referenced by client_audio_render_thread(), mixer_add_source(), mixer_create(), mixer_destroy(), mixer_process(), mixer_process_excluding_source(), and mixer_remove_source().

source_id_at_hash

uint32_t mixer_t::source_id_at_hash[256]

Client IDs stored at each hash index for collision detection.

Definition at line 345 of file mixer.h.

source_id_to_index

uint8_t mixer_t::source_id_to_index[256]

Hash table mapping client_id → mixer source index (uses hash function for 32-bit IDs)

Definition at line 343 of file mixer.h.

Referenced by mixer_add_source(), mixer_create(), mixer_process_excluding_source(), and mixer_remove_source().

source_ids

uint32_t* mixer_t::source_ids

Array of client IDs (one per source slot)

Definition at line 336 of file mixer.h.

Referenced by client_audio_render_thread(), mixer_add_source(), mixer_create(), mixer_destroy(), mixer_process(), mixer_process_excluding_source(), mixer_remove_source(), and mixer_set_source_active().

source_lock

rwlock_t mixer_t::source_lock

Reader-writer lock protecting source arrays and bitset.

Definition at line 348 of file mixer.h.

Referenced by mixer_add_source(), mixer_create(), mixer_destroy(), mixer_process(), mixer_process_excluding_source(), mixer_remove_source(), and mixer_set_source_active().

threshold

float noise_gate_t::threshold

Gate threshold in linear units (e.g., 0.01f for -40dB)

Definition at line 182 of file mixer.h.

Referenced by noise_gate_process_sample(), and noise_gate_set_params().

threshold_dB [1/2]

float compressor_t::threshold_dB

Compression threshold in dB (e.g., -10.0)

Definition at line 139 of file mixer.h.

Referenced by compressor_set_params().

threshold_dB [2/2]

float ducking_t::threshold_dB

Speaking threshold in dB (sources below this are not "speaking")

Definition at line 273 of file mixer.h.

Referenced by ducking_init(), ducking_process_frame(), and ducking_set_params().