fix(audio): avoid capture packet drops caused by queue contention - #16146

Related

• #16095 — Audio stream continuity, which introduced the capture handoff this changes.
• Queue contention discussion in #16095. This addresses the third point, whose queue redesign was deferred to a separate PR.

Summary

The capture callback currently drops its new PCM packet if the encoder worker holds the shared queue mutex, even when free buffers are available. The single try_lock() keeps the callback from waiting, but can discard audio without a backlog.

Replace that shared queue lock with atomic buffer ownership transfers. A worker paused while consuming or recycling one buffer no longer prevents the callback from using the remaining capacity. Actual buffer exhaustion still uses the existing drop-oldest policy.

Fix details

• Store the free-buffer set and ordered ready-buffer indices together in one AtomicU64. Claiming an index transfers exclusive ownership before either thread accesses its PCM.
• Keep each buffer behind a separate mutex for safe Rust access. Release that mutex before publishing the index as ready or free, so the callback cannot claim a buffer whose lock the worker still holds.
• Retain the ten preallocated buffers, packet sequence numbers, gap detection, and oldest-ready-packet discard behavior. If every buffer is checked out and none is ready, reject the new packet as before.
• Keep the existing contention_dropped log field at zero for comparison with older builds. Genuine capacity drops remain in dropped.
• Extend the existing queue tests for worker suspension before and after publication, saturation, sequence wrap, allocation behavior, and complete buffer recovery. No new dependencies or unsafe code.

Testing

Use a Windows or macOS machine as the audio-sending host. Linux and Android do not use this capture handoff. Compare the fix with master at c4221469d, using the same audio device, source, receiving machine, and network.

• Connect with audio enabled and play continuous music or a test tone on the sending host. Listen through headphones on the receiving machine for several minutes. Check for new gaps, clicks, or accumulating delay.
• Repeat while running a CPU-heavy workload, such as a build or video encode, on the sending host. Remove the load and check that audio continues normally. Repeat with both builds; contention on the old build is scheduling-dependent and may not occur in every run.
• Inspect the sending host's logs. Audio capture PCM handoff loss reports dropped, contention_dropped, oversized, and recycle_failures. The fixed build must not report contention drops. Real saturation can still increase dropped; oversized and recycle_failures should stay zero. Loss messages are only emitted when there is something to report.
• With debug logging enabled, also check Audio capture PCM handoff stats. observed_max_queued_packets must not exceed the existing capacity of ten. This is queued PCM only, not a measurement of end-to-end latency. A zero contention counter alone does not prove that no audio was lost.
• Disconnect and reconnect several times, then repeat a short playback check. Confirm that capture starts and stops normally.

For a deterministic developer check, suspend only the audio-encoder thread after it claims a buffer or just before it publishes a recycled buffer. Keep the capture thread running and leave other buffers free. Submission should continue using that capacity before the worker resumes. If the pause lasts long enough to exhaust the pool, older queued packets may be dropped. Resume the worker and verify that delivery continues. Suspending the whole process does not exercise this case.

Validation and scope

Native macOS audio tests passed on this commit with both backends: 36 with the default backend and 34 with use_samplerate. The strengthened paused-worker tests fail with the old handoff and pass with this implementation.

The changes are confined to capture queue construction, buffer transfer/recycling, and loss accounting. Playback, resampling, encoding, and stream lifecycle code are unchanged. The packed representation supports up to twelve buffers; production still uses ten.

Windows execution and the hardware checks above are still pending. A short software comparison under CPU load had no drops with either implementation, so it does not establish the frequency or audible impact of the old contention issue. This fix does not claim to eliminate all audio interruptions.

Summary by CodeRabbit

• Improvements
  • Improved audio capture buffering to reduce processing contention and provide more consistent handoff between recording and playback.
  • When the buffer reaches capacity, the oldest queued audio is discarded so newer audio remains available.
  • Improved buffer recycling and capacity validation for more reliable operation across different queue sizes.