chore: restore product scaffold to rollback baseline

crates/chanora_audio/src/ios_voice_unit.rs

@@ -25,7 +25,7 @@
 //! stream-format requests on bus 0 (output) and bus 1 (input).
 //!
 //! This file replaces the cpal capture + playback streams on iOS and macOS.
-//! Linux uses native PipeWire/PulseAudio voice I/O;
+//! Linux uses SDL2 for output (see `sdl_output.rs`) and cpal for capture;
 //! Windows uses cpal's WASAPI backend.
 //!
 //! ## What VPIO gives us
@@ -53,7 +53,7 @@
 //! thread that owns the unit. We open the unit on the same thread
 //! that calls `Self::start` (the tokio worker that runs
 //! `chanora_core::ChanoraSession::start_audio`, the same pattern
-//! the desktop backends use) and never move it. The outer `AudioEngine`
+//! cpal + SDL use) and never move it. The outer `AudioEngine`
 //! already carries an `unsafe impl Send` to satisfy the same
 //! constraint for cpal's `!Send` Stream type; that impl covers
 //! VPIO too.
@@ -589,16 +589,16 @@ impl IosVoiceUnit {
     /// captures samples, render callback fires when the hardware
     /// needs samples to play.
     ///
-    /// Parameters mirror the capture + playback inputs the desktop
-    /// backends accept so engine.rs can swap backends with
+    /// Parameters mirror the capture + playback inputs the cpal
+    /// and SDL backends accept so engine.rs can swap backends with
     /// a `cfg`.
     ///
     /// * `handler` — shared AudioHandler the inbound forwarder
     ///   feeds Opus packets into. The output render callback pulls
     ///   decoded f32 frames from it (48 kHz stereo) and downmixes
     ///   to the i16 mono buffer VPIO expects.
-    /// * `output_gain` / `output_muted` — same atomics the desktop
-    ///   output paths read on every callback so the master
+    /// * `output_gain` / `output_muted` — same atomics the cpal
+    ///   and SDL output paths read on every callback so the master
     ///   volume + local-mute UI works identically across backends.
     /// * `voice_out_tx` — channel the capture pipeline sends
     ///   encoded `OutPacket`s on.
@@ -734,7 +734,7 @@ impl IosVoiceUnit {
         //   1. Lock the AudioHandler, ask it to fill a scratch
         //      f32 stereo buffer (length = 2 * num_frames). The
         //      handler runs Opus decode + per-client jitter
-        //      buffer + mix. Same primitive desktop output
+        //      buffer + mix. Same primitive cpal + SDL output
         //      paths use; this is the platform-neutral playback
         //      contract from `tsclientlib::audio::AudioHandler`.
         //   2. Downmix to i16 mono with master gain. VPIO expects
@@ -748,10 +748,12 @@ impl IosVoiceUnit {
         //      AudioHandler in step 1 so its jitter buffer
         //      doesn't grow unbounded while muted. This is the
         //      contract every other backend follows (matches
-        //      Linux PipeWire/PulseAudio and the cpal output stream).
+        //      SdlOutput::callback and the cpal output stream).
         //
         // Build the playback pipeline (direct fill_buffer in
-        // render callback; matches the desktop voice backends).
+        // render callback; matches tsclientlib's reference SDL
+        // example at
+        // tsclientlib/examples/audio_utils/ts_to_audio.rs).
         //
         // The earlier ring-buffer attempt (rc.8+73..+74) decoupled
         // AudioHandler from the render callback via a 50 Hz
@@ -764,12 +766,14 @@ impl IosVoiceUnit {
         // consumer pull being larger, the ring averaged out empty
         // — fill_buffer was returning silence 65-84% of ticks
         // because we drained it too aggressively before packets
-        // arrived. Direct desktop callbacks follow the same pattern.
+        // arrived. Linux/SDL's same pattern works fine because
+        // SDL calls fill_buffer at exactly the device callback
+        // rate.
         //
         // Revert to direct call: render callback locks
         // AudioHandler, asks for `num_frames` stereo frames, and
         // immediately downmixes to i16 mono into the output
-        // buffer. Same as desktop output, just stereo-f32 -> mono-i16
+        // buffer. Same as Linux/SDL, just stereo-f32 -> mono-i16
         // converted at the boundary.
         let mut scratch_stereo: Vec<f32> = Vec::with_capacity(2048);
         let handler_for_render = params.handler.clone();