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.c File Reference

🔊 Client audio management: capture thread, sample processing, and playback coordination More...

Go to the source code of this file.

Macros

#define AUDIO_VOLUME_BOOST   1.0f
#define OPUS_MAX_PACKET_SIZE   500
#define CAPTURE_READ_SIZE   ((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) * 4)
#define BATCH_TIMEOUT_NS   (320LL * NS_PER_MS_INT)

Functions

asciichat_error_t audio_sender_init (client_connection_t *connection)
 Initialize async audio sender queue and thread.
void audio_sender_cleanup (client_connection_t *connection)
 Cleanup async audio sender.
void audio_sender_finalize (client_connection_t *connection)
void audio_process_received_samples (client_connection_t *connection, const float *samples, int num_samples)
 Process received audio samples from server.
int audio_client_init ()
 Initialize audio subsystem.
asciichat_error_t audio_connection_init (client_connection_t *connection)
int audio_start_thread (client_connection_t *connection)
 Start audio capture thread.
void audio_stop_thread (client_connection_t *connection)
 Stop audio capture thread.
bool audio_thread_exited (client_connection_t *connection)
 Check if audio capture thread has exited.
void audio_cleanup ()
 Cleanup audio subsystem.
client_audio_pipeline_t * audio_get_pipeline (client_connection_t *connection)
 Get the audio pipeline (for advanced usage).
int audio_decode_opus (client_connection_t *connection, 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.

Detailed Description

🔊 Client audio management: capture thread, sample processing, and playback coordination

The audio system implements a dual-thread architecture:

  • Capture Thread: Records microphone input and transmits to server
  • Playback System: Receives server audio and plays through speakers
  • Processing Pipeline: Real-time audio enhancement and filtering
  • Coordination: Thread-safe communication between capture and playback

Audio Processing Pipeline

Both incoming and outgoing audio undergo comprehensive processing:

  1. High-pass Filter: Removes low-frequency rumble and noise
  2. Noise Gate: Eliminates background noise during silence
  3. Dynamic Range: Soft clipping to prevent harsh distortion
  4. Volume Control: Configurable boost for optimal listening levels
  5. Batching: Groups samples for efficient network transmission

Capture Thread Management

Audio capture runs in a dedicated thread:

  • Continuous Recording: Real-time microphone sample capture
  • Processing Chain: Applies filters and enhancement algorithms
  • Network Transmission: Sends processed samples to server
  • Adaptive Quality: Noise gate reduces traffic during silence
  • Thread Safety: Coordinated shutdown and resource management

Batching and Network Efficiency

Audio samples are batched for network efficiency:

  • Batch Accumulation: Collect multiple sample packets
  • Smart Transmission: Send batches when full or gate closes
  • Reduced Overhead: Fewer network packets for better performance
  • Quality Preservation: Maintain audio quality while optimizing bandwidth

Platform Audio Integration

Uses PortAudio for cross-platform audio support:

  • Device Enumeration: Automatic microphone and speaker detection
  • Format Negotiation: Optimal sample rate and bit depth selection
  • Low Latency: Optimized for real-time audio processing
  • Error Handling: Graceful handling of device conflicts and changes

Integration Points

  • main.c: Audio subsystem lifecycle and initialization
  • server.c: Audio packet transmission to server
  • protocol.c: Incoming audio packet processing and dispatch
  • lib/audio.c: Low-level PortAudio device management
  • lib/mixer.c: Audio filtering and processing algorithms

Error Handling

Audio errors handled with graceful degradation:

  • Device Unavailable: Continue without audio, log warnings
  • Processing Errors: Skip problematic samples, maintain stream
  • Network Errors: Continue processing, let connection management handle
  • Resource Errors: Clean shutdown with proper resource release

Resource Management

Careful audio resource lifecycle:

  • Context Management: Proper PortAudio context initialization/cleanup
  • Thread Coordination: Clean thread shutdown and resource release
  • Buffer Management: Efficient sample buffer allocation and reuse
  • Device Release: Proper microphone and speaker device cleanup
Author
Zachary Fogg me@zf.nosp@m.o.gg
Date
2025

Definition in file src/client/audio.c.

Macro Definition Documentation

◆ AUDIO_VOLUME_BOOST

#define AUDIO_VOLUME_BOOST   1.0f

Audio volume boost multiplier for received samples

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

◆ BATCH_TIMEOUT_NS

#define BATCH_TIMEOUT_NS   (320LL * NS_PER_MS_INT)

◆ CAPTURE_READ_SIZE

#define CAPTURE_READ_SIZE   ((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) * 4)

◆ OPUS_MAX_PACKET_SIZE

#define OPUS_MAX_PACKET_SIZE   500

Function Documentation

◆ audio_cleanup()

void audio_cleanup ( void )

Cleanup audio subsystem.

Cleanup audio subsystem

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

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

1125 {
1126 if (!GET_OPTION(audio_enabled)) {
1127 return;
1128 }
1129
1130 // Connection workers have joined before application audio cleanup.
1131
1132 // Stop audio stream before destroying pipeline to prevent race condition.
1133 // PortAudio may invoke the callback one more time after we request stop.
1134 // We need to clear the pipeline pointer first so the callback can't access freed memory.
1135 if (g_audio_context.initialized) {
1136 audio_stop_duplex(&g_audio_context);
1137 }
1138
1139 // Clear the pipeline pointer from audio context BEFORE destroying pipeline
1140 // This prevents any lingering PortAudio callbacks from trying to access freed memory
1141 audio_set_pipeline(&g_audio_context, NULL);
1143
1144 // Sleep to allow CoreAudio threads to finish executing callbacks.
1145 // On macOS, CoreAudio's internal threads may continue running after Pa_StopStream() returns.
1146 // The duplex_callback may still be in-flight on other threads. Even after we set the pipeline
1147 // pointer to NULL, a CoreAudio thread may have already cached the pointer before the assignment.
1148 // This sleep ensures all in-flight callbacks have fully completed before we destroy the pipeline.
1149 // WORKAROUND: Skip sleep during shutdown (process is exiting anyway)
1150 // 500ms is sufficient on macOS for CoreAudio's internal thread pool to completely wind down.
1151 // platform_sleep_us(500 * US_PER_MS_INT); // 500ms - macOS CoreAudio needs time to shut down all threads
1152
1153 // Close WAV dumpers
1154 if (g_wav_capture_raw) {
1155 wav_writer_close(g_wav_capture_raw);
1156 g_wav_capture_raw = NULL;
1157 log_debug("Closed audio capture raw dump");
1158 }
1159 if (g_wav_capture_processed) {
1160 wav_writer_close(g_wav_capture_processed);
1161 g_wav_capture_processed = NULL;
1162 log_debug("Closed audio capture processed dump");
1163 }
1164 if (g_wav_playback_received) {
1165 wav_writer_close(g_wav_playback_received);
1166 g_wav_playback_received = NULL;
1167 log_debug("Closed audio playback received dump");
1168 }
1169
1170 // Finally destroy the audio context
1171 if (g_audio_context.initialized) {
1172 audio_destroy(&g_audio_context);
1173 }
1174}
void audio_destroy(audio_context_t *ctx)
Destroy audio context and clean up resources.
asciichat_error_t audio_stop_duplex(audio_context_t *ctx)
Stop full-duplex audio.
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.
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
#define GET_OPTION(field)
Definition options.h:1333
void wav_writer_close(wav_writer_t *writer)
Close WAV file and finalize header.
Definition wav_writer.c:116

References audio_destroy(), audio_set_pipeline(), audio_stop_duplex(), audio_terminate_portaudio_final(), GET_OPTION, log_debug, and wav_writer_close().

◆ audio_client_init()

int audio_client_init ( void )

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

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

862 {
863 if (!GET_OPTION(audio_enabled)) {
864 return 0; // Audio disabled - not an error
865 }
866
867 // Use lifecycle to ensure only one thread initializes audio at a time
868 // This prevents race conditions in worker thread creation
869 if (!lifecycle_init_once(&g_audio_client_init_lc)) {
870 // Another thread is already initializing, wait for it to complete
871 while (!lifecycle_is_initialized(&g_audio_client_init_lc)) {
872 platform_sleep_us(1000); // 1ms
873 }
874 return 0; // Already initialized by another thread
875 }
876
877 // Clean up previous audio context if it was already initialized
878 // This prevents leaks and thread creation issues on reconnection
879 if (g_audio_context.initialized) {
880 log_debug("Cleaning up previous audio context before reinitializing");
881 audio_destroy(&g_audio_context);
882 // NOTE: Do NOT reset lifecycle - keep it INITIALIZED so only ONE global
883 // audio context is ever created. Subsequent calls will return early.
884 }
885
886 // Initialize WAV dumper for received audio if debugging enabled
887 if (wav_dump_enabled()) {
888 char tmp[PLATFORM_MAX_PATH_LENGTH];
889 if (audio_dump_directory(tmp, sizeof(tmp))) {
890 char path[PLATFORM_MAX_PATH_LENGTH];
891 safe_snprintf(path, sizeof(path), "%s/audio_playback_received.wav", tmp);
892 g_wav_playback_received = wav_writer_open(path, AUDIO_SAMPLE_RATE, AUDIO_CHANNELS);
893 if (g_wav_playback_received) {
894 log_debug("Audio debugging enabled: dumping received audio to %s", path);
895 }
896 }
897 }
898
899 // Initialize PortAudio context using library function
900 log_debug("About to call audio_init()...");
901 if (audio_init(&g_audio_context) != ASCIICHAT_OK) {
902 log_error("Failed to initialize audio system");
903 // Clean up WAV writer if it was opened
904 if (g_wav_playback_received) {
905 wav_writer_close(g_wav_playback_received);
906 g_wav_playback_received = NULL;
907 }
908 lifecycle_init_abort(&g_audio_client_init_lc);
909 return -1;
910 }
911 log_debug("audio_init() completed successfully");
912
913 // Initialize WAV dumpers only once (file handles persist)
914 if (wav_dump_enabled()) {
915 char tmp[PLATFORM_MAX_PATH_LENGTH];
916 if (audio_dump_directory(tmp, sizeof(tmp))) {
917 char path[PLATFORM_MAX_PATH_LENGTH];
918 safe_snprintf(path, sizeof(path), "%s/audio_capture_raw.wav", tmp);
919 g_wav_capture_raw = wav_writer_open(path, AUDIO_SAMPLE_RATE, AUDIO_CHANNELS);
920 safe_snprintf(path, sizeof(path), "%s/audio_capture_processed.wav", tmp);
921 g_wav_capture_processed = wav_writer_open(path, AUDIO_SAMPLE_RATE, AUDIO_CHANNELS);
922 log_debug("Audio debugging enabled: dumping to %s/audio_capture_*.wav", tmp);
923 }
924 }
925
926 lifecycle_init_commit(&g_audio_client_init_lc);
927
928 return 0;
929}
#define AUDIO_SAMPLE_RATE
Definition audio/limits.h:8
#define AUDIO_CHANNELS
Definition audio/limits.h:9
asciichat_error_t audio_init(audio_context_t *ctx)
Initialize audio context and PortAudio.
#define PLATFORM_MAX_PATH_LENGTH
@ ASCIICHAT_OK
Definition error_codes.h:50
#define log_error(...)
Log an ERROR message.
Definition log/log.h:628
bool wav_dump_enabled(void)
Check if audio dumping is enabled via environment.
Definition wav_writer.c:142
wav_writer_t * wav_writer_open(const char *filepath, int sample_rate, int channels)
Open WAV file for writing.
Definition wav_writer.c:52

References ASCIICHAT_OK, AUDIO_CHANNELS, audio_destroy(), audio_init(), AUDIO_SAMPLE_RATE, GET_OPTION, log_debug, log_error, PLATFORM_MAX_PATH_LENGTH, wav_dump_enabled(), wav_writer_close(), and wav_writer_open().

◆ audio_connection_init()

asciichat_error_t audio_connection_init ( client_connection_t * connection)

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

931 {
932 if (!connection->audio_context || !connection->audio_context->initialized)
933 return ASCIICHAT_OK;
934 // Create unified audio pipeline (handles AEC, AGC, noise suppression, Opus)
937
938 // Enable echo cancellation, AGC, and essential processing for clear audio
939 // Noise suppression and VAD can destroy music quality, so keep them disabled
940 pipeline_config.flags.echo_cancel = true; // ENABLE: removes echo
941 pipeline_config.flags.jitter_buffer = true; // ENABLE: needed for AEC sync
942 pipeline_config.flags.noise_suppress = false; // DISABLED: destroys music quality
943 pipeline_config.flags.agc = true; // ENABLE: boost quiet microphones (35 dB gain)
944 pipeline_config.flags.vad = false; // DISABLED: destroys music quality
945 pipeline_config.flags.compressor = true; // ENABLE: prevent clipping from AGC boost
946 pipeline_config.flags.noise_gate = false; // DISABLED: would cut quiet music passages
947 pipeline_config.flags.highpass = true; // ENABLE: remove rumble and low-frequency feedback
948 pipeline_config.flags.lowpass = false; // DISABLED: preserve high-frequency content
949
950 // Applied before streams start; actual underflows increase this bounded target.
952
953 log_debug("About to create audio pipeline...");
954 connection->audio_pipeline = client_audio_pipeline_create(&pipeline_config);
955 log_debug("client_audio_pipeline_create() returned");
956 if (!connection->audio_pipeline) {
957 return SET_ERRNO(ERROR_AUDIO, "Failed to create connection audio pipeline");
958 }
959
960 log_debug("Audio pipeline created: %d Hz sample rate, %d bps bitrate", pipeline_config.sample_rate, pipeline_config.opus_bitrate);
961
962 // Associate pipeline with audio context for echo cancellation
963 // The audio output callback will feed playback samples directly to AEC3 from the speaker output,
964 // ensuring proper timing synchronization (not from the decode path 50-100ms earlier)
965 audio_set_pipeline(connection->audio_context, (void *)connection->audio_pipeline);
966
967 // Audio streams start from protocol_start_connection() after the network
968 // connection succeeds, so local media playback does not advance while dialing.
969
970 return 0;
971}
#define SET_ERRNO(code,...)
client_audio_pipeline_t * client_audio_pipeline_create(const client_audio_pipeline_config_t *config)
Create and initialize a client audio pipeline.
client_audio_pipeline_config_t client_audio_pipeline_config_for_source(bool has_media_audio)
unsigned int uint32_t
@ ERROR_AUDIO
Definition error_codes.h:66
bool media_source_has_audio(media_source_t *source)
Check if media source has audio stream.
Definition source.c:774
void * session_capture_get_media_source(session_capture_ctx_t *ctx)
Get the underlying media source from capture context.
void audio_ring_buffer_set_jitter_target(audio_ring_buffer_t *rb, uint32_t samples)
bool initialized
True if context has been initialized.
audio_ring_buffer_t * playback_buffer
OLD: Network → Worker (will become network_playback_rb).
Pipeline configuration parameters.
client_audio_pipeline_flags_t flags
client_audio_pipeline_t * audio_pipeline
session_capture_ctx_t * capture_context
audio_context_t * audio_context

References client_audio_pipeline_flags_t::agc, ASCIICHAT_OK, AUDIO_CHANNELS, client_connection::audio_context, client_connection::audio_pipeline, audio_ring_buffer_set_jitter_target(), audio_set_pipeline(), client_connection::capture_context, client_audio_pipeline_config_for_source(), client_audio_pipeline_create(), client_audio_pipeline_flags_t::compressor, client_audio_pipeline_flags_t::echo_cancel, ERROR_AUDIO, client_audio_pipeline_config_t::flags, client_audio_pipeline_flags_t::highpass, audio_context_t::initialized, client_audio_pipeline_flags_t::jitter_buffer, client_audio_pipeline_config_t::jitter_margin_ms, log_debug, client_audio_pipeline_flags_t::lowpass, media_source_has_audio(), client_audio_pipeline_flags_t::noise_gate, client_audio_pipeline_flags_t::noise_suppress, client_audio_pipeline_config_t::opus_bitrate, audio_context_t::playback_buffer, client_audio_pipeline_config_t::sample_rate, session_capture_get_media_source(), SET_ERRNO, and client_audio_pipeline_flags_t::vad.

Referenced by client_protocol_start().

◆ audio_decode_opus()

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

Decode Opus packet using the audio pipeline.

Parameters
opus_dataOpus packet data
opus_lenOpus packet length
outputOutput buffer for decoded samples
max_samplesMaximum samples output buffer can hold
Returns
Number of decoded samples, or negative on error

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

1196 {
1197 if (!connection->audio_pipeline || !output || max_samples <= 0) {
1198 return -1;
1199 }
1200
1201 return client_audio_pipeline_playback(connection->audio_pipeline, opus_data, (int)opus_len, output, max_samples);
1202}
int client_audio_pipeline_playback(client_audio_pipeline_t *pipeline, const uint8_t *opus_in, int opus_len, float *output, int num_samples)
Decode Opus packet and process for playback.

References client_connection::audio_pipeline, and client_audio_pipeline_playback().

◆ audio_get_context()

audio_context_t * audio_get_context ( void )

Get the global audio context for use by other subsystems.

Returns
Pointer to the audio context, or NULL if not initialized

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

1210 {
1211 return &g_audio_context;
1212}

Referenced by capture_init().

◆ audio_get_pipeline()

client_audio_pipeline_t * audio_get_pipeline ( client_connection_t * connection)

Get the audio pipeline (for advanced usage).

Returns
Pointer to the audio pipeline, or NULL if not initialized

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

1182 {
1183 return connection ? connection->audio_pipeline : NULL;
1184}

References client_connection::audio_pipeline.

◆ audio_process_received_samples()

void audio_process_received_samples ( client_connection_t * connection,
const float * samples,
int num_samples )

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
samplesRaw audio sample data from server
num_samplesNumber of samples in the buffer

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

392 {
393 // Validate parameters
394 if (!connection || !connection->audio_context || !samples || num_samples <= 0) {
395 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid audio samples: samples=%p, num_samples=%d", (void *)samples, num_samples);
396 return;
397 }
398
399 if (!GET_OPTION(audio_enabled)) {
400 log_warn_every(NS_PER_MS_INT, "Received audio samples but audio is disabled");
401 return;
402 }
403
404 // Allow both single packets and batched packets
405 if (num_samples > AUDIO_OPUS_MAX_DECODE_SAMPLES * AUDIO_CHANNELS || num_samples % AUDIO_CHANNELS) {
406 log_warn("Invalid audio sample count: %d (maximum %d)", num_samples, AUDIO_OPUS_MAX_DECODE_SAMPLES * AUDIO_CHANNELS);
407 return;
408 }
409
410 // Calculate RMS energy of received samples
411 float sum_squares = 0.0f;
412 for (int i = 0; i < num_samples; i++) {
413 sum_squares += samples[i] * samples[i];
414 }
415 float received_rms = sqrtf(sum_squares / num_samples);
416
417 // DUMP: Received audio from server (before playback processing)
418 if (g_wav_playback_received) {
419 wav_writer_write(g_wav_playback_received, samples, num_samples);
420 }
421
422 // Track samples for analysis
423 if (GET_OPTION(audio_analysis_enabled)) {
424 for (int i = 0; i < num_samples; i += AUDIO_CHANNELS) {
425 audio_analysis_track_received_sample((samples[i] + samples[i + 1]) * 0.5f);
426 }
427 }
428
429 // Copy samples to playback buffer (no processing needed - mixer already handled clipping)
430 float audio_buffer[AUDIO_OPUS_MAX_DECODE_SAMPLES * AUDIO_CHANNELS];
431 memcpy(audio_buffer, samples, (size_t)num_samples * sizeof(float));
432
433 // DEBUG: Log what we're writing to playback buffer (with first 4 samples to verify audio integrity)
434 int recv_count = ++connection->audio_receive_count;
435 if (recv_count <= 10 || recv_count % 50 == 0) {
436 float peak = 0.0f;
437 for (int i = 0; i < num_samples; i++) {
438 float abs_val = fabsf(samples[i]);
439 if (abs_val > peak)
440 peak = abs_val;
441 }
442 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,
443 num_samples > 1 ? samples[1] : 0.0f, num_samples > 2 ? samples[2] : 0.0f, num_samples > 3 ? samples[3] : 0.0f);
444 }
445
446 // Submit to playback system (goes to jitter buffer and speakers)
447 // NOTE: AEC3's AnalyzeRender is called in output_callback() when audio actually plays,
448 // NOT here. The jitter buffer adds 50-100ms delay, so calling AnalyzeRender here
449 // would give AEC3 the wrong timing and break echo cancellation.
450 audio_write_samples(connection->audio_context, audio_buffer, num_samples);
451
452 // Log latency after writing to playback buffer
453 if (connection->audio_context->playback_buffer) {
454 size_t buffer_samples = audio_ring_buffer_available_read(connection->audio_context->playback_buffer);
455 float buffer_latency_ms = (float)buffer_samples * 1000.0f / (AUDIO_SAMPLE_RATE * AUDIO_CHANNELS);
456 log_dev_every(500 * US_PER_MS_INT, "LATENCY: Client playback buffer after recv: %.1fms (%zu samples)", buffer_latency_ms, buffer_samples);
457 }
458
459#ifdef DEBUG_AUDIO
460 log_debug_every(US_PER_SEC_INT, "Processed %d received audio samples", num_samples);
461#endif
462}
void audio_analysis_track_received_sample(float sample)
Track received audio sample.
Definition analysis.c:279
#define AUDIO_OPUS_MAX_DECODE_SAMPLES
size_t audio_ring_buffer_available_read(audio_ring_buffer_t *rb)
Get number of samples available for reading.
asciichat_error_t audio_write_samples(audio_context_t *ctx, const float *buffer, int num_samples)
Write audio samples to playback buffer.
@ ERROR_INVALID_PARAM
#define log_warn(...)
Log a WARN message.
Definition log/log.h:615
#define NS_PER_MS_INT
Definition time.h:172
#define US_PER_MS_INT
Definition time.h:176
#define US_PER_SEC_INT
Definition time.h:177
#define log_debug_every(interval_us, fmt,...)
Rate-limited DEBUG logging.
Definition log/log.h:743
#define log_warn_every(interval_us, fmt,...)
Rate-limited WARN logging.
Definition log/log.h:749
#define log_dev_every(interval_us, fmt,...)
Rate-limited DEV logging.
Definition log/log.h:740
int wav_writer_write(wav_writer_t *writer, const float *samples, int num_samples)
Write audio samples to WAV file.
Definition wav_writer.c:98

References audio_analysis_track_received_sample(), AUDIO_CHANNELS, client_connection::audio_context, AUDIO_OPUS_MAX_DECODE_SAMPLES, client_connection::audio_receive_count, audio_ring_buffer_available_read(), AUDIO_SAMPLE_RATE, audio_write_samples(), ERROR_INVALID_PARAM, GET_OPTION, log_debug, log_debug_every, log_dev_every, log_warn, log_warn_every, NS_PER_MS_INT, audio_context_t::playback_buffer, SET_ERRNO, US_PER_MS_INT, US_PER_SEC_INT, and wav_writer_write().

◆ audio_sender_cleanup()

void audio_sender_cleanup ( client_connection_t * connection)

Cleanup async audio sender.

Signal the asynchronous audio sender to stop before worker threads are joined.

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

335 {
336 if (!connection)
337 return;
338 // Signal thread to exit
339 if (lifecycle_is_initialized(&connection->audio_send_queue_lc)) {
341 mutex_lock(&connection->audio_send_queue_mutex);
342 cond_signal(&connection->audio_send_queue_cond);
343 mutex_unlock(&connection->audio_send_queue_mutex);
344 }
345
346 // The worker is joined by thread_pool_stop_all() in client_connection_stop().
347 // Keep the queue synchronization objects alive until that join completes.
349 log_debug("Audio sender thread will be joined by thread pool");
350 }
351}
void atomic_store_bool(atomic_t *a, bool value)
Atomically store a boolean value.
lifecycle_t audio_send_queue_lc
#define THREAD_IS_CREATED(created_flag)
Definition thread.h:66

References atomic_store_bool(), client_connection::audio_send_queue_cond, client_connection::audio_send_queue_lc, client_connection::audio_send_queue_mutex, client_connection::audio_sender_should_exit, client_connection::audio_sender_thread_created, log_debug, and THREAD_IS_CREATED.

◆ audio_sender_finalize()

void audio_sender_finalize ( client_connection_t * connection)

Release asynchronous audio sender resources after its worker has been joined.

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

353 {
354 if (!connection)
355 return;
356 if (connection->audio_queue_cond_initialized) {
357 cond_destroy(&connection->audio_send_queue_cond);
358 connection->audio_queue_cond_initialized = false;
359 }
360 if (connection->audio_queue_mutex_initialized) {
361 mutex_destroy(&connection->audio_send_queue_mutex);
362 connection->audio_queue_mutex_initialized = false;
363 }
364 lifecycle_shutdown(&connection->audio_send_queue_lc);
365}

References client_connection::audio_queue_cond_initialized, client_connection::audio_queue_mutex_initialized, client_connection::audio_send_queue_cond, client_connection::audio_send_queue_lc, and client_connection::audio_send_queue_mutex.

◆ audio_sender_init()

asciichat_error_t audio_sender_init ( client_connection_t * connection)

Initialize async audio sender queue and 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 304 of file src/client/audio.c.

304 {
305 if (mutex_init(&connection->audio_send_queue_mutex, "audio_send_queue_mutex") != 0) {
306 return SET_ERRNO(ERROR_THREAD, "Audio queue mutex initialization failed");
307 }
308 connection->audio_queue_mutex_initialized = true;
309 if (client_connection_checkpoint("audio-queue-mutex") != ASCIICHAT_OK)
310 return ERROR_THREAD;
311 if (cond_init(&connection->audio_send_queue_cond, "audio_send_queue_cond") != 0) {
312 return SET_ERRNO(ERROR_THREAD, "Audio queue condition initialization failed");
313 }
314 connection->audio_queue_cond_initialized = true;
315 lifecycle_init(&connection->audio_send_queue_lc, "audio_queue");
316 if (client_connection_checkpoint("audio-queue") != ASCIICHAT_OK)
317 return ERROR_THREAD;
318 acip_transport_t *transport = atomic_ptr_load(&connection->transport);
319 if (transport && transport->outbound) {
320 // Admission copies bounded audio into the transport queue without socket I/O.
321 connection->audio_send_direct = true;
322 atomic_store_bool(&connection->audio_sender_exited, true);
323 return client_connection_checkpoint("audio-sender");
324 }
325 asciichat_error_t result = thread_pool_spawn(connection->client_worker_pool, audio_sender_thread_func, connection, 5, "audio_sender");
326 if (result != ASCIICHAT_OK)
327 return result;
328 connection->audio_sender_thread_created = true;
329 return client_connection_checkpoint("audio-sender");
330}
void * atomic_ptr_load(atomic_ptr_t *a)
Atomically load a pointer.
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
@ ERROR_THREAD
struct acip_transport acip_transport_t
Forward declaration of ACIP transport.
Definition host.h:508
asciichat_error_t client_connection_checkpoint(const char *stage)
struct acip_outbound * outbound
Per-connection plaintext admission and scheduling.
thread_pool_t * client_worker_pool
asciichat_error_t thread_pool_spawn(thread_pool_t *pool, void *(*thread_func)(void *), void *thread_arg, int stop_id, const char *thread_name)
Spawn a worker thread in the pool.

References ASCIICHAT_OK, atomic_ptr_load(), atomic_store_bool(), client_connection::audio_queue_cond_initialized, client_connection::audio_queue_mutex_initialized, client_connection::audio_send_direct, client_connection::audio_send_queue_cond, client_connection::audio_send_queue_lc, client_connection::audio_send_queue_mutex, client_connection::audio_sender_exited, client_connection::audio_sender_thread_created, client_connection_checkpoint(), client_connection::client_worker_pool, ERROR_THREAD, acip_transport::outbound, SET_ERRNO, thread_pool_spawn(), and client_connection::transport.

Referenced by client_protocol_start().

◆ audio_start_thread()

int audio_start_thread ( client_connection_t * connection)

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

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

983 {
984 if (!connection->audio_context)
985 return 0;
986 log_debug("audio_enabled=%d", GET_OPTION(audio_enabled));
987
988 if (!GET_OPTION(audio_enabled)) {
989 log_debug("Audio is disabled, skipping audio capture thread creation");
990 return 0; // Audio disabled - not an error
991 }
992
993 // Check if thread is already running (not just created flag)
995 log_warn("Audio capture thread already running");
996 return 0;
997 }
998
999 // Note: STREAM_START for audio was already sent by protocol_start_connection()
1000 // No need to send it again here - the protocol layer handles sending combined stream types
1001
1002 // Start audio capture thread
1004 if (thread_pool_spawn(connection->client_worker_pool, audio_capture_thread_func, connection, 4, "audio_capture") != ASCIICHAT_OK) {
1005 log_error("Failed to spawn audio capture thread in worker pool");
1006 LOG_ERRNO_IF_SET("Audio capture thread creation failed");
1007 return -1;
1008 }
1009
1010 connection->audio_capture_thread_created = true;
1011
1012 return 0;
1013}
#define LOG_ERRNO_IF_SET(message)
bool atomic_load_bool(atomic_t *a)
Atomic pointer wrapper.
atomic_t audio_capture_thread_exited

References ASCIICHAT_OK, atomic_load_bool(), atomic_store_bool(), client_connection::audio_capture_thread_created, client_connection::audio_capture_thread_exited, client_connection::audio_context, client_connection::client_worker_pool, GET_OPTION, log_debug, LOG_ERRNO_IF_SET, log_error, log_warn, and thread_pool_spawn().

Referenced by client_protocol_start().

◆ audio_stop_thread()

void audio_stop_thread ( client_connection_t * connection)

Stop audio capture thread.

Stop audio capture thread

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

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

1023 {
1024 if (!connection || !connection->audio_context)
1025 return;
1026 // If audio was never initialized (e.g., in snapshot mode), nothing to stop
1027 if (!connection->audio_context->initialized) {
1028 log_debug("[AUDIO_STOP] Audio never initialized, nothing to stop");
1029 return;
1030 }
1031
1032 // Signal audio worker thread to exit first (stop processing)
1033 log_debug("[AUDIO_STOP] Signaling audio worker thread to stop");
1035 // Wake up the worker thread if it's waiting on condition variable
1036 mutex_lock(&connection->audio_context->audio_processing_wait_guard);
1037 cond_signal(&connection->audio_context->audio_processing_wakeup);
1038 mutex_unlock(&connection->audio_context->audio_processing_wait_guard);
1039 log_debug("[AUDIO_STOP] Worker thread stop signal sent");
1040
1041 // Signal audio sender thread to exit first.
1042 // This must happen before thread_pool_stop_all() is called, otherwise the sender
1043 // thread will be stuck in cond_wait() and thread_pool_stop_all() will hang forever.
1044 // The sender thread uses a condition variable to wait for packets - we must wake it up.
1045 // NOTE: Only do this if audio_sender_init() was actually called
1046 if (lifecycle_is_initialized(&connection->audio_send_queue_lc)) {
1047 log_debug("[AUDIO_STOP] Signaling audio sender thread to exit");
1048 atomic_store_bool(&connection->audio_sender_should_exit, true);
1049 mutex_lock(&connection->audio_send_queue_mutex);
1050 cond_signal(&connection->audio_send_queue_cond);
1051 mutex_unlock(&connection->audio_send_queue_mutex);
1052 log_debug("[AUDIO_STOP] Signal sent to sender thread");
1053
1054 // Wait for audio sender thread to exit gracefully
1055 // This must complete before thread_pool_stop_all() to prevent deadlock
1056 // CRITICAL: Longer timeout to ensure thread completes any in-flight send operations
1057 // Network operations can block for 10-50ms, so we need to wait longer
1058 int wait_count = 0;
1059 log_debug("[AUDIO_STOP] Waiting for sender thread to exit, max 500ms");
1060 while (wait_count < 50 && !atomic_load_bool(&connection->audio_sender_exited)) {
1061 platform_sleep_us(10 * US_PER_MS_INT); // 10ms * 50 = 500ms max wait
1062 wait_count++;
1063 }
1064
1065 if (!atomic_load_bool(&connection->audio_sender_exited)) {
1066 log_warn("[AUDIO_STOP] Audio sender thread not responding after 500ms - will be joined by thread pool");
1067 } else {
1068 log_debug("[AUDIO_STOP] Sender thread exited successfully");
1069 }
1070 } else {
1071 log_debug("[AUDIO_STOP] Audio sender was never initialized (connection failed), skipping sender shutdown");
1072 }
1073
1074 log_debug("[AUDIO_STOP] Checking if capture thread was created: g_audio_capture_thread_created=%d", connection->audio_capture_thread_created);
1076 log_debug("[AUDIO_STOP] Capture thread was not created, committing lifecycle and returning");
1077 log_debug("[AUDIO_STOP] Lifecycle committed, returning");
1078 return;
1079 }
1080 log_debug("[AUDIO_STOP] Capture thread was created, waiting for it to exit");
1081
1082 // Note: We don't call signal_exit() here because that's for global shutdown only
1083 // The audio capture thread checks server_connection_is_active() to detect connection loss
1084
1085 // Wait for thread to exit gracefully
1086 // Threads check should_exit() every 1-5ms, so timeout can be much shorter than 500ms
1087 int wait_count2 = 0;
1088 log_debug("[AUDIO_STOP] Waiting for capture thread to exit, max 50ms");
1089 while (wait_count2 < 5 && !atomic_load_bool(&connection->audio_capture_thread_exited)) {
1090 platform_sleep_us(10 * US_PER_MS_INT); // 10ms * 5 = 50ms max wait (threads respond in ~1-5ms)
1091 wait_count2++;
1092 }
1093
1094 if (!atomic_load_bool(&connection->audio_capture_thread_exited)) {
1095 log_warn("[AUDIO_STOP] Audio capture thread not responding - will be joined by thread pool");
1096 } else {
1097 log_debug("[AUDIO_STOP] Capture thread exited successfully");
1098 }
1099
1100 // Thread will be joined by thread_pool_stop_all() in client_connection_stop()
1101 connection->audio_capture_thread_created = false;
1102
1103 log_debug("Audio capture thread stopped");
1104}
atomic_t worker_should_stop
Signal worker thread to exit.
mutex_t audio_processing_wait_guard
Coordinates device-worker sleep with shutdown.
cond_t audio_processing_wakeup
Capture/AEC work, monitor refill, or shutdown notification.

References atomic_load_bool(), atomic_store_bool(), client_connection::audio_capture_thread_created, client_connection::audio_capture_thread_exited, client_connection::audio_context, audio_context_t::audio_processing_wait_guard, audio_context_t::audio_processing_wakeup, client_connection::audio_send_queue_cond, client_connection::audio_send_queue_lc, client_connection::audio_send_queue_mutex, client_connection::audio_sender_exited, client_connection::audio_sender_should_exit, audio_context_t::initialized, log_debug, log_warn, THREAD_IS_CREATED, US_PER_MS_INT, and audio_context_t::worker_should_stop.

◆ audio_thread_exited()

bool audio_thread_exited ( client_connection_t * connection)

Check if audio capture thread has exited.

Check if audio capture thread has exited

Returns
true if thread has exited, false otherwise

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

1113 {
1114 return atomic_load_bool(&connection->audio_capture_thread_exited);
1115}

References atomic_load_bool(), and client_connection::audio_capture_thread_exited.