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

Files
file	analysis.c
	Audio Analysis Implementation.

file	audio.c
	🔊 Audio capture and playback using PortAudio with buffer management

file	mixer.c
	🎚️ Real-time audio mixer with ducking, gain control, and multi-stream blending

file	opus.c
	Opus audio codec implementation.

file	analysis.h
	Audio Analysis and Debugging Interface.

file	audio.h
	🔊 Audio Capture and Playback Interface for ascii-chat

file	client_pipeline.h
	Unified client-side audio processing pipeline.

file	mixer.h
	Multi-Source Audio Mixing and Processing System.

file	opus.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_terminate_portaudio_final (void)
	Terminate PortAudio and free all device 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_register_atomics (audio_ring_buffer_t rb, const char context_name)
	Register audio ring buffer atomic fields for debug tracking.

void	audio_ring_buffer_unregister_atomics (audio_ring_buffer_t *rb)
	Unregister audio ring buffer atomic fields.

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.

void	audio_flush_playback_buffers (audio_context_t *ctx)
	Flush all audio buffers to synchronize with seek operations.

bool	audio_should_enable_microphone (audio_capture_source_t source, bool has_media_audio)
	Determine if microphone should be enabled based on audio source setting and media state.

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)

uint64_t	compressor_t::attack_ns
	Attack time in nanoseconds (how fast compression kicks in)

uint64_t	compressor_t::release_ns
	Release time in nanoseconds (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)

uint64_t	noise_gate_t::attack_ns
	Attack time in nanoseconds (how fast gate opens)

uint64_t	noise_gate_t::release_ns
	Release time in nanoseconds (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.

uint64_t	ducking_t::attack_ns
	Ducking attack time in nanoseconds.

uint64_t	ducking_t::release_ns
	Ducking release time in nanoseconds.

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.

struct mixer_listener_buffer *	mixer_t::listener_buffers [32][32]

const char **	mixer_t::source_ids
	Array of client ID strings (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 strings)

const char *	mixer_t::source_id_at_hash [256]
	Client ID strings 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, const char client_id, audio_ring_buffer_t *buffer)
	Add an audio source to the mixer.

void	mixer_remove_source (mixer_t mixer, const char client_id)
	Remove an audio source from the mixer.

void	mixer_set_source_active (mixer_t mixer, const char client_id, bool active)
	Set whether a source is active (receiving audio)

#define	MIXER_HASH_INVALID 0xFF
	Invalid index sentinel value for mixer hash table.

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, uint64_t attack_ns, uint64_t release_ns, 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_destroy (ducking_t *duck)
	Free ducking system resources.

void	ducking_set_params (ducking_t *duck, float threshold_dB, float leader_margin_dB, float atten_dB, uint64_t attack_ns, uint64_t release_ns)
	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, uint64_t attack_ns, uint64_t release_ns, 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:

Source Reading: Reads samples from client audio ring buffers
Ducking: Identifies active speaker and attenuates background sources
Mixing: Combines all active sources with crowd scaling
Compression: Applies dynamic range compression to prevent clipping
Noise Gate: Suppresses background noise below threshold
High-Pass Filter: Removes low-frequency noise and rumble
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);

audio_destroy

void audio_destroy(audio_context_t *ctx)

Destroy audio context and clean up resources.

Definition lib/audio/audio.c:1553

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

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 91 of file include/ascii-chat/audio/audio.h.

◆ AUDIO_CHANNELS

#define AUDIO_CHANNELS 1

#include <audio.h>

Number of audio channels (1 = mono)

Definition at line 89 of file include/ascii-chat/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 87 of file include/ascii-chat/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 85 of file include/ascii-chat/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_HASH_INVALID

#define MIXER_HASH_INVALID 0xFF

#include <mixer.h>

Invalid index sentinel value for mixer hash table.

Definition at line 464 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.h>

Definition at line 66 of file opus.h.

◆ OpusEncoder

typedef struct OpusEncoder OpusEncoder

#include <opus.h>

Definition at line 65 of file opus.h.

Enumeration Type Documentation

◆ opus_application_t

enum opus_application_t

#include <opus.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.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 1186 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 2239 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 1553 of file lib/audio/audio.c.

                                         {
  if (!ctx) {
    return;
  }
 
  // Always release PortAudio refcount if it was incremented
  // audio_init() calls Pa_Initialize() very early, and if it fails partway through,
  // ctx->initialized will be false. But we MUST still call audio_release_portaudio()
  // to properly decrement the refcount and allow Pa_Terminate() to be called.
  if (ctx->initialized) {
 
    // Stop duplex stream if running (this also stops the worker thread)
    if (ctx->running) {
      audio_stop_duplex(ctx);
    }
 
    // Ensure worker thread is stopped even if streams weren't running
    if (ctx->worker_running) {
      log_debug("Stopping worker thread during audio_destroy");
      atomic_store_bool(&ctx->worker_should_stop, true);
      cond_signal(&ctx->worker_cond); // Wake up worker if waiting
      asciichat_thread_join(&ctx->worker_thread, NULL);
      ctx->worker_running = false;
    }
 
    mutex_lock(&ctx->state_mutex);
 
    // Destroy all ring buffers (old + new)
    audio_ring_buffer_destroy(ctx->capture_buffer);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->render_buffer); // May be NULL, that's OK
 
    // Free pre-allocated worker buffers
    SAFE_FREE(ctx->worker_capture_batch);
    SAFE_FREE(ctx->worker_render_batch);
    SAFE_FREE(ctx->worker_playback_batch);
 
    // Destroy worker synchronization primitives
    cond_destroy(&ctx->worker_cond);
    mutex_destroy(&ctx->worker_mutex);
 
    ctx->initialized = false;
 
    mutex_unlock(&ctx->state_mutex);
    mutex_destroy(&ctx->state_mutex);
 
    log_debug("Audio system cleanup complete (all resources released)");
  } else {
  }
}

Referenced by audio_cleanup(), audio_client_init(), session_audio_destroy(), and session_client_like_run().

◆ audio_flush_playback_buffers()

void audio_flush_playback_buffers ( audio_context_t * ctx )

#include <audio.h>

Flush all audio buffers to synchronize with seek operations.

Parameters

ctx	Audio context (must not be NULL)

Clears the playback buffers when seeking occurs. This prevents 5-10 seconds of old audio from playing after a seek operation. Called by keyboard handler when user presses seek arrow keys.

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

                                                        {
  if (!ctx || !ctx->initialized) {
    return;
  }
 
  if (ctx->playback_buffer) {
    audio_ring_buffer_clear(ctx->playback_buffer);
  }
  if (ctx->processed_playback_rb) {
    audio_ring_buffer_clear(ctx->processed_playback_rb);
  }
  if (ctx->render_buffer) {
    audio_ring_buffer_clear(ctx->render_buffer);
  }
  if (ctx->raw_render_rb) {
    audio_ring_buffer_clear(ctx->raw_render_rb);
  }
}

References audio_ring_buffer_clear(), audio_context_t::initialized, audio_context_t::playback_buffer, audio_context_t::processed_playback_rb, audio_context_t::raw_render_rb, and audio_context_t::render_buffer.

Referenced by session_handle_keyboard_input().

◆ 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 2235 of file lib/audio/audio.c.

                                                          {
  SAFE_FREE(devices);
}

References SAFE_FREE.

◆ 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 1399 of file lib/audio/audio.c.

                                                   {
  log_debug("audio_init: starting, ctx=%p", (void *)ctx);
  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, "audio_context") != 0) {
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize audio context mutex");
  }
 
  // NOTE: PortAudio initialization deferred to audio_start_duplex() where streams are actually opened
  // This avoids Pa_Initialize() overhead for contexts that might not start duplex
  // and prevents premature ALSA device allocation and memory leaks
 
  // Create capture buffer WITHOUT jitter buffering (PortAudio writes directly from microphone)
  ctx->capture_buffer = audio_ring_buffer_create_for_capture();
  if (!ctx->capture_buffer) {
    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);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create playback buffer");
  }
 
  // Create new ring buffers for worker thread architecture
  ctx->raw_capture_rb = audio_ring_buffer_create_for_capture();
  if (!ctx->raw_capture_rb) {
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create raw capture buffer");
  }
 
  ctx->raw_render_rb = audio_ring_buffer_create_for_capture();
  if (!ctx->raw_render_rb) {
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create raw render buffer");
  }
 
  ctx->processed_playback_rb = audio_ring_buffer_create();
  if (!ctx->processed_playback_rb) {
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create processed playback buffer");
  }
 
  // Initialize worker thread infrastructure
  if (mutex_init(&ctx->worker_mutex, "audio_worker_mutex") != 0) {
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize worker mutex");
  }
 
  if (cond_init(&ctx->worker_cond, "audio_worker_cond") != 0) {
    mutex_destroy(&ctx->worker_mutex);
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize worker condition variable");
  }
 
  // Allocate pre-allocated worker buffers (avoid malloc in worker loop)
  ctx->worker_capture_batch = SAFE_MALLOC(WORKER_BATCH_SAMPLES * sizeof(float), float *);
  if (!ctx->worker_capture_batch) {
    cond_destroy(&ctx->worker_cond);
    mutex_destroy(&ctx->worker_mutex);
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker capture batch buffer");
  }
 
  ctx->worker_render_batch = SAFE_MALLOC(WORKER_BATCH_SAMPLES * sizeof(float), float *);
  if (!ctx->worker_render_batch) {
    SAFE_FREE(ctx->worker_capture_batch);
    cond_destroy(&ctx->worker_cond);
    mutex_destroy(&ctx->worker_mutex);
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker render batch buffer");
  }
 
  ctx->worker_playback_batch = SAFE_MALLOC(WORKER_BATCH_SAMPLES * sizeof(float), float *);
  if (!ctx->worker_playback_batch) {
    SAFE_FREE(ctx->worker_render_batch);
    SAFE_FREE(ctx->worker_capture_batch);
    cond_destroy(&ctx->worker_cond);
    mutex_destroy(&ctx->worker_mutex);
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker playback batch buffer");
  }
 
  ctx->capture_media_source = NULL;
  ctx->monitor_local_media = false;
 
  // Initialize worker thread state (thread will be started in audio_start_duplex)
  ctx->worker_running = false;
  atomic_store_bool(&ctx->worker_should_stop, false);
 
  ctx->initialized = true;
  atomic_store_bool(&ctx->shutting_down, false);
 
  /* Register audio context with named registry */
  NAMED_REGISTER(ctx, "audio_context", "audio_context_t", "0x%tx", NULL);
 
  /* Register audio context's sync primitives with hierarchical naming */
  NAMED_REGISTER_MUTEX(&ctx->state_mutex, "state_mutex", (uintptr_t)(const void *)(ctx));
  NAMED_REGISTER_MUTEX(&ctx->worker_mutex, "worker_mutex", (uintptr_t)(const void *)(ctx));
  NAMED_REGISTER_COND(&ctx->worker_cond, "worker_cond", (uintptr_t)(const void *)(ctx));
  NAMED_REGISTER_ATOMIC(&ctx->worker_should_stop, "worker_should_stop", (uintptr_t)(const void *)(ctx));
  NAMED_REGISTER_ATOMIC(&ctx->shutting_down, "shutting_down", (uintptr_t)(const void *)(ctx));
 
  /* Register ring buffers as child structures with audio context as parent */
  NAMED_REGISTER_AUDIO_RINGBUF(ctx->capture_buffer, "capture_buffer", (uintptr_t)(const void *)(ctx));
  NAMED_REGISTER_AUDIO_RINGBUF(ctx->playback_buffer, "playback_buffer", (uintptr_t)(const void *)(ctx));
  NAMED_REGISTER_AUDIO_RINGBUF(ctx->raw_capture_rb, "raw_capture_rb", (uintptr_t)(const void *)(ctx));
  NAMED_REGISTER_AUDIO_RINGBUF(ctx->raw_render_rb, "raw_render_rb", (uintptr_t)(const void *)(ctx));
  NAMED_REGISTER_AUDIO_RINGBUF(ctx->processed_playback_rb, "processed_playback_rb", (uintptr_t)(const void *)(ctx));
 
  log_info("Audio system initialized successfully (worker thread architecture enabled)");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, atomic_store_bool(), audio_ring_buffer_create(), audio_ring_buffer_create_for_capture(), audio_ring_buffer_destroy(), audio_context_t::capture_buffer, audio_context_t::capture_media_source, cond_destroy(), cond_init(), ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_THREAD, audio_context_t::initialized, log_debug, log_info, audio_context_t::monitor_local_media, mutex_destroy(), mutex_init(), NAMED_REGISTER, NAMED_REGISTER_ATOMIC, NAMED_REGISTER_AUDIO_RINGBUF, NAMED_REGISTER_COND, NAMED_REGISTER_MUTEX, audio_context_t::playback_buffer, audio_context_t::processed_playback_rb, audio_context_t::raw_capture_rb, audio_context_t::raw_render_rb, SAFE_FREE, SAFE_MALLOC, SAFE_MEMSET, SET_ERRNO, audio_context_t::shutting_down, audio_context_t::state_mutex, WORKER_BATCH_SAMPLES, audio_context_t::worker_capture_batch, audio_context_t::worker_cond, audio_context_t::worker_mutex, audio_context_t::worker_playback_batch, audio_context_t::worker_render_batch, audio_context_t::worker_running, and audio_context_t::worker_should_stop.

Referenced by audio_client_init(), session_audio_create(), and session_client_like_run().

◆ 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 2335 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 2227 of file lib/audio/audio.c.

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

◆ 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 2231 of file lib/audio/audio.c.

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

◆ 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:

Checks that the data pointer is not NULL
Checks that len is at least sizeof(audio_batch_header_t)
Verifies that batch_count and channels are within reasonable bounds
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 2269 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_packet_t::batch_count, audio_batch_info_t::batch_count, audio_batch_packet_t::channels, audio_batch_info_t::channels, ERROR_INVALID_PARAM, audio_batch_packet_t::sample_rate, audio_batch_info_t::sample_rate, SET_ERRNO, audio_batch_packet_t::total_samples, and audio_batch_info_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 2117 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 1373 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_u64(&rb->write_index);
  unsigned int read_idx = atomic_load_u64(&rb->read_index);
 
  if (write_idx >= read_idx) {
    return write_idx - read_idx;
  }
 
  return AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
}

References atomic_load_u64(), AUDIO_RING_BUFFER_SIZE, audio_ring_buffer::read_index, and audio_ring_buffer::write_index.

Referenced by audio_process_received_samples(), and audio_ring_buffer_available_write().

◆ 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 1390 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 1071 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)
  atomic_store_u64(&rb->write_index, 0);
  atomic_store_u64(&rb->read_index, 0);
  atomic_store_bool(&rb->discard_pending, false);
  atomic_store_u64(&rb->discard_to_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 atomic_store_bool(), atomic_store_u64(), audio_ring_buffer::data, audio_ring_buffer::discard_pending, audio_ring_buffer::discard_to_index, 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_flush_playback_buffers(), audio_stop_duplex(), and media_source_seek().

◆ 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 1014 of file lib/audio/audio.c.

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

Referenced by audio_init(), and session_audio_add_source().

◆ 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 1018 of file lib/audio/audio.c.

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

Referenced by add_client(), add_webrtc_client(), 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 1022 of file lib/audio/audio.c.

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

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

Referenced by add_client(), add_webrtc_client(), audio_destroy(), audio_init(), audio_start_duplex(), audio_stop_duplex(), cleanup_client_media_buffers(), session_audio_destroy(), and session_audio_remove_source().

◆ 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 1336 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_u64(&rb->write_index);
  unsigned int read_idx = atomic_load_u64(&rb->read_index);
 
  // 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 atomic_load_u64(), 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 1191 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
  }
 
  // Keep read_index consumer-owned while letting a producer request a flush.
  if (atomic_exchange_bool(&rb->discard_pending, false)) {
    unsigned int read_idx = atomic_load_u64(&rb->read_index);
    unsigned int discard_to = atomic_load_u64(&rb->discard_to_index);
    unsigned int advance = (discard_to + AUDIO_RING_BUFFER_SIZE - read_idx) % AUDIO_RING_BUFFER_SIZE;
    // A concurrent callback may already have consumed beyond the requested
    // boundary. In that case the target is behind us and must not rewind the
    // single-consumer index.
    if (advance < AUDIO_RING_BUFFER_SIZE / 2) {
      atomic_store_u64(&rb->read_index, discard_to);
      rb->last_sample = 0.0f;
      atomic_store_u64(&rb->crossfade_samples_remaining, 0);
    }
  }
 
  // 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_u64(&rb->write_index);
  unsigned int read_idx = atomic_load_u64(&rb->read_index);
 
  // 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_u64(&rb->jitter_buffer_filled);
  int crossfade_remaining = atomic_load_u64(&rb->crossfade_samples_remaining);
  bool fade_in = atomic_load_u64(&rb->crossfade_fade_in);
 
  // 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) {
    // Check if we've accumulated enough samples to start playback
    if (available >= AUDIO_JITTER_BUFFER_THRESHOLD) {
      atomic_store_u64(&rb->jitter_buffer_filled, true);
      atomic_store_u64(&rb->crossfade_samples_remaining, AUDIO_CROSSFADE_SAMPLES);
      atomic_store_u64(&rb->crossfade_fade_in, true);
      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(NS_PER_MS_INT, "Jitter buffer filling: %zu/%d samples (%.1f%%)", available,
                      AUDIO_JITTER_BUFFER_THRESHOLD, (100.0f * available) / AUDIO_JITTER_BUFFER_THRESHOLD);
      return 0; // Return 0 samples - caller will pad with silence
    }
  }
 
  // Periodic buffer health logging (every 5 seconds when healthy)
  unsigned int underruns = atomic_load_u64(&rb->underrun_count);
  log_dev_every(5 * NS_PER_MS_INT, "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_u64(&rb->underrun_count, 1) + 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_u64(&rb->read_index, new_read_idx);
 
  // 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_u64(&rb->crossfade_samples_remaining, new_crossfade_remaining);
    if (new_crossfade_remaining <= 0) {
      atomic_store_u64(&rb->crossfade_fade_in, false);
      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];
  }
 
  // Return ACTUAL number of samples read, not padded count
  // The caller (mixer) expects truthful return values to detect underruns
  // and handle silence padding externally. Internal padding creates double-padding bugs.
  //
  // This function was incorrectly returning `samples` even when
  // it only read `to_read` samples. This broke the mixer's underrun detection.
  return to_read;
}

Referenced by audio_read_samples(), mixer_process(), mixer_process_excluding_source(), session_audio_mix_excluding(), session_audio_read_captured(), and session_capture_read_audio().

◆ audio_ring_buffer_register_atomics()

void audio_ring_buffer_register_atomics	(	audio_ring_buffer_t *	rb,
		const char *	context_name
	)

#include <audio.h>

Register audio ring buffer atomic fields for debug tracking.

Parameters

rb	Audio ring buffer (must not be NULL)
context_name	Descriptive context name for registration (e.g. client_id)

Registers all atomic fields within the audio ring buffer with the named registry for debug tracking and –sync-state output. Should be called after creation.

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

                                                                                           {
  if (!rb || !context_name || !context_name[0]) {
    return;
  }
 
  // Register the ring buffer itself with a unique name
  NAMED_REGISTER_AUDIO_RINGBUF(rb, context_name, NULL);
 
  // Ring buffer indices (lock-free producer-consumer)
  NAMED_REGISTER_ATOMIC(&rb->write_index, "write_index_producer_position", (uintptr_t)(const void *)(rb));
  NAMED_REGISTER_ATOMIC(&rb->read_index, "read_index_consumer_position", (uintptr_t)(const void *)(rb));
  NAMED_REGISTER_ATOMIC(&rb->discard_to_index, "discard_to_index_producer_position", (uintptr_t)(const void *)(rb));
 
  // Jitter buffer state management
  NAMED_REGISTER_ATOMIC(&rb->jitter_buffer_filled, "jitter_buffer_has_filled_threshold_flag",
                        (uintptr_t)(const void *)(rb));
  NAMED_REGISTER_ATOMIC(&rb->crossfade_samples_remaining, "crossfade_samples_remaining_count",
                        (uintptr_t)(const void *)(rb));
  NAMED_REGISTER_ATOMIC(&rb->crossfade_fade_in, "crossfade_fade_in_direction_flag", (uintptr_t)(const void *)(rb));
 
  // Audio quality monitoring
  NAMED_REGISTER_ATOMIC(&rb->underrun_count, "audio_underrun_event_counter", (uintptr_t)(const void *)(rb));
}

References audio_ring_buffer::crossfade_fade_in, audio_ring_buffer::crossfade_samples_remaining, audio_ring_buffer::discard_to_index, audio_ring_buffer::jitter_buffer_filled, NAMED_REGISTER_ATOMIC, NAMED_REGISTER_AUDIO_RINGBUF, audio_ring_buffer::read_index, audio_ring_buffer::underrun_count, and audio_ring_buffer::write_index.

◆ audio_ring_buffer_unregister_atomics()

void audio_ring_buffer_unregister_atomics ( audio_ring_buffer_t * rb )

#include <audio.h>

Unregister audio ring buffer atomic fields.

Parameters

rb	Audio ring buffer (must not be NULL)

Unregisters all atomic fields registered by audio_ring_buffer_register_atomics().

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

                                                                   {
  if (!rb) {
    return;
  }
 
  NAMED_UNREGISTER(&rb->write_index);
  NAMED_UNREGISTER(&rb->read_index);
  NAMED_UNREGISTER(&rb->discard_to_index);
  NAMED_UNREGISTER(&rb->jitter_buffer_filled);
  NAMED_UNREGISTER(&rb->crossfade_samples_remaining);
  NAMED_UNREGISTER(&rb->crossfade_fade_in);
  NAMED_UNREGISTER(&rb->underrun_count);
}

References audio_ring_buffer::crossfade_fade_in, audio_ring_buffer::crossfade_samples_remaining, audio_ring_buffer::discard_to_index, audio_ring_buffer::jitter_buffer_filled, NAMED_UNREGISTER, audio_ring_buffer::read_index, audio_ring_buffer::underrun_count, and audio_ring_buffer::write_index.

Referenced by audio_ring_buffer_destroy().

◆ 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 1098 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_u64(&rb->write_index);
  unsigned int read_idx = atomic_load_u64(&rb->read_index);
 
  // 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);
  }
  // Reserve 1 slot to distinguish between full and empty states
  // (when buffer is full, write_idx will be just before read_idx, not equal to it)
  int available = AUDIO_RING_BUFFER_SIZE - 1 - buffer_level;
 
  // If playback has fallen behind, ask its consumer to skip the stale queue.
  // Dropping incoming samples here preserves the old backlog, so playback
  // drains outdated audio and then underruns before it can return to live data.
  if (buffer_level > AUDIO_JITTER_HIGH_WATER_MARK) {
    if (rb->jitter_buffer_enabled) {
      // The read callback owns read_index. Let it advance to the latest write
      // position atomically on its next invocation, then preserve this fresh
      // packet so audio resumes from the current stream position.
      audio_ring_buffer_discard_pending(rb);
      log_warn_every(LOG_RATE_FAST,
                     "Audio playback backlog (%d samples); requesting consumer to skip stale queued audio",
                     buffer_level);
    } else {
      // Capture queues also have a high-water mark, but their reader may be
      // processing a matching microphone/render interval. Retain the existing
      // policy there instead of changing the reader's timeline asynchronously.
      int target_writes = AUDIO_JITTER_TARGET_LEVEL - buffer_level;
      if (target_writes < 0) {
        target_writes = 0;
      }
 
      if (samples > target_writes) {
        int dropped = samples - target_writes;
        log_warn_every(LOG_RATE_FAST,
                       "Audio capture buffer high water mark exceeded (%d > %d): dropping %d incoming samples",
                       buffer_level, AUDIO_JITTER_HIGH_WATER_MARK, dropped);
        samples = target_writes;
      }
    }
  }
 
  // 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_u64(&rb->write_index, new_write_idx);
  }
 
  // Note: jitter buffer fill check is now done in read function for better control
 
  return ASCIICHAT_OK; // Success
}

References ASCIICHAT_OK, atomic_load_u64(), atomic_store_u64(), AUDIO_JITTER_HIGH_WATER_MARK, AUDIO_JITTER_TARGET_LEVEL, audio_ring_buffer_discard_pending(), AUDIO_RING_BUFFER_SIZE, audio_ring_buffer::data, ERROR_BUFFER, ERROR_INVALID_PARAM, audio_ring_buffer::jitter_buffer_enabled, 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(), handle_audio_packet(), and session_audio_write_source().

◆ 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 1607 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 2255 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_debug("✓ Audio thread real-time priority set successfully");
  }
  return result;
}

References ASCIICHAT_OK, asciichat_thread_set_realtime_priority(), and log_debug.

Referenced by audio_start_duplex().

◆ audio_should_enable_microphone()

bool audio_should_enable_microphone	(	audio_capture_source_t	source,
		bool	has_media_audio
	)

#include <audio.h>

Determine if microphone should be enabled based on audio source setting and media state.

Smart helper function for determining microphone input availability based on:

User's –audio-capture-source preference (auto, microphone, media, both, remote)
Whether media audio is currently being played (–file or –url)

Parameters

source	Audio capture policy from –audio-capture-source option
has_media_audio	True if media with audio is being played, false otherwise

Returns: true if microphone should be enabled, false otherwise

Behavior by capture source value:

AUDIO_CAPTURE_SOURCE_AUTO: Enable microphone only when no media audio (smart default)
AUDIO_CAPTURE_SOURCE_MIC: Always enable microphone (ignore media state)
AUDIO_CAPTURE_SOURCE_MEDIA: Never enable microphone (media-only)
AUDIO_CAPTURE_SOURCE_BOTH: Always enable microphone (allow simultaneous capture)
AUDIO_CAPTURE_SOURCE_REMOTE: Disable microphone and local media capture

Usage:

bool has_media = (media_file && strlen(media_file) > 0);
bool enable_mic = audio_should_enable_microphone(GET_OPTION(audio_capture_source), has_media);
if (enable_mic) {
    audio_ctx->playback_only = false;  // Allow microphone capture
} else {
    audio_ctx->playback_only = true;   // Disable microphone to prevent interference
}

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

                                                                                         {
  switch (source) {
  case AUDIO_CAPTURE_SOURCE_AUTO:
    return !has_media_audio;
 
  case AUDIO_CAPTURE_SOURCE_MIC:
    return true;
 
  case AUDIO_CAPTURE_SOURCE_MEDIA:
    return false;
 
  case AUDIO_CAPTURE_SOURCE_BOTH:
    return true;
 
  case AUDIO_CAPTURE_SOURCE_REMOTE:
    return false;
 
  default:
    return !has_media_audio;
  }
}

References AUDIO_CAPTURE_SOURCE_AUTO, AUDIO_CAPTURE_SOURCE_BOTH, AUDIO_CAPTURE_SOURCE_MEDIA, AUDIO_CAPTURE_SOURCE_MIC, and AUDIO_CAPTURE_SOURCE_REMOTE.

Referenced by audio_start_duplex(), and session_client_like_run().

◆ 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:

Reads from playback_buffer → outputs to speakers
Processes capture through AEC3 (using render as reference)
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 1632 of file lib/audio/audio.c.

                                                           {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
  }
 
  // Check if already running (without holding lock during blocking operations)
  // Do this check first before acquiring any locks
  if (ctx->duplex_stream || ctx->input_stream || ctx->output_stream) {
    return ASCIICHAT_OK;
  }
 
  bool media_audio = ctx->capture_media_source && media_source_has_audio(ctx->capture_media_source);
  if (!audio_should_enable_microphone(GET_OPTION(audio_capture_source), media_audio))
    ctx->playback_only = true;
  bool media_only = media_audio && ctx->playback_only;
 
  // Media-only recording can run through the software worker without an audio
  // device. Initialize PortAudio opportunistically so monitoring still works
  // when a speaker is available.
  asciichat_error_t pa_result = audio_ensure_portaudio_initialized();
  if (pa_result != ASCIICHAT_OK && !media_only)
    return pa_result;
 
  if (pa_result != ASCIICHAT_OK) {
    ctx->sample_rate = AUDIO_SAMPLE_RATE;
    log_warn("PortAudio unavailable; continuing media-only audio without an audio device");
    goto start_worker;
  }
 
  // Setup input parameters (skip if playback-only mode)
  PaStreamParameters inputParams = {0};
  const PaDeviceInfo *inputInfo = NULL;
  bool has_input = false;
 
  if (!ctx->playback_only) {
    if (GET_OPTION(microphone_index) >= 0) {
      inputParams.device = GET_OPTION(microphone_index);
    } else {
      inputParams.device = Pa_GetDefaultInputDevice();
    }
 
    if (inputParams.device == paNoDevice) {
      return SET_ERRNO(ERROR_AUDIO, "No input device available");
    }
 
    inputInfo = Pa_GetDeviceInfo(inputParams.device);
    if (!inputInfo) {
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_AUDIO, "Input device info not found");
    }
 
    has_input = true;
    inputParams.channelCount = AUDIO_CHANNELS;
    inputParams.sampleFormat = paFloat32;
    inputParams.suggestedLatency = inputInfo->defaultLowInputLatency;
    inputParams.hostApiSpecificStreamInfo = NULL;
  }
 
  // Setup output parameters
  PaStreamParameters outputParams;
  const PaDeviceInfo *outputInfo = NULL;
  bool has_output = false;
 
  if (GET_OPTION(audio_no_playback)) {
    outputParams.device = paNoDevice;
    log_info("Audio playback disabled by --no-audio-playback");
  } else if (GET_OPTION(speakers_index) >= 0) {
    outputParams.device = GET_OPTION(speakers_index);
  } else {
    outputParams.device = Pa_GetDefaultOutputDevice();
  }
 
  if (outputParams.device != paNoDevice) {
    outputInfo = Pa_GetDeviceInfo(outputParams.device);
    if (outputInfo) {
      has_output = true;
      outputParams.channelCount = AUDIO_CHANNELS;
      outputParams.sampleFormat = paFloat32;
      outputParams.suggestedLatency = outputInfo->defaultLowOutputLatency;
      outputParams.hostApiSpecificStreamInfo = NULL;
    } else {
      log_warn("Output device info not found for device %d", outputParams.device);
    }
  }
 
  // Store device rates for diagnostics (only access if device info was retrieved)
  ctx->input_device_rate = (has_input && inputInfo) ? inputInfo->defaultSampleRate : 0;
  ctx->output_device_rate = (has_output && outputInfo) ? outputInfo->defaultSampleRate : 0;
 
  log_debug("Opening audio:");
  if (has_input) {
    log_info("  Input:  %s (%.0f Hz)", inputInfo->name, inputInfo->defaultSampleRate);
  } else if (ctx->playback_only) {
    log_debug("  Input:  (playback-only mode - no microphone)");
  } else {
    log_debug("  Input:  (none)");
  }
  if (has_output) {
    log_info("  Output: %s (%.0f Hz)", outputInfo->name, outputInfo->defaultSampleRate);
  } else {
    log_debug("  Output: None (input-only mode - will send audio to server)");
  }
 
  // Keep capture and playback synchronized in one 48 kHz duplex stream when
  // both devices share a native rate. PortAudio handles conversion to/from
  // that rate. Separate streams are needed only when the devices themselves
  // run at different rates or one direction is unavailable.
  bool rates_differ = has_input && has_output && (inputInfo->defaultSampleRate != outputInfo->defaultSampleRate);
  bool try_separate = rates_differ || !has_input || !has_output;
  PaError err = paNoError;
 
  if (!try_separate) {
    // Try full-duplex first (preferred - perfect AEC3 timing)
    LOG_IO("portaudio", {
      err = Pa_OpenStream(&ctx->duplex_stream, &inputParams, &outputParams, AUDIO_SAMPLE_RATE, AUDIO_FRAMES_PER_BUFFER,
                          paClipOff, duplex_callback, ctx);
    });
 
    if (err == paNoError) {
      LOG_IO("portaudio", { err = Pa_StartStream(ctx->duplex_stream); });
      if (err != paNoError) {
        LOG_IO("portaudio", { 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) {
    // Use separate streams for non-48 kHz devices and single-direction modes.
    if (has_output && has_input) {
      log_info("Using separate native-rate input/output streams (%.0f Hz in, %.0f Hz out)",
               inputInfo->defaultSampleRate, outputInfo->defaultSampleRate);
      log_info("  Converting between device rates and the %.0f Hz audio pipeline", (double)AUDIO_SAMPLE_RATE);
    } else if (has_output) {
      log_debug("Using output-only mode (playback-only for mirror/media)");
    } else if (has_input) {
      log_info("Using input-only mode (no output device available)");
    }
 
    // 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) {
      return SET_ERRNO(ERROR_MEMORY, "Failed to create render buffer");
    }
 
    // Open output stream only if output device exists
    bool output_ok = false;
    double actual_output_rate = 0;
    if (has_output) {
      // Use the device's native rate first so conversion stays explicit and stateful.
      double native_rate = outputInfo->defaultSampleRate;
      if (native_rate <= 0.0) {
        native_rate = AUDIO_SAMPLE_RATE;
      }
      double preferred_rate = native_rate;
      double fallback_rate = (preferred_rate == AUDIO_SAMPLE_RATE) ? native_rate : AUDIO_SAMPLE_RATE;
 
      log_debug("Attempting output at native rate %.0f Hz (fallback %.0f Hz)", preferred_rate, fallback_rate);
 
      // Always use output_callback for output streams (both output-only and duplex modes)
      // PortAudio will invoke the callback whenever it needs audio data
      // The callback reads PCM supplied to the shared playback buffer.
      PaStreamCallback *callback = output_callback;
 
      // Try preferred rate first
      LOG_IO("portaudio", {
        err = Pa_OpenStream(&ctx->output_stream, NULL, &outputParams, preferred_rate, AUDIO_FRAMES_PER_BUFFER,
                            paClipOff, callback, ctx);
      });
 
      if (err == paNoError) {
        actual_output_rate = preferred_rate;
        output_ok = true;
        log_info("Output stream opened at %.0f Hz", preferred_rate);
      } else {
        log_warn("Failed to open output at %.0f Hz: %s, trying %.0f Hz", preferred_rate, Pa_GetErrorText(err),
                 fallback_rate);
 
        // If first Pa_OpenStream call left a partial stream, clean it up before retrying
        if (ctx->output_stream) {
          log_debug("Closing partially-opened output stream from failed preferred rate");
          LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
          ctx->output_stream = NULL;
        }
 
        // Try the other endpoint rate if the native rate is unavailable.
        LOG_IO("portaudio", {
          err = Pa_OpenStream(&ctx->output_stream, NULL, &outputParams, fallback_rate, AUDIO_FRAMES_PER_BUFFER,
                              paClipOff, callback, ctx);
        });
 
        if (err == paNoError) {
          actual_output_rate = fallback_rate;
          output_ok = true;
          log_info("Output stream opened at fallback rate %.0f Hz", fallback_rate);
        } else {
          log_warn("Failed to open output stream at fallback rate %.0f Hz: %s", fallback_rate, Pa_GetErrorText(err));
          // Clean up if fallback also failed
          if (ctx->output_stream) {
            log_debug("Closing partially-opened output stream from failed native rate");
            LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
            ctx->output_stream = NULL;
          }
        }
      }
 
      // Store actual output rate for resampling
      if (output_ok) {
        ctx->output_device_rate = actual_output_rate;
        ctx->output_resample_phase = 0.0;
        ctx->output_resample_previous = 0.0f;
        ctx->output_resample_has_previous = false;
        if (actual_output_rate != AUDIO_SAMPLE_RATE) {
          log_warn("⚠️  Output rate mismatch: %.0f Hz output vs %.0f Hz input - resampling will be used",
                   actual_output_rate, (double)AUDIO_SAMPLE_RATE);
        }
      }
    }
 
    // Open input stream only if we have input (skip for playback-only mode)
    bool input_ok = !has_input; // If no input, mark as OK (skip)
    if (has_input) {
      // Open at the device's native rate. The separate input callback converts
      // to AUDIO_SAMPLE_RATE before samples enter the shared processing path.
      double input_stream_rate = inputInfo->defaultSampleRate;
      if (input_stream_rate <= 0.0) {
        input_stream_rate = AUDIO_SAMPLE_RATE;
      }
      LOG_IO("portaudio", {
        err = Pa_OpenStream(&ctx->input_stream, &inputParams, NULL, input_stream_rate, AUDIO_FRAMES_PER_BUFFER,
                            paClipOff, input_callback, ctx);
      });
      input_ok = (err == paNoError);
      if (input_ok) {
        ctx->input_device_rate = input_stream_rate;
        ctx->input_resample_phase = 0.0;
        ctx->input_resample_previous = 0.0f;
        ctx->input_resample_has_previous = false;
        log_info("Input stream opened at native rate %.0f Hz", input_stream_rate);
      }
 
      // If input failed, try device 0 as fallback (HDMI on BeaglePlay)
      if (!input_ok) {
        log_debug("Input failed - trying device 0 as fallback");
 
        // Clean up partial stream from first attempt before retrying
        if (ctx->input_stream) {
          log_debug("Closing partially-opened input stream from failed primary device");
          LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
          ctx->input_stream = NULL;
        }
 
        PaStreamParameters fallback_input_params = inputParams;
        fallback_input_params.device = 0;
        const PaDeviceInfo *device_0_info = Pa_GetDeviceInfo(0);
        if (device_0_info && device_0_info->maxInputChannels > 0) {
          LOG_IO("portaudio", {
            err = Pa_OpenStream(&ctx->input_stream, &fallback_input_params, NULL, input_stream_rate,
                                AUDIO_FRAMES_PER_BUFFER, paClipOff, input_callback, ctx);
          });
          if (err == paNoError) {
            log_info("Input stream opened on device 0 (fallback from default)");
            input_ok = true;
          } else {
            log_warn("Fallback also failed on device 0: %s", Pa_GetErrorText(err));
            // Clean up if fallback also failed
            if (ctx->input_stream) {
              log_debug("Closing partially-opened input stream from failed fallback device");
              LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
              ctx->input_stream = NULL;
            }
          }
        }
      }
 
      if (!input_ok) {
        log_warn("Failed to open input stream: %s", Pa_GetErrorText(err));
      }
    }
 
    // Check if we got at least one stream working
    if (!input_ok && !output_ok && !media_only) {
      // Neither stream works - fail completely
      audio_ring_buffer_destroy(ctx->render_buffer);
      ctx->render_buffer = NULL;
      return SET_ERRNO(ERROR_AUDIO, "Failed to open both input and output streams");
    }
 
    // If output failed but input works, we can still send audio to server
    if (!output_ok && input_ok) {
      log_info("Output stream unavailable - continuing with input-only (can send audio to server)");
      ctx->output_stream = NULL;
    }
    // If input failed but output works, we can still receive audio from server
    if (!input_ok && output_ok) {
      log_info("Input stream unavailable - continuing with output-only (can receive audio from server)");
      ctx->input_stream = NULL;
    }
 
    // Start output stream if it's open
    if (ctx->output_stream) {
      LOG_IO("portaudio", { err = Pa_StartStream(ctx->output_stream); });
      if (err != paNoError) {
        if (ctx->input_stream) {
          LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
        }
        LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
        ctx->input_stream = NULL;
        ctx->output_stream = NULL;
        audio_ring_buffer_destroy(ctx->render_buffer);
        ctx->render_buffer = NULL;
        return SET_ERRNO(ERROR_AUDIO, "Failed to start output stream: %s", Pa_GetErrorText(err));
      }
    }
 
    // Start input stream if it's open
    if (ctx->input_stream) {
      LOG_IO("portaudio", { err = Pa_StartStream(ctx->input_stream); });
      if (err != paNoError) {
        if (ctx->output_stream) {
          LOG_IO("portaudio", { Pa_StopStream(ctx->output_stream); });
        }
        if (ctx->input_stream) {
          LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
        }
        if (ctx->output_stream) {
          LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
        }
        ctx->input_stream = NULL;
        ctx->output_stream = NULL;
        audio_ring_buffer_destroy(ctx->render_buffer);
        ctx->render_buffer = NULL;
        return SET_ERRNO(ERROR_AUDIO, "Failed to start input stream: %s", Pa_GetErrorText(err));
      }
    }
 
    ctx->separate_streams = true;
    log_debug("Separate streams started successfully");
  } else {
    ctx->separate_streams = false;
    log_info("Full-duplex stream started (single callback, perfect AEC3 timing)");
  }
start_worker:
 
  audio_set_realtime_priority();
 
  // Start worker thread for heavy audio processing
  if (!ctx->worker_running) {
    atomic_store_bool(&ctx->worker_should_stop, false);
    if (asciichat_thread_create(&ctx->worker_thread, "audio_worker", audio_worker_thread, ctx) != 0) {
      // Failed to create worker thread - stop streams and cleanup
      if (ctx->duplex_stream) {
        LOG_IO("portaudio", {
          Pa_StopStream(ctx->duplex_stream);
          Pa_CloseStream(ctx->duplex_stream);
        });
        ctx->duplex_stream = NULL;
      }
      if (ctx->input_stream) {
        LOG_IO("portaudio", {
          Pa_StopStream(ctx->input_stream);
          Pa_CloseStream(ctx->input_stream);
        });
        ctx->input_stream = NULL;
      }
      if (ctx->output_stream) {
        LOG_IO("portaudio", {
          Pa_StopStream(ctx->output_stream);
          Pa_CloseStream(ctx->output_stream);
        });
        ctx->output_stream = NULL;
      }
      audio_ring_buffer_destroy(ctx->render_buffer);
      ctx->render_buffer = NULL;
      return SET_ERRNO(ERROR_THREAD, "Failed to create worker thread");
    }
    ctx->worker_running = true;
    log_debug("Worker thread started successfully");
  }
 
  // Lock to update final state flags atomically
  mutex_lock(&ctx->state_mutex);
  ctx->running = true;
  ctx->sample_rate = AUDIO_SAMPLE_RATE;
  mutex_unlock(&ctx->state_mutex);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, asciichat_thread_create, atomic_store_bool(), AUDIO_CHANNELS, AUDIO_FRAMES_PER_BUFFER, audio_ring_buffer_create_for_capture(), audio_ring_buffer_destroy(), AUDIO_SAMPLE_RATE, audio_set_realtime_priority(), audio_should_enable_microphone(), audio_context_t::capture_media_source, audio_context_t::duplex_stream, ERROR_AUDIO, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_THREAD, GET_OPTION, audio_context_t::initialized, audio_context_t::input_device_rate, audio_context_t::input_resample_has_previous, audio_context_t::input_resample_phase, audio_context_t::input_resample_previous, audio_context_t::input_stream, log_debug, log_info, LOG_IO, log_warn, media_source_has_audio(), mutex_lock, mutex_unlock, audio_context_t::output_device_rate, audio_context_t::output_resample_has_previous, audio_context_t::output_resample_phase, audio_context_t::output_resample_previous, audio_context_t::output_stream, paNoError, audio_context_t::playback_only, audio_context_t::render_buffer, audio_context_t::running, audio_context_t::sample_rate, audio_context_t::separate_streams, SET_ERRNO, audio_context_t::state_mutex, audio_context_t::worker_running, audio_context_t::worker_should_stop, and audio_context_t::worker_thread.

Referenced by protocol_start_connection(), session_audio_start_duplex(), and session_client_like_run().

◆ 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 2028 of file lib/audio/audio.c.

                                                          {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
  }
 
  atomic_store_bool(&ctx->shutting_down, true);
 
  // Stop worker thread before stopping streams
  if (ctx->worker_running) {
    log_debug("Stopping worker thread");
    atomic_store_bool(&ctx->worker_should_stop, true);
    cond_signal(&ctx->worker_cond); // Wake up worker if waiting
    asciichat_thread_join(&ctx->worker_thread, NULL);
    ctx->worker_running = false;
    log_debug("Worker thread stopped successfully");
  }
 
  if (ctx->playback_buffer) {
    audio_ring_buffer_clear(ctx->playback_buffer);
  }
 
  mutex_lock(&ctx->state_mutex);
 
  if (ctx->duplex_stream) {
    log_debug("Stopping duplex stream");
    PaError err;
    LOG_IO("portaudio", { err = Pa_StopStream(ctx->duplex_stream); });
    if (err != paNoError) {
      log_warn("Pa_StopStream failed: %s", Pa_GetErrorText(err));
    }
    log_debug("Closing duplex stream");
    LOG_IO("portaudio", { err = Pa_CloseStream(ctx->duplex_stream); });
    if (err != paNoError) {
      log_warn("Pa_CloseStream failed: %s", Pa_GetErrorText(err));
    } else {
      log_debug("Duplex stream closed successfully");
    }
    ctx->duplex_stream = NULL;
  }
 
  // Stop separate streams if used
  if (ctx->input_stream) {
    log_debug("Stopping input stream");
    PaError err;
    LOG_IO("portaudio", { err = Pa_StopStream(ctx->input_stream); });
    if (err != paNoError) {
      log_warn("Pa_StopStream input failed: %s", Pa_GetErrorText(err));
    }
    log_debug("Closing input stream");
    LOG_IO("portaudio", { err = Pa_CloseStream(ctx->input_stream); });
    if (err != paNoError) {
      log_warn("Pa_CloseStream input failed: %s", Pa_GetErrorText(err));
    } else {
      log_debug("Input stream closed successfully");
    }
    ctx->input_stream = NULL;
  }
 
  if (ctx->output_stream) {
    log_debug("Stopping output stream");
    PaError err;
    LOG_IO("portaudio", { err = Pa_StopStream(ctx->output_stream); });
    if (err != paNoError) {
      log_warn("Pa_StopStream output failed: %s", Pa_GetErrorText(err));
    }
    log_debug("Closing output stream");
    LOG_IO("portaudio", { err = Pa_CloseStream(ctx->output_stream); });
    if (err != paNoError) {
      log_warn("Pa_CloseStream output failed: %s", Pa_GetErrorText(err));
    } else {
      log_debug("Output stream closed successfully");
    }
    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_debug("Audio stopped");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, asciichat_thread_join, atomic_store_bool(), audio_ring_buffer_clear(), audio_ring_buffer_destroy(), cond_signal(), audio_context_t::duplex_stream, ERROR_INVALID_STATE, audio_context_t::initialized, audio_context_t::input_stream, log_debug, LOG_IO, log_warn, mutex_lock, mutex_unlock, audio_context_t::output_stream, paNoError, 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, audio_context_t::state_mutex, audio_context_t::worker_cond, audio_context_t::worker_running, audio_context_t::worker_should_stop, and audio_context_t::worker_thread.

Referenced by audio_cleanup(), audio_destroy(), session_audio_stop(), and session_client_like_run().

◆ audio_terminate_portaudio_final()

void audio_terminate_portaudio_final ( void )

#include <audio.h>

Terminate PortAudio and free all device resources.

This must be called at program shutdown to free device structures allocated by ALSA/libpulse during Pa_Initialize(). Should be called AFTER all audio contexts are destroyed and other session cleanup is complete.

Note: This is only needed if you want to ensure all memory is freed at exit. In normal operation, the OS will clean up when the process terminates.

This must be called to actually free device structures allocated by ALSA/libpulse. It should be called AFTER all audio contexts are destroyed and session cleanup is complete.

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

                                           {
  if (lifecycle_shutdown(&g_pa_lc)) {
    log_debug("[PORTAUDIO_TERM] Calling Pa_Terminate() to release PortAudio");
 
    PaError err;
    LOG_IO("portaudio", { err = Pa_Terminate(); });
 
    log_debug("[PORTAUDIO_TERM] Pa_Terminate() returned: %s", Pa_GetErrorText(err));
  }
}

References lifecycle_shutdown(), log_debug, and LOG_IO.

Referenced by audio_cleanup().

◆ 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 2294 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 2128 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_bool(&ctx->shutting_down)) {
    return ASCIICHAT_OK; // Silently discard
  }
 
  audio_recording_submit(AUDIO_RECORDING_REMOTE, buffer, num_samples, time_get_ns());
  audio_visualization_submit(AUDIO_VISUALIZATION_SOURCE_REMOTE, buffer, (size_t)num_samples);
  asciichat_error_t result = audio_ring_buffer_write(ctx->playback_buffer, buffer, num_samples);
 
  return result;
}

References ASCIICHAT_OK, atomic_load_bool(), AUDIO_RECORDING_REMOTE, audio_recording_submit(), audio_ring_buffer_write(), AUDIO_VISUALIZATION_SOURCE_REMOTE, audio_visualization_submit(), ERROR_INVALID_PARAM, audio_context_t::initialized, audio_context_t::playback_buffer, SET_ERRNO, audio_context_t::shutting_down, and time_get_ns().

Referenced by audio_process_received_samples(), and session_audio_write_playback().

◆ 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 1157 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 1165 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 1173 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 75 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 86 of file mixer.c.

                                                            {
  comp->sample_rate = sample_rate;
  comp->envelope = 0.0f;
  comp->gain_lin = 1.0f;
 
  // Set default parameters with 0dB makeup gain (unity)
  // Soft clip at 0.7 provides 3dB headroom to prevent hard clipping
  // Ducking and crowd scaling naturally reduce volume, no compensation needed
  compressor_set_params(comp, -10.0f, 4.0f, 10 * NS_PER_MS_INT, 100 * NS_PER_MS_INT, 0.0f);
}

References compressor_set_params(), compressor_t::envelope, compressor_t::gain_lin, NS_PER_MS_INT, 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 131 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,
		uint64_t	attack_ns,
		uint64_t	release_ns,
		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 97 of file mixer.c.

                                            {
  comp->threshold_dB = threshold_dB;
  comp->ratio = ratio;
  comp->attack_ns = attack_ns;
  comp->release_ns = release_ns;
  comp->makeup_dB = makeup_dB;
  comp->knee_dB = 2.0f; // Fixed soft knee
 
  // Calculate time constants
  float attack_tau = (float)attack_ns / NS_PER_SEC;
  float release_tau = (float)release_ns / NS_PER_SEC;
  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_ns, compressor_t::knee_dB, compressor_t::makeup_dB, NS_PER_SEC, compressor_t::ratio, compressor_t::release_coeff, compressor_t::release_ns, 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 1218 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 67 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_destroy()

void ducking_destroy ( 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 210 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_destroy() to prevent memory leaks.

Returns: ASCIICHAT_OK on success, error code on failure

Definition at line 155 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_ns = 10 * NS_PER_MS_INT;   // Slower attack (10ms)
  duck->release_ns = 200 * NS_PER_MS_INT; // Slower release (200ms)
  duck->envelope = NULL;
  duck->gain = NULL;
 
  // Calculate time constants
  float attack_tau = (float)duck->attack_ns / NS_PER_SEC;
  float release_tau = (float)duck->release_ns / NS_PER_SEC;
  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_ns, ducking_t::atten_dB, ducking_t::envelope, ERROR_BUFFER_OVERFLOW, ERROR_INVALID_PARAM, ERROR_MEMORY, ducking_t::gain, ducking_t::leader_margin_dB, NS_PER_MS_INT, NS_PER_SEC, ducking_t::release_coeff, ducking_t::release_ns, 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 228 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,
		uint64_t	attack_ns,
		uint64_t	release_ns
	)

#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 219 of file mixer.c.

                                             {
  duck->threshold_dB = threshold_dB;
  duck->leader_margin_dB = leader_margin_dB;
  duck->atten_dB = atten_dB;
  duck->attack_ns = attack_ns;
  duck->release_ns = release_ns;
}

References ducking_t::attack_ns, ducking_t::atten_dB, ducking_t::leader_margin_dB, ducking_t::release_ns, 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 1195 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 1207 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 1144 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 1010 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 1046 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 1032 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 1024 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 1153 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 71 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 1060 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 1095 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 1083 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 1076 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,
		const char *	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 424 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] == NULL) {
      slot = i;
      break;
    }
  }
 
  if (slot == -1) {
    rwlock_wrunlock(&mixer->source_lock);
    log_warn("Mixer: No available slots for client %s", client_id);
    return -1;
  }
 
  mixer->source_buffers[slot] = buffer;
  // Duplicate the client_id string - we own this memory now
  size_t client_id_len = strlen(client_id) + 1;
  mixer->source_ids[slot] = SAFE_MALLOC(client_id_len, char *);
  if (!mixer->source_ids[slot]) {
    log_warn("Mixer: Failed to allocate memory for client_id %s", client_id);
    mixer->source_buffers[slot] = NULL;
    rwlock_wrunlock(&mixer->source_lock);
    return -1;
  }
  asciichat_error_t strcpy_result = SAFE_STRCPY((char *)mixer->source_ids[slot], client_id_len, client_id);
  if (strcpy_result != ASCIICHAT_OK) {
    log_error("Mixer: Failed to copy client_id: %s", asciichat_error_string(strcpy_result));
    SAFE_FREE(mixer->source_ids[slot]);
    mixer->source_buffers[slot] = NULL;
    rwlock_wrunlock(&mixer->source_lock);
    return -1;
  }
  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
  // Hash table optimization disabled for string-based client_ids (linear search is acceptable for small mixer sizes)
 
  rwlock_wrunlock(&mixer->source_lock);
 
  log_info("Mixer: Added source for client %s at slot %d", client_id, slot);
  return slot;
}

References mixer_t::active_sources_mask, ASCIICHAT_OK, log_error, log_info, log_warn, mixer_t::max_sources, mixer_t::num_sources, rwlock_wrlock, rwlock_wrunlock, SAFE_FREE, SAFE_MALLOC, SAFE_STRCPY, mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_ids, and mixer_t::source_lock.

Referenced by add_client(), and add_webrtc_client().

◆ 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 262 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;
  memset(mixer->listener_buffers, 0, sizeof(mixer->listener_buffers));
 
  // 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(const char *), &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, const char **);
  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
  for (int i = 0; i < 256; i++) {
    mixer->source_id_to_index[i] = MIXER_HASH_INVALID;
  }
 
  // 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, "audio_mixer_sources") != 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_debug("Audio mixer created: max_sources=%d, sample_rate=%d", max_sources, sample_rate);
 
  // Register mixer and its sync primitives for debugging
  NAMED_REGISTER_MIXER(mixer, "audio_mixer", NULL);
  NAMED_REGISTER_RWLOCK(&mixer->source_lock, "source_lock", (uintptr_t)(const void *)(mixer));
 
  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, mixer_t::listener_buffers, log_debug, mixer_t::max_sources, mixer_t::mix_buffer, MIXER_FRAME_SIZE, MIXER_HASH_INVALID, MIXER_MAX_SOURCES, NAMED_REGISTER_MIXER, NAMED_REGISTER_RWLOCK, 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.

◆ 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 396 of file mixer.c.

                                   {
  if (!mixer)
    return;
 
  NAMED_UNREGISTER(mixer);
 
  // OPTIMIZATION 2: Destroy reader-writer lock
  rwlock_destroy(&mixer->source_lock);
 
  ducking_destroy(&mixer->ducking);
 
  // Free all allocated client_id strings before freeing the array itself
  for (int i = 0; i < mixer->max_sources; i++) {
    for (int j = 0; j < mixer->max_sources; j++)
      SAFE_FREE(mixer->listener_buffers[i][j]);
    if (mixer->source_ids[i] != NULL) {
      SAFE_FREE(mixer->source_ids[i]);
    }
  }
 
  SAFE_FREE(mixer->source_buffers);
  SAFE_FREE(mixer->source_ids);
  SAFE_FREE(mixer->source_active);
  SAFE_FREE(mixer->mix_buffer);
  SAFE_FREE(mixer);
  log_debug("Audio mixer destroyed");
}

References mixer_t::ducking, ducking_destroy(), mixer_t::listener_buffers, log_debug, mixer_t::max_sources, mixer_t::mix_buffer, NAMED_UNREGISTER, rwlock_destroy(), SAFE_FREE, mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_ids, and mixer_t::source_lock.

◆ 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 542 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;
 
      // Soft clip at 0.7 to provide 3dB headroom and prevent hard clipping
      // With +6dB makeup gain, peaks can exceed 1.0, so we need headroom
      // threshold=0.7 maps asymptotically toward 1.0, preventing harsh distortion
      output[frame_start + s] = soft_clip(mix, 0.7f, 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 687 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
 
  // Serialize sample distribution and mutable ducking/compressor state.
  rwlock_wrlock(&mixer->source_lock);
 
  // Clear output buffer
  SAFE_MEMSET(output, num_samples * sizeof(float), 0, num_samples * sizeof(float));
 
  // Source IDs are strings; match the complete ID hash used by the caller.
  uint8_t exclude_index = MIXER_HASH_INVALID;
  for (int i = 0; i < mixer->max_sources; i++) {
    if (mixer->source_ids[i] && fnv1a_hash_string(mixer->source_ids[i]) == exclude_client_id) {
      exclude_index = (uint8_t)i;
      break;
    }
  }
  if (exclude_index != MIXER_HASH_INVALID)
    mixer_distribute_samples(mixer);
  uint64_t active_mask = mixer->active_sources_mask;
 
  // Validate exclude_index before using in bitshift
  // - exclude_index == MIXER_HASH_INVALID means "not found" (sentinel value from initialization)
  // - exclude_index >= MIXER_MAX_SOURCES would cause undefined behavior in bitshift
  bool valid_exclude = (exclude_index < MIXER_MAX_SOURCES && exclude_index != MIXER_HASH_INVALID);
 
  if (valid_exclude) {
    // Apply exclusion to prevent echo feedback
    uint64_t mask_without_excluded = active_mask & ~(1ULL << exclude_index);
    active_mask = mask_without_excluded;
 
    // DIAGNOSTIC: Log which client was excluded and which remain active
    log_dev_every(
        4500 * US_PER_MS_INT,
        "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_dev_every(4500 * US_PER_MS_INT,
                  "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_wrunlock(&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;
 
    uint64_t read_start_ns = time_get_ns();
 
    // 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 = 0;
        if (valid_exclude) {
          mixer_listener_buffer_t *queue = mixer->listener_buffers[exclude_index][i];
          if (queue && queue->count >= (size_t)frame_size) {
            samples_read_size = (size_t)frame_size;
            for (int s = 0; s < frame_size; s++)
              source_samples[source_count][s] = queue->samples[(queue->read + s) % MIXER_LISTENER_SAMPLES];
            queue->read = (queue->read + samples_read_size) % MIXER_LISTENER_SAMPLES;
            queue->count -= samples_read_size;
          }
        } else {
          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_dev_every(NS_PER_MS_INT, "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++;
        }
      }
    }
 
    uint64_t read_end_ns = time_get_ns();
    uint64_t read_time_ns = time_elapsed_ns(read_start_ns, read_end_ns);
 
    if (read_time_ns > 10 * NS_PER_MS_INT) {
      char read_time_str[32];
      time_pretty(read_time_ns, -1, read_time_str, sizeof(read_time_str));
      log_warn_every(LOG_RATE_DEFAULT, "Mixer: Slow source reading took %s for %d sources", read_time_str,
                     source_count);
    }
 
    if (GET_OPTION(no_audio_mixer)) {
      for (int sample = 0; sample < frame_size; sample++) {
        for (int source = 0; source < source_count; source++)
          output[frame_start + sample] += source_samples[source][sample];
      }
      continue;
    }
 
    // 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;
 
      // Soft clip at 0.7 to provide 3dB headroom and prevent hard clipping
      // With +6dB makeup gain, peaks can exceed 1.0, so we need headroom
      // threshold=0.7 maps asymptotically toward 1.0, preventing harsh distortion
      output[frame_start + s] = soft_clip(mix, 0.7f, 3.0f);
    }
  }
 
  rwlock_wrunlock(&mixer->source_lock);
 
#ifndef NDEBUG
  STOP_TIMER_AND_LOG_EVERY(warn, NS_PER_SEC_INT, 2 * NS_PER_MS_INT, "mixer_total", "Mixer took");
#endif
 
  return num_samples;
}

References mixer_t::active_sources_mask, ducking_t::attack_coeff, audio_ring_buffer_read(), mixer_t::base_gain, mixer_t::compressor, compressor_process_sample(), mixer_listener_buffer::count, mixer_t::crowd_alpha, db_to_linear(), mixer_t::ducking, ducking_process_frame(), ducking_t::envelope, ducking_t::gain, GET_OPTION, mixer_t::listener_buffers, log_dev_every, LOG_RATE_DEFAULT, log_warn_every, mixer_t::max_sources, mixer_t::mix_buffer, MIXER_FRAME_SIZE, MIXER_HASH_INVALID, MIXER_LISTENER_SAMPLES, MIXER_MAX_SOURCES, NS_PER_MS_INT, NS_PER_SEC_INT, mixer_listener_buffer::read, ducking_t::release_coeff, rwlock_wrlock, rwlock_wrunlock, SAFE_MEMSET, mixer_listener_buffer::samples, soft_clip(), mixer_t::source_buffers, mixer_t::source_ids, mixer_t::source_lock, START_TIMER, STOP_TIMER, STOP_TIMER_AND_LOG_EVERY, time_elapsed_ns(), time_get_ns(), time_pretty(), and US_PER_MS_INT.

Referenced by client_audio_render_thread().

◆ mixer_remove_source()

void mixer_remove_source	(	mixer_t *	mixer,
		const char *	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 477 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] != NULL && strcmp(mixer->source_ids[i], client_id) == 0) {
      for (int j = 0; j < mixer->max_sources; j++) {
        SAFE_FREE(mixer->listener_buffers[i][j]);
        if (j != i)
          SAFE_FREE(mixer->listener_buffers[j][i]);
      }
      mixer->source_buffers[i] = NULL;
      // Free the allocated client_id string
      SAFE_FREE(mixer->source_ids[i]);
      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
      // Hash table optimization disabled for string-based client_ids
 
      // 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 %s 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, mixer_t::listener_buffers, log_info, mixer_t::max_sources, mixer_t::num_sources, rwlock_wrlock, rwlock_wrunlock, SAFE_FREE, mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_ids, and mixer_t::source_lock.

Referenced by remove_client().

◆ mixer_set_source_active()

void mixer_set_source_active	(	mixer_t *	mixer,
		const char *	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 515 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] != NULL && strcmp(mixer->source_ids[i], client_id) == 0) {
      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 %s 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 925 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 * NS_PER_MS_INT, 50 * NS_PER_MS_INT, 0.9f);
}

References noise_gate_t::envelope, noise_gate_t::gate_open, noise_gate_set_params(), NS_PER_MS_INT, 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 1001 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 982 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 957 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,
		uint64_t	attack_ns,
		uint64_t	release_ns,
		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 939 of file mixer.c.

                                             {
  if (!gate)
    return;
 
  gate->threshold = threshold;
  gate->attack_ns = attack_ns;
  gate->release_ns = release_ns;
  gate->hysteresis = hysteresis;
 
  // Calculate coefficients for envelope follower
  // Using exponential moving average: coeff = 1 - exp(-1 / (time_s * sample_rate))
  float attack_s = (float)attack_ns / NS_PER_SEC;
  float release_s = (float)release_ns / NS_PER_SEC;
  gate->attack_coeff = 1.0f - expf(-1.0f / (attack_s * gate->sample_rate + 1e-12f));
  gate->release_coeff = 1.0f - expf(-1.0f / (release_s * gate->sample_rate + 1e-12f));
}

References noise_gate_t::attack_coeff, noise_gate_t::attack_ns, noise_gate_t::hysteresis, NS_PER_SEC, noise_gate_t::release_coeff, noise_gate_t::release_ns, 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.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 74 of file opus.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);
 
  // Register Opus decoder for debugging
  NAMED_REGISTER_CONTEXT(codec, "opus_decoder", "opus_codec", NULL);
 
  return codec;
}

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

Referenced by handle_stream_start_packet(), and session_host_start_render().

◆ opus_codec_create_encoder()

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

#include <opus.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 19 of file opus.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;
  }
 
  // Enable DTX (Discontinuous Transmission) for efficient silence frame encoding
  // DTX allows the encoder to produce very small packets (3-4 bytes) for silence,
  // reducing bandwidth usage while maintaining audio quality for voice/music
  error = opus_encoder_ctl(codec->encoder, OPUS_SET_DTX(1));
  if (error != OPUS_OK) {
    log_warn("Failed to enable Opus DTX: %s (continuing without DTX)", opus_strerror(error));
  }
 
  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, DTX enabled", sample_rate, bitrate);
 
  // Register Opus encoder for debugging
  NAMED_REGISTER_CONTEXT(codec, "opus_encoder", "opus_codec", NULL);
 
  return codec;
}

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

Referenced by client_audio_render_thread(), session_host_start_render(), and session_participant_start_audio_capture().

◆ 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.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 143 of file opus.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.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 230 of file opus.c.

                                             {
  if (!codec) {
    return;
  }
 
  NAMED_UNREGISTER(codec);
 
  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, NAMED_UNREGISTER, SAFE_FREE, and opus_codec_t::tmp_buffer.

Referenced by cleanup_client_media_buffers(), client_audio_render_thread(), session_host_destroy(), session_host_start_render(), session_host_stop_render(), and session_participant_destroy().

◆ 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.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 112 of file opus.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.h>

Get current encoder bitrate.

Parameters

codec Opus encoder

Returns: Bitrate in bits per second, negative on error

Definition at line 195 of file opus.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.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 178 of file opus.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.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 211 of file opus.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 629 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 1136 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 1109 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 1122 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 343 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_ns [1/3]

uint64_t compressor_t::attack_ns

Attack time in nanoseconds (how fast compression kicks in)

Definition at line 145 of file mixer.h.

Referenced by compressor_set_params().

◆ attack_ns [2/3]

uint64_t noise_gate_t::attack_ns

Attack time in nanoseconds (how fast gate opens)

Definition at line 184 of file mixer.h.

Referenced by noise_gate_set_params().

◆ attack_ns [3/3]

uint64_t ducking_t::attack_ns

Ducking attack time in nanoseconds.

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 355 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 360 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 353 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 358 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_destroy(), 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_destroy(), 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().

◆ listener_buffers

struct mixer_listener_buffer* mixer_t::listener_buffers[32][32]

Definition at line 336 of file mixer.h.

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

◆ 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 mixer_add_source(), mixer_create(), mixer_destroy(), 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 363 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_ns [1/3]

uint64_t compressor_t::release_ns

Release time in nanoseconds (how fast compression releases)

Definition at line 147 of file mixer.h.

Referenced by compressor_set_params().

◆ release_ns [2/3]

uint64_t noise_gate_t::release_ns

Release time in nanoseconds (how fast gate closes)

Definition at line 186 of file mixer.h.

Referenced by noise_gate_set_params().

◆ release_ns [3/3]

uint64_t ducking_t::release_ns

Ducking release time in nanoseconds.

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 340 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 mixer_add_source(), mixer_create(), mixer_destroy(), mixer_process(), mixer_process_excluding_source(), and mixer_remove_source().

◆ source_id_at_hash

const char* mixer_t::source_id_at_hash[256]

Client ID strings stored at each hash index for collision detection.

Definition at line 347 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 strings)

Definition at line 345 of file mixer.h.

Referenced by mixer_create().

◆ source_ids

const char** mixer_t::source_ids

Array of client ID strings (one per source slot)

Definition at line 338 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().

◆ source_lock

rwlock_t mixer_t::source_lock

Reader-writer lock protecting source arrays and bitset.

Definition at line 350 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().

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Mixer Lifecycle Functions

Source Management Functions

Audio Processing Functions

Utility Functions

Compressor Functions

Ducking Functions

Noise Gate Functions

High-Pass Filter Functions

Low-Pass Filter Functions

Buffer Utility Functions

Soft Clipping Functions

Audio Mixing Configuration

Detailed Description

CORE FEATURES:

AUDIO ARCHITECTURE:

AUDIO PARAMETERS:

THREAD SAFETY:

PLATFORM SUPPORT:

CORE FEATURES:

AUDIO PROCESSING PIPELINE:

DUCKING SYSTEM:

COMPRESSION:

OPTIMIZATIONS:

THREAD SAFETY:

OPUS CODEC FEATURES:

USAGE EXAMPLE:

Audio README

Overview

What does the audio system do?

Architecture

How does PortAudio work?

What about ring buffers?

How do we handle threading?

Audio Parameters

What are the defaults?

What can I configure?

Operations

Initialization

Audio Capture

Audio Playback

Cleanup

Platform Support

Performance

How much latency do we have?

How much CPU does audio use?

How much bandwidth does audio use?

Ring Buffers

Threading

Integration

Macro Definition Documentation

◆ AUDIO_BUFFER_SIZE

◆ AUDIO_CHANNELS

◆ AUDIO_FRAMES_PER_BUFFER

◆ AUDIO_SAMPLE_RATE

◆ MIXER_FRAME_SIZE

◆ MIXER_HASH_INVALID

◆ MIXER_MAX_SOURCES

Typedef Documentation

◆ OpusDecoder

◆ OpusEncoder

Enumeration Type Documentation

◆ opus_application_t

Function Documentation

◆ apply_gain_buffer()

◆ audio_dequantize_samples()

◆ audio_destroy()

◆ audio_flush_playback_buffers()

◆ audio_free_device_list()

◆ audio_init()

◆ audio_is_supported_sample_rate()

◆ audio_list_input_devices()

◆ audio_list_output_devices()

◆ audio_parse_batch_header()