feat(audio): end-to-end 5.1/7.1 surround across the native path + all clients

Adds negotiated 5.1/7.1 surround to the punktfunk/1 protocol and every client
(previously stereo-only):

- core: new shared `audio` layout table (LAYOUT_51/71 + identity multistream
  mapping, canonical wire order FL FR FC LFE RL RR SL SR); Hello/Welcome
  `audio_channels` negotiation via the trailing-byte back-compat pattern (old
  peers fall back to stereo); C-ABI `punktfunk_connect_ex6`,
  `punktfunk_connection_audio_channels`, and in-core multistream decode
  `punktfunk_connection_next_audio_pcm` for embedders without a multistream
  Opus decoder. Real-libopus channel-identity round-trip test.
- host: native audio thread captures + Opus-(multi)stream-encodes at the
  negotiated count (with a cross-session cached-capturer channel-mismatch fix);
  GameStream surround unified onto the safe `opus::MSEncoder`, dropping
  `audiopus_sys` (~4 unsafe blocks) and un-gating Windows GameStream surround;
  WASAPI loopback capture relaxed to 2/6/8 with the correct dwChannelMask.
- clients: Linux (PipeWire), Windows (WASAPI), Android (AAudio) decode via
  `opus::MSDecoder` + render multichannel; Apple decodes in-core to PCM →
  AVAudioEngine with an explicit wire-order channel layout; each gains a
  Stereo/5.1/7.1 setting. `punktfunk-probe --audio-channels N` is the headless
  validator.

Verified on Linux: core/host/linux/probe test suites + the Android Rust
(cargo-ndk) build, clippy -D warnings, and rustfmt all green. Windows/Apple
builds, all on-glass checks, and the live native loopback are pending (CI / a
free box).

Also lands the concurrent in-tree HEVC 4:4:4 host work (PUNKTFUNK_444): it
shares the same touched files (quic.rs, punktfunk1.rs, encode/*, ...) and so
cannot be committed separately from the surround changes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

clients/linux/src/app.rs

@@ -452,6 +452,7 @@ fn speed_test(app: Rc<App>, req: ConnectRequest) {
                 GamepadPref::Auto,
                 0,    // bitrate_kbps (host default)
                 0,    // video_caps: the Linux client has no 10-bit/HDR present path yet
+                2,    // audio_channels: speed-test probe, stereo
                 None, // launch: speed-test probe connect, no game
                 pin,
                 Some(identity),
@@ -573,6 +574,7 @@ fn start_session(app: Rc<App>, req: ConnectRequest, pin: Option<[u8; 32]>) {
         },
         bitrate_kbps: s.bitrate_kbps,
         mic_enabled: s.mic_enabled,
+        audio_channels: s.audio_channels,
         pin,
         identity: app.identity.clone(),
     };

clients/linux/src/audio.rs

@@ -27,16 +27,17 @@ pub struct AudioPlayer {
 }
 
 impl AudioPlayer {
-    /// Spawn the PipeWire playback thread. Failure (no PipeWire in the session) is
-    /// survivable — the caller streams video-only.
-    pub fn spawn() -> Result<AudioPlayer> {
+    /// Spawn the PipeWire playback thread for `channels` (2/6/8, canonical wire order
+    /// FL FR FC LFE RL RR SL SR). Failure (no PipeWire in the session) is survivable — the
+    /// caller streams video-only.
+    pub fn spawn(channels: u32) -> Result<AudioPlayer> {
         // 64 × 5 ms = 320 ms of slack between the pump and the PipeWire loop.
         let (pcm_tx, pcm_rx) = std::sync::mpsc::sync_channel::<Vec<f32>>(64);
         let (quit_tx, quit_rx) = pipewire::channel::channel::<Terminate>();
         let thread = std::thread::Builder::new()
             .name("punktfunk-audio".into())
             .spawn(move || {
-                if let Err(e) = pw_thread(pcm_rx, quit_rx) {
+                if let Err(e) = pw_thread(pcm_rx, quit_rx, channels as usize) {
                     tracing::warn!(error = %e, "audio playback thread ended");
                 }
             })
@@ -48,8 +49,8 @@ impl AudioPlayer {
         })
     }
 
-    /// Queue one interleaved-stereo f32 chunk. Drops the chunk if the PipeWire side is
-    /// wedged (the renderer conceals the gap; never block the session pump).
+    /// Queue one interleaved f32 chunk (in the session's channel layout). Drops the chunk if the
+    /// PipeWire side is wedged (the renderer conceals the gap; never block the session pump).
     pub fn push(&self, pcm: Vec<f32>) {
         if let Err(TrySendError::Disconnected(_)) = self.pcm_tx.try_send(pcm) {
             // Thread already dead — Drop will reap it; nothing to do per-chunk.
@@ -71,11 +72,14 @@ struct PlayerData {
     rx: Receiver<Vec<f32>>,
     ring: VecDeque<f32>,
     primed: bool,
+    /// Interleaved channel count this stream was opened with (2/6/8).
+    channels: usize,
 }
 
 fn pw_thread(
     pcm_rx: Receiver<Vec<f32>>,
     quit_rx: pipewire::channel::Receiver<Terminate>,
+    channels: usize,
 ) -> Result<()> {
     use pipewire as pw;
     use pw::{properties::properties, spa};
@@ -115,6 +119,7 @@ fn pw_thread(
         rx: pcm_rx,
         ring: VecDeque::new(),
         primed: false,
+        channels,
     };
 
     let _listener = stream
@@ -130,19 +135,19 @@ fn pw_thread(
                 while let Ok(chunk) = ud.rx.try_recv() {
                     ud.ring.extend(chunk);
                 }
-                let stride = 4 * CHANNELS; // F32LE interleaved
+                let stride = 4 * ud.channels; // F32LE interleaved
                 let datas = buffer.datas_mut();
                 if datas.is_empty() {
                     return;
                 }
                 let data = &mut datas[0];
                 let want_frames = data.data().map(|s| s.len() / stride).unwrap_or(0);
-                let want = want_frames * CHANNELS;
+                let want = want_frames * ud.channels;
 
                 // Adaptive jitter buffer (same shape as the host's virtual mic): prime to
                 // ~3 quanta, cap at ~1 quantum of slack beyond that, re-prime after a
                 // genuine drain.
-                let target = (3 * want).clamp(720 * CHANNELS, 9600 * CHANNELS);
+                let target = (3 * want).clamp(720 * ud.channels, 9600 * ud.channels);
                 while ud.ring.len() > target.max(want) + want {
                     ud.ring.pop_front();
                 }
@@ -182,7 +187,13 @@ fn pw_thread(
     let mut info = AudioInfoRaw::new();
     info.set_format(AudioFormat::F32LE);
     info.set_rate(SAMPLE_RATE);
-    info.set_channels(CHANNELS as u32);
+    info.set_channels(channels as u32);
+    // Channel positions in canonical wire order (FL FR FC LFE RL RR SL SR) so PipeWire routes each
+    // slot to the matching speaker (and downmixes when the sink has fewer). Identity, no permute.
+    let order = punktfunk_core::audio::spa_positions(channels as u8);
+    let mut positions = [0u32; 64];
+    positions[..order.len()].copy_from_slice(order);
+    info.set_position(positions);
     let obj = pw::spa::pod::Object {
         type_: pw::spa::utils::SpaTypes::ObjectParamFormat.as_raw(),
         id: pw::spa::param::ParamType::EnumFormat.as_raw(),

clients/linux/src/session.rs

@@ -20,6 +20,8 @@ pub struct SessionParams {
     pub compositor: CompositorPref,
     pub gamepad: GamepadPref,
     pub bitrate_kbps: u32,
+    /// Requested audio channel count (2/6/8); the host echoes the resolved value.
+    pub audio_channels: u8,
     /// Stream the default microphone to the host's virtual mic source.
     pub mic_enabled: bool,
     /// Pinned host fingerprint; `None` = trust on first use (caller persists the observed one).
@@ -83,6 +85,42 @@ fn now_ns() -> u64 {
         .unwrap_or(0)
 }
 
+/// Opus decoder for the audio plane: a plain stereo decoder (the validated path) or a multistream
+/// decoder for 5.1/7.1, both behind one `decode_float`. Built from the host-RESOLVED channel count
+/// via the shared layout table.
+enum AudioDec {
+    Stereo(opus::Decoder),
+    Surround(opus::MSDecoder),
+}
+
+impl AudioDec {
+    fn new(channels: u8) -> Result<AudioDec, opus::Error> {
+        if channels == 2 {
+            Ok(AudioDec::Stereo(opus::Decoder::new(
+                48_000,
+                opus::Channels::Stereo,
+            )?))
+        } else {
+            let l = punktfunk_core::audio::layout_for(channels, false);
+            Ok(AudioDec::Surround(opus::MSDecoder::new(
+                48_000, l.streams, l.coupled, l.mapping,
+            )?))
+        }
+    }
+
+    fn decode_float(
+        &mut self,
+        input: &[u8],
+        out: &mut [f32],
+        fec: bool,
+    ) -> Result<usize, opus::Error> {
+        match self {
+            AudioDec::Stereo(d) => d.decode_float(input, out, fec),
+            AudioDec::Surround(d) => d.decode_float(input, out, fec),
+        }
+    }
+}
+
 fn pump(
     params: SessionParams,
     ev_tx: async_channel::Sender<SessionEvent>,
@@ -96,7 +134,8 @@ fn pump(
         params.compositor,
         params.gamepad,
         params.bitrate_kbps,
-        0,    // video_caps: the Linux client has no 10-bit/HDR present path yet
+        0, // video_caps: the Linux client has no 10-bit/HDR present path yet
+        params.audio_channels,
         None, // launch: the Linux client has no library picker yet
         params.pin,
         Some(params.identity),
@@ -134,11 +173,14 @@ fn pump(
         }
     };
     // Audio is best-effort: a session without it still streams. Gamepads are the
-    // app-lifetime service's job (the UI attaches it on Connected).
-    let player = audio::AudioPlayer::spawn()
+    // app-lifetime service's job (the UI attaches it on Connected). Build the decoder + playback
+    // from the host-RESOLVED channel count (never the request), so an older/clamping host that
+    // resolves stereo is decoded as stereo.
+    let channels = connector.audio_channels;
+    let player = audio::AudioPlayer::spawn(channels as u32)
         .map_err(|e| tracing::warn!(error = %e, "audio disabled"))
         .ok();
-    let mut opus_dec = opus::Decoder::new(48_000, opus::Channels::Stereo)
+    let mut opus_dec = AudioDec::new(channels)
         .map_err(|e| tracing::warn!(error = %e, "opus decoder failed — audio disabled"))
         .ok();
     let _mic = params
@@ -157,8 +199,8 @@ fn pump(
     let mut bytes_n = 0u64;
     let mut decode_us_sum = 0u64;
     let mut lat_us: Vec<u64> = Vec::with_capacity(256);
-    let mut pcm = vec![0f32; 5760 * 2]; // decode scratch: max Opus frame (120 ms stereo)
-                                        // Loss recovery: watch the host→client unrecoverable-drop count and ask for an IDR when it climbs.
+    let mut pcm = vec![0f32; 5760 * channels as usize]; // scratch: max Opus frame (120 ms) × channels
+                                                        // Loss recovery: watch the host→client unrecoverable-drop count and ask for an IDR when it climbs.
     let mut last_dropped = connector.frames_dropped();
     let mut last_kf_req: Option<Instant> = None;
 
@@ -221,7 +263,8 @@ fn pump(
         while let Ok(pkt) = connector.next_audio(Duration::ZERO) {
             if let (Some(player), Some(dec)) = (&player, opus_dec.as_mut()) {
                 match dec.decode_float(&pkt.data, &mut pcm, false) {
-                    Ok(samples) => player.push(pcm[..samples * 2].to_vec()),
+                    // `samples` is per-channel; the interleaved frame is `samples * channels`.
+                    Ok(samples) => player.push(pcm[..samples * channels as usize].to_vec()),
                     Err(e) => tracing::debug!(error = %e, "opus decode"),
                 }
             }

clients/linux/src/trust.rs

@@ -132,6 +132,9 @@ pub struct Settings {
     pub inhibit_shortcuts: bool,
     /// Stream the default microphone to the host's virtual mic source.
     pub mic_enabled: bool,
+    /// Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
+    /// can capture; the resolved count drives the decoder + playback layout.
+    pub audio_channels: u8,
 }
 
 impl Default for Settings {
@@ -145,6 +148,7 @@ impl Default for Settings {
             compositor: "auto".into(),
             inhibit_shortcuts: true,
             mic_enabled: false,
+            audio_channels: 2,
         }
     }
 }

clients/linux/src/ui_settings.rs

@@ -140,6 +140,16 @@ pub fn show(
     input.add(&inhibit_row);
 
     let audio = adw::PreferencesGroup::builder().title("Audio").build();
+    let surround_row = adw::ComboRow::builder()
+        .title("Audio channels")
+        .subtitle("Request stereo or surround (the host downmixes if its output has fewer)")
+        .model(&gtk::StringList::new(&[
+            "Stereo",
+            "5.1 Surround",
+            "7.1 Surround",
+        ]))
+        .build();
+    audio.add(&surround_row);
     let mic_row = adw::SwitchRow::builder()
         .title("Stream microphone")
         .subtitle("Send the default input device to the host's virtual microphone")
@@ -170,6 +180,11 @@ pub fn show(
         compositor_row.set_selected(comp_i as u32);
         inhibit_row.set_active(s.inhibit_shortcuts);
         mic_row.set_active(s.mic_enabled);
+        surround_row.set_selected(match s.audio_channels {
+            6 => 1,
+            8 => 2,
+            _ => 0,
+        });
     }
 
     let dialog = adw::PreferencesDialog::new();
@@ -186,6 +201,11 @@ pub fn show(
             .to_string();
         s.inhibit_shortcuts = inhibit_row.is_active();
         s.mic_enabled = mic_row.is_active();
+        s.audio_channels = match surround_row.selected() {
+            1 => 6,
+            2 => 8,
+            _ => 2,
+        };
         s.save();
     });
     dialog.present(Some(parent));