ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
Audio

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
 When code needs to work with audio device info, it keeps index, max_input_channels, max_output_channels, default_sample_rate here instead of scattering it across globals. Initialization establishes the handles and sizes; teardown must release any allocation, lock, thread, or callback context recorded in those fields. 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
 This is the handoff point for compressor. Callers fill threshold_dB, knee_dB, ratio, attack_ns before passing it on; consumers read the values during the operation and return ownership only where the member contract explicitly says they do. More...
struct  highpass_filter_t
 noise gate keeps the values that move through the subsystem: threshold, attack_ns, release_ns, hysteresis. Some members are pointers into caller- or subsystem-owned memory, so lifetime follows the API that populated them rather than the struct copy itself. More...
struct  lowpass_filter_t
 This is the handoff point for highpass filter. Callers fill cutoff_hz, sample_rate, alpha, prev_input before passing it on; consumers read the values during the operation and return ownership only where the member contract explicitly says they do. More...
struct  ducking_t
 Ducking system settings and state. More...
struct  mixer_t
 For ducking, this is the live record that ties threshold_dB, leader_margin_dB, atten_dB, attack_ns together. The owning code creates it, updates it while work is active, and releases its handles and pointed-to storage before freeing the record. More...
struct  opus_codec_t
 State for one Opus encoding or decoding direction. More...

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 }
 State for one Opus encoding or decoding direction. 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.
asciichat_error_t audio_opus_configure_encoder (OpusEncoder *encoder, int bitrate)
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_encoder_channels (opus_application_t application, int sample_rate, int bitrate, int channels)
opus_codec_t * opus_codec_create_decoder (int sample_rate)
 Create an Opus decoder.
opus_codec_t * opus_codec_create_decoder_channels (int sample_rate, int channels)
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.
atomic_t mixer_t::active_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).
unsigned mixer_t::channels
struct spectral_processor * mixer_t::spectral_left [128+1]
struct spectral_processor * mixer_t::spectral_right [128+1]
audio_ring_buffer_t ** mixer_t::source_buffers
 Array of pointers to client audio ring buffers.
struct mixer_listener_buffer * mixer_t::listener_buffers [128][128]
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 [((128+63)/64)]
 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.
mixer_t * mixer_create_channels (int max_sources, int sample_rate, unsigned channels)
int mixer_source_count (const mixer_t *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   MAX_SESSION_PARTICIPANTS
 Maximum number of simultaneous audio sources.
#define MIXER_MASK_WORDS   ((MIXER_MAX_SOURCES + 63) / 64)
#define MIXER_FRAME_SIZE   256
 Number of samples processed per audio frame.

Detailed Description

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: Interleaved stereo internally; device layouts are negotiated
  • Buffer Size: 256 frames per buffer (low latency)
  • Format: 32-bit floating point samples

THREAD SAFETY:

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

PLATFORM SUPPORT:

  • Windows: DirectSound, WASAPI, or ASIO backends
  • Linux: ALSA backend only (JACK explicitly disabled)
  • macOS: CoreAudio backend
Note
Audio capture and playback can be started/stopped independently.
The audio system uses ring buffers to smooth out timing variations between capture/playback threads and network I/O.
Real-time priority is automatically requested on supported platforms to minimize audio glitches and latency.
Author
Zachary Fogg me@zf.nosp@m.o.gg
Date
October 2025

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

CORE FEATURES:

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

AUDIO PROCESSING PIPELINE:

The mixer processes audio through the following stages:

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

DUCKING SYSTEM:

The ducking system automatically:

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

COMPRESSION:

The compressor provides:

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

OPTIMIZATIONS:

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

THREAD SAFETY:

  • Source arrays protected by reader-writer locks
  • Bitset operations are atomic
  • Mix processing is thread-safe once sources are locked
Note
The mixer processes audio in fixed-size frames (256 samples) for consistent latency and processing behavior.
Ducking parameters should be tuned based on room acoustics and expected participant count for optimal performance.
Crowd scaling automatically reduces per-source volume as more participants join, preventing audio overload.
Author
Zachary Fogg me@zf.nosp@m.o.gg
Date
October 2025

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

OPUS CODEC FEATURES:

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

USAGE EXAMPLE:

// Create encoder for voice at 24 kbps
// 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
// Decode received audio
float decoded[882];
int decoded_samples = opus_codec_decode(decoder, compressed, encoded_bytes, decoded, 882);
// Cleanup
opus_codec_t * opus_codec_create_decoder(int sample_rate)
Create an Opus decoder.
Definition opus.c:87
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.
Definition opus.c:171
opus_codec_t * opus_codec_create_encoder(opus_application_t application, int sample_rate, int bitrate)
Create an Opus encoder.
Definition opus.c:35
void opus_codec_destroy(opus_codec_t *codec)
Destroy an Opus codec instance.
Definition opus.c:271
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.
Definition opus.c:132
@ OPUS_APPLICATION_VOIP
Voice over IP (optimized for speech).
Definition opus.h:85
unsigned char uint8_t
State for one Opus encoding or decoding direction.
Definition opus.h:105
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

Macro Definition Documentation

◆ MIXER_FRAME_SIZE

#define MIXER_FRAME_SIZE   256

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

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

◆ MIXER_HASH_INVALID

#define MIXER_HASH_INVALID   0xFF

#include <include/ascii-chat/audio/mixer.h>

Invalid index sentinel value for mixer hash table.

Definition at line 489 of file mixer.h.

Referenced by mixer_create_channels(), and mixer_process_excluding_source().

◆ MIXER_MASK_WORDS

#define MIXER_MASK_WORDS   ((MIXER_MAX_SOURCES + 63) / 64)

#include <include/ascii-chat/audio/mixer.h>

Definition at line 106 of file mixer.h.

Referenced by mixer_process_excluding_source().

◆ MIXER_MAX_SOURCES

#define MIXER_MAX_SOURCES   MAX_SESSION_PARTICIPANTS

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

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

Typedef Documentation

◆ OpusDecoder

typedef struct OpusDecoder OpusDecoder

#include <include/ascii-chat/audio/client_pipeline.h>

Definition at line 77 of file client_pipeline.h.

◆ OpusEncoder

typedef struct OpusEncoder OpusEncoder

#include <include/ascii-chat/audio/client_pipeline.h>

Definition at line 76 of file client_pipeline.h.

Enumeration Type Documentation

◆ opus_application_t

#include <include/ascii-chat/audio/opus.h>

State for one Opus encoding or decoding direction.

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

84 {
opus_application_t
State for one Opus encoding or decoding direction.
Definition opus.h:84
@ OPUS_APPLICATION_AUDIO
General audio (optimized for music).
Definition opus.h:86
@ OPUS_APPLICATION_RESTRICTED_LOWDELAY
Low-latency mode.
Definition opus.h:87

Function Documentation

◆ apply_gain_buffer()

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

#include <include/ascii-chat/audio/mixer.h>

Apply gain to buffer in-place.

Parameters
bufferAudio buffer (modified in-place)
countNumber of samples
gainGain multiplier to apply

Multiplies all samples by gain factor.

Definition at line 361 of file effects.c.

361 {
362 if (!buffer || count <= 0)
363 return;
364
365 for (int i = 0; i < count; i++) {
366 buffer[i] *= gain;
367 }
368}

◆ audio_dequantize_samples()

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

#include <include/ascii-chat/audio/audio.h>

Dequantize network audio samples from int32 to float.

Parameters
samples_ptrPointer to quantized samples (network byte order uint32_t values)
total_samplesNumber of samples to convert
out_samplesOutput 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 2171 of file lib/audio/audio.c.

2171 {
2172 if (!samples_ptr || !out_samples || total_samples == 0) {
2173 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for audio dequantization");
2174 }
2175
2176 for (uint32_t i = 0; i < total_samples; i++) {
2177 uint32_t network_sample;
2178 // Use memcpy to safely handle potential misalignment from packet header
2179 memcpy(&network_sample, samples_ptr + i * sizeof(uint32_t), sizeof(uint32_t));
2180 int32_t scaled = (int32_t)NET_TO_HOST_U32(network_sample);
2181 out_samples[i] = (float)scaled / 2147483647.0f;
2182 }
2183
2184 return ASCIICHAT_OK;
2185}
#define SET_ERRNO(code,...)
#define NET_TO_HOST_U32(val)
Definition endian.h:85
unsigned int uint32_t
@ ASCIICHAT_OK
Definition error_codes.h:50
@ ERROR_INVALID_PARAM

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

Destroy audio context and clean up resources.

Parameters
ctxAudio 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 1460 of file lib/audio/audio.c.

1460 {
1461 ASCII_OTEL_SCOPE(AUDIO_DESTROY);
1462 if (!ctx) {
1463 return;
1464 }
1465
1466 // Always release PortAudio refcount if it was incremented
1467 // audio_init() calls Pa_Initialize() very early, and if it fails partway through,
1468 // ctx->initialized will be false. But we MUST still call audio_release_portaudio()
1469 // to properly decrement the refcount and allow Pa_Terminate() to be called.
1470 if (ctx->initialized) {
1471
1472 // Stop duplex stream if running (this also stops the worker thread)
1473 if (ctx->running) {
1474 audio_stop_duplex(ctx);
1475 }
1476
1477 // Ensure worker thread is stopped even if streams weren't running
1478 if (ctx->worker_running) {
1479 log_debug("Stopping worker thread");
1481 cond_signal(&ctx->audio_processing_wakeup); // Wake up worker if waiting
1482 thread_join(&ctx->worker_thread, NULL);
1483 ctx->worker_running = false;
1484 }
1485
1486 mutex_lock(&ctx->state_mutex);
1487
1488 // Destroy all ring buffers (old + new)
1494 audio_ring_buffer_destroy(ctx->render_buffer); // May be NULL, that's OK
1495
1496 // Free pre-allocated worker buffers
1500
1501 // Destroy worker synchronization primitives
1502 cond_destroy(&ctx->audio_processing_wakeup);
1503 mutex_destroy(&ctx->audio_processing_wait_guard);
1504
1505 ctx->initialized = false;
1506
1507 mutex_unlock(&ctx->state_mutex);
1508 mutex_destroy(&ctx->state_mutex);
1509
1512 NAMED_UNREGISTER(ctx);
1513
1514 log_debug("Audio system cleanup complete (all resources released)");
1515 } else {
1516 }
1517}
void atomic_store_bool(atomic_t *a, bool value)
Atomically store a boolean value.
void audio_ring_buffer_destroy(audio_ring_buffer_t *rb)
Destroy an audio ring buffer.
asciichat_error_t audio_stop_duplex(audio_context_t *ctx)
Stop full-duplex audio.
#define SAFE_FREE(ptr)
#define NAMED_UNREGISTER(ptr)
Unregister a pointer.
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
#define ASCII_OTEL_SCOPE(id)
Definition otel.h:77
bool initialized
True if context has been initialized.
platform_thread_t worker_thread
Worker thread for audio processing.
audio_ring_buffer_t * raw_render_rb
Callback → Worker: Raw speaker samples (AEC3 reference).
audio_ring_buffer_t * playback_buffer
OLD: Network → Worker (will become network_playback_rb).
float * worker_render_batch
Pre-allocated buffer for batch render processing.
bool worker_running
True if worker thread is running.
atomic_t shutting_down
True when shutdown started - callback outputs silence.
atomic_t worker_should_stop
Signal worker thread to exit.
audio_ring_buffer_t * capture_buffer
OLD: Worker → Network (will become processed_capture_rb).
bool running
True if duplex stream is active.
audio_ring_buffer_t * render_buffer
Ring buffer for render reference (separate streams mode).
audio_ring_buffer_t * raw_capture_rb
Callback → Worker: Raw mic samples (no processing).
mutex_t audio_processing_wait_guard
Coordinates device-worker sleep with shutdown.
float * worker_playback_batch
Pre-allocated buffer for batch playback processing.
mutex_t state_mutex
Mutex protecting context state.
float * worker_capture_batch
Pre-allocated buffer for batch capture processing.
audio_ring_buffer_t * processed_playback_rb
Worker → Callback: Ready for speakers.
cond_t audio_processing_wakeup
Capture/AEC work, monitor refill, or shutdown notification.

References ASCII_OTEL_SCOPE, atomic_store_bool(), audio_context_t::audio_processing_wait_guard, audio_context_t::audio_processing_wakeup, audio_ring_buffer_destroy(), audio_stop_duplex(), audio_context_t::capture_buffer, audio_context_t::initialized, log_debug, NAMED_UNREGISTER, audio_context_t::playback_buffer, audio_context_t::processed_playback_rb, audio_context_t::raw_capture_rb, audio_context_t::raw_render_rb, audio_context_t::render_buffer, audio_context_t::running, SAFE_FREE, audio_context_t::shutting_down, audio_context_t::state_mutex, audio_context_t::worker_capture_batch, audio_context_t::worker_playback_batch, audio_context_t::worker_render_batch, audio_context_t::worker_running, audio_context_t::worker_should_stop, and audio_context_t::worker_thread.

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

◆ audio_flush_playback_buffers()

void audio_flush_playback_buffers ( audio_context_t * ctx)

#include <include/ascii-chat/audio/audio.h>

Flush all audio buffers to synchronize with seek operations.

Parameters
ctxAudio 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 1525 of file lib/audio/audio.c.

1525 {
1526 if (!ctx || !ctx->initialized) {
1527 return;
1528 }
1529
1530 if (ctx->playback_buffer) {
1532 }
1533 if (ctx->processed_playback_rb) {
1535 }
1536 if (ctx->render_buffer) {
1538 }
1539 if (ctx->raw_render_rb) {
1541 }
1542}
void audio_ring_buffer_clear(audio_ring_buffer_t *rb)
Clear all audio samples from ring buffer.

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.

◆ audio_free_device_list()

void audio_free_device_list ( audio_device_info_t * devices)

#include <include/ascii-chat/audio/audio.h>

Free device list allocated by audio_list_input_devices/audio_list_output_devices.

Parameters
devicesDevice 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 2167 of file lib/audio/audio.c.

2167 {
2168 SAFE_FREE(devices);
2169}

References SAFE_FREE.

◆ audio_init()

asciichat_error_t audio_init ( audio_context_t * ctx)

#include <include/ascii-chat/audio/audio.h>

Initialize audio context and PortAudio.

Parameters
ctxAudio 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 1305 of file lib/audio/audio.c.

1305 {
1306 ASCII_OTEL_SCOPE(AUDIO_INIT);
1307 log_debug("starting, ctx=%p", (void *)ctx);
1308 if (!ctx) {
1309 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx is NULL");
1310 }
1311
1312 SAFE_MEMSET(ctx, sizeof(audio_context_t), 0, sizeof(audio_context_t));
1313
1314 if (mutex_init(&ctx->state_mutex, "audio_context") != 0) {
1315 return SET_ERRNO(ERROR_THREAD, "Failed to initialize audio context mutex");
1316 }
1317
1318 // NOTE: PortAudio initialization deferred to audio_start_duplex() where streams are actually opened
1319 // This avoids Pa_Initialize() overhead for contexts that might not start duplex
1320 // and prevents premature ALSA device allocation and memory leaks
1321
1322 // Create capture buffer WITHOUT jitter buffering (PortAudio writes directly from microphone)
1324 if (!ctx->capture_buffer) {
1325 mutex_destroy(&ctx->state_mutex);
1326 return SET_ERRNO(ERROR_MEMORY, "Failed to create capture buffer");
1327 }
1328
1330 if (!ctx->playback_buffer) {
1332 mutex_destroy(&ctx->state_mutex);
1333 return SET_ERRNO(ERROR_MEMORY, "Failed to create playback buffer");
1334 }
1335
1336 // Create new ring buffers for worker thread architecture
1338 if (!ctx->raw_capture_rb) {
1341 mutex_destroy(&ctx->state_mutex);
1342 return SET_ERRNO(ERROR_MEMORY, "Failed to create raw capture buffer");
1343 }
1344
1346 if (!ctx->raw_render_rb) {
1350 mutex_destroy(&ctx->state_mutex);
1351 return SET_ERRNO(ERROR_MEMORY, "Failed to create raw render buffer");
1352 }
1353
1355 if (!ctx->processed_playback_rb) {
1360 mutex_destroy(&ctx->state_mutex);
1361 return SET_ERRNO(ERROR_MEMORY, "Failed to create processed playback buffer");
1362 }
1363
1364 // Initialize worker thread infrastructure
1365 if (mutex_init(&ctx->audio_processing_wait_guard, "audio_processing_wait_guard") != 0) {
1371 mutex_destroy(&ctx->state_mutex);
1372 return SET_ERRNO(ERROR_THREAD, "Failed to initialize worker mutex");
1373 }
1374
1375 if (cond_init(&ctx->audio_processing_wakeup, "audio_processing_wakeup") != 0) {
1376 mutex_destroy(&ctx->audio_processing_wait_guard);
1382 mutex_destroy(&ctx->state_mutex);
1383 return SET_ERRNO(ERROR_THREAD, "Failed to initialize worker condition variable");
1384 }
1385
1386 // Allocate pre-allocated worker buffers (avoid malloc in worker loop)
1387 ctx->worker_capture_batch = SAFE_MALLOC((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) * sizeof(float), float *);
1388 if (!ctx->worker_capture_batch) {
1389 cond_destroy(&ctx->audio_processing_wakeup);
1390 mutex_destroy(&ctx->audio_processing_wait_guard);
1396 mutex_destroy(&ctx->state_mutex);
1397 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker capture batch buffer");
1398 }
1399
1400 ctx->worker_render_batch = SAFE_MALLOC((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) * sizeof(float), float *);
1401 if (!ctx->worker_render_batch) {
1403 cond_destroy(&ctx->audio_processing_wakeup);
1404 mutex_destroy(&ctx->audio_processing_wait_guard);
1410 mutex_destroy(&ctx->state_mutex);
1411 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker render batch buffer");
1412 }
1413
1414 ctx->worker_playback_batch = SAFE_MALLOC((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) * sizeof(float), float *);
1415 if (!ctx->worker_playback_batch) {
1418 cond_destroy(&ctx->audio_processing_wakeup);
1419 mutex_destroy(&ctx->audio_processing_wait_guard);
1425 mutex_destroy(&ctx->state_mutex);
1426 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker playback batch buffer");
1427 }
1428
1429 ctx->capture_media_source = NULL;
1430 ctx->monitor_local_media = false;
1431
1432 // Initialize worker thread state (thread will be started in audio_start_duplex)
1433 ctx->worker_running = false;
1435
1436 ctx->initialized = true;
1437 atomic_store_bool(&ctx->shutting_down, false);
1438
1439 /* Register audio context with named registry */
1440 NAMED_REGISTER(ctx, "audio_context", "audio_context_t", "0x%tx", NULL);
1441
1442 /* Register audio context's sync primitives with hierarchical naming */
1443 NAMED_REGISTER_MUTEX(&ctx->state_mutex, "state_mutex", (uintptr_t)(const void *)(ctx));
1444 NAMED_REGISTER_MUTEX(&ctx->audio_processing_wait_guard, "audio_processing_wait_guard", (uintptr_t)(const void *)(ctx));
1445 NAMED_REGISTER_COND(&ctx->audio_processing_wakeup, "audio_processing_wakeup", (uintptr_t)(const void *)(ctx));
1446 NAMED_REGISTER_ATOMIC(&ctx->worker_should_stop, "worker_should_stop", (uintptr_t)(const void *)(ctx));
1447 NAMED_REGISTER_ATOMIC(&ctx->shutting_down, "shutting_down", (uintptr_t)(const void *)(ctx));
1448
1449 /* Register ring buffers as child structures with audio context as parent */
1450 NAMED_REGISTER_AUDIO_RINGBUF(ctx->capture_buffer, "capture_buffer", (uintptr_t)(const void *)(ctx));
1451 NAMED_REGISTER_AUDIO_RINGBUF(ctx->playback_buffer, "playback_buffer", (uintptr_t)(const void *)(ctx));
1452 NAMED_REGISTER_AUDIO_RINGBUF(ctx->raw_capture_rb, "raw_capture_rb", (uintptr_t)(const void *)(ctx));
1453 NAMED_REGISTER_AUDIO_RINGBUF(ctx->raw_render_rb, "raw_render_rb", (uintptr_t)(const void *)(ctx));
1454 NAMED_REGISTER_AUDIO_RINGBUF(ctx->processed_playback_rb, "processed_playback_rb", (uintptr_t)(const void *)(ctx));
1455
1456 log_info("Audio system initialized successfully (worker thread architecture enabled)");
1457 return ASCIICHAT_OK;
1458}
#define OPUS_FRAME_SAMPLES
#define AUDIO_CHANNELS
Definition audio/limits.h:9
#define SAFE_MEMSET(dest, dest_size, ch, count)
#define SAFE_MALLOC(size, cast)
#define NAMED_REGISTER_ATOMIC(a, name, parent_ptr)
Register an atomic_t with automatic format specifier.
#define NAMED_REGISTER_COND(cond, name, parent_ptr)
Register a condition variable with automatic format specifier.
#define NAMED_REGISTER(ptr, name, type, fmt, parent_ptr)
Register any pointer with base name, type, format spec, and location (auto-suffix).
#define NAMED_REGISTER_AUDIO_RINGBUF(buf, name, parent_ptr)
Register an audio ring buffer with automatic format specifier.
#define NAMED_REGISTER_MUTEX(mutex, name, parent_ptr)
Register a mutex with automatic format specifier.
@ ERROR_MEMORY
Definition error_codes.h:55
@ ERROR_THREAD
#define log_info(...)
Log an INFO message.
Definition log/log.h:602
audio_ring_buffer_t * audio_ring_buffer_create_format(unsigned channels, bool capture)
When code needs to work with audio device info, it keeps index, max_input_channels,...
bool monitor_local_media
Play local file audio in solo sessions.
void * capture_media_source
Borrowed local media audio; configure before starting duplex.

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, atomic_store_bool(), AUDIO_CHANNELS, audio_context_t::audio_processing_wait_guard, audio_context_t::audio_processing_wakeup, audio_ring_buffer_create_format(), audio_ring_buffer_destroy(), audio_context_t::capture_buffer, audio_context_t::capture_media_source, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_THREAD, audio_context_t::initialized, log_debug, log_info, audio_context_t::monitor_local_media, NAMED_REGISTER, NAMED_REGISTER_ATOMIC, NAMED_REGISTER_AUDIO_RINGBUF, NAMED_REGISTER_COND, NAMED_REGISTER_MUTEX, OPUS_FRAME_SAMPLES, 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, audio_context_t::worker_capture_batch, 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(), and session_audio_create().

◆ audio_is_supported_sample_rate()

bool audio_is_supported_sample_rate ( uint32_t sample_rate)

#include <include/ascii-chat/audio/audio.h>

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

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

Parameters
sample_rateSample 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;
}
bool audio_is_supported_sample_rate(uint32_t sample_rate)
Check if a sample rate is a standard/supported rate.
#define log_error(...)
Log an ERROR message.
Definition log/log.h:628

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

2265 {
2266 // List of commonly supported audio sample rates
2267 static const uint32_t supported_rates[] = {
2268 8000, // Telephone quality
2269 16000, // Wideband telephony
2270 24000, // High quality speech
2271 32000, // Good for video
2272 44100, // CD quality (less common in VoIP)
2273 48000, // Standard professional
2274 96000, // High-end professional
2275 192000, // Ultra-high-end mastering
2276 };
2277
2278 const size_t rate_count = sizeof(supported_rates) / sizeof(supported_rates[0]);
2279 for (size_t i = 0; i < rate_count; i++) {
2280 if (sample_rate == supported_rates[i]) {
2281 return true;
2282 }
2283 }
2284
2285 return false;
2286}

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

List available audio input devices (microphones).

Parameters
out_devicesPointer to store allocated array of devices (must not be NULL)
out_countPointer 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 2159 of file lib/audio/audio.c.

2159 {
2160 return audio_list_devices_internal(out_devices, out_count, true);
2161}

◆ audio_list_output_devices()

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

#include <include/ascii-chat/audio/audio.h>

List available audio output devices (speakers).

Parameters
out_devicesPointer to store allocated array of devices (must not be NULL)
out_countPointer 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 2163 of file lib/audio/audio.c.

2163 {
2164 return audio_list_devices_internal(out_devices, out_count, false);
2165}

◆ audio_opus_configure_encoder()

asciichat_error_t audio_opus_configure_encoder ( OpusEncoder * encoder,
int bitrate )

#include <include/ascii-chat/audio/opus.h>

Configure continuous VBR output consistently for native encoders.

Definition at line 21 of file opus.c.

21 {
22 if (!encoder || bitrate < 6000 || bitrate > 510000)
23 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid Opus encoder or bitrate: %d", bitrate);
24 int result = opus_encoder_ctl(encoder, OPUS_SET_BITRATE(bitrate));
25 if (result == OPUS_OK)
26 result = opus_encoder_ctl(encoder, OPUS_SET_VBR(1));
27 // Ordered streams retain silence packets so playout timing remains continuous.
28 if (result == OPUS_OK)
29 result = opus_encoder_ctl(encoder, OPUS_SET_DTX(0));
30 if (result != OPUS_OK)
31 return SET_ERRNO(ERROR_AUDIO, "Opus configuration failed: %s", opus_strerror(result));
32 return ASCIICHAT_OK;
33}
@ ERROR_AUDIO
Definition error_codes.h:66

References ASCIICHAT_OK, ERROR_AUDIO, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by client_audio_pipeline_create(), and opus_codec_create_encoder_channels().

◆ audio_parse_batch_header()

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

#include <include/ascii-chat/audio/audio.h>

Parse an audio batch packet header from raw packet data.

Performs the following validations:

  1. Checks that the data pointer is not NULL
  2. Checks that len is at least sizeof(audio_batch_header_t)
  3. Verifies that batch_count and channels are within reasonable bounds
  4. Unpacks all 32-bit values from network byte order to host byte order
Parameters
dataPointer to packet data (must not be NULL)
lenLength of packet data in bytes
[out]out_batchPointer 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:

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);
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
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
Parsed audio batch packet header information.
uint32_t batch_count
Number of audio frames in this batch.
uint32_t channels
Number of channels (1=mono, 2=stereo).
uint32_t sample_rate
Sample rate in Hz (e.g., 48000).

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

2201 {
2202 if (!data) {
2203 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch header data pointer is NULL");
2204 }
2205
2206 if (!out_batch) {
2207 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch info output pointer is NULL");
2208 }
2209
2210 if (len < sizeof(audio_batch_packet_t)) {
2211 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch header too small (len=%zu, expected=%zu)", len, sizeof(audio_batch_packet_t));
2212 }
2213
2214 const audio_batch_packet_t *batch_header = (const audio_batch_packet_t *)data;
2215
2216 // Unpack network byte order values to host byte order
2217 out_batch->batch_count = ntohl(batch_header->batch_count);
2218 out_batch->total_samples = ntohl(batch_header->total_samples);
2219 out_batch->sample_rate = ntohl(batch_header->sample_rate);
2220 out_batch->channels = ntohl(batch_header->channels);
2221
2222 return ASCIICHAT_OK;
2223}
uint32_t total_samples
Total number of samples across all frames.
The metadata prefix for a batch of encoded audio samples. batch_count, total_samples,...
Definition packet.h:979
uint32_t channels
Number of audio channels (1=mono, 2=stereo).
Definition packet.h:987
uint32_t batch_count
Number of audio chunks in this batch (usually AUDIO_BATCH_COUNT = 32).
Definition packet.h:981
uint32_t sample_rate
Sample rate in Hz (e.g., 44100, 48000).
Definition packet.h:985
uint32_t total_samples
Total audio samples across all chunks (typically 8192).
Definition packet.h:983

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

Referenced by handle_audio_batch_packet().

◆ audio_read_samples()

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

#include <include/ascii-chat/audio/audio.h>

Read captured audio samples from capture buffer.

Parameters
ctxAudio context (must not be NULL)
bufferOutput buffer for audio samples (must not be NULL)
num_samplesNumber 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 2052 of file lib/audio/audio.c.

2052 {
2053 if (!ctx || !ctx->initialized || !buffer || num_samples <= 0) {
2054 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, buffer=%p, num_samples=%d", ctx, buffer, num_samples);
2055 }
2056
2057 // audio_ring_buffer_read now returns number of samples read, not error code
2058 int samples_read = audio_ring_buffer_read(ctx->capture_buffer, buffer, num_samples);
2059 return (samples_read >= 0) ? ASCIICHAT_OK : ERROR_AUDIO;
2060}
size_t audio_ring_buffer_read(audio_ring_buffer_t *rb, float *data, size_t samples)
Read audio samples from ring buffer.

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

Get number of samples available for reading.

Parameters
rbAudio 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 1279 of file lib/audio/audio.c.

1279 {
1280 if (!rb)
1281 return 0;
1282
1283 // LOCK-FREE: Load indices with proper memory ordering
1284 // Use acquire for write_index to see writer's updates
1285 // Use relaxed for read_index (our own index)
1286 unsigned int write_idx = atomic_load_u64(&rb->write_index);
1287 unsigned int read_idx = atomic_load_u64(&rb->read_index);
1288
1289 if (write_idx >= read_idx) {
1290 return write_idx - read_idx;
1291 }
1292
1293 return AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
1294}
uint64_t atomic_load_u64(atomic_t *a)
Atomically load a uint64_t value.
#define AUDIO_RING_BUFFER_SIZE
Audio ring buffer size in samples (192000 samples = 4 seconds @ 48kHz).
Definition ringbuffer.h:136
atomic_t read_index
Read index (consumer position) - LOCK-FREE with atomic operations.
Definition ringbuffer.h:220
atomic_t write_index
Write index (producer position) - LOCK-FREE with atomic operations.
Definition ringbuffer.h:218

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

Get number of sample slots available for writing.

Parameters
rbAudio 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 1296 of file lib/audio/audio.c.

1296 {
1297 if (!rb) {
1298 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb is NULL");
1299 return 0;
1300 }
1301
1303}
size_t audio_ring_buffer_available_read(audio_ring_buffer_t *rb)
Get number of samples available for reading.

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

Clear all audio samples from ring buffer.

Parameters
rbAudio 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 929 of file lib/audio/audio.c.

929 {
930 if (!rb)
931 return;
932
933 mutex_lock(&rb->mutex);
934 // Reset buffer to empty state (no audio to play = silence at shutdown)
939 rb->last_sample = 0.0f;
944 rb->jitter_stable_samples = 0;
945 rb->jitter_drift_phase = 0;
946 // Clear the actual data to zeros to prevent any stale audio
947 SAFE_MEMSET(rb->data, sizeof(rb->data), 0, sizeof(rb->data));
948 mutex_unlock(&rb->mutex);
949}
void atomic_store_u64(atomic_t *a, uint64_t value)
Atomically store a uint64_t value.
atomic_t discard_pending
Consumer should discard queued samples before its next read.
Definition ringbuffer.h:222
atomic_t discard_to_index
Producer position at which the stale queue ends.
Definition ringbuffer.h:224
float last_sample
Last sample value for smooth fade-out during underrun - NOT atomic (only written by reader).
Definition ringbuffer.h:232
atomic_t crossfade_fade_in
True if we're fading in (recovering from underrun).
Definition ringbuffer.h:230
atomic_t jitter_buffer_filled
True after initial jitter buffer fill.
Definition ringbuffer.h:226
double jitter_drift_phase
Consumer-owned fractional clock correction.
Definition ringbuffer.h:241
uint64_t jitter_stable_samples
Definition ringbuffer.h:240
mutex_t mutex
Mutex for SLOW PATH only (clear/destroy operations, not regular read/write).
Definition ringbuffer.h:243
uint32_t jitter_initial_samples
Definition ringbuffer.h:239
bool jitter_buffer_enabled
Whether jitter buffering is enabled (false for capture, true for playback).
Definition ringbuffer.h:236
uint32_t jitter_target_samples
Definition ringbuffer.h:238
atomic_t crossfade_samples_remaining
Samples remaining in crossfade (0 = no crossfade active).
Definition ringbuffer.h:228
float data[192000]
Audio sample data buffer.
Definition ringbuffer.h:216

References atomic_store_bool(), atomic_store_u64(), audio_ring_buffer::crossfade_fade_in, audio_ring_buffer::crossfade_samples_remaining, audio_ring_buffer::data, audio_ring_buffer::discard_pending, audio_ring_buffer::discard_to_index, audio_ring_buffer::jitter_buffer_enabled, audio_ring_buffer::jitter_buffer_filled, audio_ring_buffer::jitter_drift_phase, audio_ring_buffer::jitter_initial_samples, audio_ring_buffer::jitter_stable_samples, audio_ring_buffer::jitter_target_samples, audio_ring_buffer::last_sample, audio_ring_buffer::mutex, audio_ring_buffer::read_index, SAFE_MEMSET, and audio_ring_buffer::write_index.

Referenced by audio_flush_playback_buffers(), audio_start_duplex(), audio_stop_duplex(), and media_source_seek().

◆ audio_ring_buffer_create()

audio_ring_buffer_t * audio_ring_buffer_create ( void )

#include <include/ascii-chat/audio/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 858 of file lib/audio/audio.c.

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

◆ audio_ring_buffer_create_for_capture()

audio_ring_buffer_t * audio_ring_buffer_create_for_capture ( void )

#include <include/ascii-chat/audio/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 862 of file lib/audio/audio.c.

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

◆ audio_ring_buffer_destroy()

void audio_ring_buffer_destroy ( audio_ring_buffer_t * rb)

#include <include/ascii-chat/audio/audio.h>

Destroy an audio ring buffer.

Parameters
rbAudio 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 880 of file lib/audio/audio.c.

880 {
881 if (!rb)
882 return;
883
886
887 mutex_destroy(&rb->mutex);
888 buffer_release(rb);
889}
#define buffer_release(data)
Definition buffer.h:99
void audio_ring_buffer_unregister_atomics(audio_ring_buffer_t *rb)
Unregister audio ring buffer atomic fields.

References audio_ring_buffer_unregister_atomics(), buffer_release, audio_ring_buffer::mutex, and NAMED_UNREGISTER.

Referenced by 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 <include/ascii-chat/audio/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
rbRing buffer to peek from
dataOutput buffer for samples
samplesNumber of samples to peek
Returns
Number of samples actually peeked (may be less than requested)

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

1242 {
1243 if (!rb || !data || samples <= 0) {
1244 return 0;
1245 }
1246
1247 // LOCK-FREE: Load indices with proper memory ordering
1248 unsigned int write_idx = atomic_load_u64(&rb->write_index);
1249 unsigned int read_idx = atomic_load_u64(&rb->read_index);
1250
1251 // Calculate available samples
1252 size_t available;
1253 if (write_idx >= read_idx) {
1254 available = write_idx - read_idx;
1255 } else {
1256 available = AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
1257 }
1258
1259 size_t to_peek = (samples > available) ? available : samples;
1260
1261 if (to_peek == 0) {
1262 return 0;
1263 }
1264
1265 // Copy samples in chunks (handle wraparound)
1266 size_t first_chunk = (read_idx + to_peek <= AUDIO_RING_BUFFER_SIZE) ? to_peek : (AUDIO_RING_BUFFER_SIZE - read_idx);
1267
1268 SAFE_MEMCPY(data, first_chunk * sizeof(float), rb->data + read_idx, first_chunk * sizeof(float));
1269
1270 if (first_chunk < to_peek) {
1271 // Wraparound: copy second chunk from beginning of buffer
1272 size_t second_chunk = to_peek - first_chunk;
1273 SAFE_MEMCPY(data + first_chunk, second_chunk * sizeof(float), rb->data, second_chunk * sizeof(float));
1274 }
1275
1276 return to_peek;
1277}
#define SAFE_MEMCPY(dest, dest_size, src, count)

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

Read audio samples from ring buffer.

Parameters
rbAudio ring buffer (must not be NULL)
dataOutput buffer for audio samples (must not be NULL)
samplesMaximum 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 1056 of file lib/audio/audio.c.

1056 {
1057 if (!rb || !data || samples <= 0) {
1058 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb=%p, data=%p, samples=%d", rb, data, samples);
1059 return 0; // Return 0 samples read on error
1060 }
1061
1062 if (samples % rb->channels) {
1063 SET_ERRNO(ERROR_INVALID_PARAM, "Incomplete PCM frame in audio queue read");
1064 return 0;
1065 }
1066 // Keep read_index consumer-owned while letting a producer request a flush.
1067 if (atomic_exchange_bool(&rb->discard_pending, false)) {
1068 unsigned int read_idx = atomic_load_u64(&rb->read_index);
1069 unsigned int discard_to = atomic_load_u64(&rb->discard_to_index);
1070 unsigned int advance = (discard_to + AUDIO_RING_BUFFER_SIZE - read_idx) % AUDIO_RING_BUFFER_SIZE;
1071 // A concurrent callback may already have consumed beyond the requested
1072 // boundary. In that case the target is behind us and must not rewind the
1073 // single-consumer index.
1074 if (advance < AUDIO_RING_BUFFER_SIZE / 2) {
1075 atomic_store_u64(&rb->read_index, discard_to);
1076 rb->last_sample = 0.0f;
1078 }
1079 }
1080
1081 // LOCK-FREE: Load indices with proper memory ordering
1082 // - Load writer's write_index with acquire (see writer's data updates)
1083 // - Load our own read_index with relaxed (no sync needed with ourselves)
1084 unsigned int write_idx = atomic_load_u64(&rb->write_index);
1085 unsigned int read_idx = atomic_load_u64(&rb->read_index);
1086
1087 // Calculate available samples
1088 size_t available;
1089 if (write_idx >= read_idx) {
1090 available = write_idx - read_idx;
1091 } else {
1092 available = AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
1093 }
1094
1095 // LOCK-FREE: Load jitter buffer state with acquire ordering
1096 bool jitter_filled = atomic_load_u64(&rb->jitter_buffer_filled);
1097 int crossfade_remaining = atomic_load_u64(&rb->crossfade_samples_remaining);
1098 bool fade_in = atomic_load_u64(&rb->crossfade_fade_in);
1099
1100 // Jitter buffer: don't read until initial fill threshold is reached
1101 // (only for playback buffers - capture buffers have jitter_buffer_enabled = false)
1102 if (!jitter_filled && rb->jitter_buffer_enabled) {
1103 // Check if we've accumulated enough samples to start playback
1104 if (available >= rb->jitter_target_samples) {
1108 log_info("Jitter buffer filled (%zu samples), starting playback with fade-in", available);
1109 // Reload state for processing below
1110 jitter_filled = true;
1111 crossfade_remaining = (AUDIO_CROSSFADE_SAMPLES * (int)rb->channels);
1112 fade_in = true;
1113 } else {
1114 // Log buffer fill progress every second
1115 log_debug_every(NS_PER_MS_INT, "Jitter buffer filling: %zu/%d samples (%.1f%%)", available, rb->jitter_target_samples, (100.0f * available) / rb->jitter_target_samples);
1116 return 0; // Return 0 samples - caller will pad with silence
1117 }
1118 }
1119
1120 // Periodic buffer health logging (every 5 seconds when healthy)
1121 unsigned int underruns = atomic_load_u64(&rb->underrun_count);
1122 log_dev_every(5 * US_PER_SEC_INT, "Buffer health: %zu/%d samples (%.1f%%), underruns=%u", available, AUDIO_RING_BUFFER_SIZE, (100.0f * available) / AUDIO_RING_BUFFER_SIZE, underruns);
1123
1124 audio_metric(ASCII_OTEL_METRIC_AUDIO_FILL, (double)available);
1125 if (rb->jitter_buffer_enabled)
1126 audio_metric(ASCII_OTEL_METRIC_AUDIO_JITTER, (double)rb->jitter_target_samples / (AUDIO_SAMPLE_RATE * rb->channels));
1127 bool underrun = rb->jitter_buffer_enabled && available < samples;
1128 if (underrun) {
1129 audio_metric(ASCII_OTEL_METRIC_AUDIO_UNDERRUN, 1);
1131 // One bounded refill after a real shortage avoids alternating tiny fragments
1132 // and silence when packets resume. Low occupancy alone is not an underrun.
1134 rb->jitter_stable_samples = 0;
1135 rb->jitter_drift_phase = 0;
1137 } else if (rb->jitter_buffer_enabled) {
1138 rb->jitter_stable_samples += samples;
1139 if (rb->jitter_stable_samples >= 480000 * rb->channels) {
1141 rb->jitter_target_samples -= 480 * rb->channels;
1142 rb->jitter_stable_samples = 0;
1143 rb->jitter_drift_phase = 0;
1144 }
1145 }
1146
1147 size_t to_read = (samples > available) ? available : samples;
1148 audio_metric(rb->jitter_buffer_enabled ? ASCII_OTEL_METRIC_AUDIO_PLAYBACK : ASCII_OTEL_METRIC_AUDIO_CAPTURE, (double)to_read);
1149 size_t consumed = to_read;
1150 if (rb->jitter_buffer_enabled && !underrun && samples > 1 && available > samples) {
1151 // Slowly reconcile independent device clocks. Bound interpolation to one
1152 // sample per block and a maximum average rate correction of 1000 ppm.
1153 double error = ((double)available - rb->jitter_target_samples) / (AUDIO_SAMPLE_RATE * rb->channels);
1154 double correction = fmax(-0.001, fmin(0.001, error * 0.02));
1155 rb->jitter_drift_phase += correction * (samples / rb->channels);
1156 if (rb->jitter_drift_phase >= 1.0) {
1157 consumed += rb->channels;
1158 rb->jitter_drift_phase -= 1.0;
1159 } else if (rb->jitter_drift_phase <= -1.0) {
1160 consumed -= rb->channels;
1161 rb->jitter_drift_phase += 1.0;
1162 }
1163 }
1164
1165 if (consumed != to_read) {
1166 size_t frames = to_read / rb->channels;
1167 size_t consumed_frames = consumed / rb->channels;
1168 for (size_t frame = 0; frame < frames; frame++) {
1169 double position = frames > 1 ? (double)frame * (consumed_frames - 1) / (frames - 1) : 0;
1170 size_t first = (size_t)position;
1171 size_t next = first + 1 < consumed_frames ? first + 1 : first;
1172 float fraction = (float)(position - first);
1173 for (unsigned channel = 0; channel < rb->channels; channel++) {
1174 float a = rb->data[(read_idx + first * rb->channels + channel) % AUDIO_RING_BUFFER_SIZE];
1175 float b = rb->data[(read_idx + next * rb->channels + channel) % AUDIO_RING_BUFFER_SIZE];
1176 data[frame * rb->channels + channel] = a + fraction * (b - a);
1177 }
1178 }
1179 } else {
1180 size_t remaining = AUDIO_RING_BUFFER_SIZE - read_idx;
1181 if (to_read <= remaining) {
1182 SAFE_MEMCPY(data, to_read * sizeof(float), &rb->data[read_idx], to_read * sizeof(float));
1183 } else {
1184 SAFE_MEMCPY(data, remaining * sizeof(float), &rb->data[read_idx], remaining * sizeof(float));
1185 SAFE_MEMCPY(&data[remaining], (to_read - remaining) * sizeof(float), &rb->data[0], (to_read - remaining) * sizeof(float));
1186 }
1187 }
1188 atomic_store_u64(&rb->read_index, (read_idx + (unsigned int)consumed) % AUDIO_RING_BUFFER_SIZE);
1189
1190 // Apply fade-in if recovering from underrun
1191 if (fade_in && crossfade_remaining > 0) {
1192 int fade_start = (AUDIO_CROSSFADE_SAMPLES * (int)rb->channels) - crossfade_remaining;
1193 size_t fade_samples = (to_read < (size_t)crossfade_remaining) ? to_read : (size_t)crossfade_remaining;
1194
1195 for (size_t i = 0; i < fade_samples; i++) {
1196 float fade_factor = (float)((fade_start + (int)i) / (int)rb->channels + 1) / (float)AUDIO_CROSSFADE_SAMPLES;
1197 data[i] *= fade_factor;
1198 }
1199
1200 int new_crossfade_remaining = crossfade_remaining - (int)fade_samples;
1201 atomic_store_u64(&rb->crossfade_samples_remaining, new_crossfade_remaining);
1202 if (new_crossfade_remaining <= 0) {
1204 log_debug("Audio fade-in complete");
1205 }
1206 }
1207
1208 if (underrun && to_read > 0) {
1209 size_t max_fade_samples = (size_t)AUDIO_CROSSFADE_SAMPLES * rb->channels;
1210 size_t fade_samples = to_read < max_fade_samples ? to_read : max_fade_samples;
1211 for (size_t i = 0; i < fade_samples; ++i)
1212 data[to_read - fade_samples + i] *= (float)((fade_samples - i - 1) / rb->channels) / (float)(fade_samples / rb->channels);
1213 }
1214
1215 // Save last sample for potential fade-out
1216 // Note: only update if we actually read some data
1217 // This is NOT atomic - only the reader thread writes this
1218 if (to_read > 0) {
1219 rb->last_sample = data[to_read - 1];
1220 }
1221
1222 // Return ACTUAL number of samples read, not padded count
1223 // The caller (mixer) expects truthful return values to detect underruns
1224 // and handle silence padding externally. Internal padding creates double-padding bugs.
1225 //
1226 // This function was incorrectly returning `samples` even when
1227 // it only read `to_read` samples. This broke the mixer's underrun detection.
1228 return to_read;
1229}
uint64_t atomic_fetch_add_u64(atomic_t *a, uint64_t delta)
Atomically add to a uint64_t and return the previous value.
bool atomic_exchange_bool(atomic_t *a, bool new_value)
Atomically exchange a boolean and return the old value.
#define AUDIO_SAMPLE_RATE
Definition audio/limits.h:8
#define NS_PER_MS_INT
Definition time.h:172
#define US_PER_SEC_INT
Definition time.h:177
#define AUDIO_CROSSFADE_SAMPLES
Crossfade duration in samples for smooth underrun recovery.
Definition ringbuffer.h:194
#define log_debug_every(interval_us, fmt,...)
Rate-limited DEBUG logging.
Definition log/log.h:743
#define log_dev_every(interval_us, fmt,...)
Rate-limited DEV logging.
Definition log/log.h:740
unsigned channels
Frame width, configured before the first read/write.
Definition ringbuffer.h:214
atomic_t underrun_count
Count of underrun events for diagnostics.
Definition ringbuffer.h:234

References atomic_exchange_bool(), atomic_fetch_add_u64(), atomic_load_u64(), atomic_store_bool(), atomic_store_u64(), AUDIO_CROSSFADE_SAMPLES, AUDIO_RING_BUFFER_SIZE, AUDIO_SAMPLE_RATE, audio_ring_buffer::channels, audio_ring_buffer::crossfade_fade_in, audio_ring_buffer::crossfade_samples_remaining, audio_ring_buffer::data, audio_ring_buffer::discard_pending, audio_ring_buffer::discard_to_index, ERROR_INVALID_PARAM, audio_ring_buffer::jitter_buffer_enabled, audio_ring_buffer::jitter_buffer_filled, audio_ring_buffer::jitter_drift_phase, audio_ring_buffer::jitter_initial_samples, audio_ring_buffer::jitter_stable_samples, audio_ring_buffer::jitter_target_samples, audio_ring_buffer::last_sample, log_debug, log_debug_every, log_dev_every, log_info, NS_PER_MS_INT, OPUS_FRAME_SAMPLES, audio_ring_buffer::read_index, SAFE_MEMCPY, SET_ERRNO, audio_ring_buffer::underrun_count, US_PER_SEC_INT, and audio_ring_buffer::write_index.

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

◆ audio_ring_buffer_register_atomics()

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

#include <include/ascii-chat/audio/audio.h>

Register audio ring buffer atomic fields for debug tracking.

Parameters
rbAudio ring buffer (must not be NULL)
context_nameDescriptive 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 891 of file lib/audio/audio.c.

891 {
892 if (!rb || !context_name || !context_name[0]) {
893 return;
894 }
895
896 // Register the ring buffer itself with a unique name
897 NAMED_REGISTER_AUDIO_RINGBUF(rb, context_name, NULL);
898
899 // Ring buffer indices (lock-free producer-consumer)
900 NAMED_REGISTER_ATOMIC(&rb->write_index, "write_index_producer_position", (uintptr_t)(const void *)(rb));
901 NAMED_REGISTER_ATOMIC(&rb->read_index, "read_index_consumer_position", (uintptr_t)(const void *)(rb));
902 NAMED_REGISTER_ATOMIC(&rb->discard_pending, "discard_pending", (uintptr_t)(const void *)(rb));
903 NAMED_REGISTER_ATOMIC(&rb->discard_to_index, "discard_to_index_producer_position", (uintptr_t)(const void *)(rb));
904
905 // Jitter buffer state management
906 NAMED_REGISTER_ATOMIC(&rb->jitter_buffer_filled, "jitter_buffer_has_filled_threshold_flag", (uintptr_t)(const void *)(rb));
907 NAMED_REGISTER_ATOMIC(&rb->crossfade_samples_remaining, "crossfade_samples_remaining_count", (uintptr_t)(const void *)(rb));
908 NAMED_REGISTER_ATOMIC(&rb->crossfade_fade_in, "crossfade_fade_in_direction_flag", (uintptr_t)(const void *)(rb));
909
910 // Audio quality monitoring
911 NAMED_REGISTER_ATOMIC(&rb->underrun_count, "audio_underrun_event_counter", (uintptr_t)(const void *)(rb));
912}

References audio_ring_buffer::crossfade_fade_in, audio_ring_buffer::crossfade_samples_remaining, audio_ring_buffer::discard_pending, 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()

◆ audio_ring_buffer_write()

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

#include <include/ascii-chat/audio/audio.h>

Write audio samples to ring buffer.

Parameters
rbAudio ring buffer (must not be NULL)
dataAudio samples to write (must not be NULL)
samplesNumber 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 962 of file lib/audio/audio.c.

962 {
963 if (!rb || !data || samples <= 0)
964 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb=%p, data=%p, samples=%d", rb, data, samples);
965
966 if (samples % rb->channels)
967 return SET_ERRNO(ERROR_INVALID_PARAM, "Incomplete PCM frame in audio queue write");
968 // Validate samples doesn't exceed our buffer size
969 if (samples > AUDIO_RING_BUFFER_SIZE) {
970 return SET_ERRNO(ERROR_BUFFER, "Attempted to write %d samples, but buffer size is only %d", samples, AUDIO_RING_BUFFER_SIZE);
971 }
972
973 // LOCK-FREE: Load indices with proper memory ordering
974 // - Load our own write_index with relaxed (no sync needed with ourselves)
975 // - Load reader's read_index with acquire (see reader's updates to free space)
976 unsigned int write_idx = atomic_load_u64(&rb->write_index);
977 unsigned int read_idx = atomic_load_u64(&rb->read_index);
978
979 // Calculate current buffer level (how many samples are buffered)
980 int buffer_level;
981 if (write_idx >= read_idx) {
982 buffer_level = (int)(write_idx - read_idx);
983 } else {
984 buffer_level = AUDIO_RING_BUFFER_SIZE - (int)(read_idx - write_idx);
985 }
986 // Reserve 1 slot to distinguish between full and empty states
987 // (when buffer is full, write_idx will be just before read_idx, not equal to it)
988 int available = AUDIO_RING_BUFFER_SIZE - (int)rb->channels - buffer_level;
989
990 // If playback has fallen behind, ask its consumer to skip the stale queue.
991 // Dropping incoming samples here preserves the old backlog, so playback
992 // drains outdated audio and then underruns before it can return to live data.
993 if (buffer_level > (AUDIO_JITTER_HIGH_WATER_MARK * (int)rb->channels)) {
994 if (rb->jitter_buffer_enabled) {
995 // The read callback owns read_index. Let it advance to the latest write
996 // position atomically on its next invocation, then preserve this fresh
997 // packet so audio resumes from the current stream position.
999 log_warn_every(LOG_RATE_FAST, "Audio playback backlog (%d samples); requesting consumer to skip stale queued audio", buffer_level);
1000 } else {
1001 // Capture queues also have a high-water mark, but their reader may be
1002 // processing a matching microphone/render interval. Retain the existing
1003 // policy there instead of changing the reader's timeline asynchronously.
1004 int target_writes = AUDIO_JITTER_TARGET_LEVEL * (int)rb->channels - buffer_level;
1005 if (target_writes < 0) {
1006 target_writes = 0;
1007 }
1008
1009 if (samples > target_writes) {
1010 int dropped = samples - target_writes;
1011 audio_metric(ASCII_OTEL_METRIC_AUDIO_DROPPED, dropped);
1012 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 * (int)rb->channels),
1013 dropped);
1014 samples = target_writes;
1015 }
1016 }
1017 }
1018
1019 // Now write the new samples - should always have enough space after above
1020 int samples_to_write = samples;
1021 if (samples > available) {
1022 // This should rarely happen after the high water mark logic above
1023 int samples_dropped = samples - available;
1024 audio_metric(ASCII_OTEL_METRIC_AUDIO_DROPPED, samples_dropped);
1025 audio_metric(ASCII_OTEL_METRIC_AUDIO_OVERRUN, 1);
1026 samples_to_write = available;
1027 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,
1029 }
1030
1031 samples_to_write -= samples_to_write % (int)rb->channels;
1032 // Write only the samples that fit (preserves existing data integrity)
1033 if (samples_to_write > 0) {
1034 int remaining = AUDIO_RING_BUFFER_SIZE - (int)write_idx;
1035
1036 if (samples_to_write <= remaining) {
1037 // Can copy in one chunk
1038 SAFE_MEMCPY(&rb->data[write_idx], samples_to_write * sizeof(float), data, samples_to_write * sizeof(float));
1039 } else {
1040 // Need to wrap around - copy in two chunks
1041 SAFE_MEMCPY(&rb->data[write_idx], remaining * sizeof(float), data, remaining * sizeof(float));
1042 SAFE_MEMCPY(&rb->data[0], (samples_to_write - remaining) * sizeof(float), &data[remaining], (samples_to_write - remaining) * sizeof(float));
1043 }
1044
1045 // LOCK-FREE: Store new write_index with release ordering
1046 // This ensures all data writes above are visible before the index update
1047 unsigned int new_write_idx = (write_idx + (unsigned int)samples_to_write) % AUDIO_RING_BUFFER_SIZE;
1048 atomic_store_u64(&rb->write_index, new_write_idx);
1049 }
1050
1051 // Note: jitter buffer fill check is now done in read function for better control
1052
1053 return ASCIICHAT_OK; // Success
1054}
@ ERROR_BUFFER
#define LOG_RATE_FAST
Log rate limit: 1 second (1,000,000 microseconds).
Definition log_rates.h:30
#define AUDIO_JITTER_HIGH_WATER_MARK
High water mark - drop OLD samples when buffer exceeds this.
Definition ringbuffer.h:177
#define AUDIO_JITTER_TARGET_LEVEL
Target buffer level after dropping old samples.
Definition ringbuffer.h:187
void audio_ring_buffer_discard_pending(audio_ring_buffer_t *rb)
#define log_warn_every(interval_us, fmt,...)
Rate-limited WARN logging.
Definition log/log.h:749

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::channels, 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 <include/ascii-chat/audio/audio.h>

Set audio pipeline for echo cancellation.

Parameters
ctxAudio context (must not be NULL)
pipelineClient 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 1519 of file lib/audio/audio.c.

1519 {
1520 if (!ctx)
1521 return;
1522 ctx->audio_pipeline = pipeline;
1523}
void * audio_pipeline
Client audio pipeline for AEC3 echo cancellation (opaque pointer).

References audio_context_t::audio_pipeline.

Referenced by audio_cleanup(), audio_connection_init(), session_audio_set_capture_source(), and session_audio_start_duplex().

◆ audio_set_realtime_priority()

asciichat_error_t audio_set_realtime_priority ( void )

#include <include/ascii-chat/audio/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 2187 of file lib/audio/audio.c.

2187 {
2188 // Delegate to platform abstraction layer
2189 asciichat_error_t result = thread_set_realtime_priority();
2190 if (result == ASCIICHAT_OK) {
2191 log_debug("✓ Audio thread real-time priority set successfully");
2192 }
2193 return result;
2194}

References ASCIICHAT_OK, and log_debug.

◆ audio_should_enable_microphone()

bool audio_should_enable_microphone ( audio_capture_source_t source,
bool has_media_audio )

#include <include/ascii-chat/audio/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
sourceAudio capture policy from –audio-capture-source option
has_media_audioTrue 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
}
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.
#define GET_OPTION(field)
Definition options.h:1333

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

2288 {
2289 switch (source) {
2291 return !has_media_audio;
2292
2294 return true;
2295
2297 return false;
2298
2300 return true;
2301
2303 return false;
2304
2305 default:
2306 return !has_media_audio;
2307 }
2308}
audio_visualization_source_t source
Definition fft.c:25
@ AUDIO_CAPTURE_SOURCE_BOTH
Definition options.h:291
@ AUDIO_CAPTURE_SOURCE_REMOTE
Definition options.h:291
@ AUDIO_CAPTURE_SOURCE_MEDIA
Definition options.h:291
@ AUDIO_CAPTURE_SOURCE_MIC
Definition options.h:291
@ AUDIO_CAPTURE_SOURCE_AUTO
Definition options.h:291

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

Referenced by audio_start_duplex().

◆ audio_start_duplex()

asciichat_error_t audio_start_duplex ( audio_context_t * ctx)

#include <include/ascii-chat/audio/audio.h>

Start full-duplex audio (simultaneous capture and playback).

Parameters
ctxAudio context (must not be NULL, must be initialized)
Returns
ASCIICHAT_OK on success, error code on failure

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

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

The duplex callback:

  1. Reads from playback_buffer → outputs to speakers
  2. Processes capture through AEC3 (using render as reference)
  3. Writes processed capture to capture_buffer for encoder thread
Note
Real-time priority is automatically requested for callback thread.
If already running, this function has no effect.
Warning
Both input and output devices must be available.

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

1544 {
1545 ASCII_OTEL_SCOPE(AUDIO_START_DUPLEX);
1546 if (!ctx || !ctx->initialized) {
1547 return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
1548 }
1549
1550 // Check if already running (without holding lock during blocking operations)
1551 // Do this check first before acquiring any locks
1552 if (ctx->duplex_stream || ctx->input_stream || ctx->output_stream) {
1553 return ASCIICHAT_OK;
1554 }
1555
1556 atomic_store_bool(&ctx->shutting_down, false);
1557 bool media_audio = ctx->capture_media_source && media_source_has_audio(ctx->capture_media_source);
1559 if (GET_OPTION(test_audio) || !audio_should_enable_microphone(GET_OPTION(audio_capture_source), media_audio))
1560 ctx->playback_only = true;
1561 bool media_only = GET_OPTION(test_audio) || (media_audio && ctx->playback_only);
1562 if (ctx->playback_only && GET_OPTION(audio_no_playback)) {
1564 ctx->input_device_rate = ctx->output_device_rate = 0;
1566 goto start_worker;
1567 }
1568 if (ctx->playback_buffer) {
1569 // Local decoded PCM is paced by the speaker callback and has no network
1570 // clock to reconcile. Keep its samples exact across callback boundaries.
1571 audio_capture_source_t selection = GET_OPTION(audio_capture_source);
1572 bool local_media_selected = selection == AUDIO_CAPTURE_SOURCE_AUTO || selection == AUDIO_CAPTURE_SOURCE_MEDIA || selection == AUDIO_CAPTURE_SOURCE_BOTH;
1573 ctx->playback_buffer->jitter_buffer_enabled = !(media_audio && ctx->playback_only && ctx->monitor_local_media && local_media_selected);
1575 }
1576
1577 // Media-only recording can run through the software worker without an audio
1578 // device. Initialize PortAudio opportunistically so monitoring still works
1579 // when a speaker is available.
1581 asciichat_error_t pa_result = audio_ensure_portaudio_initialized();
1582 if (pa_result == ASCIICHAT_OK) {
1583 ASSERT_NO_ERRNO_SINCE(pa_scope);
1585 }
1586 if (pa_result != ASCIICHAT_OK && (!media_only || pa_result != ERROR_AUDIO))
1587 return pa_result;
1588
1589 if (pa_result != ASCIICHAT_OK) {
1591 log_warn("PortAudio unavailable; continuing media-only audio without an audio device");
1593 goto start_worker;
1594 }
1595
1596 // Setup input parameters (skip if playback-only mode)
1597 PaStreamParameters inputParams = {0};
1598 const PaDeviceInfo *inputInfo = NULL;
1599 bool has_input = false;
1600
1601 if (!ctx->playback_only) {
1602 if (GET_OPTION(microphone_index) >= 0) {
1603 inputParams.device = GET_OPTION(microphone_index);
1604 } else {
1605 inputParams.device = Pa_GetDefaultInputDevice();
1606 }
1607
1608 if (inputParams.device == paNoDevice) {
1609 return SET_ERRNO(ERROR_AUDIO, "No input device available");
1610 }
1611
1612 inputInfo = Pa_GetDeviceInfo(inputParams.device);
1613 if (!inputInfo) {
1614 return SET_ERRNO(ERROR_AUDIO, "Input device info not found");
1615 }
1616
1617 has_input = true;
1618 inputParams.channelCount = GET_OPTION(microphone_channels) == 2 ? 2 : 1;
1619 int first_channel = GET_OPTION(microphone_channel);
1620 if (first_channel >= 0 && (first_channel >= inputInfo->maxInputChannels || inputParams.channelCount > inputInfo->maxInputChannels - first_channel))
1621 return SET_ERRNO(ERROR_INVALID_PARAM, "Selected microphone input/pair is unavailable on %s", inputInfo->name);
1622 inputParams.sampleFormat = paFloat32;
1623 inputParams.suggestedLatency = inputInfo->defaultLowInputLatency;
1624 inputParams.hostApiSpecificStreamInfo = NULL;
1625 }
1626
1627 // Setup output parameters
1628 PaStreamParameters outputParams;
1629 const PaDeviceInfo *outputInfo = NULL;
1630 bool has_output = false;
1631
1632 if (GET_OPTION(audio_no_playback)) {
1633 outputParams.device = paNoDevice;
1634 log_info("Audio playback disabled by --no-audio-playback");
1635 } else if (GET_OPTION(speakers_index) >= 0) {
1636 outputParams.device = GET_OPTION(speakers_index);
1637 } else {
1638 outputParams.device = Pa_GetDefaultOutputDevice();
1639 }
1640
1641 if (outputParams.device != paNoDevice) {
1642 outputInfo = Pa_GetDeviceInfo(outputParams.device);
1643 if (outputInfo) {
1644 has_output = true;
1645 outputParams.channelCount = outputInfo->maxOutputChannels >= AUDIO_CHANNELS ? AUDIO_CHANNELS : 1;
1646 outputParams.sampleFormat = paFloat32;
1647 outputParams.suggestedLatency = outputInfo->defaultLowOutputLatency;
1648 outputParams.hostApiSpecificStreamInfo = NULL;
1649 } else {
1650 log_warn("Output device info not found for device %d", outputParams.device);
1651 }
1652 }
1653
1654 // Store device rates for diagnostics (only access if device info was retrieved)
1655 ctx->input_device_rate = (has_input && inputInfo) ? inputInfo->defaultSampleRate : 0;
1656 ctx->output_device_rate = (has_output && outputInfo) ? outputInfo->defaultSampleRate : 0;
1657
1658 log_debug("Opening audio:");
1659 if (has_input) {
1660 log_info(" Input: %s (%.0f Hz)", inputInfo->name, inputInfo->defaultSampleRate);
1661 } else if (ctx->playback_only) {
1662 log_debug(" Input: (playback-only mode - no microphone)");
1663 } else {
1664 log_debug(" Input: (none)");
1665 }
1666 if (has_output) {
1667 log_info(" Output: %s (%.0f Hz)", outputInfo->name, outputInfo->defaultSampleRate);
1668 } else {
1669 log_debug(" Output: None (input-only mode - will send audio to server)");
1670 }
1671
1672 // Keep capture and playback synchronized in one 48 kHz duplex stream when
1673 // both devices share a native rate. PortAudio handles conversion to/from
1674 // that rate. Separate streams are needed only when the devices themselves
1675 // run at different rates or one direction is unavailable.
1676 bool rates_differ = has_input && has_output && (inputInfo->defaultSampleRate != outputInfo->defaultSampleRate);
1677 bool try_separate = rates_differ || !has_input || !has_output || GET_OPTION(microphone_channel) != 0;
1678 ctx->input_device_channels = has_input ? (unsigned)inputParams.channelCount : 0;
1679 ctx->output_device_channels = has_output ? (unsigned)outputParams.channelCount : 0;
1680 memset(&ctx->capture_resampler, 0, sizeof(ctx->capture_resampler));
1681 memset(&ctx->playback_resampler, 0, sizeof(ctx->playback_resampler));
1682 PaError err = paNoError;
1683
1684 if (!try_separate) {
1685 // Try full-duplex first (preferred - perfect AEC3 timing)
1686 LOG_IO("portaudio", { err = Pa_OpenStream(&ctx->duplex_stream, &inputParams, &outputParams, AUDIO_SAMPLE_RATE, AUDIO_FRAMES_PER_BUFFER, paClipOff, duplex_callback, ctx); });
1687
1688 if (err == paNoError) {
1691 LOG_IO("portaudio", { err = Pa_StartStream(ctx->duplex_stream); });
1692 if (err != paNoError) {
1693 LOG_IO("portaudio", { Pa_CloseStream(ctx->duplex_stream); });
1694 ctx->duplex_stream = NULL;
1695 log_warn("Full-duplex stream failed to start: %s", Pa_GetErrorText(err));
1696 try_separate = true;
1697 }
1698 } else {
1699 log_warn("Full-duplex stream failed to open: %s", Pa_GetErrorText(err));
1700 if (ctx->duplex_stream) {
1701 LOG_IO("portaudio", { Pa_CloseStream(ctx->duplex_stream); });
1702 ctx->duplex_stream = NULL;
1703 }
1704 try_separate = true;
1705 }
1706 }
1707
1708 if (try_separate) {
1709 // Use separate streams for non-48 kHz devices and single-direction modes.
1710 if (has_output && has_input) {
1711 log_info("Using separate native-rate input/output streams (%.0f Hz in, %.0f Hz out)", inputInfo->defaultSampleRate, outputInfo->defaultSampleRate);
1712 log_info(" Converting between device rates and the %.0f Hz audio pipeline", (double)AUDIO_SAMPLE_RATE);
1713 } else if (has_output) {
1714 log_debug("Using output-only mode (playback-only for mirror/media)");
1715 } else if (has_input) {
1716 log_info("Using input-only mode (no output device available)");
1717 }
1718
1719 // Store the internal sample rate (buffer rate)
1721
1722 // Create render buffer for AEC3 reference synchronization
1724 if (!ctx->render_buffer) {
1725 return SET_ERRNO(ERROR_MEMORY, "Failed to create render buffer");
1726 }
1727
1728 // Open output stream only if output device exists
1729 bool output_ok = false;
1730 double actual_output_rate = 0;
1731 if (has_output) {
1732 // Local media already supplies 48 kHz PCM. Prefer that rate to avoid
1733 // unnecessary application resampling; retain native-rate fallback.
1734 double native_rate = outputInfo->defaultSampleRate;
1735 if (native_rate <= 0.0) {
1736 native_rate = AUDIO_SAMPLE_RATE;
1737 }
1738 double preferred_rate = media_audio && ctx->monitor_local_media ? AUDIO_SAMPLE_RATE : native_rate;
1739 double fallback_rate = (preferred_rate == AUDIO_SAMPLE_RATE) ? native_rate : AUDIO_SAMPLE_RATE;
1740
1741 log_debug("Attempting output at native rate %.0f Hz (fallback %.0f Hz)", preferred_rate, fallback_rate);
1742
1743 // Always use output_callback for output streams (both output-only and duplex modes)
1744 // PortAudio will invoke the callback whenever it needs audio data
1745 // The callback reads PCM supplied to the shared playback buffer.
1746 PaStreamCallback *callback = output_callback;
1747
1748 // Try preferred rate first
1749 LOG_IO("portaudio", { err = audio_open_device(&ctx->output_stream, NULL, &outputParams, preferred_rate, callback, ctx); });
1750
1751 if (err == paNoError) {
1752 actual_output_rate = preferred_rate;
1753 output_ok = true;
1754 log_info("Output stream opened at %.0f Hz", preferred_rate);
1755 } else {
1756 log_warn("Failed to open output at %.0f Hz: %s, trying %.0f Hz", preferred_rate, Pa_GetErrorText(err), fallback_rate);
1757
1758 // If first Pa_OpenStream call left a partial stream, clean it up before retrying
1759 if (ctx->output_stream) {
1760 log_debug("Closing partially-opened output stream from failed preferred rate");
1761 LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
1762 ctx->output_stream = NULL;
1763 }
1764
1765 // Try the other endpoint rate if the native rate is unavailable.
1766 LOG_IO("portaudio", { err = audio_open_device(&ctx->output_stream, NULL, &outputParams, fallback_rate, callback, ctx); });
1767
1768 if (err == paNoError) {
1769 actual_output_rate = fallback_rate;
1770 output_ok = true;
1771 log_info("Output stream opened at fallback rate %.0f Hz", fallback_rate);
1772 } else {
1773 log_warn("Failed to open output stream at fallback rate %.0f Hz: %s", fallback_rate, Pa_GetErrorText(err));
1774 // Clean up if fallback also failed
1775 if (ctx->output_stream) {
1776 log_debug("Closing partially-opened output stream from failed native rate");
1777 LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
1778 ctx->output_stream = NULL;
1779 }
1780 }
1781 }
1782
1783 // Store actual output rate for resampling
1784 if (output_ok) {
1785 ctx->output_device_rate = actual_output_rate;
1786 ctx->output_resample_phase = 0.0;
1787 ctx->output_resample_previous = 0.0f;
1788 ctx->output_resample_has_previous = false;
1789 if (actual_output_rate != AUDIO_SAMPLE_RATE) {
1790 log_warn("⚠️ Output rate mismatch: %.0f Hz output vs %.0f Hz input - resampling will be used", actual_output_rate, (double)AUDIO_SAMPLE_RATE);
1791 }
1792 }
1793 }
1794
1795 // Open input stream only if we have input (skip for playback-only mode)
1796 bool input_ok = !has_input; // If no input, mark as OK (skip)
1797 if (has_input) {
1798 // Open at the device's native rate. The separate input callback converts
1799 // to AUDIO_SAMPLE_RATE before samples enter the shared processing path.
1800 double input_stream_rate = inputInfo->defaultSampleRate;
1801 if (input_stream_rate <= 0.0) {
1802 input_stream_rate = AUDIO_SAMPLE_RATE;
1803 }
1804 LOG_IO("portaudio", { err = audio_open_device(&ctx->input_stream, &inputParams, NULL, input_stream_rate, input_callback, ctx); });
1805 if (err != paNoError && input_stream_rate != AUDIO_SAMPLE_RATE) {
1806 input_stream_rate = AUDIO_SAMPLE_RATE;
1807 LOG_IO("portaudio", { err = audio_open_device(&ctx->input_stream, &inputParams, NULL, input_stream_rate, input_callback, ctx); });
1808 }
1809 input_ok = (err == paNoError);
1810 if (input_ok) {
1811 ctx->input_device_rate = input_stream_rate;
1812 ctx->input_resample_phase = 0.0;
1813 ctx->input_resample_previous = 0.0f;
1814 ctx->input_resample_has_previous = false;
1815 log_info("Input stream opened at native rate %.0f Hz", input_stream_rate);
1816 }
1817
1818 // If input failed, try device 0 as fallback (HDMI on BeaglePlay)
1819 if (!input_ok && GET_OPTION(microphone_index) < 0) {
1820 log_debug("Input failed - trying device 0 as fallback");
1821
1822 // Clean up partial stream from first attempt before retrying
1823 if (ctx->input_stream) {
1824 log_debug("Closing partially-opened input stream from failed primary device");
1825 LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
1826 ctx->input_stream = NULL;
1827 }
1828
1829 PaStreamParameters fallback_input_params = inputParams;
1830 fallback_input_params.device = 0;
1831 const PaDeviceInfo *device_0_info = Pa_GetDeviceInfo(0);
1832 if (device_0_info && device_0_info->maxInputChannels > 0) {
1833 LOG_IO("portaudio", { err = audio_open_device(&ctx->input_stream, &fallback_input_params, NULL, device_0_info->defaultSampleRate, input_callback, ctx); });
1834 if (err == paNoError) {
1835 ctx->input_device_rate = device_0_info->defaultSampleRate;
1836 log_info("Input stream opened on device 0 (fallback from default)");
1837 input_ok = true;
1838 } else {
1839 log_warn("Fallback also failed on device 0: %s", Pa_GetErrorText(err));
1840 // Clean up if fallback also failed
1841 if (ctx->input_stream) {
1842 log_debug("Closing partially-opened input stream from failed fallback device");
1843 LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
1844 ctx->input_stream = NULL;
1845 }
1846 }
1847 }
1848 }
1849
1850 if (!input_ok) {
1851 log_warn("Failed to open input stream: %s", Pa_GetErrorText(err));
1852 }
1853 }
1854
1855 // Check if we got at least one stream working
1856 if (!input_ok && !output_ok && !media_only) {
1857 // Neither stream works - fail completely
1859 ctx->render_buffer = NULL;
1860 return SET_ERRNO(ERROR_AUDIO, "Failed to open both input and output streams");
1861 }
1862
1863 // If output failed but input works, we can still send audio to server
1864 if (!output_ok && input_ok) {
1865 log_info("Output stream unavailable - continuing with input-only (can send audio to server)");
1866 ctx->output_stream = NULL;
1867 }
1868 // If input failed but output works, we can still receive audio from server
1869 if (!input_ok && output_ok) {
1870 log_info("Input stream unavailable - continuing with output-only (can receive audio from server)");
1871 ctx->input_stream = NULL;
1872 }
1873
1874 // Start output stream if it's open
1875 if (ctx->output_stream) {
1876 LOG_IO("portaudio", { err = Pa_StartStream(ctx->output_stream); });
1877 if (err != paNoError) {
1878 if (ctx->input_stream) {
1879 LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
1880 }
1881 LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
1882 ctx->input_stream = NULL;
1883 ctx->output_stream = NULL;
1885 ctx->render_buffer = NULL;
1886 return SET_ERRNO(ERROR_AUDIO, "Failed to start output stream: %s", Pa_GetErrorText(err));
1887 }
1888 }
1889
1890 // Start input stream if it's open
1891 if (ctx->input_stream) {
1892 LOG_IO("portaudio", { err = Pa_StartStream(ctx->input_stream); });
1893 if (err != paNoError) {
1894 if (ctx->output_stream) {
1895 LOG_IO("portaudio", { Pa_StopStream(ctx->output_stream); });
1896 }
1897 if (ctx->input_stream) {
1898 LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
1899 }
1900 if (ctx->output_stream) {
1901 LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
1902 }
1903 ctx->input_stream = NULL;
1904 ctx->output_stream = NULL;
1906 ctx->render_buffer = NULL;
1907 return SET_ERRNO(ERROR_AUDIO, "Failed to start input stream: %s", Pa_GetErrorText(err));
1908 }
1909 }
1910
1911 ctx->separate_streams = true;
1912 log_debug("Separate streams started successfully");
1913 } else {
1914 ctx->separate_streams = false;
1915 log_info("Full-duplex stream started (single callback, perfect AEC3 timing)");
1916 }
1917start_worker:
1918
1919 // Start worker thread for heavy audio processing
1920 if (!ctx->worker_running) {
1922 if (platform_thread_create(&ctx->worker_thread, "audio_worker", audio_worker_thread, ctx) != 0) {
1923 // Failed to create worker thread - stop streams and cleanup
1924 if (ctx->duplex_stream) {
1925 LOG_IO("portaudio", {
1926 Pa_StopStream(ctx->duplex_stream);
1927 Pa_CloseStream(ctx->duplex_stream);
1928 });
1929 ctx->duplex_stream = NULL;
1930 }
1931 if (ctx->input_stream) {
1932 LOG_IO("portaudio", {
1933 Pa_StopStream(ctx->input_stream);
1934 Pa_CloseStream(ctx->input_stream);
1935 });
1936 ctx->input_stream = NULL;
1937 }
1938 if (ctx->output_stream) {
1939 LOG_IO("portaudio", {
1940 Pa_StopStream(ctx->output_stream);
1941 Pa_CloseStream(ctx->output_stream);
1942 });
1943 ctx->output_stream = NULL;
1944 }
1946 ctx->render_buffer = NULL;
1947 return SET_ERRNO(ERROR_THREAD, "Failed to create worker thread");
1948 }
1949 ctx->worker_running = true;
1950 log_debug("Worker thread started successfully");
1951 }
1952
1953 // Lock to update final state flags atomically
1954 mutex_lock(&ctx->state_mutex);
1955 ctx->running = true;
1957 mutex_unlock(&ctx->state_mutex);
1958 return ASCIICHAT_OK;
1959}
void errno_scope_end(asciichat_errno_scope_t scope, asciichat_errno_outcome_t outcome)
asciichat_errno_scope_t errno_scope_begin(void)
#define ASSERT_NO_ERRNO_SINCE(scope)
@ ASCIICHAT_ERRNO_HANDLED
#define AUDIO_FRAMES_PER_BUFFER
@ ERROR_INVALID_STATE
#define log_warn(...)
Log a WARN message.
Definition log/log.h:615
bool media_source_has_audio(media_source_t *source)
Check if media source has audio stream.
Definition source.c:774
audio_capture_source_t
Definition options.h:291
#define LOG_IO(prefix, block)
Definition io.h:104
When code needs to work with asciichat errno snapshot, it keeps total, copied here instead of scatter...
double input_device_rate
Native sample rate of input device.
float input_resample_previous
Last input sample used at a block boundary.
PaStream * input_stream
Separate input stream (when full-duplex unavailable).
bool input_resample_has_previous
Whether a prior input block has been processed.
bool separate_streams
True if using separate input/output streams.
double sample_rate
Actual sample rate of streams (48kHz).
float output_resample_previous
Last source sample used at an output boundary.
double output_device_rate
Native sample rate of output device.
double output_resample_phase
48 kHz source position carried between output callbacks
bool playback_only
True for playback-only mode (mirror), skip microphone capture.
PaStream * duplex_stream
PortAudio full-duplex stream (simultaneous input+output).
double input_resample_phase
Source position carried between native-rate input blocks.
PaStream * output_stream
Separate output stream (when full-duplex unavailable).
uint64_t test_audio_playback_position
Output callback's synthesized monitor sample clock.
bool output_resample_has_previous
Whether a prior output block has been processed.

References ASCII_OTEL_SCOPE, ASCIICHAT_ERRNO_HANDLED, ASCIICHAT_OK, ASSERT_NO_ERRNO_SINCE, atomic_store_bool(), AUDIO_CAPTURE_SOURCE_AUTO, AUDIO_CAPTURE_SOURCE_BOTH, AUDIO_CAPTURE_SOURCE_MEDIA, AUDIO_CHANNELS, AUDIO_FRAMES_PER_BUFFER, audio_ring_buffer_clear(), audio_ring_buffer_create_format(), audio_ring_buffer_destroy(), AUDIO_SAMPLE_RATE, audio_should_enable_microphone(), audio_context_t::capture_media_source, audio_context_t::capture_resampler, audio_context_t::duplex_stream, errno_scope_begin(), errno_scope_end(), ERROR_AUDIO, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_THREAD, GET_OPTION, audio_context_t::initialized, audio_context_t::input_device_channels, 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, audio_ring_buffer::jitter_buffer_enabled, log_debug, log_info, LOG_IO, log_warn, media_source_has_audio(), audio_context_t::monitor_local_media, audio_context_t::output_device_channels, 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, audio_context_t::playback_buffer, audio_context_t::playback_only, audio_context_t::playback_resampler, audio_context_t::render_buffer, audio_context_t::running, audio_context_t::sample_rate, audio_context_t::separate_streams, SET_ERRNO, audio_context_t::shutting_down, audio_context_t::state_mutex, audio_context_t::test_audio_playback_position, audio_context_t::worker_running, audio_context_t::worker_should_stop, and audio_context_t::worker_thread.

Referenced by client_protocol_start(), and session_audio_start_duplex().

◆ audio_stop_duplex()

asciichat_error_t audio_stop_duplex ( audio_context_t * ctx)

#include <include/ascii-chat/audio/audio.h>

Stop full-duplex audio.

Parameters
ctxAudio 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 1961 of file lib/audio/audio.c.

1961 {
1962 ASCII_OTEL_SCOPE(AUDIO_STOP_DUPLEX);
1963 if (!ctx || !ctx->initialized) {
1964 return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
1965 }
1966
1967 atomic_store_bool(&ctx->shutting_down, true);
1968
1969 // Stop worker thread before stopping streams
1970 if (ctx->worker_running) {
1971 log_debug("Stopping worker thread");
1973 cond_signal(&ctx->audio_processing_wakeup); // Wake up worker if waiting
1974 thread_join(&ctx->worker_thread, NULL);
1975 ctx->worker_running = false;
1976 log_debug("Worker thread stopped successfully");
1977 }
1978
1979 if (ctx->playback_buffer) {
1981 }
1982
1983 mutex_lock(&ctx->state_mutex);
1984
1985 if (ctx->duplex_stream) {
1986 log_debug("Stopping duplex stream");
1987 PaError err;
1988 LOG_IO("portaudio", { err = Pa_StopStream(ctx->duplex_stream); });
1989 if (err != paNoError) {
1990 log_warn("Pa_StopStream failed: %s", Pa_GetErrorText(err));
1991 }
1992 log_debug("Closing duplex stream");
1993 LOG_IO("portaudio", { err = Pa_CloseStream(ctx->duplex_stream); });
1994 if (err != paNoError) {
1995 log_warn("Pa_CloseStream failed: %s", Pa_GetErrorText(err));
1996 } else {
1997 log_debug("Duplex stream closed successfully");
1998 }
1999 ctx->duplex_stream = NULL;
2000 }
2001
2002 // Stop separate streams if used
2003 if (ctx->input_stream) {
2004 log_debug("Stopping input stream");
2005 PaError err;
2006 LOG_IO("portaudio", { err = Pa_StopStream(ctx->input_stream); });
2007 if (err != paNoError) {
2008 log_warn("Pa_StopStream input failed: %s", Pa_GetErrorText(err));
2009 }
2010 log_debug("Closing input stream");
2011 LOG_IO("portaudio", { err = Pa_CloseStream(ctx->input_stream); });
2012 if (err != paNoError) {
2013 log_warn("Pa_CloseStream input failed: %s", Pa_GetErrorText(err));
2014 } else {
2015 log_debug("Input stream closed successfully");
2016 }
2017 ctx->input_stream = NULL;
2018 }
2019
2020 if (ctx->output_stream) {
2021 log_debug("Stopping output stream");
2022 PaError err;
2023 LOG_IO("portaudio", { err = Pa_StopStream(ctx->output_stream); });
2024 if (err != paNoError) {
2025 log_warn("Pa_StopStream output failed: %s", Pa_GetErrorText(err));
2026 }
2027 log_debug("Closing output stream");
2028 LOG_IO("portaudio", { err = Pa_CloseStream(ctx->output_stream); });
2029 if (err != paNoError) {
2030 log_warn("Pa_CloseStream output failed: %s", Pa_GetErrorText(err));
2031 } else {
2032 log_debug("Output stream closed successfully");
2033 }
2034 ctx->output_stream = NULL;
2035 }
2036
2037 // Cleanup render buffer
2038 if (ctx->render_buffer) {
2040 ctx->render_buffer = NULL;
2041 }
2042
2043 ctx->running = false;
2044 ctx->separate_streams = false;
2045 mutex_unlock(&ctx->state_mutex);
2046
2047 audio_metrics_flush();
2048 log_debug("Audio stopped");
2049 return ASCIICHAT_OK;
2050}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, atomic_store_bool(), audio_context_t::audio_processing_wakeup, audio_ring_buffer_clear(), audio_ring_buffer_destroy(), audio_context_t::duplex_stream, ERROR_INVALID_STATE, audio_context_t::initialized, audio_context_t::input_stream, log_debug, LOG_IO, log_warn, audio_context_t::output_stream, audio_context_t::playback_buffer, audio_context_t::render_buffer, audio_context_t::running, audio_context_t::separate_streams, SET_ERRNO, audio_context_t::shutting_down, audio_context_t::state_mutex, audio_context_t::worker_running, audio_context_t::worker_should_stop, and audio_context_t::worker_thread.

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

◆ audio_terminate_portaudio_final()

void audio_terminate_portaudio_final ( void )

#include <include/ascii-chat/audio/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 153 of file lib/audio/audio.c.

153 {
154 if (lifecycle_shutdown(&g_pa_lc)) {
155 log_debug("[PORTAUDIO_TERM] Calling Pa_Terminate() to release PortAudio");
156
157 PaError err;
158 LOG_IO("portaudio", { err = Pa_Terminate(); });
159
160 log_debug("[PORTAUDIO_TERM] Pa_Terminate() returned: %s", Pa_GetErrorText(err));
161 }
162}

References 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 <include/ascii-chat/audio/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
batchPointer 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_parse_batch_header(data, len, &batch);
log_error("Audio batch parameters invalid");
return;
}
asciichat_error_t audio_validate_batch_params(const audio_batch_info_t *batch)
Validate audio batch parameters for sanity.

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

2225 {
2226 if (!batch) {
2227 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch info pointer is NULL");
2228 }
2229
2230 // Validate batch_count
2231 if (batch->batch_count == 0) {
2232 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch count cannot be zero");
2233 }
2234
2235 // Check for reasonable max (256 frames per batch is very generous)
2236 if (batch->batch_count > 256) {
2237 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch count too large (batch_count=%u, max=256)", batch->batch_count);
2238 }
2239
2240 // Validate channels (1=mono, 2=stereo, max 8 for multi-channel)
2241 if (batch->channels == 0 || batch->channels > 8) {
2242 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid channel count (channels=%u, valid=1-8)", batch->channels);
2243 }
2244
2245 // Validate sample rate
2247 return SET_ERRNO(ERROR_INVALID_PARAM, "Unsupported sample rate (sample_rate=%u)", batch->sample_rate);
2248 }
2249
2250 // Check for reasonable sample counts
2251 if (batch->total_samples == 0) {
2252 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch has zero samples");
2253 }
2254
2255 // Each batch typically has samples_per_frame worth of samples
2256 // For 48kHz at 20ms per frame: 48000 * 0.02 = 960 samples per frame
2257 // With max 256 frames, that's up to ~245k samples per batch
2258 if (batch->total_samples > 1000000) {
2259 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch sample count suspiciously large (total_samples=%u)", batch->total_samples);
2260 }
2261
2262 return ASCIICHAT_OK;
2263}

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

Write audio samples to playback buffer.

Parameters
ctxAudio context (must not be NULL)
bufferInput buffer of audio samples (must not be NULL)
num_samplesNumber 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 2062 of file lib/audio/audio.c.

2062 {
2063 if (!ctx || !ctx->initialized || !buffer || num_samples <= 0) {
2064 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, buffer=%p, num_samples=%d", ctx, buffer, num_samples);
2065 }
2066
2067 // Don't accept new audio data during shutdown - this prevents garbage/beeps
2068 if (atomic_load_bool(&ctx->shutting_down)) {
2069 return ASCIICHAT_OK; // Silently discard
2070 }
2071
2072 audio_recording_submit(AUDIO_RECORDING_REMOTE, buffer, num_samples, time_get_ns());
2074 asciichat_error_t result = audio_ring_buffer_write(ctx->playback_buffer, buffer, num_samples);
2075
2076 return result;
2077}
bool atomic_load_bool(atomic_t *a)
Atomic pointer wrapper.
asciichat_error_t audio_ring_buffer_write(audio_ring_buffer_t *rb, const float *data, int samples)
Write audio samples to ring buffer.
void audio_recording_submit(audio_recording_source_t source, const float *samples, size_t count, uint64_t start_ns)
Definition recording.c:79
@ AUDIO_RECORDING_REMOTE
Definition recording.h:13
void audio_visualization_submit_stereo(audio_visualization_source_t source, const float *samples, size_t count)
@ AUDIO_VISUALIZATION_SOURCE_REMOTE

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

Referenced by audio_process_received_samples(), and session_audio_write_playback().

◆ buffer_float_to_int16()

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

#include <include/ascii-chat/audio/mixer.h>

Convert float buffer to int16 buffer.

Parameters
srcSource float buffer
dstDestination int16 buffer
countNumber of samples to convert

Batch converts float samples to int16 format for WebRTC.

Definition at line 332 of file effects.c.

332 {
333 if (!src || !dst || count <= 0)
334 return;
335 for (int i = 0; i < count; i++) {
336 dst[i] = float_to_int16(src[i]);
337 }
338}
int16_t float_to_int16(float sample)
Convert float sample to int16 (WebRTC format).
Definition effects.c:319

References float_to_int16().

◆ buffer_int16_to_float()

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

#include <include/ascii-chat/audio/mixer.h>

Convert int16 buffer to float buffer.

Parameters
srcSource int16 buffer
dstDestination float buffer
countNumber of samples to convert

Batch converts int16 samples to float format.

Definition at line 340 of file effects.c.

340 {
341 if (!src || !dst || count <= 0)
342 return;
343 for (int i = 0; i < count; i++) {
344 dst[i] = int16_to_float(src[i]);
345 }
346}
float int16_to_float(int16_t sample)
Convert int16 sample to float.
Definition effects.c:328

References int16_to_float().

◆ buffer_peak()

float buffer_peak ( const float * buffer,
int count )

#include <include/ascii-chat/audio/mixer.h>

Find peak absolute value in buffer.

Parameters
bufferAudio buffer
countNumber 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 348 of file effects.c.

348 {
349 if (!buffer || count <= 0)
350 return 0.0f;
351
352 float peak = 0.0f;
353 for (int i = 0; i < count; i++) {
354 float abs_sample = fabsf(buffer[i]);
355 if (abs_sample > peak)
356 peak = abs_sample;
357 }
358 return peak;
359}

◆ clamp_float()

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

#include <include/ascii-chat/audio/mixer.h>

Clamp a float value to a range.

Parameters
valueValue to clamp
minMinimum value
maxMaximum 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 18 of file effects.c.

18 {
19 if (value < min) {
20 return min;
21 }
22 if (value > max) {
23 return max;
24 }
25 return value;
26}

◆ compressor_init()

void compressor_init ( compressor_t * comp,
float sample_rate )

#include <include/ascii-chat/audio/mixer.h>

Initialize a compressor.

Parameters
compCompressor structure
sample_rateSample 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 29 of file effects.c.

29 {
30 comp->sample_rate = sample_rate;
31 comp->envelope = 0.0f;
32 comp->gain_lin = 1.0f;
33
34 // Set default parameters with 0dB makeup gain (unity)
35 // Soft clip at 0.7 provides 3dB headroom to prevent hard clipping
36 // Ducking and crowd scaling naturally reduce volume, no compensation needed
37 compressor_set_params(comp, -10.0f, 4.0f, 10 * NS_PER_MS_INT, 100 * NS_PER_MS_INT, 0.0f);
38}
float envelope
Current envelope follower state (linear, 0-1).
Definition mixer.h:156
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.
Definition effects.c:40
float sample_rate
Sample rate in Hz (set during initialization).
Definition mixer.h:154
float gain_lin
Current gain multiplier (linear, calculated from envelope).
Definition mixer.h:158

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

Referenced by audio_processor_reset(), and mixer_create_channels().

◆ compressor_process_sample()

float compressor_process_sample ( compressor_t * comp,
float sidechain )

#include <include/ascii-chat/audio/mixer.h>

Process a single sample through compressor.

Parameters
compCompressor structure
sidechainInput 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 73 of file effects.c.

73 {
74 float x = fabsf(sidechain);
75
76 // Update envelope with attack/release
77 if (x > comp->envelope)
78 comp->envelope = comp->attack_coeff * comp->envelope + (1.0f - comp->attack_coeff) * x;
79 else
80 comp->envelope = comp->release_coeff * comp->envelope + (1.0f - comp->release_coeff) * x;
81
82 // Calculate gain reduction
83 float level_dB = linear_to_db(comp->envelope);
84 float gr_dB = compressor_gain_reduction_db(comp, level_dB);
85 float target_lin = db_to_linear(gr_dB + comp->makeup_dB);
86
87 // Smooth gain changes
88 if (target_lin < comp->gain_lin)
89 comp->gain_lin = comp->attack_coeff * comp->gain_lin + (1.0f - comp->attack_coeff) * target_lin;
90 else
91 comp->gain_lin = comp->release_coeff * comp->gain_lin + (1.0f - comp->release_coeff) * target_lin;
92
93 return comp->gain_lin;
94}
float db_to_linear(float db)
Convert decibels to linear gain.
Definition effects.c:10
float makeup_dB
Makeup gain in dB (compensates for gain reduction).
Definition mixer.h:151
float linear_to_db(float linear)
Convert linear gain to decibels.
Definition effects.c:14
float attack_coeff
Attack coefficient (converted from attack_ms).
Definition mixer.h:160
float release_coeff
Release coefficient (converted from release_ms).
Definition mixer.h:162

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 audio_processor_process(), 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 <include/ascii-chat/audio/mixer.h>

Set compressor parameters.

Parameters
compCompressor structure
threshold_dBCompression threshold in dB
ratioCompression ratio (e.g., 4.0 for 4:1)
attack_msAttack time in milliseconds
release_msRelease time in milliseconds
makeup_dBMakeup gain in dB

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

Definition at line 40 of file effects.c.

40 {
41 comp->threshold_dB = threshold_dB;
42 comp->ratio = ratio;
43 comp->attack_ns = attack_ns;
44 comp->release_ns = release_ns;
45 comp->makeup_dB = makeup_dB;
46 comp->knee_dB = 2.0f; // Fixed soft knee
47
48 // Calculate time constants
49 float attack_tau = (float)attack_ns / NS_PER_SEC;
50 float release_tau = (float)release_ns / NS_PER_SEC;
51 comp->attack_coeff = expf(-1.0f / (attack_tau * comp->sample_rate + 1e-12f));
52 comp->release_coeff = expf(-1.0f / (release_tau * comp->sample_rate + 1e-12f));
53}
float ratio
Compression ratio (e.g., 4.0 for 4:1 compression).
Definition mixer.h:145
float knee_dB
Knee width in dB for soft knee (e.g., 2.0).
Definition mixer.h:143
float threshold_dB
Compression threshold in dB (e.g., -10.0).
Definition mixer.h:141
uint64_t attack_ns
Attack time in nanoseconds (how fast compression kicks in).
Definition mixer.h:147
uint64_t release_ns
Release time in nanoseconds (how fast compression releases).
Definition mixer.h:149
#define NS_PER_SEC
Definition time.h:164

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 audio_processor_reset(), and compressor_init().

◆ copy_buffer_with_gain()

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

#include <include/ascii-chat/audio/mixer.h>

Copy buffer with gain scaling.

Parameters
srcSource buffer
dstDestination buffer
countNumber of samples
gainGain 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 393 of file effects.c.

393 {
394 if (!src || !dst || count <= 0)
395 return;
396
397 for (int i = 0; i < count; i++) {
398 dst[i] = src[i] * gain;
399 }
400}

◆ db_to_linear()

float db_to_linear ( float db)

#include <include/ascii-chat/audio/mixer.h>

Convert decibels to linear gain.

Parameters
dbDecibel value
Returns
Linear gain multiplier (10^(db/20))

Converts decibel value to linear gain multiplier for audio processing.

Definition at line 10 of file effects.c.

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

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

◆ ducking_destroy()

void ducking_destroy ( ducking_t * duck)

#include <include/ascii-chat/audio/mixer.h>

Free ducking system resources.

Parameters
duckDucking structure

Frees per-source arrays allocated by ducking_init().

Definition at line 153 of file mixer.c.

153 {
154 if (duck->envelope) {
155 SAFE_FREE(duck->envelope);
156 }
157 if (duck->gain) {
158 SAFE_FREE(duck->gain);
159 }
160}
float * gain
Per-source ducking gain (linear, calculated from envelope).
Definition mixer.h:304
float * envelope
Per-source envelope follower state (linear, allocated per source).
Definition mixer.h:302

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 <include/ascii-chat/audio/mixer.h>

Initialize ducking system.

Parameters
duckDucking structure
num_sourcesNumber of sources to support
sample_rateSample 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 98 of file mixer.c.

98 {
99 if (!duck) {
100 return SET_ERRNO(ERROR_INVALID_PARAM, "duck is NULL");
101 }
102
103 // Set default parameters
104 // threshold_dB: sources below this aren't considered "speaking"
105 // leader_margin_dB: sources within this margin of loudest are all "leaders"
106 // atten_dB: how much to attenuate non-leaders (was -12dB, too aggressive)
107 duck->threshold_dB = -45.0f; // More lenient threshold
108 duck->leader_margin_dB = 6.0f; // Wider margin = more sources treated as leaders
109 duck->atten_dB = -6.0f; // Only -6dB attenuation (was -12dB)
110 duck->attack_ns = 10 * NS_PER_MS_INT; // Slower attack (10ms)
111 duck->release_ns = 200 * NS_PER_MS_INT; // Slower release (200ms)
112 duck->envelope = NULL;
113 duck->gain = NULL;
114
115 // Calculate time constants
116 float attack_tau = (float)duck->attack_ns / NS_PER_SEC;
117 float release_tau = (float)duck->release_ns / NS_PER_SEC;
118 duck->attack_coeff = expf(-1.0f / (attack_tau * sample_rate + 1e-12f));
119 duck->release_coeff = expf(-1.0f / (release_tau * sample_rate + 1e-12f));
120
121 // Allocate arrays with overflow checking
122 size_t envelope_size = 0;
123 if (checked_size_mul((size_t)num_sources, sizeof(float), &envelope_size) != ASCIICHAT_OK) {
124 return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Ducking envelope array size overflow: %d sources", num_sources);
125 }
126 duck->envelope = SAFE_MALLOC(envelope_size, float *);
127 if (!duck->envelope) {
128 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate ducking envelope array");
129 }
130
131 size_t gain_size = 0;
132 if (checked_size_mul((size_t)num_sources, sizeof(float), &gain_size) != ASCIICHAT_OK) {
133 SAFE_FREE(duck->envelope);
134 duck->envelope = NULL;
135 return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Ducking gain array size overflow: %d sources", num_sources);
136 }
137 duck->gain = SAFE_MALLOC(gain_size, float *);
138 if (!duck->gain) {
139 SAFE_FREE(duck->envelope);
140 duck->envelope = NULL;
141 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate ducking gain array");
142 }
143
144 // Initialize
145 SAFE_MEMSET(duck->envelope, (size_t)num_sources * sizeof(float), 0, (size_t)num_sources * sizeof(float));
146 for (int i = 0; i < num_sources; i++) {
147 duck->gain[i] = 1.0f;
148 }
149
150 return ASCIICHAT_OK;
151}
float leader_margin_dB
Leader margin in dB (sources within this of loudest are leaders).
Definition mixer.h:289
float release_coeff
Release coefficient (converted from release_ms).
Definition mixer.h:300
float atten_dB
Attenuation in dB for non-leader sources.
Definition mixer.h:291
float attack_coeff
Attack coefficient (converted from attack_ms).
Definition mixer.h:298
uint64_t release_ns
Ducking release time in nanoseconds.
Definition mixer.h:295
float threshold_dB
Speaking threshold in dB (sources below this are not "speaking").
Definition mixer.h:287
uint64_t attack_ns
Ducking attack time in nanoseconds.
Definition mixer.h:293
@ ERROR_BUFFER_OVERFLOW

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_channels().

◆ ducking_process_frame()

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

#include <include/ascii-chat/audio/mixer.h>

Process a frame of audio through ducking system.

Parameters
duckDucking structure
envelopesArray of per-source envelope levels (input)
gainsArray of per-source ducking gains (output)
num_sourcesNumber 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 170 of file mixer.c.

170 {
171 // Find the loudest source
172 float max_dB = -120.0f;
173 float env_dB[MIXER_MAX_SOURCES];
174
175 for (int i = 0; i < num_sources; i++) {
176 env_dB[i] = linear_to_db(envelopes[i]);
177 if (env_dB[i] > max_dB)
178 max_dB = env_dB[i];
179 }
180
181 // Calculate ducking gain for each source
182 float leader_cut = db_to_linear(duck->atten_dB);
183
184 for (int i = 0; i < num_sources; i++) {
185 bool is_speaking = env_dB[i] > duck->threshold_dB;
186 bool is_leader = is_speaking && (env_dB[i] >= max_dB - duck->leader_margin_dB);
187
188 float target;
189 if (is_speaking && !is_leader) {
190 target = leader_cut;
191 } else {
192 target = 1.0f;
193 }
194
195 // Smooth gain transitions
196 if (target < gains[i])
197 gains[i] = duck->attack_coeff * gains[i] + (1.0f - duck->attack_coeff) * target;
198 else
199 gains[i] = duck->release_coeff * gains[i] + (1.0f - duck->release_coeff) * target;
200 }
201}
#define MIXER_MAX_SOURCES
Maximum number of simultaneous audio sources.
Definition mixer.h:105

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 <include/ascii-chat/audio/mixer.h>

Set ducking parameters.

Parameters
duckDucking structure
threshold_dBSpeaking threshold in dB
leader_margin_dBLeader margin in dB
atten_dBAttenuation in dB for non-leaders
attack_msAttack time in milliseconds
release_msRelease time in milliseconds

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

Definition at line 162 of file mixer.c.

162 {
163 duck->threshold_dB = threshold_dB;
164 duck->leader_margin_dB = leader_margin_dB;
165 duck->atten_dB = atten_dB;
166 duck->attack_ns = attack_ns;
167 duck->release_ns = release_ns;
168}

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 <include/ascii-chat/audio/mixer.h>

Apply linear fade to buffer in-place.

Parameters
bufferAudio buffer (modified in-place)
countNumber of samples
start_gainGain at start of buffer
end_gainGain 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 370 of file effects.c.

370 {
371 if (!buffer || count <= 0)
372 return;
373
374 float step = (end_gain - start_gain) / (float)count;
375 float gain = start_gain;
376 for (int i = 0; i < count; i++) {
377 buffer[i] *= gain;
378 gain += step;
379 }
380}

◆ fade_buffer_smooth()

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

#include <include/ascii-chat/audio/mixer.h>

Apply smoothstep fade to buffer in-place.

Parameters
bufferAudio buffer (modified in-place)
countNumber of samples
fade_inIf true, fade from 0 to 1; if false, fade from 1 to 0

Applies smoothstep curve for more natural-sounding fades.

Definition at line 382 of file effects.c.

382 {
383 if (!buffer || count <= 0)
384 return;
385
386 for (int i = 0; i < count; i++) {
387 float t = (float)i / (float)(count - 1);
388 float gain = smoothstep(fade_in ? t : (1.0f - t));
389 buffer[i] *= gain;
390 }
391}
float smoothstep(float t)
Compute smoothstep interpolation.
Definition effects.c:311

References smoothstep().

◆ float_to_int16()

int16_t float_to_int16 ( float sample)

#include <include/ascii-chat/audio/mixer.h>

Convert float sample to int16 (WebRTC format).

Parameters
sampleFloat 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 319 of file effects.c.

319 {
320 // Clamp to [-1, 1] then scale to int16 range
321 if (sample > 1.0f)
322 sample = 1.0f;
323 if (sample < -1.0f)
324 sample = -1.0f;
325 return (int16_t)(sample * 32767.0f);
326}

Referenced by buffer_float_to_int16().

◆ highpass_filter_init()

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

#include <include/ascii-chat/audio/mixer.h>

Initialize a high-pass filter.

Parameters
filterHigh-pass filter structure
cutoff_hzCutoff frequency in Hz
sample_rateSample rate in Hz

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

Definition at line 185 of file effects.c.

185 {
186 if (!filter)
187 return;
188
189 filter->cutoff_hz = cutoff_hz;
190 filter->sample_rate = sample_rate;
191
192 // Calculate filter coefficient
193 // alpha = 1 / (1 + 2*pi*fc/fs)
194 filter->alpha = 1.0f / (1.0f + 2.0f * M_PI * cutoff_hz / sample_rate);
195
196 highpass_filter_reset(filter);
197}
#define M_PI
Definition effects.c:6
float alpha
Filter coefficient alpha (calculated from cutoff_hz).
Definition mixer.h:233
void highpass_filter_reset(highpass_filter_t *filter)
Reset high-pass filter state.
Definition effects.c:199
float sample_rate
Sample rate in Hz (set during initialization).
Definition mixer.h:230
float cutoff_hz
Cutoff frequency in Hz (frequencies below this are attenuated).
Definition mixer.h:228

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

Referenced by audio_processor_reset().

◆ highpass_filter_process_buffer()

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

#include <include/ascii-chat/audio/mixer.h>

Process a buffer of samples through high-pass filter.

Parameters
filterHigh-pass filter structure
bufferAudio buffer (modified in-place)
num_samplesNumber of samples to process

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

Definition at line 221 of file effects.c.

221 {
222 if (!filter || !buffer || num_samples <= 0)
223 return;
224
225 for (int i = 0; i < num_samples; i++) {
226 buffer[i] = highpass_filter_process_sample(filter, buffer[i]);
227 }
228}
float highpass_filter_process_sample(highpass_filter_t *filter, float input)
Process a single sample through high-pass filter.
Definition effects.c:207

References highpass_filter_process_sample().

◆ highpass_filter_process_sample()

float highpass_filter_process_sample ( highpass_filter_t * filter,
float input )

#include <include/ascii-chat/audio/mixer.h>

Process a single sample through high-pass filter.

Parameters
filterHigh-pass filter structure
inputInput 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 207 of file effects.c.

207 {
208 if (!filter)
209 return input;
210
211 // First-order high-pass filter
212 // y[n] = alpha * (y[n-1] + x[n] - x[n-1])
213 float output = filter->alpha * (filter->prev_output + input - filter->prev_input);
214
215 filter->prev_input = input;
216 filter->prev_output = output;
217
218 return output;
219}
float prev_input
Previous input sample (filter state).
Definition mixer.h:235
float prev_output
Previous output sample (filter state).
Definition mixer.h:237

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

Referenced by audio_processor_process(), and highpass_filter_process_buffer().

◆ highpass_filter_reset()

void highpass_filter_reset ( highpass_filter_t * filter)

#include <include/ascii-chat/audio/mixer.h>

Reset high-pass filter state.

Parameters
filterHigh-pass filter structure

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

Definition at line 199 of file effects.c.

199 {
200 if (!filter)
201 return;
202
203 filter->prev_input = 0.0f;
204 filter->prev_output = 0.0f;
205}

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 <include/ascii-chat/audio/mixer.h>

Convert int16 sample to float.

Parameters
sampleInt16 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 328 of file effects.c.

328 {
329 return (float)sample / 32768.0f;
330}

Referenced by buffer_int16_to_float().

◆ linear_to_db()

float linear_to_db ( float linear)

#include <include/ascii-chat/audio/mixer.h>

Convert linear gain to decibels.

Parameters
linearLinear gain multiplier
Returns
Decibel value (20*log10(linear))

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

Definition at line 14 of file effects.c.

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

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 <include/ascii-chat/audio/mixer.h>

Initialize a low-pass filter.

Parameters
filterLow-pass filter structure
cutoff_hzCutoff frequency in Hz
sample_rateSample rate in Hz

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

Definition at line 235 of file effects.c.

235 {
236 if (!filter)
237 return;
238
239 filter->cutoff_hz = cutoff_hz;
240 filter->sample_rate = sample_rate;
241
242 // Calculate filter coefficient using RC time constant formula
243 // alpha = dt / (RC + dt) where RC = 1 / (2 * pi * fc)
244 float dt = 1.0f / sample_rate;
245 float rc = 1.0f / (2.0f * (float)M_PI * cutoff_hz);
246 filter->alpha = dt / (rc + dt);
247
248 lowpass_filter_reset(filter);
249}
float cutoff_hz
Cutoff frequency in Hz (frequencies above this are attenuated).
Definition mixer.h:257
float alpha
Filter coefficient alpha (calculated from cutoff_hz).
Definition mixer.h:262
float sample_rate
Sample rate in Hz (set during initialization).
Definition mixer.h:259
void lowpass_filter_reset(lowpass_filter_t *filter)
Reset low-pass filter state.
Definition effects.c:251

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

Referenced by audio_processor_reset().

◆ lowpass_filter_process_buffer()

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

#include <include/ascii-chat/audio/mixer.h>

Process a buffer of samples through low-pass filter.

Parameters
filterLow-pass filter structure
bufferAudio buffer (modified in-place)
num_samplesNumber of samples to process

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

Definition at line 270 of file effects.c.

270 {
271 if (!filter || !buffer || num_samples <= 0)
272 return;
273
274 for (int i = 0; i < num_samples; i++) {
275 buffer[i] = lowpass_filter_process_sample(filter, buffer[i]);
276 }
277}
float lowpass_filter_process_sample(lowpass_filter_t *filter, float input)
Process a single sample through low-pass filter.
Definition effects.c:258

References lowpass_filter_process_sample().

◆ lowpass_filter_process_sample()

float lowpass_filter_process_sample ( lowpass_filter_t * filter,
float input )

#include <include/ascii-chat/audio/mixer.h>

Process a single sample through low-pass filter.

Parameters
filterLow-pass filter structure
inputInput 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 258 of file effects.c.

258 {
259 if (!filter)
260 return input;
261
262 // First-order IIR low-pass filter: y[n] = alpha * x[n] + (1 - alpha) * y[n-1]
263 float output = filter->alpha * input + (1.0f - filter->alpha) * filter->prev_output;
264
265 filter->prev_output = output;
266
267 return output;
268}
float prev_output
Previous output sample (filter state).
Definition mixer.h:264

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

Referenced by audio_processor_process(), and lowpass_filter_process_buffer().

◆ lowpass_filter_reset()

void lowpass_filter_reset ( lowpass_filter_t * filter)

#include <include/ascii-chat/audio/mixer.h>

Reset low-pass filter state.

Parameters
filterLow-pass filter structure

Resets filter state (prev_output) to zero.

Definition at line 251 of file effects.c.

251 {
252 if (!filter)
253 return;
254
255 filter->prev_output = 0.0f;
256}

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 <include/ascii-chat/audio/mixer.h>

Add an audio source to the mixer.

Parameters
mixerAudio mixer
client_idClient ID for this source
bufferPointer 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 402 of file mixer.c.

402 {
403 ASCII_OTEL_SCOPE(MIXER_ADD_SOURCE);
404 if (!mixer || !buffer || buffer->channels != mixer->channels)
405 return -1;
406
407 // OPTIMIZATION 2: Acquire write lock for source modification
408 rwlock_wrlock(&mixer->source_lock);
409
410 // Find an empty slot
411 int slot = -1;
412 for (int i = 0; i < mixer->max_sources; i++) {
413 if (mixer->source_ids[i] == NULL) {
414 slot = i;
415 break;
416 }
417 }
418
419 if (slot == -1) {
420 rwlock_wrunlock(&mixer->source_lock);
421 log_warn("Mixer: No available slots for client %s", client_id);
422 return -1;
423 }
424
425 mixer->source_buffers[slot] = buffer;
426 // Duplicate the client_id string - we own this memory now
427 size_t client_id_len = strlen(client_id) + 1;
428 mixer->source_ids[slot] = SAFE_MALLOC(client_id_len, char *);
429 if (!mixer->source_ids[slot]) {
430 log_warn("Mixer: Failed to allocate memory for client_id %s", client_id);
431 mixer->source_buffers[slot] = NULL;
432 rwlock_wrunlock(&mixer->source_lock);
433 return -1;
434 }
435 asciichat_error_t strcpy_result = SAFE_STRCPY((char *)mixer->source_ids[slot], client_id_len, client_id);
436 if (strcpy_result != ASCIICHAT_OK) {
437 log_error("Mixer: Failed to copy client_id: %s", asciichat_error_format(NULL, strcpy_result));
438 SAFE_FREE(mixer->source_ids[slot]);
439 mixer->source_buffers[slot] = NULL;
440 rwlock_wrunlock(&mixer->source_lock);
441 return -1;
442 }
443 for (int other = 0; other < mixer->max_sources; other++) {
444 if (other == slot || !mixer->source_ids[other])
445 continue;
446 mixer->listener_buffers[slot][other] = SAFE_CALLOC(1, sizeof(mixer_listener_buffer_t), void *);
447 mixer->listener_buffers[other][slot] = SAFE_CALLOC(1, sizeof(mixer_listener_buffer_t), void *);
448 }
449 mixer->source_active[slot] = true;
450 mixer->num_sources++;
452
453 // OPTIMIZATION 1: Update bitset optimization structures
454 mixer->active_sources_mask[slot / 64] |= (1ULL << (slot % 64)); // Set bit for this slot
455 // Hash table optimization disabled for string-based client_ids (linear search is acceptable for small mixer sizes)
456
457 rwlock_wrunlock(&mixer->source_lock);
458
459 log_info("Mixer: Added source for client %s at slot %d", client_id, slot);
460 return slot;
461}
const char * asciichat_error_format(const char *message, asciichat_error_t code)
int atomic_fetch_add_int(atomic_t *a, int delta)
Atomically add to an int and return the previous value.
const char ** source_ids
Array of client ID strings (one per source slot).
Definition mixer.h:360
bool * source_active
Array of active flags (true if source is active).
Definition mixer.h:362
rwlock_t source_lock
Reader-writer lock protecting source arrays and bitset.
Definition mixer.h:372
atomic_t active_sources
Definition mixer.h:345
unsigned channels
Definition mixer.h:350
int num_sources
Current number of active audio sources.
Definition mixer.h:344
uint64_t active_sources_mask[((128+63)/64)]
Bitset of active sources (bit i = source i is active, O(1) iteration).
Definition mixer.h:365
int max_sources
Maximum number of sources (allocated array sizes).
Definition mixer.h:347
audio_ring_buffer_t ** source_buffers
Array of pointers to client audio ring buffers.
Definition mixer.h:356
struct mixer_listener_buffer * listener_buffers[128][128]
Definition mixer.h:358
#define SAFE_CALLOC(count, size, cast)
#define SAFE_STRCPY(dest, dest_size, src)
struct mixer_listener_buffer mixer_listener_buffer_t
Owns the temporary storage used by mixer listener buffer. The data pointers and size or cursor fields...

References mixer_t::active_sources, mixer_t::active_sources_mask, ASCII_OTEL_SCOPE, asciichat_error_format(), ASCIICHAT_OK, atomic_fetch_add_int(), audio_ring_buffer::channels, mixer_t::channels, mixer_t::listener_buffers, log_error, log_info, log_warn, mixer_t::max_sources, mixer_t::num_sources, SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, SAFE_STRCPY, mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_ids, and mixer_t::source_lock.

◆ mixer_create()

mixer_t * mixer_create ( int max_sources,
int sample_rate )

#include <include/ascii-chat/audio/mixer.h>

Create a new audio mixer.

Parameters
max_sourcesMaximum number of audio sources to support
sample_rateSample 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 204 of file mixer.c.

204 {
205 return mixer_create_channels(max_sources, sample_rate, 1);
206}
mixer_t * mixer_create_channels(int max_sources, int sample_rate, unsigned channels)
Definition mixer.c:208

References mixer_create_channels().

◆ mixer_create_channels()

mixer_t * mixer_create_channels ( int max_sources,
int sample_rate,
unsigned channels )

#include <include/ascii-chat/audio/mixer.h>

Definition at line 208 of file mixer.c.

208 {
209 if (channels != 1 && channels != 2) {
210 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid mixer channel count");
211 return NULL;
212 }
213 ASCII_OTEL_SCOPE(MIXER_CREATE);
214 // Validate parameters
215 if (max_sources <= 0 || max_sources > MIXER_MAX_SOURCES) {
216 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid max_sources: %d (must be 1-%d)", max_sources, MIXER_MAX_SOURCES);
217 return NULL;
218 }
219
220 if (sample_rate <= 0 || sample_rate > 192000) {
221 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid sample_rate: %d (must be 1-192000)", sample_rate);
222 return NULL;
223 }
224
225 mixer_t *mixer;
226 mixer = SAFE_MALLOC(sizeof(mixer_t), mixer_t *);
227 if (!mixer) {
228 SET_ERRNO(ERROR_MEMORY, "Failed to allocate mixer structure");
229 return NULL;
230 }
231
232 memset(mixer->spectral_left, 0, sizeof(mixer->spectral_left));
233 memset(mixer->spectral_right, 0, sizeof(mixer->spectral_right));
234 mixer->num_sources = 0;
236 mixer->max_sources = max_sources;
237 mixer->sample_rate = sample_rate;
238 mixer->channels = channels;
239 memset(mixer->listener_buffers, 0, sizeof(mixer->listener_buffers));
240
241 // Allocate source management arrays with overflow checking
242 size_t buffers_size = 0;
243 if (checked_size_mul((size_t)max_sources, sizeof(audio_ring_buffer_t *), &buffers_size) != ASCIICHAT_OK) {
244 SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Mixer source buffers array overflow: %d sources", max_sources);
245 SAFE_FREE(mixer);
246 return NULL;
247 }
248 mixer->source_buffers = SAFE_MALLOC(buffers_size, audio_ring_buffer_t **);
249 if (!mixer->source_buffers) {
250 SAFE_FREE(mixer);
251 return NULL;
252 }
253
254 size_t ids_size = 0;
255 if (checked_size_mul((size_t)max_sources, sizeof(const char *), &ids_size) != ASCIICHAT_OK) {
256 SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Mixer source IDs array overflow: %d sources", max_sources);
258 SAFE_FREE(mixer);
259 return NULL;
260 }
261 mixer->source_ids = SAFE_MALLOC(ids_size, const char **);
262 if (!mixer->source_ids) {
264 SAFE_FREE(mixer);
265 return NULL;
266 }
267
268 size_t active_size = 0;
269 if (checked_size_mul((size_t)max_sources, sizeof(bool), &active_size) != ASCIICHAT_OK) {
270 SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Mixer source active array overflow: %d sources", max_sources);
272 SAFE_FREE(mixer->source_ids);
273 SAFE_FREE(mixer);
274 return NULL;
275 }
276 mixer->source_active = SAFE_MALLOC(active_size, bool *);
277 if (!mixer->source_active) {
279 SAFE_FREE(mixer->source_ids);
280 SAFE_FREE(mixer);
281 return NULL;
282 }
283
284 // Initialize arrays
285 SAFE_MEMSET((void *)mixer->source_buffers, buffers_size, 0, buffers_size);
286 SAFE_MEMSET(mixer->source_ids, ids_size, 0, ids_size);
287 SAFE_MEMSET(mixer->source_active, active_size, 0, active_size);
288
289 // OPTIMIZATION 1: Initialize bitset optimization structures
290 memset(mixer->active_sources_mask, 0, sizeof(mixer->active_sources_mask)); // No sources active initially
291 for (int i = 0; i < 256; i++) {
293 }
294
295 // Allocate mix buffer BEFORE rwlock_init so cleanup path is correct
296 size_t mix_buffer_size = 0;
297 if (checked_size_mul(MIXER_FRAME_SIZE, sizeof(float), &mix_buffer_size) != ASCIICHAT_OK) {
298 SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Mixer mix buffer size overflow: %zu samples", (size_t)MIXER_FRAME_SIZE);
300 SAFE_FREE(mixer->source_ids);
301 SAFE_FREE(mixer->source_active);
302 SAFE_FREE(mixer);
303 return NULL;
304 }
305 mixer->mix_buffer = buffer_alloc(NULL, mix_buffer_size);
306 if (!mixer->mix_buffer) {
307 SET_ERRNO(ERROR_MEMORY, "Failed to allocate mix buffer");
309 SAFE_FREE(mixer->source_ids);
310 SAFE_FREE(mixer->source_active);
311 SAFE_FREE(mixer);
312 return NULL;
313 }
314
315 // OPTIMIZATION 2: Initialize reader-writer lock
316 if (rwlock_init(&mixer->source_lock, "audio_mixer_sources") != 0) {
317 SET_ERRNO(ERROR_THREAD, "Failed to initialize mixer source lock");
319 SAFE_FREE(mixer->source_ids);
320 SAFE_FREE(mixer->source_active);
322 SAFE_FREE(mixer);
323 return NULL;
324 }
325
326 // Set crowd scaling parameters
327 mixer->crowd_alpha = 0.5f; // Square root scaling
328 mixer->base_gain = 1.0f; // Unity gain - let compressor handle loudness, avoid clipping
329
330 // Initialize processing
331 if (ducking_init(&mixer->ducking, max_sources, (float)sample_rate) != ASCIICHAT_OK) {
332 rwlock_destroy(&mixer->source_lock);
334 SAFE_FREE(mixer->source_ids);
335 SAFE_FREE(mixer->source_active);
337 SAFE_FREE(mixer);
338 return NULL;
339 }
340 compressor_init(&mixer->compressor, (float)sample_rate);
341 if (GET_OPTION(audio_spectral_mixer)) {
342 spectral_config_t config = spectral_default_config(sample_rate);
343 config.fft_size = GET_OPTION(audio_fft_size);
344 config.noise_gate = GET_OPTION(audio_spectral_gate);
345 config.compressor = GET_OPTION(audio_multiband);
346 config.adaptive_eq = GET_OPTION(audio_adaptive_eq);
347 config.auto_gain = GET_OPTION(audio_spectral_agc);
348 if (channels == 2) {
349 config.auto_gain = false;
350 config.compressor = false;
351 config.noise_gate = false;
352 }
353 for (int i = 0; i <= max_sources; ++i) {
354 if (spectral_create(&config, &mixer->spectral_left[i]) != ASCIICHAT_OK || (channels == 2 && spectral_create(&config, &mixer->spectral_right[i]) != ASCIICHAT_OK)) {
355 mixer_destroy(mixer);
356 return NULL;
357 }
358 }
359 }
360
361 log_debug("Audio mixer created: max_sources=%d, sample_rate=%d", max_sources, sample_rate);
362
363 // Register mixer and its sync primitives for debugging
364 NAMED_REGISTER_MIXER(mixer, "audio_mixer", NULL);
365 NAMED_REGISTER_RWLOCK(&mixer->source_lock, "source_lock", (uintptr_t)(const void *)(mixer));
366
367 return mixer;
368}
void atomic_store_int(atomic_t *a, int value)
Atomically store an int value.
void * buffer_alloc(buffer_domain_t *domain, size_t size)
Definition buffer.c:272
struct audio_ring_buffer audio_ring_buffer_t
struct spectral_processor * spectral_left[128+1]
Definition mixer.h:352
uint8_t source_id_to_index[256]
Hash table mapping client_id → mixer source index (uses hash function for strings).
Definition mixer.h:367
float base_gain
Base gain before crowd scaling is applied.
Definition mixer.h:377
struct spectral_processor * spectral_right[128+1]
Definition mixer.h:353
float crowd_alpha
Crowd scaling exponent (typically 0.5 for sqrt scaling).
Definition mixer.h:375
ducking_t ducking
Ducking system (active speaker detection and attenuation).
Definition mixer.h:380
void compressor_init(compressor_t *comp, float sample_rate)
Initialize a compressor.
Definition effects.c:29
int ducking_init(ducking_t *duck, int num_sources, float sample_rate)
Initialize ducking system.
Definition mixer.c:98
#define MIXER_FRAME_SIZE
Number of samples processed per audio frame.
Definition mixer.h:116
float * mix_buffer
Temporary buffer for mixing operations (pre-allocated).
Definition mixer.h:385
compressor_t compressor
Compressor (dynamic range compression).
Definition mixer.h:382
#define MIXER_HASH_INVALID
Invalid index sentinel value for mixer hash table.
Definition mixer.h:489
void mixer_destroy(mixer_t *mixer)
Destroy a mixer and free all resources.
Definition mixer.c:370
int sample_rate
Sample rate in Hz (e.g., 44100).
Definition mixer.h:349
#define NAMED_REGISTER_RWLOCK(lock, name, parent_ptr)
Register an rwlock with automatic format specifier.
#define NAMED_REGISTER_MIXER(mixer, name, parent_ptr)
Register an audio mixer with automatic format specifier.
asciichat_error_t spectral_create(const spectral_config_t *c, spectral_processor_t **out)
Definition spectral.c:63
spectral_config_t spectral_default_config(int sample_rate)
Definition spectral.c:36
For ducking, this is the live record that ties threshold_dB, leader_margin_dB, atten_dB,...
Definition mixer.h:342
For spectral config, this is the live record that ties sample_rate, fft_size, noise_gate,...
Definition spectral.h:21

References mixer_t::active_sources, mixer_t::active_sources_mask, spectral_config_t::adaptive_eq, ASCII_OTEL_SCOPE, ASCIICHAT_OK, atomic_store_int(), spectral_config_t::auto_gain, mixer_t::base_gain, buffer_alloc(), buffer_release, mixer_t::channels, mixer_t::compressor, spectral_config_t::compressor, compressor_init(), mixer_t::crowd_alpha, mixer_t::ducking, ducking_init(), ERROR_BUFFER_OVERFLOW, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_THREAD, spectral_config_t::fft_size, GET_OPTION, mixer_t::listener_buffers, log_debug, mixer_t::max_sources, mixer_t::mix_buffer, mixer_destroy(), MIXER_FRAME_SIZE, MIXER_HASH_INVALID, MIXER_MAX_SOURCES, NAMED_REGISTER_MIXER, NAMED_REGISTER_RWLOCK, spectral_config_t::noise_gate, mixer_t::num_sources, 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, mixer_t::source_lock, spectral_create(), spectral_default_config(), mixer_t::spectral_left, and mixer_t::spectral_right.

Referenced by mixer_create().

◆ mixer_destroy()

void mixer_destroy ( mixer_t * mixer)

#include <include/ascii-chat/audio/mixer.h>

Destroy a mixer and free all resources.

Parameters
mixerMixer 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 370 of file mixer.c.

370 {
371 if (!mixer)
372 return;
373
374 NAMED_UNREGISTER(mixer);
375 for (int i = 0; i <= mixer->max_sources; ++i) {
378 }
379
380 // OPTIMIZATION 2: Destroy reader-writer lock
381 rwlock_destroy(&mixer->source_lock);
382
383 ducking_destroy(&mixer->ducking);
384
385 // Free all allocated client_id strings before freeing the array itself
386 for (int i = 0; i < mixer->max_sources; i++) {
387 for (int j = 0; j < mixer->max_sources; j++)
388 SAFE_FREE(mixer->listener_buffers[i][j]);
389 if (mixer->source_ids[i] != NULL) {
390 SAFE_FREE(mixer->source_ids[i]);
391 }
392 }
393
395 SAFE_FREE(mixer->source_ids);
396 SAFE_FREE(mixer->source_active);
398 SAFE_FREE(mixer);
399 log_debug("Audio mixer destroyed");
400}
void ducking_destroy(ducking_t *duck)
Free ducking system resources.
Definition mixer.c:153
void spectral_destroy(spectral_processor_t *p)
Definition spectral.c:96

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

Referenced by mixer_create_channels().

◆ mixer_process()

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

#include <include/ascii-chat/audio/mixer.h>

Process audio from all active sources.

Parameters
mixerAudio mixer
outputOutput buffer for mixed audio (must have num_samples elements)
num_samplesNumber 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 536 of file mixer.c.

536 {
537 ASCII_OTEL_SCOPE(MIXER_PROCESS);
538 if (!mixer || !output || num_samples <= 0)
539 return -1;
540
541 // Serialize source access and mutable compressor/spectral state.
542 rwlock_wrlock(&mixer->source_lock);
543
544 // Clear output buffer
545 SAFE_MEMSET(output, num_samples * sizeof(float), 0, num_samples * sizeof(float));
546
547 // Count active sources
548 int active_count = 0;
549 for (int i = 0; i < mixer->max_sources; i++) {
550 if (mixer->source_ids[i] != 0 && mixer->source_active[i] && mixer->source_buffers[i]) {
551 active_count++;
552 }
553 }
554
555 if (active_count == 0 && !mixer->spectral_left[mixer->max_sources]) {
556 rwlock_wrunlock(&mixer->source_lock);
557 return 0;
558 }
559
560 // Process in frames for efficiency
561 for (int frame_start = 0; frame_start < num_samples; frame_start += MIXER_FRAME_SIZE) {
562 int frame_size = (frame_start + MIXER_FRAME_SIZE > num_samples) ? (num_samples - frame_start) : MIXER_FRAME_SIZE;
563
564 // Clear mix buffer
565 SAFE_MEMSET(mixer->mix_buffer, frame_size * sizeof(float), 0, frame_size * sizeof(float));
566
567 // Temporary buffers for source audio
568 float source_samples[MIXER_MAX_SOURCES][MIXER_FRAME_SIZE];
569 int source_count = 0;
570 int source_map[MIXER_MAX_SOURCES]; // Maps source index to slot
571
572 // Read from each active source
573 for (int i = 0; i < mixer->max_sources; i++) {
574 if (mixer->source_ids[i] != 0 && mixer->source_active[i] && mixer->source_buffers[i]) {
575 // Read samples from this source's ring buffer
576 size_t samples_read_size = audio_ring_buffer_read(mixer->source_buffers[i], source_samples[source_count], frame_size);
577 int samples_read = (int)samples_read_size;
578
579 // Accept partial frames - pad with silence if needed
580 // This prevents audio dropouts when ring buffers are temporarily under-filled
581 if (samples_read > 0) {
582 // Pad remaining samples with silence if we got a partial frame
583 if (samples_read < frame_size) {
584 SAFE_MEMSET(&source_samples[source_count][samples_read], (frame_size - samples_read) * sizeof(float), 0, (frame_size - samples_read) * sizeof(float));
585 }
586
587 source_map[source_count] = i;
588 source_count++;
589
590 if (source_count >= MIXER_MAX_SOURCES)
591 break;
592 }
593 }
594 }
595
596 // OPTIMIZATION: Batch envelope calculation per-frame instead of per-sample
597 // Calculate peak amplitude for each source over the entire frame
598 int speaking_count = 0;
599
600 for (int i = 0; i < source_count; i++) {
601 int slot = source_map[i];
602 float peak = 0.0f;
603
604 // Find peak amplitude in frame (much faster than per-sample envelope)
605 for (int s = 0; s < frame_size; s++) {
606 float abs_sample = fabsf(source_samples[i][s]);
607 if (abs_sample > peak)
608 peak = abs_sample;
609 }
610
611 // Update envelope using frame peak (one update per frame instead of per-sample)
612 if (peak > mixer->ducking.envelope[slot]) {
613 mixer->ducking.envelope[slot] = mixer->ducking.attack_coeff * mixer->ducking.envelope[slot] + (1.0f - mixer->ducking.attack_coeff) * peak;
614 } else {
615 mixer->ducking.envelope[slot] = mixer->ducking.release_coeff * mixer->ducking.envelope[slot] + (1.0f - mixer->ducking.release_coeff) * peak;
616 }
617
618 // Count speaking sources
619 if (mixer->ducking.envelope[slot] > db_to_linear(-60.0f))
620 speaking_count++;
621 }
622
623 // Apply ducking ONCE per frame (not per-sample)
624 ducking_process_frame(&mixer->ducking, mixer->ducking.envelope, mixer->ducking.gain, mixer->max_sources);
625
626 // Calculate crowd scaling ONCE per frame
627 float crowd_gain = (speaking_count > 0) ? (1.0f / powf((float)speaking_count, mixer->crowd_alpha)) : 1.0f;
628 float pre_bus = mixer->base_gain * crowd_gain;
629
630 // Pre-calculate combined gains for each source (ducking * pre_bus)
631 float combined_gains[MIXER_MAX_SOURCES];
632 for (int i = 0; i < source_count; i++) {
633 int slot = source_map[i];
634 combined_gains[i] = mixer->ducking.gain[slot] * pre_bus;
635 }
636
637 // OPTIMIZATION: Fast mixing loop - simple multiply-add with pre-calculated gains
638 // NO per-sample compressor to avoid expensive log/pow calls (480x per iteration)
639 for (int s = 0; s < frame_size; s++) {
640 float mix = 0.0f;
641 for (int i = 0; i < source_count; i++) {
642 mix += source_samples[i][s] * combined_gains[i];
643 }
644
645 // Store in mix buffer for frame-level compression below
646 mixer->mix_buffer[s] = mix;
647 }
648
649 // OPTIMIZATION: Apply compression ONCE per frame instead of per-sample
650 // This reduces expensive log10f/powf calls from 480x to 1x per iteration
651 // Calculate frame peak for compressor sidechain
652 float frame_peak = 0.0f;
653 for (int s = 0; s < frame_size; s++) {
654 float abs_val = fabsf(mixer->mix_buffer[s]);
655 if (abs_val > frame_peak)
656 frame_peak = abs_val;
657 }
658
659 // Process compressor with frame peak (1 call instead of 480)
660 float comp_gain = compressor_process_sample(&mixer->compressor, frame_peak);
661
662 uint64_t clipped = 0;
663 // Apply compression gain and soft clipping to all samples
664 for (int s = 0; s < frame_size; s++) {
665 float mix = mixer->mix_buffer[s] * comp_gain;
666 if (fabsf(mix) > 0.7f)
667 ++clipped;
668
669 // Soft clip at 0.7 to provide 3dB headroom and prevent hard clipping
670 // With +6dB makeup gain, peaks can exceed 1.0, so we need headroom
671 // threshold=0.7 maps asymptotically toward 1.0, preventing harsh distortion
672 output[frame_start + s] = soft_clip(mix, 0.7f, 3.0f);
673 }
674 ascii_otel_metric(ASCII_OTEL_METRIC_AUDIO_CLIP, (double)clipped);
675 }
676
677 if (mixer->spectral_left[mixer->max_sources])
678 mixer_spectral_process(mixer, mixer->max_sources, output, (size_t)num_samples);
679 rwlock_wrunlock(&mixer->source_lock);
680 return num_samples;
681}
void ducking_process_frame(ducking_t *duck, float *envelopes, float *gains, int num_sources)
Process a frame of audio through ducking system.
Definition mixer.c:170
float soft_clip(float sample, float threshold, float steepness)
Apply soft clipping to a sample.
Definition effects.c:284
float compressor_process_sample(compressor_t *comp, float sidechain)
Process a single sample through compressor.
Definition effects.c:73
unsigned long long uint64_t
void ascii_otel_metric(ascii_otel_metric_t metric, double value)
Definition otel.c:159

References ascii_otel_metric(), ASCII_OTEL_SCOPE, 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, SAFE_MEMSET, soft_clip(), mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_ids, mixer_t::source_lock, and mixer_t::spectral_left.

◆ mixer_process_excluding_source()

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

#include <include/ascii-chat/audio/mixer.h>

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

Parameters
mixerAudio mixer
outputOutput buffer for mixed audio
num_samplesNumber of samples to process
exclude_client_idClient 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 683 of file mixer.c.

683 {
684 ASCII_OTEL_SCOPE(MIXER_PROCESS_EXCLUDING_SOURCE);
685 if (!mixer || !output || num_samples <= 0) {
686 return -1;
687 }
688
689 // Serialize sample distribution and mutable ducking/compressor state.
690 rwlock_wrlock(&mixer->source_lock);
691
692 // Clear output buffer
693 SAFE_MEMSET(output, num_samples * sizeof(float), 0, num_samples * sizeof(float));
694
695 // Source IDs are strings; match the complete ID hash used by the caller.
696 uint8_t exclude_index = MIXER_HASH_INVALID;
697 for (int i = 0; i < mixer->max_sources; i++) {
698 if (mixer->source_ids[i] && fnv1a_hash_string(mixer->source_ids[i]) == exclude_client_id) {
699 exclude_index = (uint8_t)i;
700 break;
701 }
702 }
703 if (exclude_index != MIXER_HASH_INVALID)
704 mixer_distribute_samples(mixer);
705 uint64_t active_mask[MIXER_MASK_WORDS];
706 memcpy(active_mask, mixer->active_sources_mask, sizeof(active_mask));
707 bool valid_exclude = exclude_index < mixer->max_sources && exclude_index != MIXER_HASH_INVALID;
708 if (valid_exclude)
709 active_mask[exclude_index / 64] &= ~(1ULL << (exclude_index % 64));
710 bool any_active = false;
711 for (size_t word = 0; word < MIXER_MASK_WORDS; ++word)
712 any_active |= active_mask[word] != 0;
713
714 // Fast check: any sources to mix?
715 int spectral_slot = valid_exclude ? exclude_index : mixer->max_sources;
716 if (!any_active && !mixer->spectral_left[spectral_slot]) {
717 rwlock_wrunlock(&mixer->source_lock);
718 return 0; // No sources to mix (excluding the specified client), output silence
719 }
720
721 // Process in frames for efficiency
722 for (int frame_start = 0; frame_start < num_samples; frame_start += MIXER_FRAME_SIZE) {
723 int frame_size = (frame_start + MIXER_FRAME_SIZE > num_samples) ? (num_samples - frame_start) : MIXER_FRAME_SIZE;
724
725 uint64_t read_start_ns = time_get_ns();
726
727 // Clear mix buffer
728 SAFE_MEMSET(mixer->mix_buffer, frame_size * sizeof(float), 0, frame_size * sizeof(float));
729
730 // Temporary buffers for source audio
731 float source_samples[MIXER_MAX_SOURCES][MIXER_FRAME_SIZE];
732 int source_count = 0;
733 int source_map[MIXER_MAX_SOURCES]; // Maps source index to slot
734
735 // OPTIMIZATION 1: Iterate only over active sources using bitset
736 size_t word = 0;
737 uint64_t current_mask = active_mask[0];
738 while (source_count < MIXER_MAX_SOURCES) {
739 while (!current_mask && word + 1 < MIXER_MASK_WORDS)
740 current_mask = active_mask[++word];
741 if (!current_mask)
742 break;
743 int i = (int)(word * 64) + find_first_set_bit(current_mask);
744 current_mask &= current_mask - 1;
745
746 // Verify source is valid (defensive programming)
747 if (i < mixer->max_sources && mixer->source_ids[i] != 0 && mixer->source_buffers[i]) {
748 // Read samples from this source's ring buffer
749 size_t samples_read_size = 0;
750 if (valid_exclude) {
751 mixer_listener_buffer_t *queue = mixer->listener_buffers[exclude_index][i];
752 if (queue && queue->count >= (size_t)frame_size) {
753 samples_read_size = (size_t)frame_size;
754 for (int s = 0; s < frame_size; s++)
755 source_samples[source_count][s] = queue->samples[(queue->read + s) % MIXER_LISTENER_SAMPLES];
756 queue->read = (queue->read + samples_read_size) % MIXER_LISTENER_SAMPLES;
757 queue->count -= samples_read_size;
758 }
759 } else {
760 samples_read_size = audio_ring_buffer_read(mixer->source_buffers[i], source_samples[source_count], frame_size);
761 }
762 int samples_read = (int)samples_read_size;
763
764 // Accept partial frames - pad with silence if needed
765 // This prevents audio dropouts when ring buffers are temporarily under-filled
766 if (samples_read > 0) {
767 // Pad remaining samples with silence if we got a partial frame
768 if (samples_read < frame_size) {
769 SAFE_MEMSET(&source_samples[source_count][samples_read], (frame_size - samples_read) * sizeof(float), 0, (frame_size - samples_read) * sizeof(float));
770 }
771
772 // DIAGNOSTIC: Calculate RMS of this source's audio
773 float source_rms = 0.0f;
774 if (frame_start == 0) { // Only log for first frame to reduce spam
775 float sum_squares = 0.0f;
776 for (int s = 0; s < samples_read; s++) {
777 sum_squares += source_samples[source_count][s] * source_samples[source_count][s];
778 }
779 source_rms = sqrtf(sum_squares / (float)samples_read);
780 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);
781 }
782
783 source_map[source_count] = i;
784 source_count++;
785 }
786 }
787 }
788
789 uint64_t read_end_ns = time_get_ns();
790 uint64_t read_time_ns = time_elapsed_ns(read_start_ns, read_end_ns);
791
792 if (read_time_ns > 10 * NS_PER_MS_INT) {
793 char read_time_str[TIME_DURATION_BUFFER_SIZE];
794 time_pretty(read_time_ns, -1, read_time_str, sizeof(read_time_str));
795 log_warn_every(LOG_RATE_DEFAULT, "Mixer: Slow source reading took %s for %d sources", read_time_str, source_count);
796 }
797
798 if (GET_OPTION(no_audio_mixer)) {
799 for (int sample = 0; sample < frame_size; sample++) {
800 for (int source = 0; source < source_count; source++)
801 output[frame_start + sample] += source_samples[source][sample];
802 }
803 continue;
804 }
805
806 // OPTIMIZATION: Batch envelope calculation per-frame instead of per-sample
807 // Calculate peak amplitude for each source over the entire frame
808 int speaking_count = 0;
809
810 for (int i = 0; i < source_count; i++) {
811 int slot = source_map[i];
812 float peak = 0.0f;
813
814 // Find peak amplitude in frame (much faster than per-sample envelope)
815 for (int s = 0; s < frame_size; s++) {
816 float abs_sample = fabsf(source_samples[i][s]);
817 if (abs_sample > peak)
818 peak = abs_sample;
819 }
820
821 // Update envelope using frame peak (one update per frame instead of per-sample)
822 if (peak > mixer->ducking.envelope[slot]) {
823 mixer->ducking.envelope[slot] = mixer->ducking.attack_coeff * mixer->ducking.envelope[slot] + (1.0f - mixer->ducking.attack_coeff) * peak;
824 } else {
825 mixer->ducking.envelope[slot] = mixer->ducking.release_coeff * mixer->ducking.envelope[slot] + (1.0f - mixer->ducking.release_coeff) * peak;
826 }
827
828 // Count speaking sources
829 if (mixer->ducking.envelope[slot] > db_to_linear(-60.0f))
830 speaking_count++;
831 }
832
833 // Apply ducking ONCE per frame (not per-sample)
834 ducking_process_frame(&mixer->ducking, mixer->ducking.envelope, mixer->ducking.gain, mixer->max_sources);
835
836 // Calculate crowd scaling ONCE per frame
837 float crowd_gain = (speaking_count > 0) ? (1.0f / powf((float)speaking_count, mixer->crowd_alpha)) : 1.0f;
838 float pre_bus = mixer->base_gain * crowd_gain;
839
840 // Pre-calculate combined gains for each source (ducking * pre_bus)
841 float combined_gains[MIXER_MAX_SOURCES];
842 for (int i = 0; i < source_count; i++) {
843 int slot = source_map[i];
844 combined_gains[i] = mixer->ducking.gain[slot] * pre_bus;
845 }
846
847 // OPTIMIZATION: Fast mixing loop - simple multiply-add with pre-calculated gains
848 // NO per-sample compressor to avoid expensive log/pow calls (480x per iteration)
849 for (int s = 0; s < frame_size; s++) {
850 float mix = 0.0f;
851 for (int i = 0; i < source_count; i++) {
852 mix += source_samples[i][s] * combined_gains[i];
853 }
854
855 // Store in mix buffer for frame-level compression below
856 mixer->mix_buffer[s] = mix;
857 }
858
859 // OPTIMIZATION: Apply compression ONCE per frame instead of per-sample
860 // This reduces expensive log10f/powf calls from 480x to 1x per iteration
861 // Calculate frame peak for compressor sidechain
862 float frame_peak = 0.0f;
863 for (int s = 0; s < frame_size; s++) {
864 float abs_val = fabsf(mixer->mix_buffer[s]);
865 if (abs_val > frame_peak)
866 frame_peak = abs_val;
867 }
868
869 // Process compressor with frame peak (1 call instead of 480)
870 float comp_gain = compressor_process_sample(&mixer->compressor, frame_peak);
871
872 uint64_t clipped = 0;
873 // Apply compression gain and soft clipping to all samples
874 for (int s = 0; s < frame_size; s++) {
875 float mix = mixer->mix_buffer[s] * comp_gain;
876 if (fabsf(mix) > 0.7f)
877 ++clipped;
878
879 // Soft clip at 0.7 to provide 3dB headroom and prevent hard clipping
880 // With +6dB makeup gain, peaks can exceed 1.0, so we need headroom
881 // threshold=0.7 maps asymptotically toward 1.0, preventing harsh distortion
882 output[frame_start + s] = soft_clip(mix, 0.7f, 3.0f);
883 }
884 ascii_otel_metric(ASCII_OTEL_METRIC_AUDIO_CLIP, (double)clipped);
885 }
886
887 if (mixer->spectral_left[spectral_slot])
888 mixer_spectral_process(mixer, spectral_slot, output, (size_t)num_samples);
889 rwlock_wrunlock(&mixer->source_lock);
890
891 return num_samples;
892}
#define MIXER_MASK_WORDS
Definition mixer.h:106
#define LOG_RATE_DEFAULT
Log rate limit: 5 seconds (5,000,000 microseconds) - default for audio/video packets.
Definition log_rates.h:36
int time_pretty(uint64_t nanoseconds, int decimals, char *buffer, size_t buffer_size)
Format nanoseconds as a compact duration with configurable sub-minute precision.
Definition time.c:368
#define TIME_DURATION_BUFFER_SIZE
Definition time.h:40
uint64_t time_elapsed_ns(uint64_t start_ns, uint64_t end_ns)
Calculate elapsed time with wraparound safety.
Definition time.c:117
#define MIXER_LISTENER_SAMPLES
Definition mixer.c:25
float samples[8192]
Definition mixer.c:32

References mixer_t::active_sources_mask, ascii_otel_metric(), ASCII_OTEL_SCOPE, 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_MASK_WORDS, MIXER_MAX_SOURCES, NS_PER_MS_INT, mixer_listener_buffer::read, ducking_t::release_coeff, SAFE_MEMSET, mixer_listener_buffer::samples, soft_clip(), source, mixer_t::source_buffers, mixer_t::source_ids, mixer_t::source_lock, mixer_t::spectral_left, TIME_DURATION_BUFFER_SIZE, time_elapsed_ns(), and time_pretty().

Referenced by client_audio_render_thread().

◆ mixer_remove_source()

void mixer_remove_source ( mixer_t * mixer,
const char * client_id )

#include <include/ascii-chat/audio/mixer.h>

Remove an audio source from the mixer.

Parameters
mixerAudio mixer
client_idClient 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 463 of file mixer.c.

463 {
464 ASCII_OTEL_SCOPE(MIXER_REMOVE_SOURCE);
465 if (!mixer)
466 return;
467
468 // OPTIMIZATION 2: Acquire write lock for source modification
469 rwlock_wrlock(&mixer->source_lock);
470
471 for (int i = 0; i < mixer->max_sources; i++) {
472 if (mixer->source_ids[i] != NULL && strcmp(mixer->source_ids[i], client_id) == 0) {
473 for (int j = 0; j < mixer->max_sources; j++) {
474 SAFE_FREE(mixer->listener_buffers[i][j]);
475 if (j != i)
476 SAFE_FREE(mixer->listener_buffers[j][i]);
477 }
478 spectral_reset(mixer->spectral_left[i]);
480 mixer->source_buffers[i] = NULL;
481 // Free the allocated client_id string
482 SAFE_FREE(mixer->source_ids[i]);
483 mixer->source_active[i] = false;
484 mixer->num_sources--;
486
487 // OPTIMIZATION 1: Update bitset optimization structures
488 mixer->active_sources_mask[i / 64] &= ~(1ULL << (i % 64)); // Clear bit for this slot
489 // Hash table optimization disabled for string-based client_ids
490
491 // Reset ducking state for this source
492 mixer->ducking.envelope[i] = 0.0f;
493 mixer->ducking.gain[i] = 1.0f;
494
495 rwlock_wrunlock(&mixer->source_lock);
496
497 log_info("Mixer: Removed source for client %s from slot %d", client_id, i);
498 return;
499 }
500 }
501
502 rwlock_wrunlock(&mixer->source_lock);
503}
int atomic_fetch_sub_int(atomic_t *a, int delta)
Atomically subtract from an int and return the previous value.
void spectral_reset(spectral_processor_t *p)
Definition spectral.c:41

References mixer_t::active_sources, mixer_t::active_sources_mask, ASCII_OTEL_SCOPE, atomic_fetch_sub_int(), mixer_t::ducking, ducking_t::envelope, ducking_t::gain, mixer_t::listener_buffers, log_info, mixer_t::max_sources, mixer_t::num_sources, SAFE_FREE, mixer_t::source_active, mixer_t::source_buffers, mixer_t::source_ids, mixer_t::source_lock, mixer_t::spectral_left, spectral_reset(), and mixer_t::spectral_right.

◆ mixer_set_source_active()

void mixer_set_source_active ( mixer_t * mixer,
const char * client_id,
bool active )

#include <include/ascii-chat/audio/mixer.h>

Set whether a source is active (receiving audio).

Parameters
mixerAudio mixer
client_idClient ID
activetrue 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 509 of file mixer.c.

509 {
510 if (!mixer)
511 return;
512
513 // OPTIMIZATION 2: Acquire write lock for source modification
514 rwlock_wrlock(&mixer->source_lock);
515
516 for (int i = 0; i < mixer->max_sources; i++) {
517 if (mixer->source_ids[i] != NULL && strcmp(mixer->source_ids[i], client_id) == 0) {
518 mixer->source_active[i] = active;
519
520 // OPTIMIZATION 1: Update bitset for active state change
521 if (active) {
522 mixer->active_sources_mask[i / 64] |= (1ULL << (i % 64)); // Set bit
523 } else {
524 mixer->active_sources_mask[i / 64] &= ~(1ULL << (i % 64)); // Clear bit
525 }
526
527 rwlock_wrunlock(&mixer->source_lock);
528 log_debug("Mixer: Set source %s active=%d", client_id, active);
529 return;
530 }
531 }
532
533 rwlock_wrunlock(&mixer->source_lock);
534}

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

◆ mixer_source_count()

int mixer_source_count ( const mixer_t * mixer)

#include <include/ascii-chat/audio/mixer.h>

Return the current number of registered audio sources without taking the mixer lock.

Definition at line 505 of file mixer.c.

505 {
506 return mixer ? atomic_load_int((atomic_t *)&mixer->active_sources) : 0;
507}
int atomic_load_int(atomic_t *a)
Atomically load an int value.
Atomic value wrapper for integral/boolean types.
Definition atomic.h:76

References mixer_t::active_sources, and atomic_load_int().

Referenced by client_audio_render_thread().

◆ noise_gate_init()

void noise_gate_init ( noise_gate_t * gate,
float sample_rate )

#include <include/ascii-chat/audio/mixer.h>

Initialize a noise gate.

Parameters
gateNoise gate structure
sample_rateSample rate in Hz

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

Definition at line 101 of file effects.c.

101 {
102 if (!gate)
103 return;
104
105 gate->sample_rate = sample_rate;
106 gate->envelope = 0.0f;
107 gate->gate_open = false;
108
109 // Default parameters
110 // Slower attack (10ms) prevents clicking artifacts during gate transitions
111 // threshold=0.01, attack=10ms, release=50ms, hysteresis=0.9
112 noise_gate_set_params(gate, 0.01f, 10 * NS_PER_MS_INT, 50 * NS_PER_MS_INT, 0.9f);
113}
float sample_rate
Sample rate in Hz (set during initialization).
Definition mixer.h:196
float envelope
Current envelope follower state (linear, 0-1).
Definition mixer.h:198
bool gate_open
True if gate is currently open (allowing audio through).
Definition mixer.h:204
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.
Definition effects.c:115

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 audio_processor_reset().

◆ noise_gate_is_open()

bool noise_gate_is_open ( const noise_gate_t * gate)

#include <include/ascii-chat/audio/mixer.h>

Check if noise gate is currently open.

Parameters
gateNoise gate structure
Returns
true if gate is open, false if closed

Returns current gate state. Useful for debugging and monitoring.

Definition at line 176 of file effects.c.

176 {
177 return gate ? gate->gate_open : false;
178}

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 <include/ascii-chat/audio/mixer.h>

Process a buffer of samples through noise gate.

Parameters
gateNoise gate structure
bufferAudio buffer (modified in-place)
num_samplesNumber 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 157 of file effects.c.

157 {
158 if (!gate || !buffer || num_samples <= 0)
159 return;
160
161 // First pass: find peak amplitude
162 float peak = 0.0f;
163 for (int i = 0; i < num_samples; i++) {
164 float abs_sample = fabsf(buffer[i]);
165 if (abs_sample > peak) {
166 peak = abs_sample;
167 }
168 }
169
170 // Second pass: apply gate
171 for (int i = 0; i < num_samples; i++) {
172 buffer[i] = noise_gate_process_sample(gate, buffer[i], peak);
173 }
174}
float noise_gate_process_sample(noise_gate_t *gate, float input, float peak_amplitude)
Process a single sample through noise gate.
Definition effects.c:132

References noise_gate_process_sample().

◆ noise_gate_process_sample()

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

#include <include/ascii-chat/audio/mixer.h>

Process a single sample through noise gate.

Parameters
gateNoise gate structure
inputInput sample value
peak_amplitudePeak 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 132 of file effects.c.

132 {
133 if (!gate)
134 return input;
135
136 // Determine target state with hysteresis
137 float target;
138 if (gate->gate_open) {
139 // Gate is open - use lower threshold (hysteresis) to close
140 target = (peak_amplitude > gate->threshold * gate->hysteresis) ? 1.0f : 0.0f;
141 } else {
142 // Gate is closed - use normal threshold to open
143 target = (peak_amplitude > gate->threshold) ? 1.0f : 0.0f;
144 }
145
146 // Update gate state
147 gate->gate_open = (target > 0.5f);
148
149 // Update envelope with appropriate coefficient
150 float coeff = (target > gate->envelope) ? gate->attack_coeff : gate->release_coeff;
151 gate->envelope += coeff * (target - gate->envelope);
152
153 // Apply gate
154 return input * gate->envelope;
155}
float hysteresis
Hysteresis factor (0-1, prevents gate chatter).
Definition mixer.h:193
float threshold
Gate threshold in linear units (e.g., 0.01f for -40dB).
Definition mixer.h:187
float attack_coeff
Attack coefficient (converted from attack_ms).
Definition mixer.h:200

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 audio_processor_process(), and 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 <include/ascii-chat/audio/mixer.h>

Set noise gate parameters.

Parameters
gateNoise gate structure
thresholdGate threshold in linear units
attack_msAttack time in milliseconds
release_msRelease time in milliseconds
hysteresisHysteresis factor (0-1) to prevent chatter

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

Definition at line 115 of file effects.c.

115 {
116 if (!gate)
117 return;
118
119 gate->threshold = threshold;
120 gate->attack_ns = attack_ns;
121 gate->release_ns = release_ns;
122 gate->hysteresis = hysteresis;
123
124 // Calculate coefficients for envelope follower
125 // Using exponential moving average: coeff = 1 - exp(-1 / (time_s * sample_rate))
126 float attack_s = (float)attack_ns / NS_PER_SEC;
127 float release_s = (float)release_ns / NS_PER_SEC;
128 gate->attack_coeff = 1.0f - expf(-1.0f / (attack_s * gate->sample_rate + 1e-12f));
129 gate->release_coeff = 1.0f - expf(-1.0f / (release_s * gate->sample_rate + 1e-12f));
130}
float release_coeff
Release coefficient (converted from release_ms).
Definition mixer.h:202
uint64_t attack_ns
Attack time in nanoseconds (how fast gate opens).
Definition mixer.h:189
uint64_t release_ns
Release time in nanoseconds (how fast gate closes).
Definition mixer.h:191

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 audio_processor_reset(), and noise_gate_init().

◆ opus_codec_create_decoder()

opus_codec_t * opus_codec_create_decoder ( int sample_rate)

#include <include/ascii-chat/audio/opus.h>

Create an Opus decoder.

Parameters
sample_rateSample rate in Hz (must match encoder)
Returns
Pointer to new decoder, NULL on error

Creates a stereo Opus decoder. The explicit-channel variant accepts mono or stereo.

Warning
Returned pointer must be freed with opus_codec_destroy()

Definition at line 87 of file opus.c.

87 {
89}
opus_codec_t * opus_codec_create_decoder_channels(int sample_rate, int channels)
Definition opus.c:91

References AUDIO_CHANNELS, and opus_codec_create_decoder_channels().

◆ opus_codec_create_decoder_channels()

opus_codec_t * opus_codec_create_decoder_channels ( int sample_rate,
int channels )

#include <include/ascii-chat/audio/opus.h>

Definition at line 91 of file opus.c.

91 {
92 ASCII_OTEL_SCOPE(OPUS_DECODER_CREATE);
93 ASCII_OTEL_ATTR_INT("audio.sample_rate", sample_rate);
94 if (sample_rate <= 0 || (channels != 1 && channels != 2)) {
95 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid sample rate: %d", sample_rate);
96 return NULL;
97 }
98
100 if (!codec) {
101 SET_ERRNO(ERROR_MEMORY, "Failed to allocate opus codec context");
102 return NULL;
103 }
104
105 // Create decoder
106 int error = OPUS_OK;
107 codec->decoder = opus_decoder_create(sample_rate, channels, &error);
108 if (error != OPUS_OK || !codec->decoder) {
109 SET_ERRNO(ERROR_AUDIO, "Failed to create Opus decoder: %s", opus_strerror(error));
110 SAFE_FREE(codec);
111 return NULL;
112 }
113
114 codec->encoder = NULL;
115 codec->sample_rate = sample_rate;
116 codec->channels = channels;
117 codec->bitrate = 0; // N/A for decoder
118 codec->tmp_buffer = NULL;
119
120 log_debug("Opus decoder created: sample_rate=%d", sample_rate);
121
122 // Register Opus decoder for debugging
123 NAMED_REGISTER_CONTEXT(codec, "opus_decoder", "opus_codec", NULL);
124
125 return codec;
126}
#define NAMED_REGISTER_CONTEXT(context, context_type, name, parent_ptr)
Register a generic context with automatic format specifier.
#define ASCII_OTEL_ATTR_INT(key, value)
Definition otel.h:72
uint8_t * tmp_buffer
Temporary buffer for internal use.
Definition opus.h:111
int bitrate
Bitrate in bits per second (encoder only).
Definition opus.h:110
int channels
PCM channels (1 or 2); sample counts include all channels.
Definition opus.h:109
int sample_rate
Sample rate in Hz (e.g., 44100).
Definition opus.h:108
OpusEncoder * encoder
Encoder state (NULL if decoder).
Definition opus.h:106
OpusDecoder * decoder
Decoder state (NULL if encoder).
Definition opus.h:107

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_SCOPE, opus_codec_t::bitrate, opus_codec_t::channels, 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(), opus_codec_create_decoder(), and session_host_receive_packet().

◆ opus_codec_create_encoder()

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

#include <include/ascii-chat/audio/opus.h>

Create an Opus encoder.

Parameters
applicationApplication mode (OPUS_APPLICATION_VOIP for voice)
sample_rateSample rate in Hz (8000, 12000, 16000, 24000, or 48000)
bitrateTarget bitrate in bits per second (6000-128000 typical)
Returns
Pointer to new encoder, NULL on error

Creates a stereo Opus encoder. The explicit-channel variant accepts mono or stereo.

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 35 of file opus.c.

35 {
36 return opus_codec_create_encoder_channels(application, sample_rate, bitrate, AUDIO_CHANNELS);
37}
opus_codec_t * opus_codec_create_encoder_channels(opus_application_t application, int sample_rate, int bitrate, int channels)
Definition opus.c:39

References AUDIO_CHANNELS, and opus_codec_create_encoder_channels().

◆ opus_codec_create_encoder_channels()

opus_codec_t * opus_codec_create_encoder_channels ( opus_application_t application,
int sample_rate,
int bitrate,
int channels )

#include <include/ascii-chat/audio/opus.h>

Definition at line 39 of file opus.c.

39 {
40 ASCII_OTEL_SCOPE(OPUS_ENCODER_CREATE);
41 ASCII_OTEL_ATTR_INT("audio.sample_rate", sample_rate);
42 ASCII_OTEL_ATTR_INT("audio.bitrate", bitrate);
43 if (sample_rate <= 0 || bitrate <= 0 || (channels != 1 && channels != 2)) {
44 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid codec parameters: sample_rate=%d, bitrate=%d", sample_rate, bitrate);
45 return NULL;
46 }
47
49 if (!codec) {
50 SET_ERRNO(ERROR_MEMORY, "Failed to allocate opus codec context");
51 return NULL;
52 }
53
54 // Create encoder
55 int error = OPUS_OK;
56 codec->encoder = opus_encoder_create(sample_rate, channels, (int)application, &error);
57 if (error != OPUS_OK || !codec->encoder) {
58 SET_ERRNO(ERROR_AUDIO, "Failed to create Opus encoder: %s", opus_strerror(error));
59 SAFE_FREE(codec);
60 return NULL;
61 }
62
63 if (audio_opus_configure_encoder(codec->encoder, bitrate) != ASCIICHAT_OK) {
64 opus_encoder_destroy(codec->encoder);
65 SAFE_FREE(codec);
66 return NULL;
67 }
68
69 codec->decoder = NULL;
70 codec->sample_rate = sample_rate;
71 codec->channels = channels;
72 codec->bitrate = bitrate;
73 codec->tmp_buffer = NULL;
74
75 log_debug("Opus encoder created: sample_rate=%d, bitrate=%d bps, continuous VBR", sample_rate, bitrate);
76
77 // Register Opus encoder for debugging
78 NAMED_REGISTER_CONTEXT(codec, "opus_encoder", "opus_codec", NULL);
79
80 return codec;
81}
asciichat_error_t audio_opus_configure_encoder(OpusEncoder *encoder, int bitrate)
Definition opus.c:21

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_SCOPE, ASCIICHAT_OK, audio_opus_configure_encoder(), opus_codec_t::bitrate, opus_codec_t::channels, 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 client_audio_render_thread(), opus_codec_create_encoder(), session_host_render_audio(), and session_participant_start_audio().

◆ 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 <include/ascii-chat/audio/opus.h>

Decode Opus audio frame.

Parameters
codecOpus decoder (created with opus_codec_create_decoder)
dataCompressed audio data (or NULL for PLC)
data_lenLength of compressed data in bytes
out_samplesOutput buffer for decoded samples (float)
out_num_samplesMaximum 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 171 of file opus.c.

171 {
172 ASCII_OTEL_SCOPE(OPUS_CODEC_DECODE);
173 ASCII_OTEL_ATTR_STRING("audio.codec", "opus");
174 ASCII_OTEL_ATTR_INT("audio.packet.size", (int64_t)data_len);
175 ASCII_OTEL_ATTR_INT("audio.packet_loss_concealment", !data || !data_len);
176 if (!codec || !codec->decoder || !out_samples || out_num_samples <= 0 || out_num_samples % codec->channels != 0) {
177 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,
178 out_num_samples);
179 return -1;
180 }
181
182 ASCII_OTEL_ATTR_INT("audio.sample_rate", codec->sample_rate);
183 ASCII_OTEL_ATTR_INT("audio.channels", codec->channels);
184 ASCII_OTEL_ATTR_INT("audio.output.capacity_samples", out_num_samples);
185 // If data is NULL, use PLC (Packet Loss Concealment)
186 if (!data || data_len == 0) {
187 log_debug_every(LOG_RATE_VERY_FAST, "Opus PLC (Packet Loss Concealment)");
188 int samples = opus_decode_float(codec->decoder, NULL, 0, out_samples, out_num_samples / codec->channels, 0);
189 if (samples < 0) {
190 SET_ERRNO(ERROR_AUDIO, "Opus PLC failed: %s", opus_strerror(samples));
191 return -1;
192 }
193 ascii_otel_metric(ASCII_OTEL_METRIC_OPUS_DECODE_SAMPLES, samples);
194 ascii_otel_metric(ASCII_OTEL_METRIC_OPUS_PLC_FRAMES, 1);
195 ASCII_OTEL_ATTR_INT("audio.frame.samples", samples);
196 return samples * codec->channels;
197 }
198
199 // Decode frame
200 int samples = opus_decode_float(codec->decoder, data, (opus_int32)data_len, out_samples, out_num_samples / codec->channels, 0);
201
202 if (samples < 0) {
203 SET_ERRNO(ERROR_AUDIO, "Opus decoding failed: %s", opus_strerror(samples));
204 return -1;
205 }
206
207 ascii_otel_metric(ASCII_OTEL_METRIC_OPUS_DECODE_BYTES, (double)data_len);
208 ASCII_OTEL_ATTR_INT("audio.frame.samples", samples);
209 ascii_otel_metric(ASCII_OTEL_METRIC_OPUS_DECODE_SAMPLES, samples);
210 return samples * codec->channels;
211}
#define LOG_RATE_VERY_FAST
Log rate limit: 0.1 seconds (100,000 microseconds) - for very high frequency operations.
Definition log_rates.h:27
#define ASCII_OTEL_ATTR_STRING(key, value)
Definition otel.h:71

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_ATTR_STRING, ascii_otel_metric(), ASCII_OTEL_SCOPE, opus_codec_t::channels, opus_codec_t::decoder, ERROR_AUDIO, ERROR_INVALID_PARAM, log_debug_every, LOG_RATE_VERY_FAST, opus_codec_t::sample_rate, and SET_ERRNO.

Referenced by handle_audio_opus_batch_packet(), handle_audio_opus_packet(), and session_host_receive_packet().

◆ opus_codec_destroy()

void opus_codec_destroy ( opus_codec_t * codec)

#include <include/ascii-chat/audio/opus.h>

Destroy an Opus codec instance.

Parameters
codecCodec to destroy (can be NULL)

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

Definition at line 271 of file opus.c.

271 {
272 if (!codec) {
273 return;
274 }
275
276 NAMED_UNREGISTER(codec);
277
278 if (codec->encoder) {
279 opus_encoder_destroy(codec->encoder);
280 codec->encoder = NULL;
281 }
282
283 if (codec->decoder) {
284 opus_decoder_destroy(codec->decoder);
285 codec->decoder = NULL;
286 }
287
288 if (codec->tmp_buffer) {
289 SAFE_FREE(codec->tmp_buffer);
290 codec->tmp_buffer = NULL;
291 }
292
293 SAFE_FREE(codec);
294}

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(), and session_participant_stop_audio().

◆ 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 <include/ascii-chat/audio/opus.h>

Encode audio frame with Opus.

Parameters
codecOpus encoder (created with opus_codec_create_encoder)
samplesInput audio samples (float, -1.0 to 1.0 range)
num_samplesTotal interleaved input samples (1920 for 20ms of stereo at 48kHz)
out_dataOutput buffer for compressed audio
out_sizeMaximum 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 132 of file opus.c.

132 {
133 ASCII_OTEL_SCOPE(OPUS_CODEC_ENCODE);
134 ASCII_OTEL_ATTR_STRING("audio.codec", "opus");
135 ASCII_OTEL_ATTR_INT("audio.frame.samples", num_samples);
136 ASCII_OTEL_ATTR_INT("audio.output.capacity", (int64_t)out_size);
137 if (!codec || !codec->encoder || !samples || num_samples <= 0 || !out_data || out_size == 0 || num_samples % codec->channels != 0) {
139 "Invalid encode parameters: codec=%p, encoder=%p, samples=%p, num_samples=%d, out_data=%p, "
140 "out_size=%zu",
141 (void *)codec, (void *)(codec ? codec->encoder : NULL), (const void *)samples, num_samples, (void *)out_data, out_size);
142 return 0;
143 }
144
145 ASCII_OTEL_ATTR_INT("audio.sample_rate", codec->sample_rate);
146 ASCII_OTEL_ATTR_INT("audio.bitrate", codec->bitrate);
147 ASCII_OTEL_ATTR_INT("audio.channels", codec->channels);
148 // Encode frame
149 opus_int32 encoded_bytes = opus_encode_float(codec->encoder, samples, num_samples / codec->channels, out_data, (opus_int32)out_size);
150
151 if (encoded_bytes < 0) {
152 SET_ERRNO(ERROR_AUDIO, "Opus encoding failed: %s", opus_strerror((int)encoded_bytes));
153 return 0;
154 }
155
156 if (encoded_bytes == 0) {
157 // DTX frame (silence) - encoder produced zero bytes
158 log_debug_every(LOG_RATE_VERY_FAST, "Opus DTX frame (silence detected)");
159 }
160
161 ascii_otel_metric(ASCII_OTEL_METRIC_OPUS_BYTES, encoded_bytes);
162 ascii_otel_metric(ASCII_OTEL_METRIC_OPUS_ENCODE_SAMPLES, num_samples);
163 ASCII_OTEL_ATTR_INT("audio.packet.size", encoded_bytes);
164 return (size_t)encoded_bytes;
165}

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_ATTR_STRING, ascii_otel_metric(), ASCII_OTEL_SCOPE, opus_codec_t::bitrate, opus_codec_t::channels, opus_codec_t::encoder, ERROR_AUDIO, ERROR_INVALID_PARAM, log_debug_every, LOG_RATE_VERY_FAST, opus_codec_t::sample_rate, and SET_ERRNO.

Referenced by client_audio_render_thread(), and session_host_render_audio().

◆ opus_codec_get_bitrate()

int opus_codec_get_bitrate ( opus_codec_t * codec)

#include <include/ascii-chat/audio/opus.h>

Get current encoder bitrate.

Parameters
codecOpus encoder
Returns
Bitrate in bits per second, negative on error

Definition at line 234 of file opus.c.

234 {
235 if (!codec || !codec->encoder) {
236 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid codec for bitrate query");
237 return -1;
238 }
239
240 opus_int32 bitrate = 0;
241 int error = opus_encoder_ctl(codec->encoder, OPUS_GET_BITRATE(&bitrate));
242 if (error != OPUS_OK) {
243 SET_ERRNO(ERROR_AUDIO, "Failed to get Opus bitrate: %s", opus_strerror(error));
244 return -1;
245 }
246
247 return (int)bitrate;
248}

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 <include/ascii-chat/audio/opus.h>

Set encoder bitrate.

Parameters
codecOpus encoder (created with opus_codec_create_encoder)
bitrateNew 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 217 of file opus.c.

217 {
218 ASCII_OTEL_SCOPE(OPUS_CODEC_SET_BITRATE);
219 if (!codec || !codec->encoder || bitrate <= 0) {
220 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid bitrate parameters: codec=%p, encoder=%p, bitrate=%d", (void *)codec, (void *)(codec ? codec->encoder : NULL), bitrate);
221 }
222
223 int error = opus_encoder_ctl(codec->encoder, OPUS_SET_BITRATE(bitrate));
224 if (error != OPUS_OK) {
225 return SET_ERRNO(ERROR_AUDIO, "Failed to set Opus bitrate: %s", opus_strerror(error));
226 }
227
228 codec->bitrate = bitrate;
229 log_debug("Opus bitrate changed to %d bps", bitrate);
230
231 return ASCIICHAT_OK;
232}

References ASCII_OTEL_SCOPE, 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 <include/ascii-chat/audio/opus.h>

Enable/disable DTX (Discontinuous Transmission).

Parameters
codecOpus encoder
enable1 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 250 of file opus.c.

250 {
251 ASCII_OTEL_SCOPE(OPUS_DTX);
252 ASCII_OTEL_ATTR_INT("audio.dtx.enabled", enable != 0);
253 if (!codec || !codec->encoder) {
254 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid codec for DTX configuration");
255 }
256
257 int error = opus_encoder_ctl(codec->encoder, OPUS_SET_DTX(enable ? 1 : 0));
258 if (error != OPUS_OK) {
259 return SET_ERRNO(ERROR_AUDIO, "Failed to set Opus DTX: %s", opus_strerror(error));
260 }
261
262 log_debug("Opus DTX %s", enable ? "enabled" : "disabled");
263
264 return ASCIICHAT_OK;
265}

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_SCOPE, 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 <include/ascii-chat/audio/audio.h>

Resample audio using linear interpolation.

Parameters
srcSource samples at src_rate
src_samplesNumber of source samples
dstDestination buffer at dst_rate
dst_samplesNumber of destination samples to produce
src_rateSource sample rate (e.g., 48000)
dst_rateDestination 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);
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.
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
srcSource samples at src_rate
src_samplesNumber of source samples
dstDestination buffer at dst_rate
dst_samplesNumber of destination samples to produce
src_rateSource sample rate (e.g., 48000)
dst_rateDestination sample rate (e.g., 44100)

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

609 {
610 if (src_samples == 0 || dst_samples == 0) {
611 SAFE_MEMSET(dst, dst_samples * sizeof(float), 0, dst_samples * sizeof(float));
612 return;
613 }
614
615 double ratio = src_rate / dst_rate;
616
617 for (size_t i = 0; i < dst_samples; i++) {
618 double src_pos = (double)i * ratio;
619 size_t idx0 = (size_t)src_pos;
620 size_t idx1 = idx0 + 1;
621 double frac = src_pos - (double)idx0;
622
623 // Clamp indices to valid range
624 if (idx0 >= src_samples)
625 idx0 = src_samples - 1;
626 if (idx1 >= src_samples)
627 idx1 = src_samples - 1;
628
629 // Linear interpolation
630 dst[i] = (float)((1.0 - frac) * src[idx0] + frac * src[idx1]);
631 }
632}

References SAFE_MEMSET.

◆ smoothstep()

float smoothstep ( float t)

#include <include/ascii-chat/audio/mixer.h>

Compute smoothstep interpolation.

Parameters
tInput 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 311 of file effects.c.

311 {
312 if (t <= 0.0f)
313 return 0.0f;
314 if (t >= 1.0f)
315 return 1.0f;
316 return t * t * (3.0f - 2.0f * t);
317}

Referenced by client_audio_pipeline_process_duplex(), and fade_buffer_smooth().

◆ soft_clip()

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

#include <include/ascii-chat/audio/mixer.h>

Apply soft clipping to a sample.

Parameters
sampleInput sample value
thresholdClipping threshold (e.g., 0.7 for 3dB headroom)
steepnessHow 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 284 of file effects.c.

284 {
285 if (sample > threshold) {
286 // Soft clip positive values using tanh curve
287 // Maps samples above threshold asymptotically toward 1.0
288 return threshold + (1.0f - threshold) * tanhf((sample - threshold) * steepness);
289 }
290 if (sample < -threshold) {
291 // Soft clip negative values symmetrically
292 return -threshold + (-1.0f + threshold) * tanhf((sample + threshold) * steepness);
293 }
294 return sample;
295}

Referenced by audio_processor_process(), 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 <include/ascii-chat/audio/mixer.h>

Apply soft clipping to a buffer.

Parameters
bufferAudio buffer (modified in-place)
num_samplesNumber of samples to process
thresholdClipping threshold (e.g., 0.7 for 3dB headroom)
steepnessHow aggressively the curve bends

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

Definition at line 297 of file effects.c.

297 {
298 if (!buffer || num_samples <= 0)
299 return;
300
301 for (int i = 0; i < num_samples; i++) {
302 buffer[i] = soft_clip(buffer[i], threshold, steepness);
303 }
304}

References soft_clip().

Variable Documentation

◆ active_sources

atomic_t mixer_t::active_sources

◆ active_sources_mask

uint64_t mixer_t::active_sources_mask[((128+63)/64)]

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

Definition at line 365 of file mixer.h.

Referenced by mixer_add_source(), mixer_create_channels(), 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 233 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 262 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 160 of file mixer.h.

Referenced by compressor_process_sample(), and compressor_set_params().

◆ attack_coeff [2/3]

float ducking_t::attack_coeff

Attack coefficient (converted from attack_ms).

Definition at line 298 of file mixer.h.

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

◆ attack_coeff [3/3]

float noise_gate_t::attack_coeff

Attack coefficient (converted from attack_ms).

Definition at line 200 of file mixer.h.

Referenced by noise_gate_process_sample(), and noise_gate_set_params().

◆ attack_ns [1/3]

uint64_t compressor_t::attack_ns

Attack time in nanoseconds (how fast compression kicks in).

Definition at line 147 of file mixer.h.

Referenced by compressor_set_params().

◆ attack_ns [2/3]

uint64_t ducking_t::attack_ns

Ducking attack time in nanoseconds.

Definition at line 293 of file mixer.h.

Referenced by ducking_init(), and ducking_set_params().

◆ attack_ns [3/3]

uint64_t noise_gate_t::attack_ns

Attack time in nanoseconds (how fast gate opens).

Definition at line 189 of file mixer.h.

Referenced by noise_gate_set_params().

◆ atten_dB

float ducking_t::atten_dB

Attenuation in dB for non-leader sources.

Definition at line 291 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 377 of file mixer.h.

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

◆ channels

unsigned mixer_t::channels

Definition at line 350 of file mixer.h.

Referenced by mixer_add_source(), and mixer_create_channels().

◆ compressor

compressor_t mixer_t::compressor

Compressor (dynamic range compression).

Definition at line 382 of file mixer.h.

Referenced by mixer_create_channels(), 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 375 of file mixer.h.

Referenced by mixer_create_channels(), 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 228 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 257 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 380 of file mixer.h.

Referenced by mixer_create_channels(), 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 156 of file mixer.h.

Referenced by compressor_init(), and compressor_process_sample().

◆ envelope [2/3]

float* ducking_t::envelope

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

Definition at line 302 of file mixer.h.

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

◆ envelope [3/3]

float noise_gate_t::envelope

Current envelope follower state (linear, 0-1).

Definition at line 198 of file mixer.h.

Referenced by noise_gate_init(), and noise_gate_process_sample().

◆ gain

float* ducking_t::gain

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

Definition at line 304 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 158 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 204 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 193 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 143 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 289 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[128][128]

◆ makeup_dB

float compressor_t::makeup_dB

Makeup gain in dB (compensates for gain reduction).

Definition at line 151 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 347 of file mixer.h.

Referenced by mixer_add_source(), mixer_create_channels(), 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 385 of file mixer.h.

Referenced by mixer_create_channels(), 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 344 of file mixer.h.

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

◆ prev_input

float highpass_filter_t::prev_input

Previous input sample (filter state).

Definition at line 235 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 237 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 264 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 145 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 162 of file mixer.h.

Referenced by compressor_process_sample(), and compressor_set_params().

◆ release_coeff [2/3]

float ducking_t::release_coeff

Release coefficient (converted from release_ms).

Definition at line 300 of file mixer.h.

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

◆ release_coeff [3/3]

float noise_gate_t::release_coeff

Release coefficient (converted from release_ms).

Definition at line 202 of file mixer.h.

Referenced by noise_gate_process_sample(), and noise_gate_set_params().

◆ release_ns [1/3]

uint64_t compressor_t::release_ns

Release time in nanoseconds (how fast compression releases).

Definition at line 149 of file mixer.h.

Referenced by compressor_set_params().

◆ release_ns [2/3]

uint64_t ducking_t::release_ns

Ducking release time in nanoseconds.

Definition at line 295 of file mixer.h.

Referenced by ducking_init(), and ducking_set_params().

◆ release_ns [3/3]

uint64_t noise_gate_t::release_ns

Release time in nanoseconds (how fast gate closes).

Definition at line 191 of file mixer.h.

Referenced by noise_gate_set_params().

◆ sample_rate [1/5]

float compressor_t::sample_rate

Sample rate in Hz (set during initialization).

Definition at line 154 of file mixer.h.

Referenced by compressor_init(), and compressor_set_params().

◆ sample_rate [2/5]

float highpass_filter_t::sample_rate

Sample rate in Hz (set during initialization).

Definition at line 230 of file mixer.h.

Referenced by highpass_filter_init().

◆ sample_rate [3/5]

float lowpass_filter_t::sample_rate

Sample rate in Hz (set during initialization).

Definition at line 259 of file mixer.h.

Referenced by lowpass_filter_init().

◆ sample_rate [4/5]

int mixer_t::sample_rate

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

Definition at line 349 of file mixer.h.

Referenced by mixer_create_channels().

◆ sample_rate [5/5]

float noise_gate_t::sample_rate

Sample rate in Hz (set during initialization).

Definition at line 196 of file mixer.h.

Referenced by noise_gate_init(), and noise_gate_set_params().

◆ source_active

bool* mixer_t::source_active

Array of active flags (true if source is active).

Definition at line 362 of file mixer.h.

Referenced by mixer_add_source(), mixer_create_channels(), 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 356 of file mixer.h.

Referenced by mixer_add_source(), mixer_create_channels(), 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 369 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 367 of file mixer.h.

Referenced by mixer_create_channels().

◆ source_ids

const char** mixer_t::source_ids

Array of client ID strings (one per source slot).

Definition at line 360 of file mixer.h.

Referenced by mixer_add_source(), mixer_create_channels(), 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 372 of file mixer.h.

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

◆ spectral_left

struct spectral_processor* mixer_t::spectral_left[128+1]

Per-source filter state; mono uses the left slot.

Definition at line 352 of file mixer.h.

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

◆ spectral_right

struct spectral_processor* mixer_t::spectral_right[128+1]

Definition at line 353 of file mixer.h.

Referenced by mixer_create_channels(), mixer_destroy(), and mixer_remove_source().

◆ threshold

float noise_gate_t::threshold

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

Definition at line 187 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 141 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 287 of file mixer.h.

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