Fix microphone capture: device-true source format + fragment-aware clip reading

[MaxHeimbrock]

Consolidated, cleaned-up version of the microphone capture fix (supersedes #303, #304, #305, #306 — see History).

Problem

Publishing the microphone with a Bluetooth HFP headset on macOS produced sample_rate and num_channels don't match errors from the native source, and — beyond the error — persistently choppy or garbled audio on receivers. The same headset works fine from Android.

Root causes (both proven empirically)

1. Hardcoded native source format. The native (Rust) audio source was created at a fixed 48000 Hz / 2ch, while captured frames arrive at whatever Unity actually delivers. The Rust source rejects mismatched frames; it does not resample.

2. Fragmented mic clip buffer on macOS + BT-HFP. A raw WAV dump of the clip's ring buffer (analyzed offline) showed: FMOD writes each real 20 ms packet of clip.frequency audio, then advances Microphone.GetPosition as if it had written k ≈ 3.2× as much, zero-filling the gap. The buffer holds valid fragments of exactly 320 samples at a stride of exactly 1024 (320/1024 = 1/k), and the fragments join continuously — the stream is intact, just scattered with zero padding. Hence:

• any playback-based capture (AudioSource + OnAudioFilterRead) plays 31% voice + 69% padding → chop
• reading at GetPosition's pace replays fragments + padding too fast over a live buffer → garbled noise

Change

• RtcAudioSource: two constructors — device-mode (format resolved from Unity's output configuration) and explicit-format (type, sampleRate, channels) for sources that know their exact rate. Frames that still mismatch the configured format are dropped with a throttled warning instead of erroring natively.
• MicrophoneSource: reads the clip ring buffer directly (no AudioSource, no OnAudioFilterRead — which also decouples capture from the output device's clock for all devices). A ~0.3 s pre-roll measures k = counterRate / clip.frequency and the counter's smallest discrete jump (the stride J):
  • k ≈ 1 (healthy devices): plain contiguous read at the counter's pace.
  • k > 1.05 (fragmented state): read only the first J/k samples of each stride — exactly the valid fragments.
  • Downmix → mono, streaming-resample clip.frequency → fixed 48 kHz native source (preserves the publish-before-start contract). Stall backlog beyond 200 ms is dropped stride-aligned so the native queue can't overrun.
• BasicAudioSource uses device-mode (drops its unused channels parameter — minor source-breaking change); the test SineWaveAudioSource declares its exact format; the Meet sample drops a redundant Microphone.Start.

Log signature in the bad state:

MicrophoneSource: fragmented clip detected (k=3.20); reading 320 of every 1024 samples at 16000Hz

Healthy devices log contiguous capture (k=1.00).

Verification

• End-to-end, on hardware: macOS publisher with the Bluetooth headset mic → Android receiver now sounds clean, correct-pitch, and continuous (previously chopped/garbled). Reconstruction was first validated offline by dumping the buffer, concatenating fragments, and listening.
• Runtime, PlayModeTests, and Meet Assembly-CSharp compile clean.
• Recommended before merge: a PlayMode E2E run against a dev server and a quick healthy-mic check (expect k≈1.0, contiguous path).

Notes

• Microphone.GetPosition's counter is packet-granular and can be rate-inflated on macOS; this PR never trusts it directly — only its measured average and jump size. The dump utility used for the diagnosis is PR Add AudioClipDump debugging utility (dump audio buffers to WAV) #307.
• This is arguably a Unity bug worth reporting upstream (clip labeled 16 kHz, position counter at ~51 k/s, zero-padded fragment writes).
• Platform Audio (native ADM capture) remains the preferred path where applications can use it; the k measurement doubles as a detector for surfacing degraded-mic states in the future.

History

The investigation went through several falsified designs, preserved on their branches: #303 (recreate + republish on mismatch), #304 (device-config init + output-rate mic open), #305 (naive direct polling — three experiments), #306 (pitch servos, then the working fragment-aware capture that this PR consolidates). The buffer dump was the decisive step.

🤖 Generated with Claude Code

[MaxHeimbrock]

Added test coverage for the capture logic (35031cc): the fragment reconstruction and resampling logic is now extracted into UnityEngine-free internal classes (MicClipReader, StreamingResampler) with EditMode tests — including a replay of the exact fragmented structure dumped from the Sony MDR-1000X (320 valid / 1024 stride, k=3.2) asserting lossless, strictly-sequential reconstruction across multiple ring laps, plus contiguous-mode, backlog-drop, and resampler continuity tests. All scenarios were additionally executed in a standalone harness to verify behavior, not just compilation. CaptureLoop is now a thin Unity shell; behavior unchanged.