Audio Processing

🔊 Audio capture, playback, and sample processing More...

Files
file	audio.c
	🔊 Client audio management: capture thread, sample processing, and playback coordination
file	audio.h
	ascii-chat Client Audio Processing Management Interface

Functions
void	audio_process_received_samples (const float *samples, int num_samples)
	Process received audio samples from server.
int	audio_client_init (void)
	Initialize audio subsystem.
int	audio_start_thread (void)
	Start audio capture thread.
void	audio_stop_thread (void)
	Stop audio capture thread.
bool	audio_thread_exited (void)
	Check if audio capture thread has exited.
void	audio_cleanup (void)
	Cleanup audio subsystem.
client_audio_pipeline_t *	audio_get_pipeline (void)
	Get the audio pipeline (for advanced usage)
int	audio_decode_opus (const uint8_t *opus_data, size_t opus_len, float *output, int max_samples)
	Decode Opus packet using the audio pipeline.
audio_context_t *	audio_get_context (void)
	Get the global audio context for use by other subsystems.
void	audio_sender_init (void)
	Initialize audio sender thread.

Detailed Description

🔊 Audio capture, playback, and sample processing

Audio Processing

Overview

The client audio subsystem manages PortAudio initialization, audio capture from microphone, transmission to server, and playback of received audio samples with jitter buffering.

Implementation: src/client/audio.c, src/client/audio.h

Configuration

Audio Parameters:

• Sample rate: 44100 Hz
• Channels: 1 (mono)
• Format: 32-bit float
• Batch size: 256 samples (~5.8ms @ 44.1kHz)
• Ring buffer: 8192 samples (~185ms jitter buffer)

Audio Capture Thread

static void *audio_capture_thread_func(void *arg)
{
  (void)arg;
 
  float capture_buffer[AUDIO_BATCH_SIZE];
 
  while (!should_exit() && server_connection_is_active()) {
    // Capture audio samples from microphone
    int samples_captured = audio_capture_samples(capture_buffer, AUDIO_BATCH_SIZE);
 
    if (samples_captured > 0) {
      // Send to server
      send_packet_to_server(PACKET_TYPE_AUDIO, capture_buffer,
                           samples_captured * sizeof(float),
                           server_connection_get_client_id());
    }
 
    // Small sleep to avoid busy loop
    platform_sleep_usec(1000);  // 1ms
  }
 
  atomic_store(&g_audio_thread_exited, true);
  return NULL;
}

Audio Playback

Jitter Buffering

void audio_process_received_samples(const float *samples, int num_samples)
{
  // Write to ring buffer for jitter compensation
  audio_ringbuffer_write(&g_playback_ringbuffer, samples, num_samples);
 
  // PortAudio callback reads from ring buffer
}
 
static int audio_playback_callback(const void *input, void *output,
                                   unsigned long frameCount,
                                   const PaStreamCallbackTimeInfo *timeInfo,
                                   PaStreamCallbackFlags statusFlags,
                                   void *userData)
{
  (void)input; (void)timeInfo; (void)statusFlags; (void)userData;
 
  float *out = (float *)output;
 
  // Read from ring buffer
  int samples_read = audio_ringbuffer_read(&g_playback_ringbuffer, out, frameCount);
 
  // Fill remaining with silence if underrun
  if (samples_read < (int)frameCount) {
    memset(&out[samples_read], 0, (frameCount - samples_read) * sizeof(float));
  }
 
  return paContinue;
}

See also

src/client/audio.c

src/client/audio.h

lib/audio.h

Client Overview

Function Documentation

audio_cleanup()

void audio_cleanup

(

)

#include <audio.c>

Cleanup audio subsystem.

Cleanup audio subsystem

Stops audio threads and cleans up PortAudio resources. Called during client shutdown.

Closes PortAudio stream and releases audio resources. Must be called after audio_stop_thread() and before process exit.

The cleanup process:

1. Stops PortAudio stream (interrupts playback)
2. Closes audio device
3. Destroys Opus encoder/decoder
4. Frees ring buffer
5. Terminates PortAudio

Must be called in proper order during shutdown to avoid resource leaks.

See also

audio_client_init "Initialize audio subsystem"

Definition at line 1252 of file src/client/audio.c.

                     {
  if (!GET_OPTION(audio_enabled)) {
    return;
  }
 
  // Stop capture thread first (stops producing packets)
  audio_stop_thread();
 
  // Stop async sender thread (drains queue and exits)
  audio_sender_cleanup();
 
  // Stop audio stream before destroying pipeline to prevent race condition.
  // PortAudio may invoke the callback one more time after we request stop.
  // We need to clear the pipeline pointer first so the callback can't access freed memory.
  if (g_audio_context.initialized) {
    audio_stop_duplex(&g_audio_context);
  }
 
  // Clear the pipeline pointer from audio context BEFORE destroying pipeline
  // This prevents any lingering PortAudio callbacks from trying to access freed memory
  audio_set_pipeline(&g_audio_context, NULL);
  audio_terminate_portaudio_final();
 
  // Sleep to allow CoreAudio threads to finish executing callbacks.
  // On macOS, CoreAudio's internal threads may continue running after Pa_StopStream() returns.
  // The duplex_callback may still be in-flight on other threads. Even after we set the pipeline
  // pointer to NULL, a CoreAudio thread may have already cached the pointer before the assignment.
  // This sleep ensures all in-flight callbacks have fully completed before we destroy the pipeline.
  // WORKAROUND: Skip sleep during shutdown (process is exiting anyway)
  // 500ms is sufficient on macOS for CoreAudio's internal thread pool to completely wind down.
  // platform_sleep_us(500 * US_PER_MS_INT); // 500ms - macOS CoreAudio needs time to shut down all threads
 
  // Destroy audio pipeline (handles Opus, AEC, etc.)
  if (g_audio_pipeline) {
    client_audio_pipeline_destroy(g_audio_pipeline);
    g_audio_pipeline = NULL;
    log_debug("Audio pipeline destroyed");
  }
 
  // Close WAV dumpers
  if (g_wav_capture_raw) {
    wav_writer_close(g_wav_capture_raw);
    g_wav_capture_raw = NULL;
    log_debug("Closed audio capture raw dump");
  }
  if (g_wav_capture_processed) {
    wav_writer_close(g_wav_capture_processed);
    g_wav_capture_processed = NULL;
    log_debug("Closed audio capture processed dump");
  }
  if (g_wav_playback_received) {
    wav_writer_close(g_wav_playback_received);
    g_wav_playback_received = NULL;
    log_debug("Closed audio playback received dump");
  }
 
  // Finally destroy the audio context
  if (g_audio_context.initialized) {
    audio_destroy(&g_audio_context);
  }
}

References audio_destroy(), audio_sender_cleanup(), audio_set_pipeline(), audio_stop_duplex(), audio_stop_thread(), audio_terminate_portaudio_final(), client_audio_pipeline_destroy(), GET_OPTION, audio_context_t::initialized, log_debug, and wav_writer_close().

audio_client_init()

int audio_client_init

(

)

#include <audio.c>

Initialize audio subsystem.

Initialize audio subsystem

Sets up PortAudio context, creates the audio pipeline, and starts audio playback/capture if audio is enabled.

Returns

0 on success, negative on error

Sets up PortAudio, selects audio device, and initializes Opus codec. Must be called before spawning audio threads.

Initialization steps:

1. Initialize PortAudio library
2. Enumerate audio devices (for –audio-device selection)
3. Open audio device for input (microphone) and output (speakers)
4. Create Opus encoder for capture
5. Create Opus decoder for playback
6. Initialize ring buffer for jitter buffering
7. Start PortAudio stream

Options affecting initialization:

• --audio-device <index>: Which audio device to use (default: system default)
• --audio flag must be set (audio disabled by default)

Returns

0 on success, negative on error:

• ERROR_AUDIO: Device not found or PortAudio error
• ERROR_MEMORY: Insufficient memory for buffers

Note

Optional - only called if –audio flag is set. Client works without audio (defaults to disabled).

See also

audio_cleanup "Cleanup audio resources"

Definition at line 956 of file src/client/audio.c.

                        {
  if (!GET_OPTION(audio_enabled)) {
    return 0; // Audio disabled - not an error
  }
 
  // Use lifecycle to ensure only one thread initializes audio at a time
  // This prevents race conditions in worker thread creation
  if (!lifecycle_init_once(&g_audio_client_init_lc)) {
    // Another thread is already initializing, wait for it to complete
    while (!lifecycle_is_initialized(&g_audio_client_init_lc)) {
      platform_sleep_us(1000); // 1ms
    }
    return 0; // Already initialized by another thread
  }
 
  // Clean up previous audio context if it was already initialized
  // This prevents leaks and thread creation issues on reconnection
  if (g_audio_context.initialized) {
    log_debug("Cleaning up previous audio context before reinitializing");
    audio_destroy(&g_audio_context);
    // NOTE: Do NOT reset lifecycle - keep it INITIALIZED so only ONE global
    // audio context is ever created. Subsequent calls will return early.
  }
 
  // Initialize WAV dumper for received audio if debugging enabled
  if (wav_dump_enabled()) {
    char tmp[PLATFORM_MAX_PATH_LENGTH];
    if (platform_get_temp_dir(tmp, sizeof(tmp))) {
      char path[PLATFORM_MAX_PATH_LENGTH];
      safe_snprintf(path, sizeof(path), "%s/audio_playback_received.wav", tmp);
      g_wav_playback_received = wav_writer_open(path, AUDIO_SAMPLE_RATE, 1);
      if (g_wav_playback_received) {
        log_debug("Audio debugging enabled: dumping received audio to %s", path);
      }
    }
  }
 
  // Initialize PortAudio context using library function
  log_debug("DEBUG: About to call audio_init()...");
  if (audio_init(&g_audio_context) != ASCIICHAT_OK) {
    log_error("Failed to initialize audio system");
    // Clean up WAV writer if it was opened
    if (g_wav_playback_received) {
      wav_writer_close(g_wav_playback_received);
      g_wav_playback_received = NULL;
    }
    lifecycle_init_abort(&g_audio_client_init_lc);
    return -1;
  }
  log_debug("DEBUG: audio_init() completed successfully");
 
  lifecycle_init_commit(&g_audio_client_init_lc);
 
  // Create unified audio pipeline (handles AEC, AGC, noise suppression, Opus)
  client_audio_pipeline_config_t pipeline_config = client_audio_pipeline_default_config();
  pipeline_config.opus_bitrate = 128000; // 128 kbps AUDIO mode for music quality
 
  // Enable echo cancellation, AGC, and essential processing for clear audio
  // Noise suppression and VAD can destroy music quality, so keep them disabled
  pipeline_config.flags.echo_cancel = true;     // ENABLE: removes echo
  pipeline_config.flags.jitter_buffer = true;   // ENABLE: needed for AEC sync
  pipeline_config.flags.noise_suppress = false; // DISABLED: destroys music quality
  pipeline_config.flags.agc = true;             // ENABLE: boost quiet microphones (35 dB gain)
  pipeline_config.flags.vad = false;            // DISABLED: destroys music quality
  pipeline_config.flags.compressor = true;      // ENABLE: prevent clipping from AGC boost
  pipeline_config.flags.noise_gate = false;     // DISABLED: would cut quiet music passages
  pipeline_config.flags.highpass = true;        // ENABLE: remove rumble and low-frequency feedback
  pipeline_config.flags.lowpass = false;        // DISABLED: preserve high-frequency content
 
  // Set jitter buffer margin for smooth playback without excessive delay
  // 100ms is conservative - AEC3 will adapt to actual network delay automatically
  // We don't tune this; let the system adapt to its actual conditions
  pipeline_config.jitter_margin_ns = 100;
 
  log_debug("DEBUG: About to create audio pipeline...");
  g_audio_pipeline = client_audio_pipeline_create(&pipeline_config);
  log_debug("DEBUG: client_audio_pipeline_create() returned");
  if (!g_audio_pipeline) {
    log_error("Failed to create audio pipeline");
    audio_destroy(&g_audio_context);
    // Clean up WAV writer if it was opened
    if (g_wav_playback_received) {
      wav_writer_close(g_wav_playback_received);
      g_wav_playback_received = NULL;
    }
    return -1;
  }
 
  log_debug("Audio pipeline created: %d Hz sample rate, %d bps bitrate", pipeline_config.sample_rate,
            pipeline_config.opus_bitrate);
 
  // Associate pipeline with audio context for echo cancellation
  // The audio output callback will feed playback samples directly to AEC3 from the speaker output,
  // ensuring proper timing synchronization (not from the decode path 50-100ms earlier)
  audio_set_pipeline(&g_audio_context, (void *)g_audio_pipeline);
 
  // Audio streams start from protocol_start_connection() after the network
  // connection succeeds, so local media playback does not advance while dialing.
 
  return 0;
}

References client_audio_pipeline_flags_t::agc, ASCIICHAT_OK, audio_destroy(), audio_init(), AUDIO_SAMPLE_RATE, audio_set_pipeline(), client_audio_pipeline_create(), client_audio_pipeline_default_config(), client_audio_pipeline_flags_t::compressor, client_audio_pipeline_flags_t::echo_cancel, client_audio_pipeline_config_t::flags, GET_OPTION, client_audio_pipeline_flags_t::highpass, audio_context_t::initialized, client_audio_pipeline_flags_t::jitter_buffer, client_audio_pipeline_config_t::jitter_margin_ns, lifecycle_init_abort(), lifecycle_init_commit(), lifecycle_init_once(), lifecycle_is_initialized(), log_debug, log_error, client_audio_pipeline_flags_t::lowpass, client_audio_pipeline_flags_t::noise_gate, client_audio_pipeline_flags_t::noise_suppress, client_audio_pipeline_config_t::opus_bitrate, platform_get_temp_dir(), PLATFORM_MAX_PATH_LENGTH, platform_sleep_us(), safe_snprintf(), client_audio_pipeline_config_t::sample_rate, client_audio_pipeline_flags_t::vad, wav_dump_enabled(), wav_writer_close(), and wav_writer_open().

audio_decode_opus()

int audio_decode_opus	(	const uint8_t *	opus_data,
		size_t	opus_len,
		float *	output,
		int	max_samples
	)

#include <audio.c>

Decode Opus packet using the audio pipeline.

Parameters

opus_data	Opus packet data
opus_len	Opus packet length
output	Output buffer for decoded samples
max_samples	Maximum samples output buffer can hold

Returns

Number of decoded samples, or negative on error

Decodes a single Opus-encoded audio packet to PCM samples. Can be used independently of the audio pipeline for testing or external audio processing.

Parameters

opus_data	Opus packet data (variable-length frame)
opus_len	Opus packet length in bytes
output	Output buffer for decoded samples (float array)
max_samples	Maximum samples output buffer can hold

Returns

Number of decoded samples, or negative on error (invalid Opus data)

Note

The pipeline must be initialized (audio_client_init) for this to work.

Definition at line 1334 of file src/client/audio.c.

                                                                                                 {
  if (!g_audio_pipeline || !output || max_samples <= 0) {
    return -1;
  }
 
  return client_audio_pipeline_playback(g_audio_pipeline, opus_data, (int)opus_len, output, max_samples);
}

References client_audio_pipeline_playback().

audio_get_context()

audio_context_t * audio_get_context

(

void

)

#include <audio.c>

Get the global audio context for use by other subsystems.

Returns

Pointer to the audio context, or NULL if not initialized

Returns the audio context for access to low-level audio state. Used by capture subsystem to enable microphone fallback when media file has no audio.

Returns

Pointer to the audio context, or NULL if not initialized

Note

Most code should use the higher-level interface functions rather than direct context access.

Definition at line 1348 of file src/client/audio.c.

                                         {
  return &g_audio_context;
}

Referenced by capture_init(), and protocol_start_connection().

audio_get_pipeline()

client_audio_pipeline_t * audio_get_pipeline

(

void

)

#include <audio.c>

Get the audio pipeline (for advanced usage)

Returns

Pointer to the audio pipeline, or NULL if not initialized

Returns the internal audio pipeline structure for direct access to encoder/decoder or buffer manipulation (advanced usage only).

Returns

Pointer to the audio pipeline, or NULL if not initialized

Note

Most code should use audio_process_received_samples() and the capture thread instead of direct pipeline access.

Definition at line 1320 of file src/client/audio.c.

                                                  {
  return g_audio_pipeline;
}

audio_process_received_samples()

void audio_process_received_samples	(	const float *	samples,
		int	num_samples
	)

#include <audio.c>

Process received audio samples from server.

Process received audio samples from server

Uses the audio pipeline for processing:

1. Input validation and size checking
2. Feed samples to pipeline (applies soft clipping)
3. Feed echo reference for AEC
4. Submit processed samples to PortAudio playback queue

Parameters

samples	Raw audio sample data from server
num_samples	Number of samples in the buffer

Queues received audio samples for playback. Handles jitter buffering to smooth out network timing variations. Called by protocol thread when processing PACKET_TYPE_AUDIO_BATCH from server.

The samples are queued in a ring buffer that smooths out timing variations. The playback thread drains this buffer at a constant rate.

Parameters

samples	Audio sample data from server (32-bit float, mono)
num_samples	Number of samples in buffer

Note

This is called by the protocol thread - must be thread-safe. Ring buffer handles synchronization internally.

Definition at line 450 of file src/client/audio.c.

                                                                           {
  // Validate parameters
  if (!samples || num_samples <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid audio samples: samples=%p, num_samples=%d", (void *)samples, num_samples);
    return;
  }
 
  if (!GET_OPTION(audio_enabled)) {
    log_warn_every(NS_PER_MS_INT, "Received audio samples but audio is disabled");
    return;
  }
 
  // Allow both single packets and batched packets
  if (num_samples > AUDIO_BATCH_SAMPLES) {
    log_warn("Audio packet too large: %d samples (max %d)", num_samples, AUDIO_BATCH_SAMPLES);
    return;
  }
 
  // Calculate RMS energy of received samples
  float sum_squares = 0.0f;
  for (int i = 0; i < num_samples; i++) {
    sum_squares += samples[i] * samples[i];
  }
  float received_rms = sqrtf(sum_squares / num_samples);
 
  // DUMP: Received audio from server (before playback processing)
  if (g_wav_playback_received) {
    wav_writer_write(g_wav_playback_received, samples, num_samples);
  }
 
  // Track samples for analysis
  if (GET_OPTION(audio_analysis_enabled)) {
    for (int i = 0; i < num_samples; i++) {
      audio_analysis_track_received_sample(samples[i]);
    }
  }
 
  // Copy samples to playback buffer (no processing needed - mixer already handled clipping)
  float audio_buffer[AUDIO_BATCH_SAMPLES];
  memcpy(audio_buffer, samples, (size_t)num_samples * sizeof(float));
 
  // DEBUG: Log what we're writing to playback buffer (with first 4 samples to verify audio integrity)
  static int recv_count = 0;
  recv_count++;
  if (recv_count <= 10 || recv_count % 50 == 0) {
    float peak = 0.0f;
    for (int i = 0; i < num_samples; i++) {
      float abs_val = fabsf(samples[i]);
      if (abs_val > peak)
        peak = abs_val;
    }
    log_debug("CLIENT AUDIO RECV #%d: %d samples, RMS=%.6f, Peak=%.6f, first4=[%.4f,%.4f,%.4f,%.4f]", recv_count,
              num_samples, received_rms, peak, num_samples > 0 ? samples[0] : 0.0f, num_samples > 1 ? samples[1] : 0.0f,
              num_samples > 2 ? samples[2] : 0.0f, num_samples > 3 ? samples[3] : 0.0f);
  }
 
  // Submit to playback system (goes to jitter buffer and speakers)
  // NOTE: AEC3's AnalyzeRender is called in output_callback() when audio actually plays,
  // NOT here. The jitter buffer adds 50-100ms delay, so calling AnalyzeRender here
  // would give AEC3 the wrong timing and break echo cancellation.
  audio_write_samples(&g_audio_context, audio_buffer, num_samples);
 
  // Log latency after writing to playback buffer
  if (g_audio_context.playback_buffer) {
    size_t buffer_samples = audio_ring_buffer_available_read(g_audio_context.playback_buffer);
    float buffer_latency_ms = (float)buffer_samples / 48.0f;
    log_dev_every(500 * US_PER_MS_INT, "LATENCY: Client playback buffer after recv: %.1fms (%zu samples)",
                  buffer_latency_ms, buffer_samples);
  }
 
#ifdef DEBUG_AUDIO
  log_debug("Processed %d received audio samples", num_samples);
#endif
}

References audio_analysis_track_received_sample(), AUDIO_BATCH_SAMPLES, audio_ring_buffer_available_read(), audio_write_samples(), ERROR_INVALID_PARAM, GET_OPTION, log_debug, log_dev_every, log_warn, log_warn_every, NS_PER_MS_INT, audio_context_t::playback_buffer, SET_ERRNO, US_PER_MS_INT, and wav_writer_write().

audio_sender_init()

void audio_sender_init

(

void

)

#include <audio.h>

Initialize audio sender thread.

Spawns the audio sender thread in the worker pool. This thread pulls packets from the send queue (populated by the capture thread) and sends them to the server.

Must be called after audio_client_init() and BEFORE audio_start_thread() during protocol_start_connection() after server connection succeeds.

Note

This is called automatically by protocol_start_connection() and should not be called directly in most code.

See also

audio_start_thread "Start audio capture thread"

Initialize audio sender thread.

Uses mutex protection to prevent TOCTOU race conditions where multiple threads might attempt initialization simultaneously.

Called from protocol_start_connection() after server connection succeeds, to prevent deadlock if connection fails before capture thread starts.

Definition at line 345 of file src/client/audio.c.

                             {
  log_info("[AUDIO_SENDER_INIT] Starting audio sender initialization");
 
  if (!lifecycle_init(&g_audio_send_queue_lc, "audio_queue")) {
    log_info("[AUDIO_SENDER_INIT] Already initialized, returning early");
    return; // Already initialized
  }
 
  log_info("[AUDIO_SENDER_INIT] Initializing mutex");
  // Initialize queue structures with error checking
  if (mutex_init(&g_audio_send_queue_mutex, "audio_send_queue_mutex") != 0) {
    log_error("[AUDIO_SENDER_INIT] Failed to initialize audio queue mutex");
    return;
  }
 
  log_info("[AUDIO_SENDER_INIT] Initializing condition variable");
  if (cond_init(&g_audio_send_queue_cond, "audio_send_queue_cond") != 0) {
    log_error("[AUDIO_SENDER_INIT] Failed to initialize audio queue condition variable");
    mutex_destroy(&g_audio_send_queue_mutex);
    return;
  }
 
  log_info("[AUDIO_SENDER_INIT] Setting queue state");
  g_audio_send_queue_head = 0;
  g_audio_send_queue_tail = 0;
  atomic_store_bool(&g_audio_sender_should_exit, false);
  atomic_store_bool(&g_audio_sender_exited, false);
 
  log_info("[AUDIO_SENDER_INIT] Spawning audio sender thread");
  // Start sender thread (after lock release to avoid blocking other threads)
  if (thread_pool_spawn(g_client_worker_pool, audio_sender_thread_func, NULL, 5, "audio_sender") == ASCIICHAT_OK) {
    g_audio_sender_thread_created = true;
    log_info("[AUDIO_SENDER_INIT] ✓ Audio sender thread created successfully");
  } else {
    log_error("[AUDIO_SENDER_INIT] Failed to spawn audio sender thread in worker pool");
    LOG_ERRNO_IF_SET("Audio sender thread creation failed");
  }
}

References ASCIICHAT_OK, atomic_store_bool(), cond_init(), g_client_worker_pool, lifecycle_init(), LOG_ERRNO_IF_SET, log_error, log_info, mutex_destroy(), mutex_init(), and thread_pool_spawn().

Referenced by protocol_start_connection().

audio_start_thread()

int audio_start_thread

(

)

#include <audio.c>

Start audio capture thread.

Start audio capture thread

Creates and starts the audio capture thread. Also sends stream start notification to server.

Returns

0 on success, negative on error

Spawns audio capture/transmission thread in global worker pool. Thread continuously captures audio from microphone, encodes with Opus, and sends to server.

The capture loop:

1. Captures samples from PortAudio input stream
2. Encodes with Opus encoder (variable bitrate)
3. Sends PACKET_TYPE_AUDIO_OPUS packet to server
4. Checks exit signals
5. Repeats until exit signal or connection loss

Must be called after audio_client_init() and server connection established.

Returns

0 on success, negative on error (thread pool full)

Note

Audio playback (from ring buffer) happens continuously in PortAudio callback, not in a separate thread.

See also

audio_stop_thread "Stop audio capture thread"

Definition at line 1068 of file src/client/audio.c.

                         {
  log_debug("audio_start_thread called: audio_enabled=%d", GET_OPTION(audio_enabled));
 
  // Register audio atomics for debug sync state monitoring (one-time registration)
  static bool audio_atomics_registered = false;
  if (!audio_atomics_registered) {
    NAMED_REGISTER_ATOMIC(&g_audio_capture_thread_exited, "audio_capture_thread_exit_confirmation", NULL);
    NAMED_REGISTER_ATOMIC(&g_audio_sender_should_exit, "audio_sender_exit_flag", NULL);
    NAMED_REGISTER_ATOMIC(&g_audio_sender_exited, "audio_sender_exited_confirmation", NULL);
    audio_atomics_registered = true;
  }
 
  if (!GET_OPTION(audio_enabled)) {
    log_debug("Audio is disabled, skipping audio capture thread creation");
    return 0; // Audio disabled - not an error
  }
 
  // Check if thread is already running (not just created flag)
  if (g_audio_capture_thread_created && !atomic_load_bool(&g_audio_capture_thread_exited)) {
    log_warn("Audio capture thread already running");
    return 0;
  }
 
  // If thread exited, allow recreation
  if (g_audio_capture_thread_created && atomic_load_bool(&g_audio_capture_thread_exited)) {
    log_debug("Previous audio capture thread exited, recreating");
    // Use timeout to prevent indefinite blocking
    int join_result = asciichat_thread_join_timeout(&g_audio_capture_thread, NULL, 5000 * NS_PER_MS_INT);
    if (join_result != 0) {
      log_warn("Audio capture thread join timed out after 5s - thread may be deadlocked, "
               "forcing thread handle reset (stuck thread resources will not be cleaned up)");
      // Thread is stuck - we can't safely reuse the handle, but we can reset our tracking
      // This is a resource leak of the stuck thread but continuing is safer than hanging
    }
    g_audio_capture_thread_created = false;
  }
 
  // Note: STREAM_START for audio was already sent by protocol_start_connection()
  // No need to send it again here - the protocol layer handles sending combined stream types
 
  // Start audio capture thread
  atomic_store_bool(&g_audio_capture_thread_exited, false);
  if (thread_pool_spawn(g_client_worker_pool, audio_capture_thread_func, NULL, 4, "audio_capture") != ASCIICHAT_OK) {
    log_error("Failed to spawn audio capture thread in worker pool");
    LOG_ERRNO_IF_SET("Audio capture thread creation failed");
    return -1;
  }
 
  g_audio_capture_thread_created = true;
 
  return 0;
}

References ASCIICHAT_OK, asciichat_thread_join_timeout(), atomic_load_bool(), atomic_store_bool(), g_client_worker_pool, GET_OPTION, log_debug, LOG_ERRNO_IF_SET, log_error, log_warn, NAMED_REGISTER_ATOMIC, NS_PER_MS_INT, and thread_pool_spawn().

Referenced by protocol_start_connection().

audio_stop_thread()

void audio_stop_thread

(

)

#include <audio.c>

Stop audio capture thread.

Stop audio capture thread

Gracefully stops the audio capture thread and cleans up resources. Safe to call multiple times.

Signals audio capture thread to exit and waits for it to join. Must be called before reconnection or shutdown.

The function:

1. Sets exit flag
2. Polls audio_thread_exited() until thread exits
3. Drains remaining samples in ring buffer

Playback continues until ring buffer is empty (graceful fade-out).

Note

Audio playback thread is internal to PortAudio callback and continues until PortAudio stream is closed in audio_cleanup().

See also

audio_start_thread "Start audio capture thread"

Definition at line 1129 of file src/client/audio.c.

                         {
  // If audio was never initialized (e.g., in snapshot mode), nothing to stop
  if (!lifecycle_is_initialized(&g_audio_client_init_lc)) {
    log_debug("[AUDIO_STOP] Audio never initialized, nothing to stop");
    return;
  }
 
  // Ensure only one thread performs cleanup - prevent double-join and double-cleanup
  // First, initialize the lifecycle if it hasn't been yet (moves UNINITIALIZED → INITIALIZED)
  if (!lifecycle_is_initialized(&g_audio_stop_thread_lc)) {
    if (!lifecycle_init(&g_audio_stop_thread_lc, "audio_stop_thread")) {
      // Already initialized by another thread or being destroyed
      log_debug("[AUDIO_STOP] Lifecycle already initialized by another thread");
      return;
    }
    log_debug("[AUDIO_STOP] Initialized stop thread lifecycle");
  }
 
  // Now destroy it (moves INITIALIZED → DESTROYING)
  if (!lifecycle_destroy_once(&g_audio_stop_thread_lc)) {
    log_debug("[AUDIO_STOP] lifecycle_destroy_once() returned false - already destroying/destroyed");
    log_debug("[AUDIO_STOP] Audio stop already in progress or completed, skipping");
    return;
  }
  log_debug("[AUDIO_STOP] lifecycle_destroy_once() returned true, proceeding with audio stop");
 
  // Signal audio worker thread to exit first (stop processing)
  log_debug("[AUDIO_STOP] Signaling audio worker thread to stop");
  atomic_store_bool(&g_audio_context.worker_should_stop, true);
  // Wake up the worker thread if it's waiting on condition variable
  mutex_lock(&g_audio_context.worker_mutex);
  cond_signal(&g_audio_context.worker_cond);
  mutex_unlock(&g_audio_context.worker_mutex);
  log_debug("[AUDIO_STOP] Worker thread stop signal sent");
 
  // Signal audio sender thread to exit first.
  // This must happen before thread_pool_stop_all() is called, otherwise the sender
  // thread will be stuck in cond_wait() and thread_pool_stop_all() will hang forever.
  // The sender thread uses a condition variable to wait for packets - we must wake it up.
  // NOTE: Only do this if audio_sender_init() was actually called
  if (lifecycle_is_initialized(&g_audio_send_queue_lc)) {
    log_debug("[AUDIO_STOP] Signaling audio sender thread to exit");
    atomic_store_bool(&g_audio_sender_should_exit, true);
    mutex_lock(&g_audio_send_queue_mutex);
    cond_signal(&g_audio_send_queue_cond);
    mutex_unlock(&g_audio_send_queue_mutex);
    log_debug("[AUDIO_STOP] Signal sent to sender thread");
 
    // Wait for audio sender thread to exit gracefully
    // This must complete before thread_pool_stop_all() to prevent deadlock
    // CRITICAL: Longer timeout to ensure thread completes any in-flight send operations
    // Network operations can block for 10-50ms, so we need to wait longer
    int wait_count = 0;
    log_debug("[AUDIO_STOP] Waiting for sender thread to exit, max 500ms");
    while (wait_count < 50 && !atomic_load_bool(&g_audio_sender_exited)) {
      platform_sleep_us(10 * US_PER_MS_INT); // 10ms * 50 = 500ms max wait
      wait_count++;
    }
 
    if (!atomic_load_bool(&g_audio_sender_exited)) {
      log_warn("[AUDIO_STOP] Audio sender thread not responding after 500ms - will be joined by thread pool");
    } else {
      log_debug("[AUDIO_STOP] Sender thread exited successfully");
    }
  } else {
    log_debug("[AUDIO_STOP] Audio sender was never initialized (connection failed), skipping sender shutdown");
  }
 
  log_debug("[AUDIO_STOP] Checking if capture thread was created: g_audio_capture_thread_created=%d",
            g_audio_capture_thread_created);
  if (!THREAD_IS_CREATED(g_audio_capture_thread_created)) {
    log_debug("[AUDIO_STOP] Capture thread was not created, committing lifecycle and returning");
    lifecycle_destroy_commit(&g_audio_stop_thread_lc);
    log_debug("[AUDIO_STOP] Lifecycle committed, returning");
    return;
  }
  log_debug("[AUDIO_STOP] Capture thread was created, waiting for it to exit");
 
  // Note: We don't call signal_exit() here because that's for global shutdown only
  // The audio capture thread checks server_connection_is_active() to detect connection loss
 
  // Wait for thread to exit gracefully
  // Threads check should_exit() every 1-5ms, so timeout can be much shorter than 500ms
  int wait_count2 = 0;
  log_debug("[AUDIO_STOP] Waiting for capture thread to exit, max 50ms");
  while (wait_count2 < 5 && !atomic_load_bool(&g_audio_capture_thread_exited)) {
    platform_sleep_us(10 * US_PER_MS_INT); // 10ms * 5 = 50ms max wait (threads respond in ~1-5ms)
    wait_count2++;
  }
 
  if (!atomic_load_bool(&g_audio_capture_thread_exited)) {
    log_warn("[AUDIO_STOP] Audio capture thread not responding - will be joined by thread pool");
  } else {
    log_debug("[AUDIO_STOP] Capture thread exited successfully");
  }
 
  // Thread will be joined by thread_pool_stop_all() in protocol_stop_connection()
  g_audio_capture_thread_created = false;
 
  lifecycle_destroy_commit(&g_audio_stop_thread_lc);
 
  log_debug("Audio capture thread stopped");
}

References atomic_load_bool(), atomic_store_bool(), cond_signal(), lifecycle_destroy_commit(), lifecycle_destroy_once(), lifecycle_init(), lifecycle_is_initialized(), log_debug, log_warn, mutex_lock, mutex_unlock, platform_sleep_us(), THREAD_IS_CREATED, US_PER_MS_INT, audio_context_t::worker_cond, audio_context_t::worker_mutex, and audio_context_t::worker_should_stop.

Referenced by audio_cleanup(), protocol_stop_connection(), and session_client_like_run().

audio_thread_exited()

bool audio_thread_exited

(

)

#include <audio.c>

Check if audio capture thread has exited.

Check if audio capture thread has exited

Returns

true if thread has exited, false otherwise

Atomically checks whether the audio capture thread has finished. Main thread uses this to wait for clean shutdown before reconnection.

Returns

true if thread exited, false otherwise

Note

Playback thread (PortAudio callback) exits when PortAudio stream is closed, not when capture thread exits.

Definition at line 1240 of file src/client/audio.c.

                           {
  return atomic_load_bool(&g_audio_capture_thread_exited);
}

References atomic_load_bool().