ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
lib/audio/audio.c
Go to the documentation of this file.
1
2/* Storage capacities in elements; text buffers include the terminating NUL. */
3
5#include <ascii-chat/otel.h>
7
13
20#include <ascii-chat/common.h>
21#include <ascii-chat/log/io.h>
23#include <ascii-chat/util/time.h> // For monotonic timing
24#include <libplatform/lifecycle.h> // For lifecycle_t
25#include <ascii-chat/asciichat_errno.h> // For asciichat_errno system
26#include <ascii-chat/buffer.h>
27#include <options/options.h>
28#include <ascii-chat/common/sync.h> // For static_mutex_t
29#include <libplatform/compiler.h>
30#include <libplatform/system.h> // For platform_sleep_us
31#include <libplatform/terminal.h>
32#include <ascii-chat/network/packet/packet.h> // For audio_batch_packet_t
33#include <ascii-chat/log/log.h> // For log_* macros
35#include <ascii-chat/media/source.h> // For media_source_read_audio()
36#include <stdlib.h>
37#include <string.h>
38#include <math.h>
39#include <libplatform/atomic.h>
40#include <stdatomic.h>
41
42// PortAudio callbacks publish bounded, lock-free telemetry samples. The audio
43// worker exports them so the telemetry backend never runs on a device callback.
44#define AUDIO_RT_METRIC_SLOTS 1024
45#if !defined(_WIN32) || !defined(__clang__)
46_Static_assert(ATOMIC_INT_LOCK_FREE == 2 && ATOMIC_POINTER_LOCK_FREE == 2, "Audio telemetry requires lock-free unsigned and pointer atomics");
47#endif
48typedef struct {
49 _Atomic unsigned state; // 0 free, 1 owned, 2 ready
51 double value;
58static audio_rt_metric_t g_audio_rt_metrics[AUDIO_RT_METRIC_SLOTS];
59static _Atomic unsigned g_audio_rt_next;
60static _Atomic unsigned g_audio_rt_dropped;
61static _Thread_local bool g_audio_callback_thread;
62
63static void audio_metric(ascii_otel_metric_t metric, double value) {
64 if (!g_audio_callback_thread) {
65 ascii_otel_metric(metric, value);
66 return;
67 }
68 if (!ascii_otel_enabled())
69 return;
70 unsigned index = atomic_fetch_add_explicit(&g_audio_rt_next, 1, memory_order_relaxed) % AUDIO_RT_METRIC_SLOTS;
71 audio_rt_metric_t *slot = &g_audio_rt_metrics[index];
72 unsigned free_slot = 0;
73 if (!atomic_compare_exchange_strong_explicit(&slot->state, &free_slot, 1, memory_order_acquire, memory_order_relaxed)) {
74 atomic_fetch_add_explicit(&g_audio_rt_dropped, 1, memory_order_relaxed);
75 return;
76 }
77 slot->metric = metric;
78 slot->value = value;
79 atomic_store_explicit(&slot->state, 2, memory_order_release);
80}
81
82static void audio_metrics_flush(void) {
83 for (size_t i = 0; i < AUDIO_RT_METRIC_SLOTS; ++i) {
84 audio_rt_metric_t *slot = &g_audio_rt_metrics[i];
85 unsigned ready = 2;
86 if (!atomic_compare_exchange_strong_explicit(&slot->state, &ready, 1, memory_order_acquire, memory_order_relaxed))
87 continue;
88 ascii_otel_metric_t metric = slot->metric;
89 double value = slot->value;
90 atomic_store_explicit(&slot->state, 0, memory_order_release);
91 ascii_otel_metric(metric, value);
92 }
93 unsigned dropped = atomic_exchange_explicit(&g_audio_rt_dropped, 0, memory_order_relaxed);
94 if (dropped)
95 log_warn("Dropped %u audio telemetry samples while the queue was full", dropped);
96}
97
98#ifdef _WIN32
99#include <malloc.h> // For _alloca on Windows
100#define alloca _alloca
101#else
102#include <unistd.h> // For dup, dup2, close, STDERR_FILENO
103#include <fcntl.h> // For O_WRONLY
104#endif
105
106// PortAudio initialization lifecycle (one-time init/shutdown, no refcounting)
107// Uses lifecycle_t for thread-safe, lock-free initialization tracking
108static lifecycle_t g_pa_lc = LIFECYCLE_INIT;
109
123static asciichat_error_t audio_ensure_portaudio_initialized(void) {
124 // Check if already initialized
125 if (lifecycle_is_initialized(&g_pa_lc)) {
126 return ASCIICHAT_OK;
127 }
128
129 // Try to win the initialization race
130 if (!lifecycle_init(&g_pa_lc, "portaudio")) {
131 return ASCIICHAT_OK; // Already initialized by another thread
132 }
133
134 // First initialization - call Pa_Initialize() exactly once
135 // Suppress PortAudio backend probe errors (ALSA/JACK/OSS warnings)
136 // These are harmless - PortAudio tries multiple backends until one works
137 PaError err;
138 LOG_IO("portaudio", { err = Pa_Initialize(); });
139
140 if (err != paNoError) {
141 return SET_ERRNO(ERROR_AUDIO, "Failed to initialize PortAudio: %s", Pa_GetErrorText(err));
142 }
143
144 return ASCIICHAT_OK;
145}
146
154 if (lifecycle_shutdown(&g_pa_lc)) {
155 log_debug("[PORTAUDIO_TERM] Calling Pa_Terminate() to release PortAudio");
156
157 PaError err;
158 LOG_IO("portaudio", { err = Pa_Terminate(); });
159
160 log_debug("[PORTAUDIO_TERM] Pa_Terminate() returned: %s", Pa_GetErrorText(err));
161 }
162}
163
164// AEC processes complete 480-sample blocks; the worker buffers must hold at least one block.
165// Device callbacks signal after capture/consumption. The fallback follows the
166// 20 ms worker cadence for software sources and missed notifications.
167#define WORKER_TIMEOUT_MS 20
168
169// Device callbacks remain 10 ms; publish two complete AEC frames per wake.
170// The bounded worker timeout also flushes partial batches and missed signals.
171static void audio_wake_capture_worker(audio_context_t *ctx) {
173 cond_signal(&ctx->audio_processing_wakeup);
174}
175
176static void audio_publish_local_capture(audio_context_t *ctx, float *samples, size_t count, bool use_media) {
177 uint64_t now = time_get_ns();
178 uint64_t duration = count * 1000000000ULL / (AUDIO_SAMPLE_RATE * AUDIO_CHANNELS);
179 uint64_t block_start = now > duration ? now - duration : 0;
180 audio_recording_submit(AUDIO_RECORDING_MIC, samples, count, block_start);
182 if (use_media) {
183 float media[(OPUS_FRAME_SAMPLES * AUDIO_CHANNELS)];
184 size_t read = media_source_read_audio(ctx->capture_media_source, media, count);
185 audio_recording_submit(AUDIO_RECORDING_MEDIA, media, read, block_start);
187 for (size_t i = 0; i < read; i++)
188 samples[i] = fmaxf(-1.0f, fminf(1.0f, samples[i] + media[i]));
189 if (ctx->monitor_local_media)
190 audio_ring_buffer_write(ctx->playback_buffer, media, (int)read);
191 }
192 // Mirror may record and visualize the microphone without a transmission
193 // consumer. Do not repeatedly overflow and log from that undrained queue.
195 audio_ring_buffer_write(ctx->capture_buffer, samples, (int)count);
196}
197
223static void *audio_worker_thread(void *arg) {
224 audio_context_t *ctx = (audio_context_t *)arg;
225 if (ctx->capture_media_source && ctx->playback_only && ctx->monitor_local_media) {
226 // Scheduling is optional; retain diagnostics without opening an error popup.
227 bool notifications = errno_notifications_suppress(true);
229 (void)thread_set_realtime_priority();
231 errno_notifications_suppress(notifications);
232 }
233 log_debug("Audio worker thread started (batch size: %d frames = %d samples)", OPUS_FRAME_SAMPLES, (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS));
234
235 // Check for AEC3 bypass (static, checked once)
236 static int bypass_aec3_worker = -1;
237 if (bypass_aec3_worker == -1) {
238 const char *env = platform_getenv("BYPASS_AEC3");
239 bypass_aec3_worker = (env && (strcmp(env, "1") == 0 || strcmp(env, "true") == 0)) ? 1 : 0;
240 if (bypass_aec3_worker) {
241 log_warn("Worker thread: AEC3 BYPASSED via BYPASS_AEC3=1 (worker will skip AEC3 processing)");
242 }
243 }
244
245 // Timing instrumentation for debugging
246 static uint64_t loop_count = 0;
247 static uint64_t timeout_count = 0;
248 static uint64_t signal_count = 0;
249 static uint64_t process_count = 0;
250
251 // Detailed timing stats
252 static double total_wait_ns = 0;
253 static double total_capture_ns = 0;
254 static double total_playback_ns = 0;
255 static double max_wait_ns = 0;
256 static double max_capture_ns = 0;
257 static double max_playback_ns = 0;
258
259 uint64_t media_start_ns = time_get_ns();
260 uint64_t media_samples = 0;
261 // Only this worker uses the wait guard; condition waits release it while sleeping.
262 mutex_lock(&ctx->audio_processing_wait_guard);
263 while (true) {
264 audio_metrics_flush();
265 loop_count++;
266 uint64_t loop_start_ns = time_get_ns();
267
268 // The device callback wakes the producer after consumption. The bounded
269 // timeout also drives software-only recording and recovers lost wakeups.
270 uint64_t wait_start_ns = time_get_ns();
271 // Local media playback maintains 150 ms of queued audio. Refill below
272 // 100 ms instead of waking for every callback or 10 ms timeout. Capture
273 // and software-only transmission use a 20 ms processing cadence.
274 bool buffered_media = ctx->capture_media_source && ctx->playback_only && ctx->monitor_local_media && ctx->output_stream;
275 bool transmitted_media = ctx->capture_media_source && ctx->playback_only && !ctx->monitor_local_media;
276 // Device callbacks publish every 20 ms. Leave a second batch of grace
277 // before the watchdog flushes a partial batch, avoiding a timeout racing
278 // the callback that is already about to wake us.
279 bool device_capture = ctx->duplex_stream || ctx->input_stream;
280 int timeout_ms = buffered_media ? 100 : device_capture ? 40 : WORKER_TIMEOUT_MS;
281 int wait_result;
282 if (transmitted_media) {
283 // This producer follows the media clock, not device callbacks. A bounded
284 // 20 ms sleep also bounds stop latency without a wakeup mutex round trip.
285 platform_sleep_us(20 * US_PER_MS_INT);
286 wait_result = 1;
287 } else {
288 wait_result = cond_timedwait(&ctx->audio_processing_wakeup, &ctx->audio_processing_wait_guard, timeout_ms * NS_PER_MS_INT);
289 }
290 double wait_time_ns = (double)time_elapsed_ns(wait_start_ns, time_get_ns());
291 total_wait_ns += wait_time_ns;
292 if (wait_time_ns > max_wait_ns)
293 max_wait_ns = wait_time_ns;
294
295 // Check shutdown flag
297 log_debug("Worker thread received shutdown signal");
298 break;
299 }
300
301 // Count wake-ups
302 if (wait_result == 0) {
303 signal_count++;
304 } else {
305 timeout_count++;
306 }
307
308 // Skip processing if we timed out and no data available
309 size_t capture_available = audio_ring_buffer_available_read(ctx->raw_capture_rb);
310 size_t render_available = audio_ring_buffer_available_read(ctx->raw_render_rb);
311 size_t playback_available = audio_ring_buffer_available_read(ctx->playback_buffer);
312
313 // Log worker loop state every 100 iterations with detailed timing
314 if (loop_count % 100 == 0) {
315 char avg_wait_str[TIME_DURATION_BUFFER_SIZE], max_wait_str[TIME_DURATION_BUFFER_SIZE];
316 char avg_capture_str[TIME_DURATION_BUFFER_SIZE], max_capture_str[TIME_DURATION_BUFFER_SIZE];
317 char avg_playback_str[TIME_DURATION_BUFFER_SIZE], max_playback_str[TIME_DURATION_BUFFER_SIZE];
318 time_pretty((uint64_t)(total_wait_ns / loop_count), -1, avg_wait_str, sizeof(avg_wait_str));
319 time_pretty(max_wait_ns, -1, max_wait_str, sizeof(max_wait_str));
320 time_pretty((uint64_t)(total_capture_ns / (process_count > 0 ? process_count : 1)), -1, avg_capture_str, sizeof(avg_capture_str));
321 time_pretty(max_capture_ns, -1, max_capture_str, sizeof(max_capture_str));
322 time_pretty((uint64_t)(total_playback_ns / (process_count > 0 ? process_count : 1)), -1, avg_playback_str, sizeof(avg_playback_str));
323 time_pretty(max_playback_ns, -1, max_playback_str, sizeof(max_playback_str));
324
325 log_debug("Worker stats: loops=%lu, signals=%lu, timeouts=%lu, processed=%lu", loop_count, signal_count, timeout_count, process_count);
326 log_debug("Worker timing: wait avg=%s max=%s, capture avg=%s max=%s, playback avg=%s max=%s", avg_wait_str, max_wait_str, avg_capture_str, max_capture_str, avg_playback_str, max_playback_str);
327 log_debug("Worker buffers: capture=%zu, render=%zu, playback=%zu (need >= %d to process)", capture_available, render_available, playback_available, (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS));
328 }
329
330 if (wait_result != 0 && capture_available == 0 && playback_available == 0 && !ctx->capture_media_source && !GET_OPTION(test_audio)) {
331 // Timeout with no data - continue waiting
332 continue;
333 }
334
335 process_count++;
336
338 audio_capture_source_t selection = GET_OPTION(audio_capture_source);
339 bool test_audio = GET_OPTION(test_audio);
340 bool use_media = !test_audio && has_media && (selection == AUDIO_CAPTURE_SOURCE_AUTO || selection == AUDIO_CAPTURE_SOURCE_MEDIA || selection == AUDIO_CAPTURE_SOURCE_BOTH);
341 bool use_mic = !test_audio && audio_should_enable_microphone(selection, has_media);
342 if (test_audio || (use_media && !use_mic)) {
343 uint64_t now = time_get_ns();
344 // Local playback follows device consumption, not an unbounded wall-clock
345 // catch-up burst. Keep 150 ms of decoded PCM ready without dropping or
346 // stretching samples through the network jitter controller.
347 bool local_playback = use_media && ctx->monitor_local_media && ctx->output_stream;
348 size_t queued = local_playback ? audio_ring_buffer_available_read(ctx->playback_buffer) : 0;
349 size_t refill = queued < 7200 * AUDIO_CHANNELS ? 7200 * AUDIO_CHANNELS - queued : 0;
350 uint64_t due = local_playback ? media_samples + refill : (now - media_start_ns) / (20 * NS_PER_MS_INT) * (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS);
351 float media[(OPUS_FRAME_SAMPLES * AUDIO_CHANNELS)];
352 while (media_samples < due) {
353 size_t count = due - media_samples > (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) ? (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) : (size_t)(due - media_samples);
354 size_t read = count;
355 if (test_audio) {
356 audio_test_pattern(media, count / AUDIO_CHANNELS, media_samples / AUDIO_CHANNELS, AUDIO_SAMPLE_RATE);
357 (void)audio_convert_channels(media, count / AUDIO_CHANNELS, 1, media, AUDIO_CHANNELS);
358 } else
359 read = media_source_read_audio(ctx->capture_media_source, media, count);
360 if (read < count)
361 memset(media + read, 0, (count - read) * sizeof(float));
362 audio_recording_submit(AUDIO_RECORDING_MEDIA, media, count, media_start_ns + media_samples * 1000000000ULL / (AUDIO_SAMPLE_RATE * AUDIO_CHANNELS));
364 // Keep transmission available, but avoid overrunning an undrained
365 // local-monitor queue once it is full.
367 audio_ring_buffer_write(ctx->capture_buffer, media, (int)count);
368 if (!test_audio && ctx->monitor_local_media)
369 audio_ring_buffer_write(ctx->playback_buffer, media, (int)count);
370 media_samples += count;
371 }
372 }
373 if (!use_mic && capture_available > 0) {
374 size_t drain = capture_available > (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) ? (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) : capture_available;
376 capture_available = 0;
377 }
378
379 // STEP 1: Process capture path (mic → AEC3 → encoder)
380 // Process capture samples if available (don't wait for full batch - reduces latency)
381 // Minimum: 64 samples (1.3ms @ 48kHz) to avoid excessive overhead
382 // AEC3 requires 480-sample frames (10ms @ 48kHz). Process only complete
383 // frames where both render and capture are available. Remainders stay in
384 // the ring buffers and get processed next iteration - no zero-padding,
385 // no data corruption, no skipped echo cancellation.
386 const size_t AEC3_FRAME_SIZE = AUDIO_BUFFER_SIZE;
387 bool want_aec3 = !bypass_aec3_worker && ctx->audio_pipeline;
388
389 if (want_aec3) {
390 // Process matched render and capture where a playback reference is
391 // available. Microphone capture must still progress when playback is
392 // silent or has not produced a reference yet.
393 size_t matched = (capture_available < render_available) ? capture_available : render_available;
394 size_t aligned = (matched / AEC3_FRAME_SIZE) * AEC3_FRAME_SIZE;
395 if (aligned > (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS))
396 aligned = ((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) / AEC3_FRAME_SIZE) * AEC3_FRAME_SIZE;
397
398 bool has_render_reference = aligned > 0;
399 if (aligned == 0 && capture_available >= AEC3_FRAME_SIZE) {
400 // AEC3 consumes paired 10 ms frames. With no complete render frame,
401 // use a zero reference so an empty playback buffer cannot stall the
402 // microphone ring buffer until it overflows.
403 aligned = (capture_available / AEC3_FRAME_SIZE) * AEC3_FRAME_SIZE;
404 if (aligned > (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS))
405 aligned = ((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) / AEC3_FRAME_SIZE) * AEC3_FRAME_SIZE;
406 if (render_available > 0) {
407 size_t discard = render_available > (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) ? (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) : render_available;
409 }
410 }
411
412 if (aligned > 0) {
413 uint64_t capture_start_ns = time_get_ns();
414
415 size_t capture_read = audio_ring_buffer_read(ctx->raw_capture_rb, ctx->worker_capture_batch, aligned);
416 size_t render_read = 0;
417 if (has_render_reference) {
418 render_read = audio_ring_buffer_read(ctx->raw_render_rb, ctx->worker_render_batch, aligned);
419 } else {
420 memset(ctx->worker_render_batch, 0, capture_read * sizeof(float));
421 render_read = capture_read;
422 }
423
424 if (capture_read > 0 && render_read > 0) {
425 uint64_t aec3_start_ns = time_get_ns();
426
427 // Both buffers have identical, frame-aligned sample counts. A zero
428 // render reference leaves near-end microphone audio available when
429 // there is no speaker signal to cancel.
431
432 long aec3_ns = (long)time_elapsed_ns(aec3_start_ns, time_get_ns());
433
434 static int aec3_count = 0;
435 static long aec3_total_ns = 0;
436 static long aec3_max_ns = 0;
437 aec3_count++;
438 aec3_total_ns += aec3_ns;
439 if (aec3_ns > aec3_max_ns)
440 aec3_max_ns = aec3_ns;
441
442 if (aec3_count % 100 == 0) {
443 long avg_ns = aec3_total_ns / aec3_count;
445 time_pretty((uint64_t)avg_ns, -1, avg_str, sizeof(avg_str));
446 time_pretty((uint64_t)aec3_max_ns, -1, max_str, sizeof(max_str));
447 time_pretty((uint64_t)aec3_ns, -1, latest_str, sizeof(latest_str));
448 log_debug("AEC3 performance: avg=%s, max=%s, latest=%s (samples=%zu, %d calls)", avg_str, max_str, latest_str, capture_read, aec3_count);
449 }
450 }
451
452 // Apply microphone sensitivity
453 float mic_sensitivity = GET_OPTION(microphone_sensitivity);
454 if (mic_sensitivity != 1.0f) {
455 if (mic_sensitivity < 0.0f)
456 mic_sensitivity = 0.0f;
457 if (mic_sensitivity > 1.0f)
458 mic_sensitivity = 1.0f;
459 for (size_t i = 0; i < capture_read; i++) {
460 ctx->worker_capture_batch[i] *= mic_sensitivity;
461 }
462 }
463
464 audio_publish_local_capture(ctx, ctx->worker_capture_batch, capture_read, use_media);
465
466 log_debug_every(NS_PER_MS_INT, "Worker processed %zu samples (AEC3 applied, render=%zu)", capture_read, render_read);
467
468 double capture_time_ns = (double)time_elapsed_ns(capture_start_ns, time_get_ns());
469 total_capture_ns += capture_time_ns;
470 if (capture_time_ns > max_capture_ns)
471 max_capture_ns = capture_time_ns;
472 }
473 } else if (capture_available >= 64) {
474 // No AEC3 (bypassed or no pipeline): process capture directly
475 uint64_t capture_start_ns = time_get_ns();
476
477 size_t samples_to_process = (capture_available > (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS)) ? (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) : capture_available;
478 size_t capture_read = audio_ring_buffer_read(ctx->raw_capture_rb, ctx->worker_capture_batch, samples_to_process);
479
480 if (capture_read > 0) {
481 // Drain render buffer to keep it from growing unbounded
482 if (render_available > 0) {
483 size_t drain = (render_available > (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS)) ? (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) : render_available;
485 }
486
487 // Capture samples are normalized to AUDIO_SAMPLE_RATE by the input callback.
488
489 // Apply microphone sensitivity (volume control)
490 float mic_sensitivity = GET_OPTION(microphone_sensitivity);
491 if (mic_sensitivity != 1.0f) {
492 // Clamp to valid range [0.0, 1.0]
493 if (mic_sensitivity < 0.0f)
494 mic_sensitivity = 0.0f;
495 if (mic_sensitivity > 1.0f)
496 mic_sensitivity = 1.0f;
497
498 for (size_t i = 0; i < capture_read; i++) {
499 ctx->worker_capture_batch[i] *= mic_sensitivity;
500 }
501 }
502
503 // Write processed capture to encoder buffer
504 audio_publish_local_capture(ctx, ctx->worker_capture_batch, capture_read, use_media);
505
506 log_debug_every(NS_PER_MS_INT, "Worker processed %zu capture samples (AEC3 %s)", capture_read, bypass_aec3_worker ? "BYPASSED" : "applied");
507 }
508
509 double capture_time_ns = (double)time_elapsed_ns(capture_start_ns, time_get_ns());
510 total_capture_ns += capture_time_ns;
511 if (capture_time_ns > max_capture_ns)
512 max_capture_ns = capture_time_ns;
513 }
514
515 // STEP 2: Output/Playback handling
516 // With output_callback registered, PortAudio handles calling it automatically
517 // No need for worker thread to manually write data via Pa_WriteStream
518 (void)playback_available; // Suppress unused variable warning if not used in this build
519
520 // Log overall loop iteration time
521 double loop_time_ns = (double)time_elapsed_ns(loop_start_ns, time_get_ns());
522 static double total_loop_ns = 0;
523 static double max_loop_ns = 0;
524 total_loop_ns += loop_time_ns;
525 if (loop_time_ns > max_loop_ns)
526 max_loop_ns = loop_time_ns;
527
528 if (loop_count % 100 == 0) {
529 char avg_loop_str[TIME_DURATION_BUFFER_SIZE], max_loop_str[TIME_DURATION_BUFFER_SIZE];
530 time_pretty((uint64_t)(total_loop_ns / loop_count), -1, avg_loop_str, sizeof(avg_loop_str));
531 time_pretty(max_loop_ns, -1, max_loop_str, sizeof(max_loop_str));
532 log_debug("Worker loop timing: avg=%s max=%s", avg_loop_str, max_loop_str);
533 }
534 }
535
536 mutex_unlock(&ctx->audio_processing_wait_guard);
537 log_debug("Audio worker thread exiting");
538 return NULL;
539}
540
555// Mix the local test monitor into the same output frames as received audio.
556// Appending it to the network playback queue would stretch time and cause drops.
557static void audio_monitor_test(audio_context_t *ctx, float *output, size_t count, uint32_t rate) {
558 if (!GET_OPTION(test_audio) || !output)
559 return;
560 float samples[AUDIO_FRAMES_PER_BUFFER];
561 float volume = fmaxf(0, fminf(1, GET_OPTION(speakers_volume)));
562 for (size_t offset = 0; offset < count;) {
563 size_t block = count - offset > ARRAY_SIZE(samples) ? ARRAY_SIZE(samples) : count - offset;
565 (void)audio_convert_channels(samples, block / AUDIO_CHANNELS, 1, samples, AUDIO_CHANNELS);
566 for (size_t i = 0; i < block; ++i)
567 output[offset + i] = fmaxf(-1, fminf(1, output[offset + i] + samples[i] * volume));
568 ctx->test_audio_playback_position += block;
569 offset += block;
570 }
571}
572
573// Only PortAudio callback threads need real-time scheduling. Raising the caller
574// of audio_start_duplex instead promotes the video/render or capture owner and
575// can starve both keyboard input and the actual audio device callbacks.
576static void audio_callback_prepare(void) {
577 g_audio_callback_thread = true;
578 static _Thread_local bool prepared;
579 if (!prepared) {
580 prepared = true;
581 // Scheduling is optional; retain diagnostics without opening an error popup.
582 bool notifications = errno_notifications_suppress(true);
584 (void)thread_set_realtime_priority();
586 errno_notifications_suppress(notifications);
587 }
588}
589
590static int input_callback(const void *, void *, unsigned long, const PaStreamCallbackTimeInfo *, PaStreamCallbackFlags, void *);
591static int output_callback(const void *, void *, unsigned long, const PaStreamCallbackTimeInfo *, PaStreamCallbackFlags, void *);
592
593static int duplex_callback(const void *input, void *output, unsigned long frames, const PaStreamCallbackTimeInfo *time, PaStreamCallbackFlags flags, void *data) {
594 int result = output_callback(NULL, output, frames, time, flags, data);
595 return result == paContinue ? input_callback(input, NULL, frames, time, flags, data) : result;
596}
597
609void resample_linear(const float *src, size_t src_samples, float *dst, size_t dst_samples, double src_rate, double dst_rate) {
610 if (src_samples == 0 || dst_samples == 0) {
611 SAFE_MEMSET(dst, dst_samples * sizeof(float), 0, dst_samples * sizeof(float));
612 return;
613 }
614
615 double ratio = src_rate / dst_rate;
616
617 for (size_t i = 0; i < dst_samples; i++) {
618 double src_pos = (double)i * ratio;
619 size_t idx0 = (size_t)src_pos;
620 size_t idx1 = idx0 + 1;
621 double frac = src_pos - (double)idx0;
622
623 // Clamp indices to valid range
624 if (idx0 >= src_samples)
625 idx0 = src_samples - 1;
626 if (idx1 >= src_samples)
627 idx1 = src_samples - 1;
628
629 // Linear interpolation
630 dst[i] = (float)((1.0 - frac) * src[idx0] + frac * src[idx1]);
631 }
632}
633
646static int output_callback(const void *input, void *output_buffer, unsigned long frames, const PaStreamCallbackTimeInfo *time, PaStreamCallbackFlags flags, void *data) {
647 audio_callback_prepare();
648 (void)input;
649 (void)time;
650 audio_context_t *ctx = data;
651 if (!ctx || !output_buffer)
652 return paAbort;
653 unsigned channels = ctx->output_device_channels ? ctx->output_device_channels : AUDIO_CHANNELS;
654 float *output = output_buffer;
655 memset(output, 0, frames * channels * sizeof(float));
657 return paContinue;
658 if (flags & paOutputUnderflow)
660 if (!frames || frames > AUDIO_FRAMES_PER_BUFFER)
661 return paContinue;
662
663 double rate = ctx->output_device_rate > 0 ? ctx->output_device_rate : AUDIO_SAMPLE_RATE;
664 double step = AUDIO_SAMPLE_RATE / rate;
665 bool resample = rate != AUDIO_SAMPLE_RATE;
666 // At most a 24:1 ratio between the supported 8 kHz and 192 kHz endpoints.
668 float rendered[AUDIO_BUFFER_SIZE];
669 size_t needed = frames;
670 if (resample) {
671 double last = ctx->playback_resampler.phase + (double)(frames - 1) * step;
672 needed = last < 0 ? 1 : (size_t)floor(last) + 2;
673 }
674 if (needed > sizeof(source) / sizeof(source[0]) / AUDIO_CHANNELS)
675 return paContinue;
676 size_t read = ctx->playback_buffer ? audio_ring_buffer_read(ctx->playback_buffer, source, needed * AUDIO_CHANNELS) : 0;
677 memset(source + read, 0, (needed * AUDIO_CHANNELS - read) * sizeof(float));
678 float volume = fmaxf(0, fminf(1, GET_OPTION(speakers_volume)));
679 for (size_t i = 0; i < needed * AUDIO_CHANNELS; i++)
680 source[i] *= volume;
681 // Mono-only speakers play the same centered signal represented in the AEC reference.
682 if (channels == 1)
683 for (size_t i = 0; i < needed; i++)
684 source[i * 2] = source[i * 2 + 1] = source[i * 2] * 0.5f + source[i * 2 + 1] * 0.5f;
685 if (!ctx->playback_only) {
686 audio_ring_buffer_t *reference = ctx->render_buffer ? ctx->render_buffer : ctx->raw_render_rb;
687 if (reference)
688 audio_ring_buffer_write(reference, source, (int)(needed * AUDIO_CHANNELS));
689 }
690 if (resample) {
691 for (size_t frame = 0; frame < frames; frame++) {
692 double position = ctx->playback_resampler.phase + frame * step;
693 size_t index = position < 0 ? 0 : (size_t)position;
694 double fraction = position < 0 ? position + 1 : position - index;
695 for (unsigned channel = 0; channel < AUDIO_CHANNELS; channel++) {
696 float a = position < 0 ? ctx->playback_resampler.previous[channel] : source[index * 2 + channel];
697 float b = position < 0 ? source[channel] : source[(index + 1) * 2 + channel];
698 rendered[frame * 2 + channel] = (float)(a + fraction * (b - a));
699 }
700 }
701 ctx->playback_resampler.phase += frames * step - needed;
702 ctx->playback_resampler.previous[0] = source[(needed - 1) * 2];
703 ctx->playback_resampler.previous[1] = source[(needed - 1) * 2 + 1];
705 } else {
706 memcpy(rendered, source, frames * AUDIO_CHANNELS * sizeof(float));
707 }
708 audio_monitor_test(ctx, rendered, frames * AUDIO_CHANNELS, (uint32_t)rate);
709 if (channels <= 2) {
710 (void)audio_convert_channels(rendered, frames, AUDIO_CHANNELS, output, channels);
711 } else {
712 for (size_t frame = 0; frame < frames; frame++) {
713 output[frame * channels] = rendered[frame * 2];
714 output[frame * channels + 1] = rendered[frame * 2 + 1];
715 }
716 }
718 cond_signal(&ctx->audio_processing_wakeup);
719 return paContinue;
720}
721
722static int input_callback(const void *input, void *output, unsigned long frames, const PaStreamCallbackTimeInfo *time, PaStreamCallbackFlags flags, void *data) {
723 audio_callback_prepare();
724 (void)output;
725 (void)time;
726 audio_context_t *ctx = data;
727 if (!ctx)
728 return paAbort;
729 if (!input || ctx->playback_only || atomic_load_bool(&ctx->shutting_down))
730 return paContinue;
731 if (flags & paInputOverflow)
733 if (frames > AUDIO_FRAMES_PER_BUFFER)
734 return paContinue;
735 float routed[AUDIO_BUFFER_SIZE];
736 float converted[AUDIO_BUFFER_SIZE * 24];
737 unsigned channels = ctx->input_device_channels ? ctx->input_device_channels : 1;
738 unsigned selected = GET_OPTION(microphone_channels) == 2 ? 2 : 1;
739 if (audio_route_capture(input, frames, channels, GET_OPTION(microphone_channel), selected, routed) != ASCIICHAT_OK)
740 return paAbort;
741 const float *capture = routed;
742 size_t count = frames * AUDIO_CHANNELS;
743 if (ctx->input_device_rate > 0 && ctx->input_device_rate != AUDIO_SAMPLE_RATE) {
744 count = audio_resample_stereo(&ctx->capture_resampler, routed, frames, ctx->input_device_rate, converted, sizeof(converted) / sizeof(converted[0]) / AUDIO_CHANNELS, AUDIO_SAMPLE_RATE) *
746 capture = converted;
747 }
748 if (count && ctx->raw_capture_rb)
749 audio_ring_buffer_write(ctx->raw_capture_rb, capture, (int)count);
750 if (ctx->render_buffer && ctx->raw_render_rb && count) {
751 float render[AUDIO_BUFFER_SIZE * 24];
752 size_t read = audio_ring_buffer_read(ctx->render_buffer, render, count);
753 if (read)
754 audio_ring_buffer_write(ctx->raw_render_rb, render, (int)read);
755 }
756 audio_wake_capture_worker(ctx);
757 return paContinue;
758}
759
760// Try the requested layout before layouts required by some hardware backends.
761// Successful opens, rather than maxInputChannels alone, establish support.
762static PaError audio_open_device(PaStream **stream, PaStreamParameters *input, PaStreamParameters *output, double rate, PaStreamCallback *callback, audio_context_t *ctx) {
763 if (!isfinite(rate) || rate < 8000 || rate > 192000)
764 return paInvalidSampleRate;
765 PaStreamParameters *params = input ? input : output;
766 const PaDeviceInfo *info = Pa_GetDeviceInfo(params->device);
767 if (!info)
768 return paInvalidDevice;
769 int maximum = input ? info->maxInputChannels : info->maxOutputChannels;
770 if (maximum > AUDIO_DEVICE_MAX_CHANNELS)
772 int selected = GET_OPTION(microphone_channels) == 2 ? 2 : 1;
773 int first = GET_OPTION(microphone_channel);
774 int minimum = input ? (first < 0 ? maximum : first + selected) : 1;
775 int candidates[] = {input ? minimum : 2, 1, 2, maximum};
776 PaError error = paInvalidChannelCount;
777 for (size_t i = 0; i < sizeof(candidates) / sizeof(candidates[0]); i++) {
778 int channels = candidates[i];
779 if (channels < minimum || channels > maximum)
780 continue;
781 bool duplicate = false;
782 for (size_t j = 0; j < i; j++)
783 duplicate |= candidates[j] == channels;
784 if (duplicate)
785 continue;
786 params->channelCount = channels;
787 error = Pa_OpenStream(stream, input, output, rate, AUDIO_FRAMES_PER_BUFFER, paClipOff, callback, ctx);
788 if (error == paNoError) {
789 if (input)
790 ctx->input_device_channels = (unsigned)channels;
791 else
792 ctx->output_device_channels = (unsigned)channels;
793 log_info("Audio %s: %d device channels at %.0f Hz; internal PCM is stereo", input ? "input" : "output", channels, rate);
794 return error;
795 }
796 if (*stream) {
797 Pa_CloseStream(*stream);
798 *stream = NULL;
799 }
800 }
801 return error;
802}
803
804// Forward declaration for internal helper function
805static audio_ring_buffer_t *audio_ring_buffer_create_internal(bool jitter_buffer_enabled);
806
807static audio_ring_buffer_t *audio_ring_buffer_create_internal(bool jitter_buffer_enabled) {
808 size_t rb_size = sizeof(audio_ring_buffer_t);
810
811 if (!rb) {
812 SET_ERRNO(ERROR_MEMORY, "Failed to allocate audio ring buffer from buffer domain");
813 return NULL;
814 }
815
816 SAFE_MEMSET(rb->data, sizeof(rb->data), 0, sizeof(rb->data));
821 // For capture buffers (jitter_buffer_enabled=false), mark as already filled to bypass jitter logic
822 // For playback buffers (jitter_buffer_enabled=true), start unfilled to wait for threshold
823 atomic_store_bool(&rb->jitter_buffer_filled, !jitter_buffer_enabled);
826 rb->last_sample = 0.0f;
828 rb->jitter_buffer_enabled = jitter_buffer_enabled;
829 rb->channels = 1;
830 rb->jitter_initial_samples = 2880; // 60 ms at 48 kHz
832 rb->jitter_stable_samples = 0;
833 rb->jitter_drift_phase = 0;
834
835 if (mutex_init(&rb->mutex, "audio_ring_buffer") != 0) {
836 SET_ERRNO(ERROR_THREAD, "Failed to initialize audio ring buffer mutex");
837 buffer_release(rb);
838 return NULL;
839 }
840
841 audio_ring_buffer_register_atomics(rb, "audio_ring_buffer");
842 return rb;
843}
844
846 if (!rb)
847 return;
848 if (samples < OPUS_FRAME_SAMPLES * rb->channels)
849 samples = OPUS_FRAME_SAMPLES * rb->channels;
850 if (samples > 7680 * rb->channels)
851 samples = 7680 * rb->channels;
852 rb->jitter_initial_samples = samples;
853 rb->jitter_target_samples = samples;
854 rb->jitter_stable_samples = 0;
855 rb->jitter_drift_phase = 0;
856}
857
859 return audio_ring_buffer_create_internal(true); // Default: enable jitter buffering for playback
860}
861
863 return audio_ring_buffer_create_internal(false); // Disable jitter buffering for capture
864}
865
866audio_ring_buffer_t *audio_ring_buffer_create_format(unsigned channels, bool capture) {
867 if (channels != 1 && channels != 2) {
868 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid audio queue channel count");
869 return NULL;
870 }
871 audio_ring_buffer_t *rb = audio_ring_buffer_create_internal(!capture);
872 if (rb) {
873 rb->channels = channels;
874 rb->jitter_initial_samples *= channels;
876 }
877 return rb;
878}
879
881 if (!rb)
882 return;
883
886
887 mutex_destroy(&rb->mutex);
888 buffer_release(rb);
889}
890
891void audio_ring_buffer_register_atomics(audio_ring_buffer_t *rb, const char *context_name) {
892 if (!rb || !context_name || !context_name[0]) {
893 return;
894 }
895
896 // Register the ring buffer itself with a unique name
897 NAMED_REGISTER_AUDIO_RINGBUF(rb, context_name, NULL);
898
899 // Ring buffer indices (lock-free producer-consumer)
900 NAMED_REGISTER_ATOMIC(&rb->write_index, "write_index_producer_position", (uintptr_t)(const void *)(rb));
901 NAMED_REGISTER_ATOMIC(&rb->read_index, "read_index_consumer_position", (uintptr_t)(const void *)(rb));
902 NAMED_REGISTER_ATOMIC(&rb->discard_pending, "discard_pending", (uintptr_t)(const void *)(rb));
903 NAMED_REGISTER_ATOMIC(&rb->discard_to_index, "discard_to_index_producer_position", (uintptr_t)(const void *)(rb));
904
905 // Jitter buffer state management
906 NAMED_REGISTER_ATOMIC(&rb->jitter_buffer_filled, "jitter_buffer_has_filled_threshold_flag", (uintptr_t)(const void *)(rb));
907 NAMED_REGISTER_ATOMIC(&rb->crossfade_samples_remaining, "crossfade_samples_remaining_count", (uintptr_t)(const void *)(rb));
908 NAMED_REGISTER_ATOMIC(&rb->crossfade_fade_in, "crossfade_fade_in_direction_flag", (uintptr_t)(const void *)(rb));
909
910 // Audio quality monitoring
911 NAMED_REGISTER_ATOMIC(&rb->underrun_count, "audio_underrun_event_counter", (uintptr_t)(const void *)(rb));
912}
913
928
930 if (!rb)
931 return;
932
933 mutex_lock(&rb->mutex);
934 // Reset buffer to empty state (no audio to play = silence at shutdown)
939 rb->last_sample = 0.0f;
944 rb->jitter_stable_samples = 0;
945 rb->jitter_drift_phase = 0;
946 // Clear the actual data to zeros to prevent any stale audio
947 SAFE_MEMSET(rb->data, sizeof(rb->data), 0, sizeof(rb->data));
948 mutex_unlock(&rb->mutex);
949}
950
952 if (rb) {
953 // Capture the current producer position before the caller writes its new
954 // samples. The consumer can drop everything through this point while
955 // preserving samples appended afterward.
956 unsigned int write_idx = atomic_load_u64(&rb->write_index);
957 atomic_store_u64(&rb->discard_to_index, write_idx);
959 }
960}
961
963 if (!rb || !data || samples <= 0)
964 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb=%p, data=%p, samples=%d", rb, data, samples);
965
966 if (samples % rb->channels)
967 return SET_ERRNO(ERROR_INVALID_PARAM, "Incomplete PCM frame in audio queue write");
968 // Validate samples doesn't exceed our buffer size
969 if (samples > AUDIO_RING_BUFFER_SIZE) {
970 return SET_ERRNO(ERROR_BUFFER, "Attempted to write %d samples, but buffer size is only %d", samples, AUDIO_RING_BUFFER_SIZE);
971 }
972
973 // LOCK-FREE: Load indices with proper memory ordering
974 // - Load our own write_index with relaxed (no sync needed with ourselves)
975 // - Load reader's read_index with acquire (see reader's updates to free space)
976 unsigned int write_idx = atomic_load_u64(&rb->write_index);
977 unsigned int read_idx = atomic_load_u64(&rb->read_index);
978
979 // Calculate current buffer level (how many samples are buffered)
980 int buffer_level;
981 if (write_idx >= read_idx) {
982 buffer_level = (int)(write_idx - read_idx);
983 } else {
984 buffer_level = AUDIO_RING_BUFFER_SIZE - (int)(read_idx - write_idx);
985 }
986 // Reserve 1 slot to distinguish between full and empty states
987 // (when buffer is full, write_idx will be just before read_idx, not equal to it)
988 int available = AUDIO_RING_BUFFER_SIZE - (int)rb->channels - buffer_level;
989
990 // If playback has fallen behind, ask its consumer to skip the stale queue.
991 // Dropping incoming samples here preserves the old backlog, so playback
992 // drains outdated audio and then underruns before it can return to live data.
993 if (buffer_level > (AUDIO_JITTER_HIGH_WATER_MARK * (int)rb->channels)) {
994 if (rb->jitter_buffer_enabled) {
995 // The read callback owns read_index. Let it advance to the latest write
996 // position atomically on its next invocation, then preserve this fresh
997 // packet so audio resumes from the current stream position.
999 log_warn_every(LOG_RATE_FAST, "Audio playback backlog (%d samples); requesting consumer to skip stale queued audio", buffer_level);
1000 } else {
1001 // Capture queues also have a high-water mark, but their reader may be
1002 // processing a matching microphone/render interval. Retain the existing
1003 // policy there instead of changing the reader's timeline asynchronously.
1004 int target_writes = AUDIO_JITTER_TARGET_LEVEL * (int)rb->channels - buffer_level;
1005 if (target_writes < 0) {
1006 target_writes = 0;
1007 }
1008
1009 if (samples > target_writes) {
1010 int dropped = samples - target_writes;
1011 audio_metric(ASCII_OTEL_METRIC_AUDIO_DROPPED, dropped);
1012 log_warn_every(LOG_RATE_FAST, "Audio capture buffer high water mark exceeded (%d > %d): dropping %d incoming samples", buffer_level, (AUDIO_JITTER_HIGH_WATER_MARK * (int)rb->channels),
1013 dropped);
1014 samples = target_writes;
1015 }
1016 }
1017 }
1018
1019 // Now write the new samples - should always have enough space after above
1020 int samples_to_write = samples;
1021 if (samples > available) {
1022 // This should rarely happen after the high water mark logic above
1023 int samples_dropped = samples - available;
1024 audio_metric(ASCII_OTEL_METRIC_AUDIO_DROPPED, samples_dropped);
1025 audio_metric(ASCII_OTEL_METRIC_AUDIO_OVERRUN, 1);
1026 samples_to_write = available;
1027 log_warn_every(LOG_RATE_FAST, "Audio buffer overflow: dropping %d of %d incoming samples (buffer_used=%d/%d)", samples_dropped, samples, AUDIO_RING_BUFFER_SIZE - available,
1029 }
1030
1031 samples_to_write -= samples_to_write % (int)rb->channels;
1032 // Write only the samples that fit (preserves existing data integrity)
1033 if (samples_to_write > 0) {
1034 int remaining = AUDIO_RING_BUFFER_SIZE - (int)write_idx;
1035
1036 if (samples_to_write <= remaining) {
1037 // Can copy in one chunk
1038 SAFE_MEMCPY(&rb->data[write_idx], samples_to_write * sizeof(float), data, samples_to_write * sizeof(float));
1039 } else {
1040 // Need to wrap around - copy in two chunks
1041 SAFE_MEMCPY(&rb->data[write_idx], remaining * sizeof(float), data, remaining * sizeof(float));
1042 SAFE_MEMCPY(&rb->data[0], (samples_to_write - remaining) * sizeof(float), &data[remaining], (samples_to_write - remaining) * sizeof(float));
1043 }
1044
1045 // LOCK-FREE: Store new write_index with release ordering
1046 // This ensures all data writes above are visible before the index update
1047 unsigned int new_write_idx = (write_idx + (unsigned int)samples_to_write) % AUDIO_RING_BUFFER_SIZE;
1048 atomic_store_u64(&rb->write_index, new_write_idx);
1049 }
1050
1051 // Note: jitter buffer fill check is now done in read function for better control
1052
1053 return ASCIICHAT_OK; // Success
1054}
1055
1056size_t audio_ring_buffer_read(audio_ring_buffer_t *rb, float *data, size_t samples) {
1057 if (!rb || !data || samples <= 0) {
1058 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb=%p, data=%p, samples=%d", rb, data, samples);
1059 return 0; // Return 0 samples read on error
1060 }
1061
1062 if (samples % rb->channels) {
1063 SET_ERRNO(ERROR_INVALID_PARAM, "Incomplete PCM frame in audio queue read");
1064 return 0;
1065 }
1066 // Keep read_index consumer-owned while letting a producer request a flush.
1067 if (atomic_exchange_bool(&rb->discard_pending, false)) {
1068 unsigned int read_idx = atomic_load_u64(&rb->read_index);
1069 unsigned int discard_to = atomic_load_u64(&rb->discard_to_index);
1070 unsigned int advance = (discard_to + AUDIO_RING_BUFFER_SIZE - read_idx) % AUDIO_RING_BUFFER_SIZE;
1071 // A concurrent callback may already have consumed beyond the requested
1072 // boundary. In that case the target is behind us and must not rewind the
1073 // single-consumer index.
1074 if (advance < AUDIO_RING_BUFFER_SIZE / 2) {
1075 atomic_store_u64(&rb->read_index, discard_to);
1076 rb->last_sample = 0.0f;
1078 }
1079 }
1080
1081 // LOCK-FREE: Load indices with proper memory ordering
1082 // - Load writer's write_index with acquire (see writer's data updates)
1083 // - Load our own read_index with relaxed (no sync needed with ourselves)
1084 unsigned int write_idx = atomic_load_u64(&rb->write_index);
1085 unsigned int read_idx = atomic_load_u64(&rb->read_index);
1086
1087 // Calculate available samples
1088 size_t available;
1089 if (write_idx >= read_idx) {
1090 available = write_idx - read_idx;
1091 } else {
1092 available = AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
1093 }
1094
1095 // LOCK-FREE: Load jitter buffer state with acquire ordering
1096 bool jitter_filled = atomic_load_u64(&rb->jitter_buffer_filled);
1097 int crossfade_remaining = atomic_load_u64(&rb->crossfade_samples_remaining);
1098 bool fade_in = atomic_load_u64(&rb->crossfade_fade_in);
1099
1100 // Jitter buffer: don't read until initial fill threshold is reached
1101 // (only for playback buffers - capture buffers have jitter_buffer_enabled = false)
1102 if (!jitter_filled && rb->jitter_buffer_enabled) {
1103 // Check if we've accumulated enough samples to start playback
1104 if (available >= rb->jitter_target_samples) {
1108 log_info("Jitter buffer filled (%zu samples), starting playback with fade-in", available);
1109 // Reload state for processing below
1110 jitter_filled = true;
1111 crossfade_remaining = (AUDIO_CROSSFADE_SAMPLES * (int)rb->channels);
1112 fade_in = true;
1113 } else {
1114 // Log buffer fill progress every second
1115 log_debug_every(NS_PER_MS_INT, "Jitter buffer filling: %zu/%d samples (%.1f%%)", available, rb->jitter_target_samples, (100.0f * available) / rb->jitter_target_samples);
1116 return 0; // Return 0 samples - caller will pad with silence
1117 }
1118 }
1119
1120 // Periodic buffer health logging (every 5 seconds when healthy)
1121 unsigned int underruns = atomic_load_u64(&rb->underrun_count);
1122 log_dev_every(5 * US_PER_SEC_INT, "Buffer health: %zu/%d samples (%.1f%%), underruns=%u", available, AUDIO_RING_BUFFER_SIZE, (100.0f * available) / AUDIO_RING_BUFFER_SIZE, underruns);
1123
1124 audio_metric(ASCII_OTEL_METRIC_AUDIO_FILL, (double)available);
1125 if (rb->jitter_buffer_enabled)
1126 audio_metric(ASCII_OTEL_METRIC_AUDIO_JITTER, (double)rb->jitter_target_samples / (AUDIO_SAMPLE_RATE * rb->channels));
1127 bool underrun = rb->jitter_buffer_enabled && available < samples;
1128 if (underrun) {
1129 audio_metric(ASCII_OTEL_METRIC_AUDIO_UNDERRUN, 1);
1131 // One bounded refill after a real shortage avoids alternating tiny fragments
1132 // and silence when packets resume. Low occupancy alone is not an underrun.
1134 rb->jitter_stable_samples = 0;
1135 rb->jitter_drift_phase = 0;
1137 } else if (rb->jitter_buffer_enabled) {
1138 rb->jitter_stable_samples += samples;
1139 if (rb->jitter_stable_samples >= 480000 * rb->channels) {
1141 rb->jitter_target_samples -= 480 * rb->channels;
1142 rb->jitter_stable_samples = 0;
1143 rb->jitter_drift_phase = 0;
1144 }
1145 }
1146
1147 size_t to_read = (samples > available) ? available : samples;
1148 audio_metric(rb->jitter_buffer_enabled ? ASCII_OTEL_METRIC_AUDIO_PLAYBACK : ASCII_OTEL_METRIC_AUDIO_CAPTURE, (double)to_read);
1149 size_t consumed = to_read;
1150 if (rb->jitter_buffer_enabled && !underrun && samples > 1 && available > samples) {
1151 // Slowly reconcile independent device clocks. Bound interpolation to one
1152 // sample per block and a maximum average rate correction of 1000 ppm.
1153 double error = ((double)available - rb->jitter_target_samples) / (AUDIO_SAMPLE_RATE * rb->channels);
1154 double correction = fmax(-0.001, fmin(0.001, error * 0.02));
1155 rb->jitter_drift_phase += correction * (samples / rb->channels);
1156 if (rb->jitter_drift_phase >= 1.0) {
1157 consumed += rb->channels;
1158 rb->jitter_drift_phase -= 1.0;
1159 } else if (rb->jitter_drift_phase <= -1.0) {
1160 consumed -= rb->channels;
1161 rb->jitter_drift_phase += 1.0;
1162 }
1163 }
1164
1165 if (consumed != to_read) {
1166 size_t frames = to_read / rb->channels;
1167 size_t consumed_frames = consumed / rb->channels;
1168 for (size_t frame = 0; frame < frames; frame++) {
1169 double position = frames > 1 ? (double)frame * (consumed_frames - 1) / (frames - 1) : 0;
1170 size_t first = (size_t)position;
1171 size_t next = first + 1 < consumed_frames ? first + 1 : first;
1172 float fraction = (float)(position - first);
1173 for (unsigned channel = 0; channel < rb->channels; channel++) {
1174 float a = rb->data[(read_idx + first * rb->channels + channel) % AUDIO_RING_BUFFER_SIZE];
1175 float b = rb->data[(read_idx + next * rb->channels + channel) % AUDIO_RING_BUFFER_SIZE];
1176 data[frame * rb->channels + channel] = a + fraction * (b - a);
1177 }
1178 }
1179 } else {
1180 size_t remaining = AUDIO_RING_BUFFER_SIZE - read_idx;
1181 if (to_read <= remaining) {
1182 SAFE_MEMCPY(data, to_read * sizeof(float), &rb->data[read_idx], to_read * sizeof(float));
1183 } else {
1184 SAFE_MEMCPY(data, remaining * sizeof(float), &rb->data[read_idx], remaining * sizeof(float));
1185 SAFE_MEMCPY(&data[remaining], (to_read - remaining) * sizeof(float), &rb->data[0], (to_read - remaining) * sizeof(float));
1186 }
1187 }
1188 atomic_store_u64(&rb->read_index, (read_idx + (unsigned int)consumed) % AUDIO_RING_BUFFER_SIZE);
1189
1190 // Apply fade-in if recovering from underrun
1191 if (fade_in && crossfade_remaining > 0) {
1192 int fade_start = (AUDIO_CROSSFADE_SAMPLES * (int)rb->channels) - crossfade_remaining;
1193 size_t fade_samples = (to_read < (size_t)crossfade_remaining) ? to_read : (size_t)crossfade_remaining;
1194
1195 for (size_t i = 0; i < fade_samples; i++) {
1196 float fade_factor = (float)((fade_start + (int)i) / (int)rb->channels + 1) / (float)AUDIO_CROSSFADE_SAMPLES;
1197 data[i] *= fade_factor;
1198 }
1199
1200 int new_crossfade_remaining = crossfade_remaining - (int)fade_samples;
1201 atomic_store_u64(&rb->crossfade_samples_remaining, new_crossfade_remaining);
1202 if (new_crossfade_remaining <= 0) {
1204 log_debug("Audio fade-in complete");
1205 }
1206 }
1207
1208 if (underrun && to_read > 0) {
1209 size_t max_fade_samples = (size_t)AUDIO_CROSSFADE_SAMPLES * rb->channels;
1210 size_t fade_samples = to_read < max_fade_samples ? to_read : max_fade_samples;
1211 for (size_t i = 0; i < fade_samples; ++i)
1212 data[to_read - fade_samples + i] *= (float)((fade_samples - i - 1) / rb->channels) / (float)(fade_samples / rb->channels);
1213 }
1214
1215 // Save last sample for potential fade-out
1216 // Note: only update if we actually read some data
1217 // This is NOT atomic - only the reader thread writes this
1218 if (to_read > 0) {
1219 rb->last_sample = data[to_read - 1];
1220 }
1221
1222 // Return ACTUAL number of samples read, not padded count
1223 // The caller (mixer) expects truthful return values to detect underruns
1224 // and handle silence padding externally. Internal padding creates double-padding bugs.
1225 //
1226 // This function was incorrectly returning `samples` even when
1227 // it only read `to_read` samples. This broke the mixer's underrun detection.
1228 return to_read;
1229}
1230
1242size_t audio_ring_buffer_peek(audio_ring_buffer_t *rb, float *data, size_t samples) {
1243 if (!rb || !data || samples <= 0) {
1244 return 0;
1245 }
1246
1247 // LOCK-FREE: Load indices with proper memory ordering
1248 unsigned int write_idx = atomic_load_u64(&rb->write_index);
1249 unsigned int read_idx = atomic_load_u64(&rb->read_index);
1250
1251 // Calculate available samples
1252 size_t available;
1253 if (write_idx >= read_idx) {
1254 available = write_idx - read_idx;
1255 } else {
1256 available = AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
1257 }
1258
1259 size_t to_peek = (samples > available) ? available : samples;
1260
1261 if (to_peek == 0) {
1262 return 0;
1263 }
1264
1265 // Copy samples in chunks (handle wraparound)
1266 size_t first_chunk = (read_idx + to_peek <= AUDIO_RING_BUFFER_SIZE) ? to_peek : (AUDIO_RING_BUFFER_SIZE - read_idx);
1267
1268 SAFE_MEMCPY(data, first_chunk * sizeof(float), rb->data + read_idx, first_chunk * sizeof(float));
1269
1270 if (first_chunk < to_peek) {
1271 // Wraparound: copy second chunk from beginning of buffer
1272 size_t second_chunk = to_peek - first_chunk;
1273 SAFE_MEMCPY(data + first_chunk, second_chunk * sizeof(float), rb->data, second_chunk * sizeof(float));
1274 }
1275
1276 return to_peek;
1277}
1278
1280 if (!rb)
1281 return 0;
1282
1283 // LOCK-FREE: Load indices with proper memory ordering
1284 // Use acquire for write_index to see writer's updates
1285 // Use relaxed for read_index (our own index)
1286 unsigned int write_idx = atomic_load_u64(&rb->write_index);
1287 unsigned int read_idx = atomic_load_u64(&rb->read_index);
1288
1289 if (write_idx >= read_idx) {
1290 return write_idx - read_idx;
1291 }
1292
1293 return AUDIO_RING_BUFFER_SIZE - read_idx + write_idx;
1294}
1295
1297 if (!rb) {
1298 SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: rb is NULL");
1299 return 0;
1300 }
1301
1303}
1304
1306 ASCII_OTEL_SCOPE(AUDIO_INIT);
1307 log_debug("starting, ctx=%p", (void *)ctx);
1308 if (!ctx) {
1309 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx is NULL");
1310 }
1311
1312 SAFE_MEMSET(ctx, sizeof(audio_context_t), 0, sizeof(audio_context_t));
1313
1314 if (mutex_init(&ctx->state_mutex, "audio_context") != 0) {
1315 return SET_ERRNO(ERROR_THREAD, "Failed to initialize audio context mutex");
1316 }
1317
1318 // NOTE: PortAudio initialization deferred to audio_start_duplex() where streams are actually opened
1319 // This avoids Pa_Initialize() overhead for contexts that might not start duplex
1320 // and prevents premature ALSA device allocation and memory leaks
1321
1322 // Create capture buffer WITHOUT jitter buffering (PortAudio writes directly from microphone)
1324 if (!ctx->capture_buffer) {
1325 mutex_destroy(&ctx->state_mutex);
1326 return SET_ERRNO(ERROR_MEMORY, "Failed to create capture buffer");
1327 }
1328
1330 if (!ctx->playback_buffer) {
1332 mutex_destroy(&ctx->state_mutex);
1333 return SET_ERRNO(ERROR_MEMORY, "Failed to create playback buffer");
1334 }
1335
1336 // Create new ring buffers for worker thread architecture
1338 if (!ctx->raw_capture_rb) {
1341 mutex_destroy(&ctx->state_mutex);
1342 return SET_ERRNO(ERROR_MEMORY, "Failed to create raw capture buffer");
1343 }
1344
1346 if (!ctx->raw_render_rb) {
1350 mutex_destroy(&ctx->state_mutex);
1351 return SET_ERRNO(ERROR_MEMORY, "Failed to create raw render buffer");
1352 }
1353
1355 if (!ctx->processed_playback_rb) {
1360 mutex_destroy(&ctx->state_mutex);
1361 return SET_ERRNO(ERROR_MEMORY, "Failed to create processed playback buffer");
1362 }
1363
1364 // Initialize worker thread infrastructure
1365 if (mutex_init(&ctx->audio_processing_wait_guard, "audio_processing_wait_guard") != 0) {
1371 mutex_destroy(&ctx->state_mutex);
1372 return SET_ERRNO(ERROR_THREAD, "Failed to initialize worker mutex");
1373 }
1374
1375 if (cond_init(&ctx->audio_processing_wakeup, "audio_processing_wakeup") != 0) {
1376 mutex_destroy(&ctx->audio_processing_wait_guard);
1382 mutex_destroy(&ctx->state_mutex);
1383 return SET_ERRNO(ERROR_THREAD, "Failed to initialize worker condition variable");
1384 }
1385
1386 // Allocate pre-allocated worker buffers (avoid malloc in worker loop)
1387 ctx->worker_capture_batch = SAFE_MALLOC((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) * sizeof(float), float *);
1388 if (!ctx->worker_capture_batch) {
1389 cond_destroy(&ctx->audio_processing_wakeup);
1390 mutex_destroy(&ctx->audio_processing_wait_guard);
1396 mutex_destroy(&ctx->state_mutex);
1397 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker capture batch buffer");
1398 }
1399
1400 ctx->worker_render_batch = SAFE_MALLOC((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) * sizeof(float), float *);
1401 if (!ctx->worker_render_batch) {
1403 cond_destroy(&ctx->audio_processing_wakeup);
1404 mutex_destroy(&ctx->audio_processing_wait_guard);
1410 mutex_destroy(&ctx->state_mutex);
1411 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker render batch buffer");
1412 }
1413
1414 ctx->worker_playback_batch = SAFE_MALLOC((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) * sizeof(float), float *);
1415 if (!ctx->worker_playback_batch) {
1418 cond_destroy(&ctx->audio_processing_wakeup);
1419 mutex_destroy(&ctx->audio_processing_wait_guard);
1425 mutex_destroy(&ctx->state_mutex);
1426 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker playback batch buffer");
1427 }
1428
1429 ctx->capture_media_source = NULL;
1430 ctx->monitor_local_media = false;
1431
1432 // Initialize worker thread state (thread will be started in audio_start_duplex)
1433 ctx->worker_running = false;
1435
1436 ctx->initialized = true;
1437 atomic_store_bool(&ctx->shutting_down, false);
1438
1439 /* Register audio context with named registry */
1440 NAMED_REGISTER(ctx, "audio_context", "audio_context_t", "0x%tx", NULL);
1441
1442 /* Register audio context's sync primitives with hierarchical naming */
1443 NAMED_REGISTER_MUTEX(&ctx->state_mutex, "state_mutex", (uintptr_t)(const void *)(ctx));
1444 NAMED_REGISTER_MUTEX(&ctx->audio_processing_wait_guard, "audio_processing_wait_guard", (uintptr_t)(const void *)(ctx));
1445 NAMED_REGISTER_COND(&ctx->audio_processing_wakeup, "audio_processing_wakeup", (uintptr_t)(const void *)(ctx));
1446 NAMED_REGISTER_ATOMIC(&ctx->worker_should_stop, "worker_should_stop", (uintptr_t)(const void *)(ctx));
1447 NAMED_REGISTER_ATOMIC(&ctx->shutting_down, "shutting_down", (uintptr_t)(const void *)(ctx));
1448
1449 /* Register ring buffers as child structures with audio context as parent */
1450 NAMED_REGISTER_AUDIO_RINGBUF(ctx->capture_buffer, "capture_buffer", (uintptr_t)(const void *)(ctx));
1451 NAMED_REGISTER_AUDIO_RINGBUF(ctx->playback_buffer, "playback_buffer", (uintptr_t)(const void *)(ctx));
1452 NAMED_REGISTER_AUDIO_RINGBUF(ctx->raw_capture_rb, "raw_capture_rb", (uintptr_t)(const void *)(ctx));
1453 NAMED_REGISTER_AUDIO_RINGBUF(ctx->raw_render_rb, "raw_render_rb", (uintptr_t)(const void *)(ctx));
1454 NAMED_REGISTER_AUDIO_RINGBUF(ctx->processed_playback_rb, "processed_playback_rb", (uintptr_t)(const void *)(ctx));
1455
1456 log_info("Audio system initialized successfully (worker thread architecture enabled)");
1457 return ASCIICHAT_OK;
1458}
1459
1461 ASCII_OTEL_SCOPE(AUDIO_DESTROY);
1462 if (!ctx) {
1463 return;
1464 }
1465
1466 // Always release PortAudio refcount if it was incremented
1467 // audio_init() calls Pa_Initialize() very early, and if it fails partway through,
1468 // ctx->initialized will be false. But we MUST still call audio_release_portaudio()
1469 // to properly decrement the refcount and allow Pa_Terminate() to be called.
1470 if (ctx->initialized) {
1471
1472 // Stop duplex stream if running (this also stops the worker thread)
1473 if (ctx->running) {
1474 audio_stop_duplex(ctx);
1475 }
1476
1477 // Ensure worker thread is stopped even if streams weren't running
1478 if (ctx->worker_running) {
1479 log_debug("Stopping worker thread");
1481 cond_signal(&ctx->audio_processing_wakeup); // Wake up worker if waiting
1482 thread_join(&ctx->worker_thread, NULL);
1483 ctx->worker_running = false;
1484 }
1485
1486 mutex_lock(&ctx->state_mutex);
1487
1488 // Destroy all ring buffers (old + new)
1494 audio_ring_buffer_destroy(ctx->render_buffer); // May be NULL, that's OK
1495
1496 // Free pre-allocated worker buffers
1500
1501 // Destroy worker synchronization primitives
1502 cond_destroy(&ctx->audio_processing_wakeup);
1503 mutex_destroy(&ctx->audio_processing_wait_guard);
1504
1505 ctx->initialized = false;
1506
1507 mutex_unlock(&ctx->state_mutex);
1508 mutex_destroy(&ctx->state_mutex);
1509
1512 NAMED_UNREGISTER(ctx);
1513
1514 log_debug("Audio system cleanup complete (all resources released)");
1515 } else {
1516 }
1517}
1518
1519void audio_set_pipeline(audio_context_t *ctx, void *pipeline) {
1520 if (!ctx)
1521 return;
1522 ctx->audio_pipeline = pipeline;
1523}
1524
1526 if (!ctx || !ctx->initialized) {
1527 return;
1528 }
1529
1530 if (ctx->playback_buffer) {
1532 }
1533 if (ctx->processed_playback_rb) {
1535 }
1536 if (ctx->render_buffer) {
1538 }
1539 if (ctx->raw_render_rb) {
1541 }
1542}
1543
1545 ASCII_OTEL_SCOPE(AUDIO_START_DUPLEX);
1546 if (!ctx || !ctx->initialized) {
1547 return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
1548 }
1549
1550 // Check if already running (without holding lock during blocking operations)
1551 // Do this check first before acquiring any locks
1552 if (ctx->duplex_stream || ctx->input_stream || ctx->output_stream) {
1553 return ASCIICHAT_OK;
1554 }
1555
1556 atomic_store_bool(&ctx->shutting_down, false);
1557 bool media_audio = ctx->capture_media_source && media_source_has_audio(ctx->capture_media_source);
1559 if (GET_OPTION(test_audio) || !audio_should_enable_microphone(GET_OPTION(audio_capture_source), media_audio))
1560 ctx->playback_only = true;
1561 bool media_only = GET_OPTION(test_audio) || (media_audio && ctx->playback_only);
1562 if (ctx->playback_only && GET_OPTION(audio_no_playback)) {
1564 ctx->input_device_rate = ctx->output_device_rate = 0;
1566 goto start_worker;
1567 }
1568 if (ctx->playback_buffer) {
1569 // Local decoded PCM is paced by the speaker callback and has no network
1570 // clock to reconcile. Keep its samples exact across callback boundaries.
1571 audio_capture_source_t selection = GET_OPTION(audio_capture_source);
1572 bool local_media_selected = selection == AUDIO_CAPTURE_SOURCE_AUTO || selection == AUDIO_CAPTURE_SOURCE_MEDIA || selection == AUDIO_CAPTURE_SOURCE_BOTH;
1573 ctx->playback_buffer->jitter_buffer_enabled = !(media_audio && ctx->playback_only && ctx->monitor_local_media && local_media_selected);
1575 }
1576
1577 // Media-only recording can run through the software worker without an audio
1578 // device. Initialize PortAudio opportunistically so monitoring still works
1579 // when a speaker is available.
1581 asciichat_error_t pa_result = audio_ensure_portaudio_initialized();
1582 if (pa_result == ASCIICHAT_OK) {
1583 ASSERT_NO_ERRNO_SINCE(pa_scope);
1585 }
1586 if (pa_result != ASCIICHAT_OK && (!media_only || pa_result != ERROR_AUDIO))
1587 return pa_result;
1588
1589 if (pa_result != ASCIICHAT_OK) {
1591 log_warn("PortAudio unavailable; continuing media-only audio without an audio device");
1593 goto start_worker;
1594 }
1595
1596 // Setup input parameters (skip if playback-only mode)
1597 PaStreamParameters inputParams = {0};
1598 const PaDeviceInfo *inputInfo = NULL;
1599 bool has_input = false;
1600
1601 if (!ctx->playback_only) {
1602 if (GET_OPTION(microphone_index) >= 0) {
1603 inputParams.device = GET_OPTION(microphone_index);
1604 } else {
1605 inputParams.device = Pa_GetDefaultInputDevice();
1606 }
1607
1608 if (inputParams.device == paNoDevice) {
1609 return SET_ERRNO(ERROR_AUDIO, "No input device available");
1610 }
1611
1612 inputInfo = Pa_GetDeviceInfo(inputParams.device);
1613 if (!inputInfo) {
1614 return SET_ERRNO(ERROR_AUDIO, "Input device info not found");
1615 }
1616
1617 has_input = true;
1618 inputParams.channelCount = GET_OPTION(microphone_channels) == 2 ? 2 : 1;
1619 int first_channel = GET_OPTION(microphone_channel);
1620 if (first_channel >= 0 && (first_channel >= inputInfo->maxInputChannels || inputParams.channelCount > inputInfo->maxInputChannels - first_channel))
1621 return SET_ERRNO(ERROR_INVALID_PARAM, "Selected microphone input/pair is unavailable on %s", inputInfo->name);
1622 inputParams.sampleFormat = paFloat32;
1623 inputParams.suggestedLatency = inputInfo->defaultLowInputLatency;
1624 inputParams.hostApiSpecificStreamInfo = NULL;
1625 }
1626
1627 // Setup output parameters
1628 PaStreamParameters outputParams;
1629 const PaDeviceInfo *outputInfo = NULL;
1630 bool has_output = false;
1631
1632 if (GET_OPTION(audio_no_playback)) {
1633 outputParams.device = paNoDevice;
1634 log_info("Audio playback disabled by --no-audio-playback");
1635 } else if (GET_OPTION(speakers_index) >= 0) {
1636 outputParams.device = GET_OPTION(speakers_index);
1637 } else {
1638 outputParams.device = Pa_GetDefaultOutputDevice();
1639 }
1640
1641 if (outputParams.device != paNoDevice) {
1642 outputInfo = Pa_GetDeviceInfo(outputParams.device);
1643 if (outputInfo) {
1644 has_output = true;
1645 outputParams.channelCount = outputInfo->maxOutputChannels >= AUDIO_CHANNELS ? AUDIO_CHANNELS : 1;
1646 outputParams.sampleFormat = paFloat32;
1647 outputParams.suggestedLatency = outputInfo->defaultLowOutputLatency;
1648 outputParams.hostApiSpecificStreamInfo = NULL;
1649 } else {
1650 log_warn("Output device info not found for device %d", outputParams.device);
1651 }
1652 }
1653
1654 // Store device rates for diagnostics (only access if device info was retrieved)
1655 ctx->input_device_rate = (has_input && inputInfo) ? inputInfo->defaultSampleRate : 0;
1656 ctx->output_device_rate = (has_output && outputInfo) ? outputInfo->defaultSampleRate : 0;
1657
1658 log_debug("Opening audio:");
1659 if (has_input) {
1660 log_info(" Input: %s (%.0f Hz)", inputInfo->name, inputInfo->defaultSampleRate);
1661 } else if (ctx->playback_only) {
1662 log_debug(" Input: (playback-only mode - no microphone)");
1663 } else {
1664 log_debug(" Input: (none)");
1665 }
1666 if (has_output) {
1667 log_info(" Output: %s (%.0f Hz)", outputInfo->name, outputInfo->defaultSampleRate);
1668 } else {
1669 log_debug(" Output: None (input-only mode - will send audio to server)");
1670 }
1671
1672 // Keep capture and playback synchronized in one 48 kHz duplex stream when
1673 // both devices share a native rate. PortAudio handles conversion to/from
1674 // that rate. Separate streams are needed only when the devices themselves
1675 // run at different rates or one direction is unavailable.
1676 bool rates_differ = has_input && has_output && (inputInfo->defaultSampleRate != outputInfo->defaultSampleRate);
1677 bool try_separate = rates_differ || !has_input || !has_output || GET_OPTION(microphone_channel) != 0;
1678 ctx->input_device_channels = has_input ? (unsigned)inputParams.channelCount : 0;
1679 ctx->output_device_channels = has_output ? (unsigned)outputParams.channelCount : 0;
1680 memset(&ctx->capture_resampler, 0, sizeof(ctx->capture_resampler));
1681 memset(&ctx->playback_resampler, 0, sizeof(ctx->playback_resampler));
1682 PaError err = paNoError;
1683
1684 if (!try_separate) {
1685 // Try full-duplex first (preferred - perfect AEC3 timing)
1686 LOG_IO("portaudio", { err = Pa_OpenStream(&ctx->duplex_stream, &inputParams, &outputParams, AUDIO_SAMPLE_RATE, AUDIO_FRAMES_PER_BUFFER, paClipOff, duplex_callback, ctx); });
1687
1688 if (err == paNoError) {
1691 LOG_IO("portaudio", { err = Pa_StartStream(ctx->duplex_stream); });
1692 if (err != paNoError) {
1693 LOG_IO("portaudio", { Pa_CloseStream(ctx->duplex_stream); });
1694 ctx->duplex_stream = NULL;
1695 log_warn("Full-duplex stream failed to start: %s", Pa_GetErrorText(err));
1696 try_separate = true;
1697 }
1698 } else {
1699 log_warn("Full-duplex stream failed to open: %s", Pa_GetErrorText(err));
1700 if (ctx->duplex_stream) {
1701 LOG_IO("portaudio", { Pa_CloseStream(ctx->duplex_stream); });
1702 ctx->duplex_stream = NULL;
1703 }
1704 try_separate = true;
1705 }
1706 }
1707
1708 if (try_separate) {
1709 // Use separate streams for non-48 kHz devices and single-direction modes.
1710 if (has_output && has_input) {
1711 log_info("Using separate native-rate input/output streams (%.0f Hz in, %.0f Hz out)", inputInfo->defaultSampleRate, outputInfo->defaultSampleRate);
1712 log_info(" Converting between device rates and the %.0f Hz audio pipeline", (double)AUDIO_SAMPLE_RATE);
1713 } else if (has_output) {
1714 log_debug("Using output-only mode (playback-only for mirror/media)");
1715 } else if (has_input) {
1716 log_info("Using input-only mode (no output device available)");
1717 }
1718
1719 // Store the internal sample rate (buffer rate)
1721
1722 // Create render buffer for AEC3 reference synchronization
1724 if (!ctx->render_buffer) {
1725 return SET_ERRNO(ERROR_MEMORY, "Failed to create render buffer");
1726 }
1727
1728 // Open output stream only if output device exists
1729 bool output_ok = false;
1730 double actual_output_rate = 0;
1731 if (has_output) {
1732 // Local media already supplies 48 kHz PCM. Prefer that rate to avoid
1733 // unnecessary application resampling; retain native-rate fallback.
1734 double native_rate = outputInfo->defaultSampleRate;
1735 if (native_rate <= 0.0) {
1736 native_rate = AUDIO_SAMPLE_RATE;
1737 }
1738 double preferred_rate = media_audio && ctx->monitor_local_media ? AUDIO_SAMPLE_RATE : native_rate;
1739 double fallback_rate = (preferred_rate == AUDIO_SAMPLE_RATE) ? native_rate : AUDIO_SAMPLE_RATE;
1740
1741 log_debug("Attempting output at native rate %.0f Hz (fallback %.0f Hz)", preferred_rate, fallback_rate);
1742
1743 // Always use output_callback for output streams (both output-only and duplex modes)
1744 // PortAudio will invoke the callback whenever it needs audio data
1745 // The callback reads PCM supplied to the shared playback buffer.
1746 PaStreamCallback *callback = output_callback;
1747
1748 // Try preferred rate first
1749 LOG_IO("portaudio", { err = audio_open_device(&ctx->output_stream, NULL, &outputParams, preferred_rate, callback, ctx); });
1750
1751 if (err == paNoError) {
1752 actual_output_rate = preferred_rate;
1753 output_ok = true;
1754 log_info("Output stream opened at %.0f Hz", preferred_rate);
1755 } else {
1756 log_warn("Failed to open output at %.0f Hz: %s, trying %.0f Hz", preferred_rate, Pa_GetErrorText(err), fallback_rate);
1757
1758 // If first Pa_OpenStream call left a partial stream, clean it up before retrying
1759 if (ctx->output_stream) {
1760 log_debug("Closing partially-opened output stream from failed preferred rate");
1761 LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
1762 ctx->output_stream = NULL;
1763 }
1764
1765 // Try the other endpoint rate if the native rate is unavailable.
1766 LOG_IO("portaudio", { err = audio_open_device(&ctx->output_stream, NULL, &outputParams, fallback_rate, callback, ctx); });
1767
1768 if (err == paNoError) {
1769 actual_output_rate = fallback_rate;
1770 output_ok = true;
1771 log_info("Output stream opened at fallback rate %.0f Hz", fallback_rate);
1772 } else {
1773 log_warn("Failed to open output stream at fallback rate %.0f Hz: %s", fallback_rate, Pa_GetErrorText(err));
1774 // Clean up if fallback also failed
1775 if (ctx->output_stream) {
1776 log_debug("Closing partially-opened output stream from failed native rate");
1777 LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
1778 ctx->output_stream = NULL;
1779 }
1780 }
1781 }
1782
1783 // Store actual output rate for resampling
1784 if (output_ok) {
1785 ctx->output_device_rate = actual_output_rate;
1786 ctx->output_resample_phase = 0.0;
1787 ctx->output_resample_previous = 0.0f;
1788 ctx->output_resample_has_previous = false;
1789 if (actual_output_rate != AUDIO_SAMPLE_RATE) {
1790 log_warn("⚠️ Output rate mismatch: %.0f Hz output vs %.0f Hz input - resampling will be used", actual_output_rate, (double)AUDIO_SAMPLE_RATE);
1791 }
1792 }
1793 }
1794
1795 // Open input stream only if we have input (skip for playback-only mode)
1796 bool input_ok = !has_input; // If no input, mark as OK (skip)
1797 if (has_input) {
1798 // Open at the device's native rate. The separate input callback converts
1799 // to AUDIO_SAMPLE_RATE before samples enter the shared processing path.
1800 double input_stream_rate = inputInfo->defaultSampleRate;
1801 if (input_stream_rate <= 0.0) {
1802 input_stream_rate = AUDIO_SAMPLE_RATE;
1803 }
1804 LOG_IO("portaudio", { err = audio_open_device(&ctx->input_stream, &inputParams, NULL, input_stream_rate, input_callback, ctx); });
1805 if (err != paNoError && input_stream_rate != AUDIO_SAMPLE_RATE) {
1806 input_stream_rate = AUDIO_SAMPLE_RATE;
1807 LOG_IO("portaudio", { err = audio_open_device(&ctx->input_stream, &inputParams, NULL, input_stream_rate, input_callback, ctx); });
1808 }
1809 input_ok = (err == paNoError);
1810 if (input_ok) {
1811 ctx->input_device_rate = input_stream_rate;
1812 ctx->input_resample_phase = 0.0;
1813 ctx->input_resample_previous = 0.0f;
1814 ctx->input_resample_has_previous = false;
1815 log_info("Input stream opened at native rate %.0f Hz", input_stream_rate);
1816 }
1817
1818 // If input failed, try device 0 as fallback (HDMI on BeaglePlay)
1819 if (!input_ok && GET_OPTION(microphone_index) < 0) {
1820 log_debug("Input failed - trying device 0 as fallback");
1821
1822 // Clean up partial stream from first attempt before retrying
1823 if (ctx->input_stream) {
1824 log_debug("Closing partially-opened input stream from failed primary device");
1825 LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
1826 ctx->input_stream = NULL;
1827 }
1828
1829 PaStreamParameters fallback_input_params = inputParams;
1830 fallback_input_params.device = 0;
1831 const PaDeviceInfo *device_0_info = Pa_GetDeviceInfo(0);
1832 if (device_0_info && device_0_info->maxInputChannels > 0) {
1833 LOG_IO("portaudio", { err = audio_open_device(&ctx->input_stream, &fallback_input_params, NULL, device_0_info->defaultSampleRate, input_callback, ctx); });
1834 if (err == paNoError) {
1835 ctx->input_device_rate = device_0_info->defaultSampleRate;
1836 log_info("Input stream opened on device 0 (fallback from default)");
1837 input_ok = true;
1838 } else {
1839 log_warn("Fallback also failed on device 0: %s", Pa_GetErrorText(err));
1840 // Clean up if fallback also failed
1841 if (ctx->input_stream) {
1842 log_debug("Closing partially-opened input stream from failed fallback device");
1843 LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
1844 ctx->input_stream = NULL;
1845 }
1846 }
1847 }
1848 }
1849
1850 if (!input_ok) {
1851 log_warn("Failed to open input stream: %s", Pa_GetErrorText(err));
1852 }
1853 }
1854
1855 // Check if we got at least one stream working
1856 if (!input_ok && !output_ok && !media_only) {
1857 // Neither stream works - fail completely
1859 ctx->render_buffer = NULL;
1860 return SET_ERRNO(ERROR_AUDIO, "Failed to open both input and output streams");
1861 }
1862
1863 // If output failed but input works, we can still send audio to server
1864 if (!output_ok && input_ok) {
1865 log_info("Output stream unavailable - continuing with input-only (can send audio to server)");
1866 ctx->output_stream = NULL;
1867 }
1868 // If input failed but output works, we can still receive audio from server
1869 if (!input_ok && output_ok) {
1870 log_info("Input stream unavailable - continuing with output-only (can receive audio from server)");
1871 ctx->input_stream = NULL;
1872 }
1873
1874 // Start output stream if it's open
1875 if (ctx->output_stream) {
1876 LOG_IO("portaudio", { err = Pa_StartStream(ctx->output_stream); });
1877 if (err != paNoError) {
1878 if (ctx->input_stream) {
1879 LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
1880 }
1881 LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
1882 ctx->input_stream = NULL;
1883 ctx->output_stream = NULL;
1885 ctx->render_buffer = NULL;
1886 return SET_ERRNO(ERROR_AUDIO, "Failed to start output stream: %s", Pa_GetErrorText(err));
1887 }
1888 }
1889
1890 // Start input stream if it's open
1891 if (ctx->input_stream) {
1892 LOG_IO("portaudio", { err = Pa_StartStream(ctx->input_stream); });
1893 if (err != paNoError) {
1894 if (ctx->output_stream) {
1895 LOG_IO("portaudio", { Pa_StopStream(ctx->output_stream); });
1896 }
1897 if (ctx->input_stream) {
1898 LOG_IO("portaudio", { Pa_CloseStream(ctx->input_stream); });
1899 }
1900 if (ctx->output_stream) {
1901 LOG_IO("portaudio", { Pa_CloseStream(ctx->output_stream); });
1902 }
1903 ctx->input_stream = NULL;
1904 ctx->output_stream = NULL;
1906 ctx->render_buffer = NULL;
1907 return SET_ERRNO(ERROR_AUDIO, "Failed to start input stream: %s", Pa_GetErrorText(err));
1908 }
1909 }
1910
1911 ctx->separate_streams = true;
1912 log_debug("Separate streams started successfully");
1913 } else {
1914 ctx->separate_streams = false;
1915 log_info("Full-duplex stream started (single callback, perfect AEC3 timing)");
1916 }
1917start_worker:
1918
1919 // Start worker thread for heavy audio processing
1920 if (!ctx->worker_running) {
1922 if (platform_thread_create(&ctx->worker_thread, "audio_worker", audio_worker_thread, ctx) != 0) {
1923 // Failed to create worker thread - stop streams and cleanup
1924 if (ctx->duplex_stream) {
1925 LOG_IO("portaudio", {
1926 Pa_StopStream(ctx->duplex_stream);
1927 Pa_CloseStream(ctx->duplex_stream);
1928 });
1929 ctx->duplex_stream = NULL;
1930 }
1931 if (ctx->input_stream) {
1932 LOG_IO("portaudio", {
1933 Pa_StopStream(ctx->input_stream);
1934 Pa_CloseStream(ctx->input_stream);
1935 });
1936 ctx->input_stream = NULL;
1937 }
1938 if (ctx->output_stream) {
1939 LOG_IO("portaudio", {
1940 Pa_StopStream(ctx->output_stream);
1941 Pa_CloseStream(ctx->output_stream);
1942 });
1943 ctx->output_stream = NULL;
1944 }
1946 ctx->render_buffer = NULL;
1947 return SET_ERRNO(ERROR_THREAD, "Failed to create worker thread");
1948 }
1949 ctx->worker_running = true;
1950 log_debug("Worker thread started successfully");
1951 }
1952
1953 // Lock to update final state flags atomically
1954 mutex_lock(&ctx->state_mutex);
1955 ctx->running = true;
1957 mutex_unlock(&ctx->state_mutex);
1958 return ASCIICHAT_OK;
1959}
1960
1962 ASCII_OTEL_SCOPE(AUDIO_STOP_DUPLEX);
1963 if (!ctx || !ctx->initialized) {
1964 return SET_ERRNO(ERROR_INVALID_STATE, "Audio context not initialized");
1965 }
1966
1967 atomic_store_bool(&ctx->shutting_down, true);
1968
1969 // Stop worker thread before stopping streams
1970 if (ctx->worker_running) {
1971 log_debug("Stopping worker thread");
1973 cond_signal(&ctx->audio_processing_wakeup); // Wake up worker if waiting
1974 thread_join(&ctx->worker_thread, NULL);
1975 ctx->worker_running = false;
1976 log_debug("Worker thread stopped successfully");
1977 }
1978
1979 if (ctx->playback_buffer) {
1981 }
1982
1983 mutex_lock(&ctx->state_mutex);
1984
1985 if (ctx->duplex_stream) {
1986 log_debug("Stopping duplex stream");
1987 PaError err;
1988 LOG_IO("portaudio", { err = Pa_StopStream(ctx->duplex_stream); });
1989 if (err != paNoError) {
1990 log_warn("Pa_StopStream failed: %s", Pa_GetErrorText(err));
1991 }
1992 log_debug("Closing duplex stream");
1993 LOG_IO("portaudio", { err = Pa_CloseStream(ctx->duplex_stream); });
1994 if (err != paNoError) {
1995 log_warn("Pa_CloseStream failed: %s", Pa_GetErrorText(err));
1996 } else {
1997 log_debug("Duplex stream closed successfully");
1998 }
1999 ctx->duplex_stream = NULL;
2000 }
2001
2002 // Stop separate streams if used
2003 if (ctx->input_stream) {
2004 log_debug("Stopping input stream");
2005 PaError err;
2006 LOG_IO("portaudio", { err = Pa_StopStream(ctx->input_stream); });
2007 if (err != paNoError) {
2008 log_warn("Pa_StopStream input failed: %s", Pa_GetErrorText(err));
2009 }
2010 log_debug("Closing input stream");
2011 LOG_IO("portaudio", { err = Pa_CloseStream(ctx->input_stream); });
2012 if (err != paNoError) {
2013 log_warn("Pa_CloseStream input failed: %s", Pa_GetErrorText(err));
2014 } else {
2015 log_debug("Input stream closed successfully");
2016 }
2017 ctx->input_stream = NULL;
2018 }
2019
2020 if (ctx->output_stream) {
2021 log_debug("Stopping output stream");
2022 PaError err;
2023 LOG_IO("portaudio", { err = Pa_StopStream(ctx->output_stream); });
2024 if (err != paNoError) {
2025 log_warn("Pa_StopStream output failed: %s", Pa_GetErrorText(err));
2026 }
2027 log_debug("Closing output stream");
2028 LOG_IO("portaudio", { err = Pa_CloseStream(ctx->output_stream); });
2029 if (err != paNoError) {
2030 log_warn("Pa_CloseStream output failed: %s", Pa_GetErrorText(err));
2031 } else {
2032 log_debug("Output stream closed successfully");
2033 }
2034 ctx->output_stream = NULL;
2035 }
2036
2037 // Cleanup render buffer
2038 if (ctx->render_buffer) {
2040 ctx->render_buffer = NULL;
2041 }
2042
2043 ctx->running = false;
2044 ctx->separate_streams = false;
2045 mutex_unlock(&ctx->state_mutex);
2046
2047 audio_metrics_flush();
2048 log_debug("Audio stopped");
2049 return ASCIICHAT_OK;
2050}
2051
2052asciichat_error_t audio_read_samples(audio_context_t *ctx, float *buffer, int num_samples) {
2053 if (!ctx || !ctx->initialized || !buffer || num_samples <= 0) {
2054 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, buffer=%p, num_samples=%d", ctx, buffer, num_samples);
2055 }
2056
2057 // audio_ring_buffer_read now returns number of samples read, not error code
2058 int samples_read = audio_ring_buffer_read(ctx->capture_buffer, buffer, num_samples);
2059 return (samples_read >= 0) ? ASCIICHAT_OK : ERROR_AUDIO;
2060}
2061
2062asciichat_error_t audio_write_samples(audio_context_t *ctx, const float *buffer, int num_samples) {
2063 if (!ctx || !ctx->initialized || !buffer || num_samples <= 0) {
2064 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, buffer=%p, num_samples=%d", ctx, buffer, num_samples);
2065 }
2066
2067 // Don't accept new audio data during shutdown - this prevents garbage/beeps
2068 if (atomic_load_bool(&ctx->shutting_down)) {
2069 return ASCIICHAT_OK; // Silently discard
2070 }
2071
2072 audio_recording_submit(AUDIO_RECORDING_REMOTE, buffer, num_samples, time_get_ns());
2074 asciichat_error_t result = audio_ring_buffer_write(ctx->playback_buffer, buffer, num_samples);
2075
2076 return result;
2077}
2078
2079// Internal helper to list audio devices (input or output)
2080static asciichat_error_t audio_list_devices_internal(audio_device_info_t **out_devices, unsigned int *out_count, bool list_inputs) {
2081 if (!out_devices || !out_count) {
2082 return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameters");
2083 }
2084
2085 *out_devices = NULL;
2086 *out_count = 0;
2087
2088 // Ensure PortAudio is initialized (centralized initialization)
2089 asciichat_error_t pa_result = audio_ensure_portaudio_initialized();
2090 if (pa_result != ASCIICHAT_OK) {
2091 return pa_result;
2092 }
2093
2094 int num_devices = Pa_GetDeviceCount();
2095 if (num_devices < 0) {
2096 return SET_ERRNO(ERROR_AUDIO, "Failed to get device count: %s", Pa_GetErrorText(num_devices));
2097 }
2098
2099 if (num_devices == 0) {
2100 return ASCIICHAT_OK; // No devices found
2101 }
2102
2103 // Get default device indices
2104 PaDeviceIndex default_input = Pa_GetDefaultInputDevice();
2105 PaDeviceIndex default_output = Pa_GetDefaultOutputDevice();
2106
2107 // First pass: count matching devices
2108 unsigned int device_count = 0;
2109 for (int i = 0; i < num_devices; i++) {
2110 const PaDeviceInfo *info = Pa_GetDeviceInfo(i);
2111 if (info) {
2112 bool matches = list_inputs ? (info->maxInputChannels > 0) : (info->maxOutputChannels > 0);
2113 if (matches) {
2114 device_count++;
2115 }
2116 }
2117 }
2118
2119 if (device_count == 0) {
2120 return ASCIICHAT_OK; // No matching devices
2121 }
2122
2123 // Allocate device array
2124 audio_device_info_t *devices = SAFE_CALLOC(device_count, sizeof(audio_device_info_t), audio_device_info_t *);
2125 if (!devices) {
2126 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate audio device info array");
2127 }
2128
2129 // Second pass: populate device info
2130 unsigned int idx = 0;
2131 for (int i = 0; i < num_devices && idx < device_count; i++) {
2132 const PaDeviceInfo *info = Pa_GetDeviceInfo(i);
2133 if (!info)
2134 continue;
2135
2136 bool match = list_inputs ? (info->maxInputChannels > 0) : (info->maxOutputChannels > 0);
2137 if (!match)
2138 continue;
2139
2140 devices[idx].index = i;
2141 if (info->name) {
2142 SAFE_STRNCPY(devices[idx].name, info->name, AUDIO_DEVICE_NAME_MAX);
2143 } else {
2144 SAFE_STRNCPY(devices[idx].name, "<Unknown>", AUDIO_DEVICE_NAME_MAX);
2145 }
2146 devices[idx].max_input_channels = info->maxInputChannels;
2147 devices[idx].max_output_channels = info->maxOutputChannels;
2148 devices[idx].default_sample_rate = info->defaultSampleRate;
2149 devices[idx].is_default_input = (i == default_input);
2150 devices[idx].is_default_output = (i == default_output);
2151 idx++;
2152 }
2153
2154 *out_devices = devices;
2155 *out_count = idx;
2156 return ASCIICHAT_OK;
2157}
2158
2159asciichat_error_t audio_list_input_devices(audio_device_info_t **out_devices, unsigned int *out_count) {
2160 return audio_list_devices_internal(out_devices, out_count, true);
2161}
2162
2163asciichat_error_t audio_list_output_devices(audio_device_info_t **out_devices, unsigned int *out_count) {
2164 return audio_list_devices_internal(out_devices, out_count, false);
2165}
2166
2168 SAFE_FREE(devices);
2169}
2170
2171asciichat_error_t audio_dequantize_samples(const uint8_t *samples_ptr, uint32_t total_samples, float *out_samples) {
2172 if (!samples_ptr || !out_samples || total_samples == 0) {
2173 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for audio dequantization");
2174 }
2175
2176 for (uint32_t i = 0; i < total_samples; i++) {
2177 uint32_t network_sample;
2178 // Use memcpy to safely handle potential misalignment from packet header
2179 memcpy(&network_sample, samples_ptr + i * sizeof(uint32_t), sizeof(uint32_t));
2180 int32_t scaled = (int32_t)NET_TO_HOST_U32(network_sample);
2181 out_samples[i] = (float)scaled / 2147483647.0f;
2182 }
2183
2184 return ASCIICHAT_OK;
2185}
2186
2188 // Delegate to platform abstraction layer
2189 asciichat_error_t result = thread_set_realtime_priority();
2190 if (result == ASCIICHAT_OK) {
2191 log_debug("✓ Audio thread real-time priority set successfully");
2192 }
2193 return result;
2194}
2195
2196/* ============================================================================
2197 * Audio Batch Packet Parsing
2198 * ============================================================================
2199 */
2200
2201asciichat_error_t audio_parse_batch_header(const void *data, size_t len, audio_batch_info_t *out_batch) {
2202 if (!data) {
2203 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch header data pointer is NULL");
2204 }
2205
2206 if (!out_batch) {
2207 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch info output pointer is NULL");
2208 }
2209
2210 if (len < sizeof(audio_batch_packet_t)) {
2211 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch header too small (len=%zu, expected=%zu)", len, sizeof(audio_batch_packet_t));
2212 }
2213
2214 const audio_batch_packet_t *batch_header = (const audio_batch_packet_t *)data;
2215
2216 // Unpack network byte order values to host byte order
2217 out_batch->batch_count = ntohl(batch_header->batch_count);
2218 out_batch->total_samples = ntohl(batch_header->total_samples);
2219 out_batch->sample_rate = ntohl(batch_header->sample_rate);
2220 out_batch->channels = ntohl(batch_header->channels);
2221
2222 return ASCIICHAT_OK;
2223}
2224
2226 if (!batch) {
2227 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch info pointer is NULL");
2228 }
2229
2230 // Validate batch_count
2231 if (batch->batch_count == 0) {
2232 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch count cannot be zero");
2233 }
2234
2235 // Check for reasonable max (256 frames per batch is very generous)
2236 if (batch->batch_count > 256) {
2237 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch count too large (batch_count=%u, max=256)", batch->batch_count);
2238 }
2239
2240 // Validate channels (1=mono, 2=stereo, max 8 for multi-channel)
2241 if (batch->channels == 0 || batch->channels > 8) {
2242 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid channel count (channels=%u, valid=1-8)", batch->channels);
2243 }
2244
2245 // Validate sample rate
2247 return SET_ERRNO(ERROR_INVALID_PARAM, "Unsupported sample rate (sample_rate=%u)", batch->sample_rate);
2248 }
2249
2250 // Check for reasonable sample counts
2251 if (batch->total_samples == 0) {
2252 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch has zero samples");
2253 }
2254
2255 // Each batch typically has samples_per_frame worth of samples
2256 // For 48kHz at 20ms per frame: 48000 * 0.02 = 960 samples per frame
2257 // With max 256 frames, that's up to ~245k samples per batch
2258 if (batch->total_samples > 1000000) {
2259 return SET_ERRNO(ERROR_INVALID_PARAM, "Audio batch sample count suspiciously large (total_samples=%u)", batch->total_samples);
2260 }
2261
2262 return ASCIICHAT_OK;
2263}
2264
2266 // List of commonly supported audio sample rates
2267 static const uint32_t supported_rates[] = {
2268 8000, // Telephone quality
2269 16000, // Wideband telephony
2270 24000, // High quality speech
2271 32000, // Good for video
2272 44100, // CD quality (less common in VoIP)
2273 48000, // Standard professional
2274 96000, // High-end professional
2275 192000, // Ultra-high-end mastering
2276 };
2277
2278 const size_t rate_count = sizeof(supported_rates) / sizeof(supported_rates[0]);
2279 for (size_t i = 0; i < rate_count; i++) {
2280 if (sample_rate == supported_rates[i]) {
2281 return true;
2282 }
2283 }
2284
2285 return false;
2286}
2287
2289 switch (source) {
2291 return !has_media_audio;
2292
2294 return true;
2295
2297 return false;
2298
2300 return true;
2301
2303 return false;
2304
2305 default:
2306 return !has_media_audio;
2307 }
2308}
void errno_scope_end(asciichat_errno_scope_t scope, asciichat_errno_outcome_t outcome)
bool errno_notifications_suppress(bool suppress)
asciichat_errno_scope_t errno_scope_begin(void)
Synchronized per-thread pending error stacks and value snapshots. SET_ERRNO pushes,...
#define SET_ERRNO(code,...)
#define ASSERT_NO_ERRNO_SINCE(scope)
@ ASCIICHAT_ERRNO_HANDLED
uint64_t atomic_fetch_add_u64(atomic_t *a, uint64_t delta)
Atomically add to a uint64_t and return the previous value.
void atomic_store_bool(atomic_t *a, bool value)
Atomically store a boolean value.
bool atomic_load_bool(atomic_t *a)
Atomic pointer wrapper.
void atomic_store_u64(atomic_t *a, uint64_t value)
Atomically store a uint64_t value.
uint64_t atomic_load_u64(atomic_t *a)
Atomically load a uint64_t value.
bool atomic_exchange_bool(atomic_t *a, bool new_value)
Atomically exchange a boolean and return the old value.
asciichat_error_t audio_route_capture(const float *input, size_t frames, unsigned channels, int first_channel, unsigned selected_channels, float *output)
Definition audio/format.c:4
asciichat_error_t audio_convert_channels(const float *input, size_t frames, unsigned input_channels, float *output, unsigned output_channels)
size_t audio_resample_stereo(audio_resampler_t *state, const float *input, size_t frames, double input_rate, float *output, size_t capacity, double output_rate)
#define OPUS_FRAME_SAMPLES
#define AUDIO_BUFFER_SIZE
#define AUDIO_DEVICE_MAX_CHANNELS
#define AUDIO_SAMPLE_RATE
Definition audio/limits.h:8
#define AUDIO_FRAMES_PER_BUFFER
#define AUDIO_CHANNELS
Definition audio/limits.h:9
void audio_test_pattern(float *output, size_t count, uint64_t position, uint32_t sample_rate)
void * buffer_alloc(buffer_domain_t *domain, size_t size)
Definition buffer.c:272
#define buffer_release(data)
Definition buffer.h:99
void client_audio_pipeline_process_duplex(client_audio_pipeline_t *pipeline, const float *render_samples, int render_count, const float *capture_samples, int capture_count, float *processed_output)
Process AEC3 inline in full-duplex callback.
Unified client-side audio processing pipeline.
Platform initialization and static synchronization helpers.
struct audio_ring_buffer audio_ring_buffer_t
Named object registry for debugging — log identifiable resource names.
🔄 Network byte order conversion helpers
#define NET_TO_HOST_U32(val)
Definition endian.h:85
audio_visualization_source_t source
Definition fft.c:25
bool audio_should_enable_microphone(audio_capture_source_t source, bool has_media_audio)
Determine if microphone should be enabled based on audio source setting and media state.
size_t audio_ring_buffer_read(audio_ring_buffer_t *rb, float *data, size_t samples)
Read audio samples from ring buffer.
void audio_free_device_list(audio_device_info_t *devices)
Free device list allocated by audio_list_input_devices/audio_list_output_devices.
asciichat_error_t audio_ring_buffer_write(audio_ring_buffer_t *rb, const float *data, int samples)
Write audio samples to ring buffer.
void audio_ring_buffer_destroy(audio_ring_buffer_t *rb)
Destroy an audio ring buffer.
asciichat_error_t audio_init(audio_context_t *ctx)
Initialize audio context and PortAudio.
asciichat_error_t audio_set_realtime_priority(void)
Request real-time priority for current thread.
audio_ring_buffer_t * audio_ring_buffer_create(void)
Create a new audio ring buffer (for playback with jitter buffering).
bool audio_is_supported_sample_rate(uint32_t sample_rate)
Check if a sample rate is a standard/supported rate.
size_t audio_ring_buffer_available_read(audio_ring_buffer_t *rb)
Get number of samples available for reading.
asciichat_error_t audio_start_duplex(audio_context_t *ctx)
Start full-duplex audio (simultaneous capture and playback).
void audio_ring_buffer_register_atomics(audio_ring_buffer_t *rb, const char *context_name)
Register audio ring buffer atomic fields for debug tracking.
asciichat_error_t audio_parse_batch_header(const void *data, size_t len, audio_batch_info_t *out_batch)
Parse an audio batch packet header from raw packet data.
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_ring_buffer_unregister_atomics(audio_ring_buffer_t *rb)
Unregister audio ring buffer atomic fields.
asciichat_error_t audio_write_samples(audio_context_t *ctx, const float *buffer, int num_samples)
Write audio samples to playback buffer.
void audio_terminate_portaudio_final(void)
Terminate PortAudio and free all device resources.
void audio_flush_playback_buffers(audio_context_t *ctx)
Flush all audio buffers to synchronize with seek operations.
void audio_set_pipeline(audio_context_t *ctx, void *pipeline)
Set audio pipeline for echo cancellation.
audio_ring_buffer_t * audio_ring_buffer_create_for_capture(void)
Create a new audio ring buffer for capture (without jitter buffering).
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).
asciichat_error_t audio_validate_batch_params(const audio_batch_info_t *batch)
Validate audio batch parameters for sanity.
asciichat_error_t audio_list_input_devices(audio_device_info_t **out_devices, unsigned int *out_count)
List available audio input devices (microphones).
asciichat_error_t audio_dequantize_samples(const uint8_t *samples_ptr, uint32_t total_samples, float *out_samples)
Dequantize network audio samples from int32 to float.
asciichat_error_t audio_list_output_devices(audio_device_info_t **out_devices, unsigned int *out_count)
List available audio output devices (speakers).
void audio_ring_buffer_clear(audio_ring_buffer_t *rb)
Clear all audio samples from ring buffer.
asciichat_error_t audio_read_samples(audio_context_t *ctx, float *buffer, int num_samples)
Read captured audio samples from capture buffer.
void resample_linear(const float *src, size_t src_samples, float *dst, size_t dst_samples, double src_rate, double dst_rate)
Resample audio using linear interpolation.
size_t audio_ring_buffer_available_write(audio_ring_buffer_t *rb)
Get number of sample slots available for writing.
unsigned int uint32_t
#define SAFE_FREE(ptr)
#define SAFE_MEMSET(dest, dest_size, ch, count)
#define SAFE_MALLOC(size, cast)
#define SAFE_CALLOC(count, size, cast)
unsigned long long uint64_t
unsigned char uint8_t
#define SAFE_MEMCPY(dest, dest_size, src, count)
#define NAMED_REGISTER_ATOMIC(a, name, parent_ptr)
Register an atomic_t with automatic format specifier.
#define NAMED_REGISTER_COND(cond, name, parent_ptr)
Register a condition variable with automatic format specifier.
#define NAMED_REGISTER(ptr, name, type, fmt, parent_ptr)
Register any pointer with base name, type, format spec, and location (auto-suffix).
#define NAMED_REGISTER_AUDIO_RINGBUF(buf, name, parent_ptr)
Register an audio ring buffer with automatic format specifier.
#define NAMED_UNREGISTER(ptr)
Unregister a pointer.
#define NAMED_REGISTER_MUTEX(mutex, name, parent_ptr)
Register a mutex with automatic format specifier.
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
@ ERROR_INVALID_STATE
@ ERROR_AUDIO
Definition error_codes.h:66
@ ERROR_MEMORY
Definition error_codes.h:55
@ ASCIICHAT_OK
Definition error_codes.h:50
@ ERROR_INVALID_PARAM
@ ERROR_BUFFER
@ ERROR_THREAD
#define LOG_RATE_FAST
Log rate limit: 1 second (1,000,000 microseconds).
Definition log_rates.h:30
#define log_warn(...)
Log a WARN message.
Definition log/log.h:615
#define log_info(...)
Log an INFO message.
Definition log/log.h:602
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
size_t media_source_read_audio(media_source_t *source, float *buffer, size_t num_samples)
Read audio samples from media source.
Definition source.c:697
bool media_source_has_audio(media_source_t *source)
Check if media source has audio stream.
Definition source.c:774
int time_pretty(uint64_t nanoseconds, int decimals, char *buffer, size_t buffer_size)
Format nanoseconds as a compact duration with configurable sub-minute precision.
Definition time.c:368
#define TIME_DURATION_BUFFER_SIZE
Definition time.h:40
#define NS_PER_MS_INT
Definition time.h:172
uint64_t time_elapsed_ns(uint64_t start_ns, uint64_t end_ns)
Calculate elapsed time with wraparound safety.
Definition time.c:117
#define US_PER_MS_INT
Definition time.h:176
#define US_PER_SEC_INT
Definition time.h:177
audio_capture_source_t
Definition options.h:291
#define GET_OPTION(field)
Definition options.h:1333
@ AUDIO_CAPTURE_SOURCE_BOTH
Definition options.h:291
@ AUDIO_CAPTURE_SOURCE_REMOTE
Definition options.h:291
@ AUDIO_CAPTURE_SOURCE_MEDIA
Definition options.h:291
@ AUDIO_CAPTURE_SOURCE_MIC
Definition options.h:291
@ AUDIO_CAPTURE_SOURCE_AUTO
Definition options.h:291
#define AUDIO_JITTER_HIGH_WATER_MARK
High water mark - drop OLD samples when buffer exceeds this.
Definition ringbuffer.h:177
#define AUDIO_RING_BUFFER_SIZE
Audio ring buffer size in samples (192000 samples = 4 seconds @ 48kHz).
Definition ringbuffer.h:136
#define AUDIO_JITTER_TARGET_LEVEL
Target buffer level after dropping old samples.
Definition ringbuffer.h:187
#define AUDIO_CROSSFADE_SAMPLES
Crossfade duration in samples for smooth underrun recovery.
Definition ringbuffer.h:194
🔊 Audio Capture and Playback Interface for ascii-chat
⚙️ Common definitions, error codes, macros, and types shared throughout the application
Capture stdout/stderr and redirect to logging system.
#define LOG_IO(prefix, block)
Definition io.h:104
void audio_ring_buffer_discard_pending(audio_ring_buffer_t *rb)
void audio_ring_buffer_set_jitter_target(audio_ring_buffer_t *rb, uint32_t samples)
#define WORKER_TIMEOUT_MS
audio_ring_buffer_t * audio_ring_buffer_create_format(unsigned channels, bool capture)
#define AUDIO_RT_METRIC_SLOTS
void stats_counter_add(stats_scope_t *scope, stats_counter_id_t id, uint64_t amount)
📝 Logging API with multiple log levels and terminal output control
#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
🔢 Mathematical Utility Functions
⚙️ Unified options parsing system for ascii-chat with builder pattern and lock-free access
bool ascii_otel_enabled(void)
Definition otel.c:153
void ascii_otel_metric(ascii_otel_metric_t metric, double value)
Definition otel.c:159
#define ASCII_OTEL_SCOPE(id)
Definition otel.h:77
ascii_otel_metric_t
Definition otel.h:12
static bool size_t index
Definition queries.h:8
void audio_recording_submit(audio_recording_source_t source, const float *samples, size_t count, uint64_t start_ns)
Definition recording.c:79
@ AUDIO_RECORDING_MIC
Definition recording.h:13
@ AUDIO_RECORDING_REMOTE
Definition recording.h:13
@ AUDIO_RECORDING_MEDIA
Definition recording.h:13
stats_scope_t * stats_runtime_scope(void)
Definition runtime.c:78
🎬 Unified media source abstraction for webcam, files, and stdin
🔤 String Manipulation and Shell Escaping Utilities
When code needs to work with asciichat errno snapshot, it keeps total, copied here instead of scatter...
Parsed audio batch packet header information.
uint32_t batch_count
Number of audio frames in this batch.
uint32_t channels
Number of channels (1=mono, 2=stereo).
uint32_t sample_rate
Sample rate in Hz (e.g., 48000).
uint32_t total_samples
Total number of samples across all frames.
The metadata prefix for a batch of encoded audio samples. batch_count, total_samples,...
Definition packet.h:979
uint32_t channels
Number of audio channels (1=mono, 2=stereo).
Definition packet.h:987
uint32_t batch_count
Number of audio chunks in this batch (usually AUDIO_BATCH_COUNT = 32).
Definition packet.h:981
uint32_t sample_rate
Sample rate in Hz (e.g., 44100, 48000).
Definition packet.h:985
uint32_t total_samples
Total audio samples across all chunks (typically 8192).
Definition packet.h:983
When code needs to work with audio device info, it keeps index, max_input_channels,...
bool initialized
True if context has been initialized.
platform_thread_t worker_thread
Worker thread for audio processing.
audio_ring_buffer_t * raw_render_rb
Callback → Worker: Raw speaker samples (AEC3 reference).
double input_device_rate
Native sample rate of input device.
audio_ring_buffer_t * playback_buffer
OLD: Network → Worker (will become network_playback_rb).
float * worker_render_batch
Pre-allocated buffer for batch render processing.
float input_resample_previous
Last input sample used at a block boundary.
PaStream * input_stream
Separate input stream (when full-duplex unavailable).
bool worker_running
True if worker thread is running.
atomic_t shutting_down
True when shutdown started - callback outputs silence.
bool monitor_local_media
Play local file audio in solo sessions.
atomic_t worker_should_stop
Signal worker thread to exit.
bool input_resample_has_previous
Whether a prior input block has been processed.
void * capture_media_source
Borrowed local media audio; configure before starting duplex.
bool separate_streams
True if using separate input/output streams.
double sample_rate
Actual sample rate of streams (48kHz).
audio_ring_buffer_t * capture_buffer
OLD: Worker → Network (will become processed_capture_rb).
void * audio_pipeline
Client audio pipeline for AEC3 echo cancellation (opaque pointer).
bool running
True if duplex stream is active.
float output_resample_previous
Last source sample used at an output boundary.
audio_ring_buffer_t * render_buffer
Ring buffer for render reference (separate streams mode).
audio_ring_buffer_t * raw_capture_rb
Callback → Worker: Raw mic samples (no processing).
mutex_t audio_processing_wait_guard
Coordinates device-worker sleep with shutdown.
double output_device_rate
Native sample rate of output device.
float * worker_playback_batch
Pre-allocated buffer for batch playback processing.
double output_resample_phase
48 kHz source position carried between output callbacks
mutex_t state_mutex
Mutex protecting context state.
float * worker_capture_batch
Pre-allocated buffer for batch capture processing.
bool playback_only
True for playback-only mode (mirror), skip microphone capture.
audio_ring_buffer_t * processed_playback_rb
Worker → Callback: Ready for speakers.
PaStream * duplex_stream
PortAudio full-duplex stream (simultaneous input+output).
double input_resample_phase
Source position carried between native-rate input blocks.
PaStream * output_stream
Separate output stream (when full-duplex unavailable).
uint64_t test_audio_playback_position
Output callback's synthesized monitor sample clock.
cond_t audio_processing_wakeup
Capture/AEC work, monitor refill, or shutdown notification.
bool output_resample_has_previous
Whether a prior output block has been processed.
Audio device information structure.
int index
PortAudio device index.
float previous[AUDIO_CHANNELS]
atomic_t discard_pending
Consumer should discard queued samples before its next read.
Definition ringbuffer.h:222
atomic_t discard_to_index
Producer position at which the stale queue ends.
Definition ringbuffer.h:224
float last_sample
Last sample value for smooth fade-out during underrun - NOT atomic (only written by reader).
Definition ringbuffer.h:232
atomic_t crossfade_fade_in
True if we're fading in (recovering from underrun).
Definition ringbuffer.h:230
atomic_t jitter_buffer_filled
True after initial jitter buffer fill.
Definition ringbuffer.h:226
double jitter_drift_phase
Consumer-owned fractional clock correction.
Definition ringbuffer.h:241
uint64_t jitter_stable_samples
Definition ringbuffer.h:240
unsigned channels
Frame width, configured before the first read/write.
Definition ringbuffer.h:214
atomic_t read_index
Read index (consumer position) - LOCK-FREE with atomic operations.
Definition ringbuffer.h:220
mutex_t mutex
Mutex for SLOW PATH only (clear/destroy operations, not regular read/write).
Definition ringbuffer.h:243
uint32_t jitter_initial_samples
Definition ringbuffer.h:239
bool jitter_buffer_enabled
Whether jitter buffering is enabled (false for capture, true for playback).
Definition ringbuffer.h:236
uint32_t jitter_target_samples
Definition ringbuffer.h:238
atomic_t underrun_count
Count of underrun events for diagnostics.
Definition ringbuffer.h:234
atomic_t write_index
Write index (producer position) - LOCK-FREE with atomic operations.
Definition ringbuffer.h:218
atomic_t crossfade_samples_remaining
Samples remaining in crossfade (0 = no crossfade active).
Definition ringbuffer.h:228
float data[192000]
Audio sample data buffer.
Definition ringbuffer.h:216
_Atomic unsigned state
ascii_otel_metric_t metric
const char * platform_getenv(const char *name)
Definition system.c:45
⏱️ High-precision timing utilities using sokol_time.h and uthash
void audio_visualization_submit_stereo(audio_visualization_source_t source, const float *samples, size_t count)
@ AUDIO_VISUALIZATION_SOURCE_MEDIA
@ AUDIO_VISUALIZATION_SOURCE_MIC
@ AUDIO_VISUALIZATION_SOURCE_REMOTE