audio.c File Reference

🔊 Audio capture and playback using PortAudio with buffer management More...

Go to the source code of this file.

Macros
#define	WORKER_BATCH_FRAMES   128
#define	WORKER_BATCH_SAMPLES   (WORKER_BATCH_FRAMES * AUDIO_CHANNELS)
#define	WORKER_TIMEOUT_MS   1

Functions
void	audio_terminate_portaudio_final (void)
	Terminate PortAudio and free all device resources.
void	resample_linear (const float *src, size_t src_samples, float *dst, size_t dst_samples, double src_rate, double dst_rate)
audio_ring_buffer_t *	audio_ring_buffer_create (void)
audio_ring_buffer_t *	audio_ring_buffer_create_for_capture (void)
void	audio_ring_buffer_destroy (audio_ring_buffer_t *rb)
void	audio_ring_buffer_clear (audio_ring_buffer_t *rb)
asciichat_error_t	audio_ring_buffer_write (audio_ring_buffer_t *rb, const float *data, int samples)
size_t	audio_ring_buffer_read (audio_ring_buffer_t *rb, float *data, size_t samples)
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)
size_t	audio_ring_buffer_available_write (audio_ring_buffer_t *rb)
asciichat_error_t	audio_init (audio_context_t *ctx)
void	audio_destroy (audio_context_t *ctx)
void	audio_set_pipeline (audio_context_t *ctx, void *pipeline)
void	audio_flush_playback_buffers (audio_context_t *ctx)
asciichat_error_t	audio_start_duplex (audio_context_t *ctx)
asciichat_error_t	audio_stop_duplex (audio_context_t *ctx)
asciichat_error_t	audio_read_samples (audio_context_t *ctx, float *buffer, int num_samples)
asciichat_error_t	audio_write_samples (audio_context_t *ctx, const float *buffer, int num_samples)
asciichat_error_t	audio_list_input_devices (audio_device_info_t **out_devices, unsigned int *out_count)
asciichat_error_t	audio_list_output_devices (audio_device_info_t **out_devices, unsigned int *out_count)
void	audio_free_device_list (audio_device_info_t *devices)
asciichat_error_t	audio_dequantize_samples (const uint8_t *samples_ptr, uint32_t total_samples, float *out_samples)
asciichat_error_t	audio_set_realtime_priority (void)
asciichat_error_t	audio_parse_batch_header (const void *data, size_t len, audio_batch_info_t *out_batch)
asciichat_error_t	audio_validate_batch_params (const audio_batch_info_t *batch)
bool	audio_is_supported_sample_rate (uint32_t sample_rate)
bool	audio_should_enable_microphone (audio_source_t source, bool has_media_audio)

Detailed Description

🔊 Audio capture and playback using PortAudio with buffer management

Definition in file lib/audio/audio.c.

Macro Definition Documentation

WORKER_BATCH_FRAMES

#define WORKER_BATCH_FRAMES   128

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

WORKER_BATCH_SAMPLES

#define WORKER_BATCH_SAMPLES   (WORKER_BATCH_FRAMES * AUDIO_CHANNELS)

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

WORKER_TIMEOUT_MS

#define WORKER_TIMEOUT_MS   1

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

Function Documentation

audio_dequantize_samples()

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

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

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

Referenced by handle_audio_batch_packet().

audio_destroy()

void audio_destroy

(

audio_context_t *

ctx

)

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

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

References asciichat_thread_join(), audio_ring_buffer_destroy(), audio_stop_duplex(), and mutex_destroy().

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

audio_flush_playback_buffers()

void audio_flush_playback_buffers

(

audio_context_t *

ctx

)

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

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

References audio_ring_buffer_clear().

Referenced by session_handle_keyboard_input().

audio_free_device_list()

void audio_free_device_list

(

audio_device_info_t *

devices

)

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

                                                          {
  SAFE_FREE(devices);
}

audio_init()

asciichat_error_t audio_init

(

audio_context_t *

ctx

)

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

                                                   {
  log_debug("audio_init: starting, ctx=%p", (void *)ctx);
  if (!ctx) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx is NULL");
  }
 
  SAFE_MEMSET(ctx, sizeof(audio_context_t), 0, sizeof(audio_context_t));
 
  if (mutex_init(&ctx->state_mutex) != 0) {
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize audio context mutex");
  }
 
  // NOTE: PortAudio initialization deferred to audio_start_duplex() where streams are actually opened
  // This avoids Pa_Initialize() overhead for contexts that might not start duplex
  // and prevents premature ALSA device allocation and memory leaks
 
  // Create capture buffer WITHOUT jitter buffering (PortAudio writes directly from microphone)
  ctx->capture_buffer = audio_ring_buffer_create_for_capture();
  if (!ctx->capture_buffer) {
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create capture buffer");
  }
 
  ctx->playback_buffer = audio_ring_buffer_create();
  if (!ctx->playback_buffer) {
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create playback buffer");
  }
 
  // Create new ring buffers for worker thread architecture
  ctx->raw_capture_rb = audio_ring_buffer_create_for_capture();
  if (!ctx->raw_capture_rb) {
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create raw capture buffer");
  }
 
  ctx->raw_render_rb = audio_ring_buffer_create_for_capture();
  if (!ctx->raw_render_rb) {
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create raw render buffer");
  }
 
  ctx->processed_playback_rb = audio_ring_buffer_create();
  if (!ctx->processed_playback_rb) {
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create processed playback buffer");
  }
 
  // Initialize worker thread infrastructure
  if (mutex_init(&ctx->worker_mutex) != 0) {
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    audio_release_portaudio();
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize worker mutex");
  }
 
  if (cond_init(&ctx->worker_cond) != 0) {
    mutex_destroy(&ctx->worker_mutex);
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    audio_release_portaudio();
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize worker condition variable");
  }
 
  // Allocate pre-allocated worker buffers (avoid malloc in worker loop)
  ctx->worker_capture_batch = SAFE_MALLOC(WORKER_BATCH_SAMPLES * sizeof(float), float *);
  if (!ctx->worker_capture_batch) {
    cond_destroy(&ctx->worker_cond);
    mutex_destroy(&ctx->worker_mutex);
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    audio_release_portaudio();
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker capture batch buffer");
  }
 
  ctx->worker_render_batch = SAFE_MALLOC(WORKER_BATCH_SAMPLES * sizeof(float), float *);
  if (!ctx->worker_render_batch) {
    SAFE_FREE(ctx->worker_capture_batch);
    cond_destroy(&ctx->worker_cond);
    mutex_destroy(&ctx->worker_mutex);
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    audio_release_portaudio();
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker render batch buffer");
  }
 
  ctx->worker_playback_batch = SAFE_MALLOC(WORKER_BATCH_SAMPLES * sizeof(float), float *);
  if (!ctx->worker_playback_batch) {
    SAFE_FREE(ctx->worker_render_batch);
    SAFE_FREE(ctx->worker_capture_batch);
    cond_destroy(&ctx->worker_cond);
    mutex_destroy(&ctx->worker_mutex);
    audio_ring_buffer_destroy(ctx->processed_playback_rb);
    audio_ring_buffer_destroy(ctx->raw_render_rb);
    audio_ring_buffer_destroy(ctx->raw_capture_rb);
    audio_ring_buffer_destroy(ctx->playback_buffer);
    audio_ring_buffer_destroy(ctx->capture_buffer);
    audio_release_portaudio();
    mutex_destroy(&ctx->state_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker playback batch buffer");
  }
 
  // Initialize worker thread state (thread will be started in audio_start_duplex)
  ctx->worker_running = false;
  atomic_store(&ctx->worker_should_stop, false);
 
  ctx->initialized = true;
  atomic_store(&ctx->shutting_down, false);
  log_info("Audio system initialized successfully (worker thread architecture enabled)");
  return ASCIICHAT_OK;
}

References audio_ring_buffer_create(), audio_ring_buffer_create_for_capture(), audio_ring_buffer_destroy(), mutex_destroy(), mutex_init(), and WORKER_BATCH_SAMPLES.

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

audio_is_supported_sample_rate()

bool audio_is_supported_sample_rate

(

uint32_t

sample_rate

)

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

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

Referenced by audio_validate_batch_params().

audio_list_input_devices()

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

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

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

audio_list_output_devices()

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

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

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

audio_parse_batch_header()

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

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

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

References audio_batch_info_t::batch_count, audio_batch_info_t::channels, audio_batch_info_t::sample_rate, and audio_batch_info_t::total_samples.

Referenced by handle_audio_batch_packet().

audio_read_samples()

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

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

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

References audio_ring_buffer_read().

Referenced by session_audio_read_captured().

audio_ring_buffer_available_read()

size_t audio_ring_buffer_available_read

(

audio_ring_buffer_t *

rb

)

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

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

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

audio_ring_buffer_available_write()

size_t audio_ring_buffer_available_write

(

audio_ring_buffer_t *

rb

)

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

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

References audio_ring_buffer_available_read().

audio_ring_buffer_clear()

void audio_ring_buffer_clear

(

audio_ring_buffer_t *

rb

)

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

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

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

audio_ring_buffer_create()

audio_ring_buffer_t * audio_ring_buffer_create

(

void

)

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

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

Referenced by audio_init(), and session_audio_add_source().

audio_ring_buffer_create_for_capture()

audio_ring_buffer_t * audio_ring_buffer_create_for_capture

(

void

)

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

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

Referenced by add_client(), add_webrtc_client(), audio_init(), and audio_start_duplex().

audio_ring_buffer_destroy()

void audio_ring_buffer_destroy

(

audio_ring_buffer_t *

rb

)

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

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

References buffer_pool_free(), and mutex_destroy().

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

audio_ring_buffer_peek()

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

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

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

Parameters

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

Returns

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

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

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

audio_ring_buffer_read()

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

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

                                                                                    {
  if (!rb || !data || samples <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb=%p, data=%p, samples=%d", rb, data, samples);
    return 0; // Return 0 samples read on error
  }
 
  // LOCK-FREE: Load indices with proper memory ordering
  // - Load writer's write_index with acquire (see writer's data updates)
  // - Load our own read_index with relaxed (no sync needed with ourselves)
  unsigned int write_idx = atomic_load_explicit(&rb->write_index, memory_order_acquire);
  unsigned int read_idx = atomic_load_explicit(&rb->read_index, memory_order_relaxed);
 
  // Calculate available samples
  size_t available;
  if (write_idx >= read_idx) {
    available = write_idx - read_idx;
  } else {
    available = AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
  }
 
  // LOCK-FREE: Load jitter buffer state with acquire ordering
  bool jitter_filled = atomic_load_explicit(&rb->jitter_buffer_filled, memory_order_acquire);
  int crossfade_remaining = atomic_load_explicit(&rb->crossfade_samples_remaining, memory_order_acquire);
  bool fade_in = atomic_load_explicit(&rb->crossfade_fade_in, memory_order_acquire);
 
  // Jitter buffer: don't read until initial fill threshold is reached
  // (only for playback buffers - capture buffers have jitter_buffer_enabled = false)
  if (!jitter_filled && rb->jitter_buffer_enabled) {
    // Check if we've accumulated enough samples to start playback
    if (available >= AUDIO_JITTER_BUFFER_THRESHOLD) {
      atomic_store_explicit(&rb->jitter_buffer_filled, true, memory_order_release);
      atomic_store_explicit(&rb->crossfade_samples_remaining, AUDIO_CROSSFADE_SAMPLES, memory_order_release);
      atomic_store_explicit(&rb->crossfade_fade_in, true, memory_order_release);
      log_info("Jitter buffer filled (%zu samples), starting playback with fade-in", available);
      // Reload state for processing below
      jitter_filled = true;
      crossfade_remaining = AUDIO_CROSSFADE_SAMPLES;
      fade_in = true;
    } else {
      // Log buffer fill progress every second
      log_debug_every(NS_PER_MS_INT, "Jitter buffer filling: %zu/%d samples (%.1f%%)", available,
                      AUDIO_JITTER_BUFFER_THRESHOLD, (100.0f * available) / AUDIO_JITTER_BUFFER_THRESHOLD);
      return 0; // Return 0 samples - caller will pad with silence
    }
  }
 
  // Periodic buffer health logging (every 5 seconds when healthy)
  unsigned int underruns = atomic_load_explicit(&rb->underrun_count, memory_order_relaxed);
  log_dev_every(5 * NS_PER_MS_INT, "Buffer health: %zu/%d samples (%.1f%%), underruns=%u", available,
                AUDIO_RING_BUFFER_SIZE, (100.0f * available) / AUDIO_RING_BUFFER_SIZE, underruns);
 
  // Low buffer handling: DON'T pause playback - continue reading what's available
  // and fill the rest with silence. Pausing causes a feedback loop where:
  // 1. Underrun -> pause reading -> buffer overflows from incoming samples
  // 2. Threshold reached -> resume reading -> drains too fast -> underrun again
  //
  // Instead: always consume samples to prevent overflow, use silence for missing data
  if (rb->jitter_buffer_enabled && available < AUDIO_JITTER_LOW_WATER_MARK) {
    unsigned int underrun_count = atomic_fetch_add_explicit(&rb->underrun_count, 1, memory_order_relaxed) + 1;
    log_warn_every(LOG_RATE_FAST,
                   "Audio buffer low #%u: only %zu samples available (low water mark: %d), padding with silence",
                   underrun_count, available, AUDIO_JITTER_LOW_WATER_MARK);
    // Don't set jitter_buffer_filled = false - keep reading to prevent overflow
  }
 
  size_t to_read = (samples > available) ? available : samples;
 
  // Optimize: copy in chunks instead of one sample at a time
  size_t remaining = AUDIO_RING_BUFFER_SIZE - read_idx;
 
  if (to_read <= remaining) {
    // Can copy in one chunk
    SAFE_MEMCPY(data, to_read * sizeof(float), &rb->data[read_idx], to_read * sizeof(float));
  } else {
    // Need to wrap around - copy in two chunks
    SAFE_MEMCPY(data, remaining * sizeof(float), &rb->data[read_idx], remaining * sizeof(float));
    SAFE_MEMCPY(&data[remaining], (to_read - remaining) * sizeof(float), &rb->data[0],
                (to_read - remaining) * sizeof(float));
  }
 
  // LOCK-FREE: Store new read_index with release ordering
  // This ensures all data reads above complete before the index update
  unsigned int new_read_idx = (read_idx + (unsigned int)to_read) % AUDIO_RING_BUFFER_SIZE;
  atomic_store_explicit(&rb->read_index, new_read_idx, memory_order_release);
 
  // Apply fade-in if recovering from underrun
  if (fade_in && crossfade_remaining > 0) {
    int fade_start = AUDIO_CROSSFADE_SAMPLES - crossfade_remaining;
    size_t fade_samples = (to_read < (size_t)crossfade_remaining) ? to_read : (size_t)crossfade_remaining;
 
    for (size_t i = 0; i < fade_samples; i++) {
      float fade_factor = (float)(fade_start + (int)i + 1) / (float)AUDIO_CROSSFADE_SAMPLES;
      data[i] *= fade_factor;
    }
 
    int new_crossfade_remaining = crossfade_remaining - (int)fade_samples;
    atomic_store_explicit(&rb->crossfade_samples_remaining, new_crossfade_remaining, memory_order_release);
    if (new_crossfade_remaining <= 0) {
      atomic_store_explicit(&rb->crossfade_fade_in, false, memory_order_release);
      log_debug("Audio fade-in complete");
    }
  }
 
  // Save last sample for potential fade-out
  // Note: only update if we actually read some data
  // This is NOT atomic - only the reader thread writes this
  if (to_read > 0) {
    rb->last_sample = data[to_read - 1];
  }
 
  // Return ACTUAL number of samples read, not padded count
  // The caller (mixer) expects truthful return values to detect underruns
  // and handle silence padding externally. Internal padding creates double-padding bugs.
  //
  // This function was incorrectly returning `samples` even when
  // it only read `to_read` samples. This broke the mixer's underrun detection.
  return to_read;
}

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

audio_ring_buffer_write()

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

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

                                                                                                   {
  if (!rb || !data || samples <= 0)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb=%p, data=%p, samples=%d", rb, data, samples);
 
  // Validate samples doesn't exceed our buffer size
  if (samples > AUDIO_RING_BUFFER_SIZE) {
    return SET_ERRNO(ERROR_BUFFER, "Attempted to write %d samples, but buffer size is only %d", samples,
                     AUDIO_RING_BUFFER_SIZE);
  }
 
  // LOCK-FREE: Load indices with proper memory ordering
  // - Load our own write_index with relaxed (no sync needed with ourselves)
  // - Load reader's read_index with acquire (see reader's updates to free space)
  unsigned int write_idx = atomic_load_explicit(&rb->write_index, memory_order_relaxed);
  unsigned int read_idx = atomic_load_explicit(&rb->read_index, memory_order_acquire);
 
  // Calculate current buffer level (how many samples are buffered)
  int buffer_level;
  if (write_idx >= read_idx) {
    buffer_level = (int)(write_idx - read_idx);
  } else {
    buffer_level = AUDIO_RING_BUFFER_SIZE - (int)(read_idx - write_idx);
  }
  // Reserve 1 slot to distinguish between full and empty states
  // (when buffer is full, write_idx will be just before read_idx, not equal to it)
  int available = AUDIO_RING_BUFFER_SIZE - 1 - buffer_level;
 
  // HIGH WATER MARK: Drop INCOMING samples to prevent latency accumulation
  // Writer must not modify read_index (race condition with reader).
  // Instead, we drop incoming samples to keep buffer bounded.
  // This sacrifices newest data to prevent unbounded latency growth.
  if (buffer_level > AUDIO_JITTER_HIGH_WATER_MARK) {
    // Buffer is already too full - drop incoming samples to maintain target level
    int target_writes = AUDIO_JITTER_TARGET_LEVEL - buffer_level;
    if (target_writes < 0) {
      target_writes = 0; // Buffer is way over - drop everything
    }
 
    if (samples > target_writes) {
      int dropped = samples - target_writes;
      log_warn_every(LOG_RATE_FAST,
                     "Audio buffer high water mark exceeded (%d > %d): dropping %d INCOMING samples "
                     "(keeping newest %d to maintain target %d)",
                     buffer_level, AUDIO_JITTER_HIGH_WATER_MARK, dropped, target_writes, AUDIO_JITTER_TARGET_LEVEL);
      samples = target_writes; // Only write what fits within target level
    }
  }
 
  // Now write the new samples - should always have enough space after above
  int samples_to_write = samples;
  if (samples > available) {
    // This should rarely happen after the high water mark logic above
    int samples_dropped = samples - available;
    samples_to_write = available;
    log_warn_every(LOG_RATE_FAST, "Audio buffer overflow: dropping %d of %d incoming samples (buffer_used=%d/%d)",
                   samples_dropped, samples, AUDIO_RING_BUFFER_SIZE - available, AUDIO_RING_BUFFER_SIZE);
  }
 
  // Write only the samples that fit (preserves existing data integrity)
  if (samples_to_write > 0) {
    int remaining = AUDIO_RING_BUFFER_SIZE - (int)write_idx;
 
    if (samples_to_write <= remaining) {
      // Can copy in one chunk
      SAFE_MEMCPY(&rb->data[write_idx], samples_to_write * sizeof(float), data, samples_to_write * sizeof(float));
    } else {
      // Need to wrap around - copy in two chunks
      SAFE_MEMCPY(&rb->data[write_idx], remaining * sizeof(float), data, remaining * sizeof(float));
      SAFE_MEMCPY(&rb->data[0], (samples_to_write - remaining) * sizeof(float), &data[remaining],
                  (samples_to_write - remaining) * sizeof(float));
    }
 
    // LOCK-FREE: Store new write_index with release ordering
    // This ensures all data writes above are visible before the index update
    unsigned int new_write_idx = (write_idx + (unsigned int)samples_to_write) % AUDIO_RING_BUFFER_SIZE;
    atomic_store_explicit(&rb->write_index, new_write_idx, memory_order_release);
  }
 
  // Note: jitter buffer fill check is now done in read function for better control
 
  return ASCIICHAT_OK; // Success
}

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
	)

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

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

Referenced by audio_cleanup(), and audio_client_init().

audio_set_realtime_priority()

asciichat_error_t audio_set_realtime_priority

(

void

)

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

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

Referenced by audio_start_duplex().

audio_should_enable_microphone()

bool audio_should_enable_microphone	(	audio_source_t	source,
		bool	has_media_audio
	)

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

                                                                                 {
  switch (source) {
  case AUDIO_SOURCE_AUTO:
    return !has_media_audio;
 
  case AUDIO_SOURCE_MIC:
    return true;
 
  case AUDIO_SOURCE_MEDIA:
    return false;
 
  case AUDIO_SOURCE_BOTH:
    return true;
 
  default:
    return !has_media_audio;
  }
}

Referenced by session_client_like_run().

audio_start_duplex()

asciichat_error_t audio_start_duplex

(

audio_context_t *

ctx

)

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

                                                           {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
  }
 
  // Initialize PortAudio here, when we actually need to open streams
  // This defers Pa_Initialize() until necessary, avoiding premature ALSA allocation
  asciichat_error_t pa_result = audio_ensure_portaudio_initialized();
  if (pa_result != ASCIICHAT_OK) {
    return pa_result;
  }
 
  mutex_lock(&ctx->state_mutex);
 
  // Already running?
  if (ctx->duplex_stream || ctx->input_stream || ctx->output_stream) {
    mutex_unlock(&ctx->state_mutex);
    return ASCIICHAT_OK;
  }
 
  // Setup input parameters (skip if playback-only mode)
  PaStreamParameters inputParams = {0};
  const PaDeviceInfo *inputInfo = NULL;
  bool has_input = false;
 
  if (!ctx->playback_only) {
    if (GET_OPTION(microphone_index) >= 0) {
      inputParams.device = GET_OPTION(microphone_index);
    } else {
      inputParams.device = Pa_GetDefaultInputDevice();
    }
 
    if (inputParams.device == paNoDevice) {
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_AUDIO, "No input device available");
    }
 
    inputInfo = Pa_GetDeviceInfo(inputParams.device);
    if (!inputInfo) {
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_AUDIO, "Input device info not found");
    }
 
    has_input = true;
    inputParams.channelCount = AUDIO_CHANNELS;
    inputParams.sampleFormat = paFloat32;
    inputParams.suggestedLatency = inputInfo->defaultLowInputLatency;
    inputParams.hostApiSpecificStreamInfo = NULL;
  }
 
  // Setup output parameters
  PaStreamParameters outputParams;
  const PaDeviceInfo *outputInfo = NULL;
  bool has_output = false;
 
  if (GET_OPTION(speakers_index) >= 0) {
    outputParams.device = GET_OPTION(speakers_index);
  } else {
    outputParams.device = Pa_GetDefaultOutputDevice();
  }
 
  if (outputParams.device != paNoDevice) {
    outputInfo = Pa_GetDeviceInfo(outputParams.device);
    if (outputInfo) {
      has_output = true;
      outputParams.channelCount = AUDIO_CHANNELS;
      outputParams.sampleFormat = paFloat32;
      outputParams.suggestedLatency = outputInfo->defaultLowOutputLatency;
      outputParams.hostApiSpecificStreamInfo = NULL;
    } else {
      log_warn("Output device info not found for device %d", outputParams.device);
    }
  }
 
  // Store device rates for diagnostics (only access if device info was retrieved)
  ctx->input_device_rate = (has_input && inputInfo) ? inputInfo->defaultSampleRate : 0;
  ctx->output_device_rate = (has_output && outputInfo) ? outputInfo->defaultSampleRate : 0;
 
  log_debug("Opening audio:");
  if (has_input) {
    log_info("  Input:  %s (%.0f Hz)", inputInfo->name, inputInfo->defaultSampleRate);
  } else if (ctx->playback_only) {
    log_debug("  Input:  (playback-only mode - no microphone)");
  } else {
    log_debug("  Input:  (none)");
  }
  if (has_output) {
    log_info("  Output: %s (%.0f Hz)", outputInfo->name, outputInfo->defaultSampleRate);
  } else {
    log_debug("  Output: None (input-only mode - will send audio to server)");
  }
 
  // Check if sample rates differ - ALSA full-duplex doesn't handle this well
  // If no input or no output, always use separate streams
  bool rates_differ = has_input && has_output && (inputInfo->defaultSampleRate != outputInfo->defaultSampleRate);
  bool try_separate = rates_differ || !has_input || !has_output;
  PaError err = paNoError;
 
  if (!try_separate) {
    // Try full-duplex first (preferred - perfect AEC3 timing)
    err = Pa_OpenStream(&ctx->duplex_stream, &inputParams, &outputParams, AUDIO_SAMPLE_RATE, AUDIO_FRAMES_PER_BUFFER,
                        paClipOff, duplex_callback, ctx);
 
    if (err == paNoError) {
      err = Pa_StartStream(ctx->duplex_stream);
      if (err != paNoError) {
        Pa_CloseStream(ctx->duplex_stream);
        ctx->duplex_stream = NULL;
        log_warn("Full-duplex stream failed to start: %s", Pa_GetErrorText(err));
        try_separate = true;
      }
    } else {
      log_warn("Full-duplex stream failed to open: %s", Pa_GetErrorText(err));
      try_separate = true;
    }
  }
 
  if (try_separate) {
    // Fall back to separate streams (needed when sample rates differ or input-only/playback-only mode)
    if (has_output && has_input) {
      log_info("Using separate input/output streams (sample rates differ: %.0f vs %.0f Hz)",
               inputInfo->defaultSampleRate, outputInfo->defaultSampleRate);
      log_info("  Will resample: buffer at %.0f Hz → output at %.0f Hz", (double)AUDIO_SAMPLE_RATE,
               outputInfo->defaultSampleRate);
    } else if (has_output) {
      log_debug("Using output-only mode (playback-only for mirror/media)");
    } else if (has_input) {
      log_info("Using input-only mode (no output device available)");
    }
 
    // Store the internal sample rate (buffer rate)
    ctx->sample_rate = AUDIO_SAMPLE_RATE;
 
    // Create render buffer for AEC3 reference synchronization
    ctx->render_buffer = audio_ring_buffer_create_for_capture();
    if (!ctx->render_buffer) {
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_MEMORY, "Failed to create render buffer");
    }
 
    // Open output stream only if output device exists
    bool output_ok = false;
    double actual_output_rate = 0;
    if (has_output) {
      // Try to use AUDIO_SAMPLE_RATE (48kHz) first for best quality and duplex compatibility
      // Fall back to native rate if 48kHz not supported
      double preferred_rate = AUDIO_SAMPLE_RATE;
      double native_rate = outputInfo->defaultSampleRate;
 
      log_debug("Attempting output at %.0f Hz (preferred) vs %.0f Hz (native)", preferred_rate, native_rate);
 
      // Always use output_callback for output streams (both output-only and duplex modes)
      // PortAudio will invoke the callback whenever it needs audio data
      // The callback reads from media_source (mirror mode) or playback buffers (network mode)
      PaStreamCallback *callback = output_callback;
 
      // Try preferred rate first
      err = Pa_OpenStream(&ctx->output_stream, NULL, &outputParams, preferred_rate, AUDIO_FRAMES_PER_BUFFER, paClipOff,
                          callback, ctx);
 
      if (err == paNoError) {
        actual_output_rate = preferred_rate;
        output_ok = true;
        log_info("✓ Output opened at preferred rate: %.0f Hz (matches input - optimal!)", preferred_rate);
      } else {
        log_warn("Failed to open output at %.0f Hz: %s, trying native rate %.0f Hz", preferred_rate,
                 Pa_GetErrorText(err), native_rate);
 
        // If first Pa_OpenStream call left a partial stream, clean it up before retrying
        if (ctx->output_stream) {
          log_debug("Closing partially-opened output stream from failed preferred rate");
          Pa_CloseStream(ctx->output_stream);
          ctx->output_stream = NULL;
        }
 
        // Fall back to native rate (still using blocking mode for output-only)
        err = Pa_OpenStream(&ctx->output_stream, NULL, &outputParams, native_rate, AUDIO_FRAMES_PER_BUFFER, paClipOff,
                            callback, ctx);
 
        if (err == paNoError) {
          actual_output_rate = native_rate;
          output_ok = true;
          log_info("✓ Output opened at native rate: %.0f Hz (will need resampling)", native_rate);
        } else {
          log_warn("Failed to open output stream at native rate: %s", Pa_GetErrorText(err));
          // Clean up if fallback also failed
          if (ctx->output_stream) {
            log_debug("Closing partially-opened output stream from failed native rate");
            Pa_CloseStream(ctx->output_stream);
            ctx->output_stream = NULL;
          }
        }
      }
 
      // Store actual output rate for resampling
      if (output_ok) {
        ctx->output_device_rate = actual_output_rate;
        if (actual_output_rate != AUDIO_SAMPLE_RATE) {
          log_warn("⚠️  Output rate mismatch: %.0f Hz output vs %.0f Hz input - resampling will be used",
                   actual_output_rate, (double)AUDIO_SAMPLE_RATE);
        }
      }
    }
 
    // Open input stream only if we have input (skip for playback-only mode)
    bool input_ok = !has_input; // If no input, mark as OK (skip)
    if (has_input) {
      // Use pipeline sample rate (AUDIO_SAMPLE_RATE)
      // In input-only mode, we don't need to match output device rate
      double input_stream_rate = AUDIO_SAMPLE_RATE;
      err = Pa_OpenStream(&ctx->input_stream, &inputParams, NULL, input_stream_rate, AUDIO_FRAMES_PER_BUFFER, paClipOff,
                          input_callback, ctx);
      input_ok = (err == paNoError);
 
      // If input failed, try device 0 as fallback (HDMI on BeaglePlay)
      if (!input_ok) {
        log_debug("Input failed - trying device 0 as fallback");
 
        // Clean up partial stream from first attempt before retrying
        if (ctx->input_stream) {
          log_debug("Closing partially-opened input stream from failed primary device");
          Pa_CloseStream(ctx->input_stream);
          ctx->input_stream = NULL;
        }
 
        PaStreamParameters fallback_input_params = inputParams;
        fallback_input_params.device = 0;
        const PaDeviceInfo *device_0_info = Pa_GetDeviceInfo(0);
        if (device_0_info && device_0_info->maxInputChannels > 0) {
          err = Pa_OpenStream(&ctx->input_stream, &fallback_input_params, NULL, input_stream_rate,
                              AUDIO_FRAMES_PER_BUFFER, paClipOff, input_callback, ctx);
          if (err == paNoError) {
            log_info("Input stream opened on device 0 (fallback from default)");
            input_ok = true;
          } else {
            log_warn("Fallback also failed on device 0: %s", Pa_GetErrorText(err));
            // Clean up if fallback also failed
            if (ctx->input_stream) {
              log_debug("Closing partially-opened input stream from failed fallback device");
              Pa_CloseStream(ctx->input_stream);
              ctx->input_stream = NULL;
            }
          }
        }
      }
 
      if (!input_ok) {
        log_warn("Failed to open input stream: %s", Pa_GetErrorText(err));
      }
    }
 
    // Check if we got at least one stream working
    if (!input_ok && !output_ok) {
      // Neither stream works - fail completely
      audio_ring_buffer_destroy(ctx->render_buffer);
      ctx->render_buffer = NULL;
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_AUDIO, "Failed to open both input and output streams");
    }
 
    // If output failed but input works, we can still send audio to server
    if (!output_ok && input_ok) {
      log_info("Output stream unavailable - continuing with input-only (can send audio to server)");
      ctx->output_stream = NULL;
    }
    // If input failed but output works, we can still receive audio from server
    if (!input_ok && output_ok) {
      log_info("Input stream unavailable - continuing with output-only (can receive audio from server)");
      ctx->input_stream = NULL;
    }
 
    // Start output stream if it's open
    if (ctx->output_stream) {
      err = Pa_StartStream(ctx->output_stream);
      if (err != paNoError) {
        if (ctx->input_stream)
          Pa_CloseStream(ctx->input_stream);
        Pa_CloseStream(ctx->output_stream);
        ctx->input_stream = NULL;
        ctx->output_stream = NULL;
        audio_ring_buffer_destroy(ctx->render_buffer);
        ctx->render_buffer = NULL;
        mutex_unlock(&ctx->state_mutex);
        return SET_ERRNO(ERROR_AUDIO, "Failed to start output stream: %s", Pa_GetErrorText(err));
      }
    }
 
    // Start input stream if it's open
    if (ctx->input_stream) {
      err = Pa_StartStream(ctx->input_stream);
      if (err != paNoError) {
        if (ctx->output_stream)
          Pa_StopStream(ctx->output_stream);
        if (ctx->input_stream)
          Pa_CloseStream(ctx->input_stream);
        if (ctx->output_stream)
          Pa_CloseStream(ctx->output_stream);
        ctx->input_stream = NULL;
        ctx->output_stream = NULL;
        audio_ring_buffer_destroy(ctx->render_buffer);
        ctx->render_buffer = NULL;
        mutex_unlock(&ctx->state_mutex);
        return SET_ERRNO(ERROR_AUDIO, "Failed to start input stream: %s", Pa_GetErrorText(err));
      }
    }
 
    ctx->separate_streams = true;
    log_debug("Separate streams started successfully");
  } else {
    ctx->separate_streams = false;
    log_info("Full-duplex stream started (single callback, perfect AEC3 timing)");
  }
 
  audio_set_realtime_priority();
 
  // Start worker thread for heavy audio processing
  if (!ctx->worker_running) {
    atomic_store(&ctx->worker_should_stop, false);
    if (asciichat_thread_create(&ctx->worker_thread, audio_worker_thread, ctx) != 0) {
      // Failed to create worker thread - stop streams and cleanup
      if (ctx->duplex_stream) {
        Pa_StopStream(ctx->duplex_stream);
        Pa_CloseStream(ctx->duplex_stream);
        ctx->duplex_stream = NULL;
      }
      if (ctx->input_stream) {
        Pa_StopStream(ctx->input_stream);
        Pa_CloseStream(ctx->input_stream);
        ctx->input_stream = NULL;
      }
      if (ctx->output_stream) {
        Pa_StopStream(ctx->output_stream);
        Pa_CloseStream(ctx->output_stream);
        ctx->output_stream = NULL;
      }
      audio_ring_buffer_destroy(ctx->render_buffer);
      ctx->render_buffer = NULL;
      mutex_unlock(&ctx->state_mutex);
      return SET_ERRNO(ERROR_THREAD, "Failed to create worker thread");
    }
    ctx->worker_running = true;
    log_debug("Worker thread started successfully");
  }
 
  ctx->running = true;
  ctx->sample_rate = AUDIO_SAMPLE_RATE;
  mutex_unlock(&ctx->state_mutex);
  return ASCIICHAT_OK;
}

References asciichat_thread_create(), audio_ring_buffer_create_for_capture(), audio_ring_buffer_destroy(), audio_set_realtime_priority(), and paNoError.

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

audio_stop_duplex()

asciichat_error_t audio_stop_duplex

(

audio_context_t *

ctx

)

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

                                                          {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
  }
 
  atomic_store(&ctx->shutting_down, true);
 
  // Stop worker thread before stopping streams
  if (ctx->worker_running) {
    log_debug("Stopping worker thread");
    atomic_store(&ctx->worker_should_stop, true);
    cond_signal(&ctx->worker_cond); // Wake up worker if waiting
    asciichat_thread_join(&ctx->worker_thread, NULL);
    ctx->worker_running = false;
    log_debug("Worker thread stopped successfully");
  }
 
  if (ctx->playback_buffer) {
    audio_ring_buffer_clear(ctx->playback_buffer);
  }
 
  Pa_Sleep(50); // Let callbacks drain
 
  mutex_lock(&ctx->state_mutex);
 
  if (ctx->duplex_stream) {
    log_debug("Stopping duplex stream");
    PaError err = Pa_StopStream(ctx->duplex_stream);
    if (err != paNoError) {
      log_warn("Pa_StopStream failed: %s", Pa_GetErrorText(err));
    }
    log_debug("Closing duplex stream");
    err = Pa_CloseStream(ctx->duplex_stream);
    if (err != paNoError) {
      log_warn("Pa_CloseStream failed: %s", Pa_GetErrorText(err));
    } else {
      log_debug("Duplex stream closed successfully");
    }
    ctx->duplex_stream = NULL;
  }
 
  // Stop separate streams if used
  if (ctx->input_stream) {
    log_debug("Stopping input stream");
    PaError err = Pa_StopStream(ctx->input_stream);
    if (err != paNoError) {
      log_warn("Pa_StopStream input failed: %s", Pa_GetErrorText(err));
    }
    log_debug("Closing input stream");
    err = Pa_CloseStream(ctx->input_stream);
    if (err != paNoError) {
      log_warn("Pa_CloseStream input failed: %s", Pa_GetErrorText(err));
    } else {
      log_debug("Input stream closed successfully");
    }
    ctx->input_stream = NULL;
  }
 
  if (ctx->output_stream) {
    log_debug("Stopping output stream");
    PaError err = Pa_StopStream(ctx->output_stream);
    if (err != paNoError) {
      log_warn("Pa_StopStream output failed: %s", Pa_GetErrorText(err));
    }
    log_debug("Closing output stream");
    err = Pa_CloseStream(ctx->output_stream);
    if (err != paNoError) {
      log_warn("Pa_CloseStream output failed: %s", Pa_GetErrorText(err));
    } else {
      log_debug("Output stream closed successfully");
    }
    ctx->output_stream = NULL;
  }
 
  // Cleanup render buffer
  if (ctx->render_buffer) {
    audio_ring_buffer_destroy(ctx->render_buffer);
    ctx->render_buffer = NULL;
  }
 
  ctx->running = false;
  ctx->separate_streams = false;
  mutex_unlock(&ctx->state_mutex);
 
  log_debug("Audio stopped");
  return ASCIICHAT_OK;
}

References asciichat_thread_join(), audio_ring_buffer_clear(), audio_ring_buffer_destroy(), and paNoError.

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

audio_terminate_portaudio_final()

void audio_terminate_portaudio_final

(

void

)

Terminate PortAudio and free all device resources.

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

                                           {
  static_mutex_lock(&g_pa_refcount_mutex);
 
  if (g_pa_init_refcount == 0 && g_pa_init_count > 0 && g_pa_terminate_count == 0) {
    log_debug("[PORTAUDIO_TERM] Calling Pa_Terminate() to release PortAudio");
 
    PaError err = Pa_Terminate();
    g_pa_terminate_count++;
 
    log_debug("[PORTAUDIO_TERM] Pa_Terminate() returned: %s", Pa_GetErrorText(err));
  }
 
  static_mutex_unlock(&g_pa_refcount_mutex);
}

Referenced by audio_cleanup(), and session_client_like_run().

audio_validate_batch_params()

asciichat_error_t audio_validate_batch_params

(

const audio_batch_info_t *

batch

)

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

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

References audio_is_supported_sample_rate(), audio_batch_info_t::batch_count, audio_batch_info_t::channels, audio_batch_info_t::sample_rate, 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
	)

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

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

References audio_ring_buffer_write().

Referenced by audio_process_received_samples(), and session_audio_write_playback().

resample_linear()

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

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

Parameters

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

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

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