Skip to main content

pcmflux/
lib.rs

1/*
2 * This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
5 */
6
7//! pcmflux: PulseAudio/PipeWire audio capture with Opus encoding, plus mic-uplink
8//! playback, as a Rust library with an optional Python bridge (the audio sibling of
9//! pixelflux).
10//!
11//! The capture thread pulls S16LE PCM fragments from a PulseAudio record stream,
12//! reassembles them into fixed-size Opus frames, encodes them (mono/stereo via the
13//! single-stream encoder, 5.1/7.1 surround via the multistream API), optionally wraps them
14//! in RFC 2198 RED framing — redundant copies of recent frames, so a client on a lossy
15//! transport rebuilds a dropped packet from the next one it receives instead of stalling
16//! for a retransmit — and hands each frame to a delivery thread that runs the
17//! [`AudioSink`] off the audio path, so a slow or blocked consumer can never stall the
18//! PulseAudio pump. The playback path mirrors this in reverse: it decodes the Opus mic
19//! uplink and writes PCM into a virtual sink.
20//!
21//! The public API is [`AudioCapture`] and [`AudioPlayback`], configured by
22//! [`AudioCaptureSettings`] and [`AudioPlaybackSettings`] (whose `Default` is the
23//! configuration the Python classes start with, and whose `validate` is the one place a
24//! setting is refused), delivering [`AudioFrame`]s to an [`AudioSink`], reporting through
25//! [`State`], `last_error`, and [`Error`], and swept by [`stop_all`]. The `python` feature
26//! adds the `pcmflux` extension module (`python.rs`), thin wrappers over these types that
27//! read settings by attribute name, export a frame through the buffer protocol, call the
28//! capture callback on the delivery thread, and release the GIL around every join.
29//!
30//! Concurrency design (the invariants below are load-bearing):
31//!   - A lifecycle mutex serializes joining/reassigning the capture thread.
32//!   - A single stop_state atomic is the one source of truth (0 = running, -1 =
33//!     external stop, a positive value = self-stop recorded under the issuing thread's
34//!     tid — the delivery thread's for a sink-issued stop). The
35//!     external -1 is stored INSIDE that lock immediately before join, so a stop can
36//!     never be lost between observing a live thread and asking it to stop. A
37//!     re-entrant self-start undoes only its own self-stop via one compare-exchange,
38//!     so a racing external stop is never clobbered.
39//!   - The PulseAudio mainloop is pumped with a bounded ~20ms timeout, so a stop is
40//!     observed within ~20ms even if the audio source delivers no data (is wedged).
41//!   - Joining the capture thread transitively joins the delivery thread, so a stop must
42//!     never wait for a lock the sink's in-flight call may need: the Python bridge releases
43//!     the GIL around every join for that reason, and a Rust sink owes its callers the same.
44//!   - A sink may itself call stop/start; the sink runs on the delivery thread, so that
45//!     re-entrant case is detected via the delivery thread's OS tid (the capture thread's
46//!     tid is checked too) and short-circuits without joining — a join from inside the sink
47//!     would cycle (stopper joins capture, capture joins delivery, delivery is the stopper).
48
49use std::collections::VecDeque;
50use std::fmt;
51use std::sync::atomic::{
52    AtomicBool, AtomicI32, AtomicI64, AtomicU8, AtomicU64, AtomicUsize, Ordering,
53};
54use std::sync::{Arc, Condvar, Mutex, OnceLock, Weak};
55use std::thread::{JoinHandle, ThreadId};
56use std::time::{Duration, Instant};
57
58use libpulse_binding as pulse;
59use pulse::callbacks::ListResult;
60use pulse::channelmap::Map as ChannelMap;
61use pulse::context::{Context, FlagSet as CtxFlags};
62use pulse::def::BufferAttr;
63use pulse::mainloop::standard::Mainloop;
64use pulse::sample::{Format, Spec};
65use pulse::stream::{FlagSet as StreamFlags, PeekResult, Stream};
66use pulse::time::MicroSeconds;
67
68/// Non-panicking `println!` replacement that swallows write errors (e.g. EPIPE) instead
69/// of panicking, so a broken output pipe can't unwind the capture thread or a callback.
70macro_rules! plog {
71    ($($arg:tt)*) => {{
72        use std::io::Write;
73        let _ = writeln!(std::io::stdout().lock(), $($arg)*);
74    }};
75}
76/// Non-panicking `eprintln!` replacement — the stderr sibling of `plog!`.
77macro_rules! elog {
78    ($($arg:tt)*) => {{
79        use std::io::Write;
80        let _ = writeln!(std::io::stderr().lock(), $($arg)*);
81    }};
82}
83
84mod ogg_sink;
85#[cfg(feature = "python")]
86mod python;
87mod red;
88
89use red::RED_MAX_DISTANCE;
90
91/// The crate version compiled in, for a host that names the pcmflux it links.
92pub const VERSION: &str = env!("CARGO_PKG_VERSION");
93
94/// Returns the calling thread's OS tid (`gettid` syscall) so a stop/start issued from
95/// inside the sink can detect it is on one of the run's own threads and avoid self-joining.
96#[inline]
97fn gettid() -> i64 {
98    unsafe { libc::syscall(libc::SYS_gettid) as i64 }
99}
100
101/// `start_state`: no worker has run yet, or the last run stopped cleanly.
102const ST_IDLE: u8 = 0;
103/// `start_state` handshake: startup in progress.
104const ST_STARTING: u8 = 1;
105/// `start_state` handshake: the hot loop is running.
106const ST_RUNNING: u8 = 2;
107/// `start_state`: the last run ended in error (startup or mid-run); `last_error` says why.
108const ST_FAILED: u8 = 3;
109
110/// Opus target-bitrate bounds (bits/s); the initial `opus_bitrate` and every live update
111/// are clamped into this range so the encoder never sees a value it would reject.
112const OPUS_BITRATE_MIN: i32 = 6000;
113const OPUS_BITRATE_MAX: i32 = 510000;
114
115/// `stop_state` sentinel: no stop pending (running).
116const STOP_NONE: i64 = 0;
117/// `stop_state` sentinel: authoritative external stop (-1). Any positive value
118/// instead is the OS tid of a capture thread that self-stopped from its callback.
119const STOP_EXTERNAL: i64 = -1;
120
121/// PulseAudio mainloop pump timeout (~20 ms) — upper bound on how long a pending
122/// stop can go unobserved even when the audio source delivers nothing.
123const PUMP_TIMEOUT_US: u64 = 20 * 1000;
124/// Max Opus output packet size in bytes per stream; sizes the emit buffer pool.
125const MAX_OPUS_PACKET: usize = 4000;
126
127/// Max RED timestamp offset — 14-bit ceiling in 48 kHz samples from the primary.
128const RED_MAX_OFFSET: u64 = 16383;
129/// Max RED block length — 10-bit ceiling in bytes.
130const RED_MAX_LEN: usize = 1023;
131/// RED block payload type.
132const RED_BLOCK_PT: u8 = 0;
133/// Bit of a header-carrying capture's second byte that marks where the stream pauses by the
134/// sender's choice. Alone, as `[0x01, WS_QUIET]` with no Opus, it is sent where a sound ends
135/// (and when the session drops after sound): a player plays out what it holds at once
136/// rather than waiting for more, and running dry after it is not a late delivery. It is set
137/// as well on the silent frame sent right behind that mark, whose Opus carries the end of
138/// the sound the encoder held back, so a player appends that frame to the sound rather than
139/// taking it for a new one. Never part of `n_red`, which fits below it (`RED_MAX_DISTANCE`).
140const WS_QUIET: u8 = 0x80;
141
142/// Test-only reference implementation of the WS audio frame body — builds the
143/// full RFC 2198 RED framing + primary Opus packet for byte-for-byte assertion
144/// against the pooled in-place `write_ws_prefix_into` on the hot path.
145///
146/// RED carries redundant copies of recent frames alongside each primary, so a client on a
147/// lossy transport can rebuild a dropped packet from the next one it receives with no
148/// retransmit — that packet-loss concealment is the whole reason the layout below exists.
149///
150/// `history` is oldest-first (front = oldest, largest timestamp offset back from
151/// `primary_pts`). The layout is chosen by `emit_header` and `red_distance`:
152///
153/// 1. **Header omitted** (`!emit_header`): the raw primary Opus packet, with no framing
154///    bytes — the header is what carries the redundant-block count, so without it there
155///    is no `[0x01,n]` prefix.
156/// 2. **`red_distance == 0`, or no usable redundancy**: the 2-byte `[0x01, 0x00]` framing
157///    then the primary. On this wire `n_red == 0` must mean **exactly** those two bytes,
158///    so a first frame after a (re)start or a gated silence (empty history) collapses here
159///    too; emitting a lone primary-only RED header instead would be mis-stripped by the
160///    client's `n_red == 0` path and corrupt the frame.
161/// 3. **`red_distance > 0` with usable history**: the full RFC 2198 RED framing —
162///    - `0x01` audio-chunk tag, then `n_red` (count of redundant blocks that actually fit).
163///    - The primary timestamp (low 32 bits, big-endian), letting the client order and dedup
164///      recovered frames against what it has already played.
165///    - One 4-byte header per redundant block, oldest-first: `0x80 | PT` (F bit set,
166///      i.e. another block follows), then `(offset14 << 10) | len10` big-endian.
167///    - The 1-byte primary block header (`PT`, F bit clear).
168///    - The block payloads in that same order: redundant oldest-first, then the primary.
169///
170/// A redundant block whose 48 kHz sample offset overflows `RED_MAX_OFFSET` (14 bits) or
171/// whose byte length overflows `RED_MAX_LEN` (10 bits) is skipped, so `n_red` counts only
172/// what fit. The second byte's top bit is not part of `n_red`: it is `WS_QUIET`, set by the
173/// emit path on the silent frame that ends a sound.
174#[cfg(test)]
175fn build_ws_body(
176    primary: &[u8],
177    primary_pts: u64,
178    history: &VecDeque<(Vec<u8>, u64)>,
179    red_distance: usize,
180    emit_header: bool,
181) -> Vec<u8> {
182    if !emit_header {
183        return primary.to_vec();
184    }
185    if red_distance == 0 {
186        let mut out = Vec::with_capacity(2 + primary.len());
187        out.push(0x01);
188        out.push(0x00);
189        out.extend_from_slice(primary);
190        return out;
191    }
192    let start = history.len().saturating_sub(red_distance);
193    let mut blocks: Vec<(&[u8], u32)> = Vec::with_capacity(red_distance);
194    for (data, pts) in history.iter().skip(start) {
195        let offset = primary_pts.saturating_sub(*pts);
196        if offset > RED_MAX_OFFSET || data.len() > RED_MAX_LEN {
197            continue;
198        }
199        blocks.push((data.as_slice(), offset as u32));
200    }
201    if blocks.is_empty() {
202        let mut out = Vec::with_capacity(2 + primary.len());
203        out.push(0x01);
204        out.push(0x00);
205        out.extend_from_slice(primary);
206        return out;
207    }
208    let redundant_bytes: usize = blocks.iter().map(|(d, _)| d.len()).sum();
209    let mut out = Vec::with_capacity(6 + 4 * blocks.len() + 1 + redundant_bytes + primary.len());
210    out.push(0x01);
211    out.push(blocks.len() as u8);
212    out.extend_from_slice(&(primary_pts as u32).to_be_bytes());
213    for (data, offset) in &blocks {
214        out.push(0x80 | (RED_BLOCK_PT & 0x7F));
215        let word = ((offset & 0x3FFF) << 10) | (data.len() as u32 & 0x3FF);
216        out.push((word >> 16) as u8);
217        out.push((word >> 8) as u8);
218        out.push(word as u8);
219    }
220    out.push(RED_BLOCK_PT & 0x7F);
221    for (data, _) in &blocks {
222        out.extend_from_slice(data);
223    }
224    out.extend_from_slice(primary);
225    out
226}
227
228/// Worst-case byte length of the WS frame prefix (tag + n_red + pts + headers + payloads).
229const RED_PREFIX_MAX: usize =
230    6 + 4 * RED_MAX_DISTANCE as usize + 1 + RED_MAX_DISTANCE as usize * RED_MAX_LEN;
231
232/// Emit the RFC 2198 RED framing prefix into `buf` in-place and return its length,
233/// so the encoder can serialize the Opus packet directly after it with no scratch
234/// buffer and no per-frame allocation. The runtime counterpart of `build_ws_body`.
235///
236/// 1. **Header omitted**: returns `0`; the caller emits the raw primary with no prefix.
237/// 2. **`red_distance > 0` with usable history**: writes the full RED header — tag,
238///    `n_red`, the primary timestamp (low 32 bits, big-endian), one 4-byte header per
239///    redundant block (F bit set, then `(offset14 << 10) | len10`), the 1-byte primary
240///    header (F bit clear), and the redundant block payloads oldest-first. Usable blocks
241///    are selected by history index into a fixed `RED_MAX_DISTANCE` array — the distance is
242///    clamped at ingest, so this allocates nothing.
243/// 3. **`red_distance == 0`, or no usable redundancy**: the 2-byte `[0x01, 0x00]` framing.
244///
245/// `buf` must hold at least `RED_PREFIX_MAX` bytes when `emit_header && red_distance > 0`,
246/// and at least 2 bytes otherwise.
247fn write_ws_prefix_into(
248    buf: &mut [u8],
249    primary_pts: u64,
250    history: &VecDeque<(Vec<u8>, u64)>,
251    red_distance: usize,
252    emit_header: bool,
253) -> usize {
254    if !emit_header {
255        return 0;
256    }
257    if red_distance > 0 {
258        debug_assert!(red_distance <= RED_MAX_DISTANCE as usize);
259        let start = history.len().saturating_sub(red_distance);
260        let mut idx = [0usize; RED_MAX_DISTANCE as usize];
261        let mut n = 0usize;
262        for (i, (data, pts)) in history.iter().enumerate().skip(start) {
263            let offset = primary_pts.saturating_sub(*pts);
264            if offset <= RED_MAX_OFFSET && data.len() <= RED_MAX_LEN {
265                idx[n] = i;
266                n += 1;
267            }
268        }
269        if n > 0 {
270            buf[0] = 0x01;
271            buf[1] = n as u8;
272            buf[2..6].copy_from_slice(&(primary_pts as u32).to_be_bytes());
273            let mut i = 6;
274            for &k in &idx[..n] {
275                let (data, pts) = &history[k];
276                let offset = primary_pts.saturating_sub(*pts) as u32;
277                buf[i] = 0x80 | (RED_BLOCK_PT & 0x7F);
278                let word = ((offset & 0x3FFF) << 10) | (data.len() as u32 & 0x3FF);
279                buf[i + 1] = (word >> 16) as u8;
280                buf[i + 2] = (word >> 8) as u8;
281                buf[i + 3] = word as u8;
282                i += 4;
283            }
284            buf[i] = RED_BLOCK_PT & 0x7F;
285            i += 1;
286            for &k in &idx[..n] {
287                let data = &history[k].0;
288                buf[i..i + data.len()].copy_from_slice(data);
289                i += data.len();
290            }
291            return i;
292        }
293    }
294    buf[0] = 0x01;
295    buf[1] = 0x00;
296    2
297}
298
299/// Why a call was refused: the one error type of the crate, which the Python bridge maps
300/// onto `ValueError` and `RuntimeError`.
301#[derive(Debug, Clone, PartialEq, Eq)]
302pub enum Error {
303    /// A setting the encoder or the sound server could never accept, refused before a
304    /// thread is spawned.
305    Settings(String),
306    /// A run that could not be started: a thread that failed to spawn, a decoder that could
307    /// not be created, or a worker that reported its failure within the start handshake.
308    Start(String),
309    /// A playback write while no playback thread services the queue: never started,
310    /// stopped, or failed.
311    NotRunning,
312}
313
314impl fmt::Display for Error {
315    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
316        match self {
317            Error::Settings(msg) | Error::Start(msg) => f.write_str(msg),
318            Error::NotRunning => f.write_str(
319                "audio playback is not running (stream failed, stopped, or never started)",
320            ),
321        }
322    }
323}
324
325impl std::error::Error for Error {}
326
327/// Lifecycle phase of a capture or playback: `Idle` (no run yet, or the last run stopped
328/// cleanly), `Starting` (worker spawned, first PulseAudio session not yet up), `Running`
329/// (connected, or reconnecting mid-run, with no stop pending), or `Failed` (the last run
330/// ended in error; `last_error` says why). A run that was stopped reads `Idle` again even
331/// while its thread is still winding down.
332#[derive(Debug, Clone, Copy, PartialEq, Eq)]
333pub enum State {
334    Idle,
335    Starting,
336    Running,
337    Failed,
338}
339
340impl State {
341    /// The phase as the Python `state` getters spell it: `"idle"`, `"starting"`,
342    /// `"running"`, or `"failed"`.
343    pub fn as_str(self) -> &'static str {
344        match self {
345            State::Idle => "idle",
346            State::Starting => "starting",
347            State::Running => "running",
348            State::Failed => "failed",
349        }
350    }
351}
352
353impl fmt::Display for State {
354    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
355        f.write_str(self.as_str())
356    }
357}
358
359/// Where a capture delivers its encoded frames: `frame` is called on the capture's
360/// delivery thread, off the audio path, once per frame, in order. A closure
361/// `Fn(AudioFrame) + Send + Sync` is a sink. The sink may call the capture's `stop` or
362/// `start` from inside `frame`; such a re-entrant call is detected by thread and never
363/// joins.
364pub trait AudioSink: Send + Sync {
365    /// Take one encoded frame; dropping it returns its buffer to the capture.
366    fn frame(&self, frame: AudioFrame);
367}
368
369impl<F> AudioSink for F
370where
371    F: Fn(AudioFrame) + Send + Sync,
372{
373    fn frame(&self, frame: AudioFrame) {
374        self(frame)
375    }
376}
377
378/// Capture/encode configuration, read once by `AudioCapture::start`. `Default` is the
379/// configuration the Python `AudioCaptureSettings` starts with: the system default source,
380/// 48 kHz stereo at 128 kbps VBR in 20 ms frames, the silence gate on, the audio header
381/// emitted, no RED, no output socket.
382#[derive(Clone, Debug, PartialEq)]
383pub struct AudioCaptureSettings {
384    /// The PulseAudio source to record; `None` or empty for the system default.
385    pub device_name: Option<String>,
386    /// 8000, 12000, 16000, 24000, or 48000.
387    pub sample_rate: u32,
388    /// 1, 2, 6 (5.1), or 8 (7.1).
389    pub channels: i32,
390    /// Opus target bitrate in bits/s, clamped into the encoder's range at start.
391    pub opus_bitrate: i32,
392    /// 2.5, 5, 10, 20, 40, or 60.
393    pub frame_duration_ms: f64,
394    pub use_vbr: bool,
395    /// Opus encoder complexity, 0 (cheapest) to 10; `None` leaves libopus's default.
396    /// Applied when the encoder is created, so it does not change during a running capture.
397    pub opus_complexity: Option<i32>,
398    /// Drop frames of digital silence before encoding them.
399    pub use_silence_gate: bool,
400    /// Print a status line every two seconds.
401    pub debug_logging: bool,
402    /// The record stream's fragment size in milliseconds; 0 selects the default.
403    pub latency_ms: i32,
404    /// Deliver raw Opus packets instead of the two-byte header and RED framing.
405    pub omit_audio_header: bool,
406    /// Redundant copies of recent frames each frame carries, 0 to `RED_MAX_DISTANCE`.
407    pub red_distance: i32,
408    /// Unix socket path on which the capture serves its packets as an Ogg Opus stream to
409    /// every consumer that connects; empty serves none. A path that cannot be bound fails
410    /// the start like any other startup error.
411    pub output_socket: String,
412}
413
414impl Default for AudioCaptureSettings {
415    fn default() -> Self {
416        AudioCaptureSettings {
417            device_name: None,
418            sample_rate: 48000,
419            channels: 2,
420            opus_bitrate: 128000,
421            frame_duration_ms: 20.0,
422            use_vbr: true,
423            opus_complexity: None,
424            use_silence_gate: true,
425            debug_logging: false,
426            latency_ms: 0,
427            omit_audio_header: false,
428            red_distance: 0,
429            output_socket: String::new(),
430        }
431    }
432}
433
434impl AudioCaptureSettings {
435    /// The settings a run snapshots, or why they are refused: what the worker could only
436    /// fail on later is rejected here, before a thread is spawned.
437    ///
438    /// `opus_bitrate` is clamped into the Opus range exactly as `update_audio_bitrate`
439    /// clamps a live update; `red_distance` into `[0, RED_MAX_DISTANCE]` — it selects how
440    /// many redundant Opus copies each frame carries, and cannot exceed the RFC 2198
441    /// history depth. An empty `device_name` becomes `None`, the system default, and one
442    /// with an interior NUL is refused: the name becomes a C string for libpulse on the
443    /// worker thread, where it could only surface as a panic. `latency_ms == 0` selects the
444    /// default fragment size.
445    pub fn validate(&self) -> Result<AudioCaptureSettings, Error> {
446        let parsed = AudioCaptureSettings {
447            device_name: checked_device_name(self.device_name.as_deref())?,
448            opus_bitrate: self.opus_bitrate.clamp(OPUS_BITRATE_MIN, OPUS_BITRATE_MAX),
449            red_distance: self.red_distance.clamp(0, RED_MAX_DISTANCE),
450            ..self.clone()
451        };
452        check_opus_sample_rate(parsed.sample_rate)?;
453        if !valid_opus_duration(parsed.frame_duration_ms) {
454            return settings_error(format!(
455                "frame_duration_ms must be one of 2.5, 5, 10, 20, 40, or 60 (got {})",
456                parsed.frame_duration_ms
457            ));
458        }
459        if let Some(c) = parsed.opus_complexity
460            && !(0..=OPUS_COMPLEXITY_MAX).contains(&c)
461        {
462            return settings_error(format!(
463                "opus_complexity must be None or between 0 and {OPUS_COMPLEXITY_MAX} (got {c})"
464            ));
465        }
466        if !matches!(parsed.channels, 1 | 2 | 6 | 8) {
467            return settings_error(format!(
468                "channels must be 1, 2, 6, or 8 (got {})",
469                parsed.channels
470            ));
471        }
472        if parsed.latency_ms < 0 {
473            return settings_error(format!(
474                "latency_ms must be >= 0 (got {}); 0 selects the default fragment size",
475                parsed.latency_ms
476            ));
477        }
478        Ok(parsed)
479    }
480}
481
482/// Highest Opus encoder complexity.
483const OPUS_COMPLEXITY_MAX: i32 = 10;
484
485/// True if `ms` is a valid Opus frame duration (2.5, 5, 10, 20, 40, or 60 ms).
486///
487/// The comparison is done in tenths of a millisecond (`round(ms * 10)`) so the fractional
488/// 2.5 ms case is accepted exactly, without float-equality pitfalls.
489fn valid_opus_duration(ms: f64) -> bool {
490    matches!((ms * 10.0).round() as i64, 25 | 50 | 100 | 200 | 400 | 600)
491}
492
493/// A device name as libpulse gets it: `None` and the empty string both mean the system
494/// default, and an interior NUL is refused. Shared by both settings' validation.
495fn checked_device_name(name: Option<&str>) -> Result<Option<String>, Error> {
496    match name {
497        None | Some("") => Ok(None),
498        Some(v) if v.contains('\0') => settings_error("device_name must not contain NUL bytes"),
499        Some(v) => Ok(Some(v.to_string())),
500    }
501}
502
503/// Build the `Error::Settings` for a rejected settings field.
504fn settings_error<T>(msg: impl Into<String>) -> Result<T, Error> {
505    Err(Error::Settings(msg.into()))
506}
507
508/// Opus codecs only run at 8, 12, 16, 24, or 48 kHz; anything else would fail encoder or
509/// decoder creation on the worker, so it is rejected up front.
510fn check_opus_sample_rate(rate: u32) -> Result<(), Error> {
511    if matches!(rate, 8000 | 12000 | 16000 | 24000 | 48000) {
512        Ok(())
513    } else {
514        settings_error(format!(
515            "sample_rate must be 8000, 12000, 16000, 24000, or 48000 (got {rate})"
516        ))
517    }
518}
519
520/// Mic-playback configuration, read once by `AudioPlayback::start`, so the playback
521/// thread owns an immutable copy for the run's lifetime. `Default` is the configuration
522/// the Python `AudioPlaybackSettings` starts with, matching the client mic wire: the
523/// `input` sink, S16LE mono at 24 kHz, a 40 ms sink buffer, and a queue bound of 96000
524/// bytes (about 2 s).
525#[derive(Clone, Debug, PartialEq, Eq)]
526pub struct AudioPlaybackSettings {
527    /// The PulseAudio sink to play into; `None` or empty for the system default.
528    pub device_name: Option<String>,
529    /// 8000, 12000, 16000, 24000, or 48000.
530    pub sample_rate: u32,
531    /// 1 or 2.
532    pub channels: i32,
533    /// The sink buffer's target latency in milliseconds; must be positive.
534    pub latency_ms: i32,
535    /// The single byte bound on the drop-oldest playback queue; must be positive.
536    pub max_buffer_bytes: usize,
537    /// Print a status line every second.
538    pub debug_logging: bool,
539}
540
541impl Default for AudioPlaybackSettings {
542    fn default() -> Self {
543        AudioPlaybackSettings {
544            device_name: Some("input".to_string()),
545            sample_rate: 24000,
546            channels: 1,
547            latency_ms: 40,
548            max_buffer_bytes: 96000,
549            debug_logging: false,
550        }
551    }
552}
553
554impl AudioPlaybackSettings {
555    /// The settings a run snapshots, or why they are refused: what the playback thread
556    /// could only fail on later is rejected here, before a thread is spawned.
557    ///
558    /// `latency_ms` must be positive: it sizes the sink buffer, and a zero target would
559    /// make PulseAudio start playback with nothing prebuffered and underrun on every write.
560    /// `max_buffer_bytes` must be positive: it bounds the drop-oldest queue, and a zero
561    /// bound would discard every chunk as soon as it was queued. `device_name` is checked
562    /// as the capture's is.
563    pub fn validate(&self) -> Result<AudioPlaybackSettings, Error> {
564        let parsed = AudioPlaybackSettings {
565            device_name: checked_device_name(self.device_name.as_deref())?,
566            ..self.clone()
567        };
568        check_opus_sample_rate(parsed.sample_rate)?;
569        if !matches!(parsed.channels, 1 | 2) {
570            return settings_error(format!(
571                "playback channels must be 1 or 2 (got {})",
572                parsed.channels
573            ));
574        }
575        if parsed.latency_ms <= 0 {
576            return settings_error(format!(
577                "latency_ms must be > 0 (got {})",
578                parsed.latency_ms
579            ));
580        }
581        if parsed.max_buffer_bytes == 0 {
582            return settings_error("max_buffer_bytes must be > 0 (got 0)");
583        }
584        Ok(parsed)
585    }
586}
587
588/// One encoded frame as the capture delivers it: the two-byte header and RED framing
589/// followed by the Opus packet, or the raw packet on a capture that omits the header, with
590/// the `pts` it starts at and the channels its Opus carries.
591///
592/// Owns its buffer; when the frame is dropped, a pooled buffer is recycled back to the
593/// capture thread (see the `Drop` impl), keeping the steady-state emit path
594/// allocation-free, so a consumer that must keep the bytes copies them out.
595pub struct AudioFrame {
596    data: Vec<u8>,
597    pts: u64,
598    /// Channels the frame's Opus carries: the capture's own, or 2 for its stereo companion.
599    channels: u8,
600    /// Set when the buffer came from a capture's `BufferPool`; recycled to it on drop.
601    pool: Option<Arc<BufferPool>>,
602}
603
604impl AudioFrame {
605    /// The frame's bytes.
606    pub fn as_bytes(&self) -> &[u8] {
607        &self.data
608    }
609
610    /// The frame's length in bytes.
611    pub fn len(&self) -> usize {
612        self.data.len()
613    }
614
615    /// Whether the frame carries no bytes.
616    pub fn is_empty(&self) -> bool {
617        self.data.is_empty()
618    }
619
620    /// Presentation timestamp in input samples: the capture's running sample count before
621    /// this frame.
622    pub fn pts(&self) -> u64 {
623        self.pts
624    }
625
626    /// Channels the frame's Opus carries: the capture's own count, or 2 for a frame of the
627    /// stereo companion (`AudioCapture::set_stereo_companion`), which shares its pts.
628    pub fn channels(&self) -> u8 {
629        self.channels
630    }
631}
632
633impl fmt::Debug for AudioFrame {
634    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
635        f.debug_struct("AudioFrame")
636            .field("len", &self.data.len())
637            .field("pts", &self.pts)
638            .field("channels", &self.channels)
639            .finish()
640    }
641}
642
643impl Drop for AudioFrame {
644    fn drop(&mut self) {
645        if let Some(pool) = self.pool.take() {
646            pool.put(std::mem::take(&mut self.data));
647        }
648    }
649}
650
651/// Shared state for one capture (or playback) run: the lifecycle state machine plus the
652/// per-frame settings mirrors the worker reads on the hot path — all lock-free except the
653/// rarely touched `last_error`.
654///
655/// The lifecycle is driven by two atomics — `stop_state` (the single source of truth for
656/// "should this run stop") and `start_state` (IDLE → STARTING → RUNNING, then FAILED with a
657/// `last_error` or back to IDLE on a clean stop) — plus `capture_tid` and `deliver_tid`, the
658/// worker and delivery threads' OS tids used to detect a re-entrant stop/start issued from
659/// inside the sink (which runs on the delivery thread). The remaining atomics
660/// mirror settings the worker consults each frame without re-snapshotting `Settings`, so
661/// `update_audio_bitrate` can retune the encoder mid-run without locking; the silence and
662/// header flags are published once at start and only read per frame.
663struct Inner {
664    /// Single lifecycle source of truth: `STOP_NONE` (running), `STOP_EXTERNAL`, or a
665    /// positive tid meaning the run self-stopped from inside its own callback (recorded
666    /// under the issuing thread's tid — the delivery thread's). A re-entrant start clears
667    /// only its own self-stop via compare-exchange, so it can never clobber an external
668    /// stop that raced in mid-join (which would strand it).
669    stop_state: AtomicI64,
670    started_ok: AtomicBool,
671    start_state: AtomicU8,
672    /// Why the last run failed (`start_state == ST_FAILED`), for `last_error`.
673    /// Written before `ST_FAILED` is published and cleared when a new run is spawned, so
674    /// a failure that lands after the start handshake returned — the retry ladder giving
675    /// up, a mid-run reconnect budget spent, a worker panic — is still observable.
676    last_error: Mutex<Option<String>>,
677    /// OS tid of the running capture thread; `0` when no worker is live.
678    capture_tid: AtomicI64,
679    /// OS tid of the running delivery thread (the one that calls the sink); `0` when none
680    /// is live. Checked by the re-entrancy guards alongside `capture_tid`, because a
681    /// stop/start issued from inside the sink executes on THIS thread — a
682    /// join from it would cycle (stopper joins capture, capture joins delivery).
683    deliver_tid: AtomicI64,
684    /// Lock-free per-frame settings mirrors, re-read by the worker each frame.
685    /// `opus_bitrate` is republished by `update_audio_bitrate`; the rest are published
686    /// once, by the run that starts.
687    opus_bitrate: AtomicI32,
688    use_silence_gate: AtomicBool,
689    debug_logging: AtomicBool,
690    emit_audio_header: AtomicBool,
691    /// Whether a surround capture also emits every frame downmixed to stereo; toggled live.
692    stereo_companion: AtomicBool,
693}
694
695impl Inner {
696    fn new() -> Self {
697        Inner {
698            stop_state: AtomicI64::new(STOP_NONE),
699            started_ok: AtomicBool::new(false),
700            start_state: AtomicU8::new(ST_IDLE),
701            last_error: Mutex::new(None),
702            capture_tid: AtomicI64::new(0),
703            deliver_tid: AtomicI64::new(0),
704            opus_bitrate: AtomicI32::new(128000),
705            use_silence_gate: AtomicBool::new(true),
706            debug_logging: AtomicBool::new(false),
707            emit_audio_header: AtomicBool::new(true),
708            stereo_companion: AtomicBool::new(false),
709        }
710    }
711
712    /// Request an authoritative external stop, stored unconditionally.
713    ///
714    /// The single source of truth for stopping a run. External stops win every race: they
715    /// are published (inside the lifecycle lock, immediately before join) with a plain
716    /// store, so a concurrent self-stop/self-start — which only ever compare-exchanges
717    /// state it owns — can never clobber one and strand the join forever.
718    fn request_external_stop(&self) {
719        self.stop_state.store(STOP_EXTERNAL, Ordering::Release);
720    }
721
722    /// Record a re-entrant self-stop from inside the run's own callback.
723    ///
724    /// Only transitions `STOP_NONE -> me` via compare-exchange, so it never overwrites a
725    /// pending external stop (which must win the join).
726    fn request_self_stop(&self, me: i64) {
727        let _ =
728            self.stop_state
729                .compare_exchange(STOP_NONE, me, Ordering::AcqRel, Ordering::Acquire);
730    }
731
732    /// Undo a re-entrant self-stop (self-start from inside the callback).
733    ///
734    /// Compare-exchanges `me -> STOP_NONE`, clearing the stop only if this same thread
735    /// still owns it. If an external stop landed in between, the CAS fails and that stop
736    /// stands.
737    fn undo_self_stop(&self, me: i64) {
738        let _ =
739            self.stop_state
740                .compare_exchange(me, STOP_NONE, Ordering::AcqRel, Ordering::Acquire);
741    }
742
743    /// Clear the stop state back to running. Only ever called under the lifecycle
744    /// lock (after join, before spawn), where no external stop can be in flight — the
745    /// lost-stop invariant that lets this be an unconditional store.
746    fn clear_stop(&self) {
747        self.stop_state.store(STOP_NONE, Ordering::Release);
748    }
749
750    /// True once any stop (external or self) is pending; the hot loops poll this.
751    fn stop_pending(&self) -> bool {
752        self.stop_state.load(Ordering::Acquire) != STOP_NONE
753    }
754
755    /// True while a worker is (or is still becoming) live: the startup handshake
756    /// is in flight, or the hot loop is running with no stop pending.
757    ///
758    /// Goes false the moment the worker fails, is stopped, or dies mid-run — the hot loop
759    /// clears `started_ok` before breaking on error, even with no stop pending and
760    /// `start_state` still `RUNNING`. Producers (e.g. `AudioPlayback::write`) gate on this
761    /// so they surface a dead stream instead of feeding state nothing services.
762    fn worker_alive(&self) -> bool {
763        self.start_state.load(Ordering::Acquire) == ST_STARTING || self.running()
764    }
765
766    /// True while the worker is connected and running with no stop pending — the
767    /// `is_capturing` / `is_running` getters.
768    fn running(&self) -> bool {
769        self.started_ok.load(Ordering::Acquire) && !self.stop_pending()
770    }
771
772    /// The lifecycle phase (`State`) behind the `state` getters.
773    fn state(&self) -> State {
774        match self.start_state.load(Ordering::Acquire) {
775            ST_STARTING => State::Starting,
776            ST_FAILED => State::Failed,
777            ST_RUNNING if self.running() => State::Running,
778            _ => State::Idle,
779        }
780    }
781
782    /// Mark the run dead with a reason: logs `msg` to stderr, records it for `last_error`,
783    /// and only then publishes `ST_FAILED`, so a reader that observes the failed state also
784    /// finds its message. Every terminal worker error goes through here.
785    fn fail(&self, msg: String) {
786        elog!("[pcmflux] ERROR: {msg}");
787        *self.last_error.lock().unwrap_or_else(|e| e.into_inner()) = Some(msg);
788        self.started_ok.store(false, Ordering::Release);
789        self.start_state.store(ST_FAILED, Ordering::Release);
790    }
791
792    /// The message of the last run's failure, or `None` while no run has failed since the
793    /// last (re)start.
794    fn last_error(&self) -> Option<String> {
795        self.last_error
796            .lock()
797            .unwrap_or_else(|e| e.into_inner())
798            .clone()
799    }
800
801    /// Forget the previous run's failure; called by `spawn_worker` as a new run is armed.
802    fn clear_error(&self) {
803        *self.last_error.lock().unwrap_or_else(|e| e.into_inner()) = None;
804    }
805
806    /// True when the calling thread is one of this run's own threads — the capture
807    /// worker or the delivery thread that runs the sink — i.e. the call is a
808    /// re-entrant stop/start/drop from inside the sink. Such a caller must never
809    /// join: teardown has the capture thread join the delivery thread, so a join from
810    /// either one closes a cycle and deadlocks.
811    fn is_own_thread(&self, me: i64) -> bool {
812        self.capture_tid.load(Ordering::Acquire) == me
813            || self.deliver_tid.load(Ordering::Acquire) == me
814    }
815}
816
817/// Per-`AudioCapture` shared handle: the lock-free `Inner` state plus the
818/// lifecycle-locked join handle for the capture thread.
819struct Shared {
820    inner: Arc<Inner>,
821    /// Lifecycle lock: serializes take/join/reassign of the capture thread's handle.
822    thread: Mutex<Option<JoinHandle<()>>>,
823}
824
825/// Process-wide registry of live captures, swept by `stop_all`. Holds `Weak`
826/// references so it keeps nothing alive on its own.
827static REGISTRY: OnceLock<Mutex<Vec<Weak<Shared>>>> = OnceLock::new();
828/// Lazily initialize and return the capture registry.
829fn registry() -> &'static Mutex<Vec<Weak<Shared>>> {
830    REGISTRY.get_or_init(|| Mutex::new(Vec::new()))
831}
832
833/// Join the worker `slot` holds, having set the external stop INSIDE the caller's lock
834/// immediately before `join()` — the set-before-join ordering the lost-stop invariant rests on
835/// — and clear `capture_tid` so a later start sees no stale owner. Every stop path ends here.
836fn join_held_worker(slot: &mut Option<JoinHandle<()>>, inner: &Inner) {
837    if let Some(handle) = slot.take() {
838        inner.request_external_stop();
839        let _ = handle.join();
840        inner.capture_tid.store(0, Ordering::Release);
841    }
842}
843
844/// `join_held_worker` behind the lifecycle lock, for the stop paths that want nothing else from
845/// it. A lock poisoned by an unrelated panic is taken anyway: it must never be what leaves a
846/// worker thread running into process exit.
847fn stop_and_join(slot: &Mutex<Option<JoinHandle<()>>>, inner: &Inner) {
848    join_held_worker(&mut slot.lock().unwrap_or_else(|e| e.into_inner()), inner);
849}
850
851/// Locked takeover + spawn of a worker thread, shared by the capture and playback
852/// starts. Returns the new thread's id, or `None` if the spawn failed.
853///
854/// Under the lifecycle lock, in order:
855///
856/// 1. **Stop and join any prior worker** through `join_held_worker`, under this lock.
857/// 2. **Reset the lifecycle state**: clears `stop_state` back to `STOP_NONE` (done ONLY
858///    here, under the lock, after the join and before the spawn, where no external stop
859///    can be in flight), forgets the previous run's `last_error`, and arms the startup
860///    handshake at `ST_STARTING`.
861/// 3. **Spawn `body` on a named thread**: the thread applies a best-effort `nice` boost
862///    (audio must not stutter when the captured workload saturates the CPU; EPERM without
863///    `CAP_SYS_NICE` is silently a no-op), publishes its OS tid into `capture_tid` for the
864///    re-entrancy guard, runs `body`, then clears the tid on exit.
865///
866/// The returned `ThreadId` is the identity a failed start later hands to
867/// `join_failed_start`, so a losing start tears down only the thread it spawned.
868fn spawn_worker(
869    slot: &Mutex<Option<JoinHandle<()>>>,
870    inner: &Arc<Inner>,
871    name: &str,
872    body: impl FnOnce() + Send + 'static,
873) -> Option<ThreadId> {
874    let mut guard = slot.lock().unwrap_or_else(|e| e.into_inner());
875    join_held_worker(&mut guard, inner);
876    inner.clear_stop();
877    inner.clear_error();
878    inner.started_ok.store(false, Ordering::Release);
879    inner.start_state.store(ST_STARTING, Ordering::Release);
880    let t_inner = inner.clone();
881    match std::thread::Builder::new()
882        .name(name.into())
883        .spawn(move || {
884            unsafe {
885                let _ = libc::setpriority(libc::PRIO_PROCESS, gettid() as libc::id_t, -15);
886            }
887            t_inner.capture_tid.store(gettid(), Ordering::Release);
888            // A worker panic must flip the liveness contract (started_ok/start_state):
889            // an unguarded unwind would leave is_capturing reporting true forever with
890            // no frames flowing and no error anywhere.
891            if let Err(payload) = std::panic::catch_unwind(std::panic::AssertUnwindSafe(body)) {
892                let what = payload
893                    .downcast_ref::<&str>()
894                    .map(|s| s.to_string())
895                    .or_else(|| payload.downcast_ref::<String>().cloned())
896                    .unwrap_or_else(|| "unknown panic payload".to_string());
897                t_inner.fail(format!("worker thread panicked: {what}"));
898            }
899            t_inner.capture_tid.store(0, Ordering::Release);
900        }) {
901        Ok(h) => {
902            let id = h.thread().id();
903            *guard = Some(h);
904            Some(id)
905        }
906        Err(_) => None,
907    }
908}
909
910/// Failed-start teardown: stop and join the thread `spawned` by THIS start attempt,
911/// but only if it still owns the slot.
912///
913/// A concurrent start may have already joined this thread and published a live replacement,
914/// which must not be torn down. The guard is an identity check: `ThreadId`s are never reused
915/// within a process, so it cannot false-match. When it does own the slot, the teardown is
916/// `join_held_worker`'s, like every other stop path.
917fn join_failed_start(slot: &Mutex<Option<JoinHandle<()>>>, inner: &Inner, spawned: ThreadId) {
918    let mut guard = slot.lock().unwrap_or_else(|e| e.into_inner());
919    if guard.as_ref().map(|h| h.thread().id()) != Some(spawned) {
920        return;
921    }
922    join_held_worker(&mut guard, inner);
923}
924
925/// Startup handshake shared by the capture and playback starts: waits up to ~2 s for the
926/// worker this call spawned (`spawned`) to publish `RUNNING` or `FAILED`. A worker still
927/// `STARTING` when the window closes counts as started — its retry ladder legitimately
928/// runs longer than this — and a failure after that is exposed through `state` /
929/// `last_error` instead. On `FAILED`, `join_failed_start` tears down only that thread
930/// (identity-checked, sparing a concurrent winner) and the worker's recorded error is
931/// returned as `Error::Start`.
932fn await_start(
933    slot: &Mutex<Option<JoinHandle<()>>>,
934    inner: &Inner,
935    spawned: ThreadId,
936    what: &str,
937) -> Result<(), Error> {
938    let mut state = inner.start_state.load(Ordering::Acquire);
939    if state == ST_STARTING {
940        for _ in 0..200 {
941            state = inner.start_state.load(Ordering::Acquire);
942            if state != ST_STARTING {
943                break;
944            }
945            std::thread::sleep(Duration::from_millis(10));
946        }
947    }
948    if state == ST_FAILED {
949        join_failed_start(slot, inner, spawned);
950        let why = inner
951            .last_error()
952            .unwrap_or_else(|| "unknown error".to_string());
953        return Err(Error::Start(format!("{what} failed to start: {why}")));
954    }
955    Ok(())
956}
957
958/// Bounded, drop-oldest byte queue for the mic-PCM handoff into the virtual
959/// "input" sink — the whole of the playback path's buffering in a single bound.
960///
961/// `push` runs on the writer's thread; `drain_upto` and `splice_head` run on the
962/// playback thread. Overflow discards the OLDEST bytes, keeping
963/// the newest window (mic audio is drift-tolerant and stale samples are worthless); the
964/// depth that stands below the bound is cut by the playback thread (`StandingDepth`).
965struct PlayQueue {
966    buf: Mutex<VecDeque<u8>>,
967    /// Bounds (re)published by `start()`; atomics so a restart can reconfigure the
968    /// `Arc`-shared queue in place without swapping it. `frame_bytes >= 1` (set at `new()`).
969    max_bytes: AtomicUsize,
970    frame_bytes: AtomicUsize,
971}
972
973impl PlayQueue {
974    fn new() -> Self {
975        PlayQueue {
976            buf: Mutex::new(VecDeque::new()),
977            max_bytes: AtomicUsize::new(96000),
978            frame_bytes: AtomicUsize::new(2),
979        }
980    }
981
982    /// Apply this run's byte bound and frame alignment, and drop any stale audio
983    /// left from a prior run. `frame_bytes` is floored to 1; the bound is floored
984    /// to a whole-frame multiple (min one frame) so overflow drops can never split
985    /// a sample frame.
986    fn configure(&self, max_bytes: usize, frame_bytes: usize) {
987        let fb = frame_bytes.max(1);
988        self.frame_bytes.store(fb, Ordering::Relaxed);
989        self.max_bytes
990            .store((max_bytes / fb * fb).max(fb), Ordering::Relaxed);
991        self.clear();
992    }
993
994    /// Drop everything queued, keeping the bounds. Used when a run starts and whenever the
995    /// playback session is reopened, since audio buffered across an outage is stale.
996    fn clear(&self) {
997        self.buf.lock().unwrap_or_else(|e| e.into_inner()).clear();
998    }
999
1000    /// Append client PCM, dropping the OLDEST whole frames once the queue passes
1001    /// the byte bound so the newest audio is always retained. Drops stay
1002    /// frame-aligned: trimming mid-frame would phase-shift every later drain into
1003    /// interleaved garbage.
1004    fn push(&self, data: &[u8]) {
1005        let max = self.max_bytes.load(Ordering::Relaxed);
1006        let fb = self.frame_bytes.load(Ordering::Relaxed);
1007        let mut q = self.buf.lock().unwrap_or_else(|e| e.into_inner());
1008        q.extend(data.iter().copied());
1009        let over = q.len().saturating_sub(max);
1010        if over > 0 {
1011            let drop = (over.div_ceil(fb) * fb).min(q.len());
1012            q.drain(..drop);
1013        }
1014    }
1015
1016    /// Drain up to `n` bytes into `out`, clamped to what is queued and floored to a
1017    /// whole frame, since a PA write must be a multiple of the sample-spec frame size.
1018    /// Returns the bytes left queued.
1019    fn drain_upto(&self, n: usize, out: &mut Vec<u8>) -> usize {
1020        let fb = self.frame_bytes.load(Ordering::Relaxed);
1021        let mut q = self.buf.lock().unwrap_or_else(|e| e.into_inner());
1022        let mut take = n.min(q.len());
1023        take -= take % fb;
1024        out.clear();
1025        out.extend(q.drain(..take));
1026        q.len()
1027    }
1028
1029    /// Cut `cut` bytes out right behind the head, the next audio the sink plays: the
1030    /// `fade` bytes at the head, which continue what the sink already holds, are blended
1031    /// linearly into the `fade` bytes after the cut, so the seam is a short crossfade
1032    /// rather than a step. Both are floored to whole frames, and nothing is cut unless
1033    /// `cut + fade` bytes are queued.
1034    fn splice_head(&self, cut: usize, fade: usize) {
1035        let fb = self.frame_bytes.load(Ordering::Relaxed);
1036        let (cut, fade) = (cut / fb * fb, fade / fb * fb);
1037        let mut q = self.buf.lock().unwrap_or_else(|e| e.into_inner());
1038        if cut == 0 || cut + fade > q.len() {
1039            return;
1040        }
1041        let channels = (fb / 2).max(1);
1042        let frames = (fade / fb) as f32;
1043        for i in (0..fade).step_by(2) {
1044            let w = ((i / 2 / channels) as f32 + 1.0) / (frames + 1.0);
1045            let a = f32::from(i16::from_le_bytes([q[i], q[i + 1]]));
1046            let b = f32::from(i16::from_le_bytes([q[cut + i], q[cut + i + 1]]));
1047            let [lo, hi] = ((a + (b - a) * w).round() as i16).to_le_bytes();
1048            q[cut + i] = lo;
1049            q[cut + i + 1] = hi;
1050        }
1051        q.drain(..cut);
1052    }
1053}
1054
1055/// The playback queue's standing depth, and when to cut it.
1056///
1057/// The bytes left queued after each drain are tracked at their minimum over a window of
1058/// one second of written audio. What stayed queued at every drain of a whole window was
1059/// never needed to ride out the uplink's jitter, which the sink's own buffer covers, so it
1060/// is pure delay: a burst after a network stall or a stalled tab, a client clock running
1061/// fast of the sink, or a sink that resumed late leaves it there, and with the drain rate
1062/// equal to the arrival rate it would stay for the rest of the session. A window that
1063/// closes with at least `min_cut` of it above `keep` cuts down to `keep`, the length of
1064/// the splice's crossfade; smaller excess waits, so drift is shed in a few cuts rather than
1065/// a splice every window.
1066struct StandingDepth {
1067    window: usize,
1068    keep: usize,
1069    min_cut: usize,
1070    frame_bytes: usize,
1071    written: usize,
1072    min_left: usize,
1073}
1074
1075impl StandingDepth {
1076    /// Size the window, the crossfade kept, and the least cut for a stream of
1077    /// `bytes_per_sec` in frames of `frame_bytes`: one second, 2 ms, and 10 ms.
1078    fn new(bytes_per_sec: usize, frame_bytes: usize) -> Self {
1079        let fb = frame_bytes.max(1);
1080        let frames = |ms: usize| (bytes_per_sec * ms / 1000 / fb).max(1) * fb;
1081        StandingDepth {
1082            window: frames(1000),
1083            keep: frames(2),
1084            min_cut: frames(10),
1085            frame_bytes: fb,
1086            written: 0,
1087            min_left: usize::MAX,
1088        }
1089    }
1090
1091    /// Start a fresh window, as after the queue was cleared.
1092    fn reset(&mut self) {
1093        self.written = 0;
1094        self.min_left = usize::MAX;
1095    }
1096
1097    /// Record one drain that wrote `written` bytes and left `left` queued; returns the
1098    /// bytes to cut when this drain closes a window over a standing excess.
1099    fn after_drain(&mut self, written: usize, left: usize) -> Option<usize> {
1100        self.written += written;
1101        self.min_left = self.min_left.min(left);
1102        if self.written < self.window {
1103            return None;
1104        }
1105        let excess = self.min_left.saturating_sub(self.keep);
1106        self.reset();
1107        (excess >= self.min_cut).then(|| excess / self.frame_bytes * self.frame_bytes)
1108    }
1109}
1110
1111/// Turns the mic uplink back into PCM: the client always sends the mic as Opus, so
1112/// every inbound packet must be decoded before it can be queued for the virtual sink. It
1113/// decodes one packet to interleaved S16LE PCM, reusing a scratch buffer across calls to
1114/// stay off the per-decode allocation path. Lives behind a `Mutex` on `PbShared` and is
1115/// driven from `write` / `write_red`.
1116struct OpusPlaybackDecoder {
1117    dec: OpusDec,
1118    channels: usize,
1119    pcm: Vec<i16>,
1120    /// RFC 2198 RED recovery cursor: the timestamp of the last frame decoded, so a
1121    /// redundant copy of a dropped frame is decoded exactly once, in order. `None` until
1122    /// the first RED frame arrives.
1123    last_ts: Option<i64>,
1124}
1125
1126/// Owning wrapper over a raw `OpusDecoder`.
1127///
1128/// The pointer is only touched from the thread holding the enclosing `Mutex`, which is what
1129/// makes the `unsafe impl Send` sound; `Drop` destroys the C decoder.
1130struct OpusDec {
1131    st: *mut opusic_sys::OpusDecoder,
1132}
1133
1134unsafe impl Send for OpusDec {}
1135
1136impl Drop for OpusDec {
1137    fn drop(&mut self) {
1138        unsafe { opusic_sys::opus_decoder_destroy(self.st) }
1139    }
1140}
1141
1142impl OpusPlaybackDecoder {
1143    /// Create a mono/stereo Opus decoder for the mic uplink; `None` if creation
1144    /// fails. `channels <= 1` decodes as mono, otherwise stereo.
1145    fn new(sample_rate: u32, channels: i32) -> Option<Self> {
1146        let mut err = 0;
1147        let st = unsafe {
1148            opusic_sys::opus_decoder_create(
1149                sample_rate as i32,
1150                if channels <= 1 { 1 } else { 2 },
1151                &mut err,
1152            )
1153        };
1154        if st.is_null() || err != 0 {
1155            return None;
1156        }
1157        let dec = OpusDec { st };
1158        Some(OpusPlaybackDecoder {
1159            dec,
1160            channels: channels.max(1) as usize,
1161            pcm: Vec::new(),
1162            last_ts: None,
1163        })
1164    }
1165
1166    /// Decode one Opus packet and return the interleaved S16LE PCM as bytes, or `None`
1167    /// for an empty or undecodable packet.
1168    ///
1169    /// The scratch `pcm` buffer is grown once to `5760 * channels` — an Opus packet decodes
1170    /// to at most 120 ms, which is 5760 samples per channel at 48 kHz — then reused across
1171    /// calls, and the result is a view straight over it, so a decode never allocates. The
1172    /// view borrows the decoder, so callers must queue it before decoding the next packet.
1173    /// Reinterpreting the samples as S16LE bytes assumes a little-endian host, exactly as
1174    /// the capture side does when it fills `accum` from PulseAudio fragments.
1175    fn decode_to_pcm(&mut self, packet: &[u8]) -> Option<&[u8]> {
1176        if packet.is_empty() {
1177            return None;
1178        }
1179        let cap = 5760 * self.channels;
1180        if self.pcm.len() < cap {
1181            self.pcm.resize(cap, 0);
1182        }
1183        let samples = unsafe {
1184            opusic_sys::opus_decode(
1185                self.dec.st,
1186                packet.as_ptr(),
1187                packet.len() as i32,
1188                self.pcm.as_mut_ptr(),
1189                (cap / self.channels) as i32,
1190                0,
1191            )
1192        };
1193        if samples < 0 {
1194            return None;
1195        }
1196        let n = samples as usize * self.channels;
1197        Some(bytemuck::cast_slice(&self.pcm[..n]))
1198    }
1199
1200    /// Reconstruct the mic uplink across packet loss: recover any frames the sender
1201    /// dropped from the redundant copies RED carries, and decode each new frame exactly once
1202    /// into `queue`. This is what lets a lossy UDP/WebRTC uplink play through gaps without ever
1203    /// waiting for a retransmit. The work is pure byte-slicing plus Opus decode on the
1204    /// writer's thread, so the Python bridge runs it with the GIL released.
1205    ///
1206    /// 1. **Parse the block headers** (`red::red_blocks`): walk the redundant headers (F bit
1207    ///    set) collecting each block's 14-bit timestamp offset and 10-bit length, then consume
1208    ///    the 1-byte primary header (F bit clear). A truncated payload, or more redundancy than
1209    ///    `RED_MAX_DISTANCE`, bails out.
1210    /// 2. **Resolve block boundaries**: turn the headers into `(ts, start, len)` triples,
1211    ///    oldest-first, where each redundant `ts` is `primary_ts - offset` and the primary is
1212    ///    whatever bytes remain.
1213    /// 3. **Anchor the first packet**: with no prior `last_ts`, decode only the primary and set
1214    ///    `last_ts` to it — its trailing redundancy describes frames never played, so it is not
1215    ///    replayed.
1216    /// 4. **Recover and advance**: otherwise decode every block whose `ts` is strictly newer
1217    ///    than `last_ts` (in oldest-first order, so a gap left by a dropped packet is filled
1218    ///    before the primary), pushing PCM to `queue` and advancing `last_ts`. Blocks at or
1219    ///    below `last_ts` are already-played duplicates and are skipped — the timestamp dedup
1220    ///    that makes redundancy free of double-decoding under no loss.
1221    fn decode_red_into_queue(&mut self, payload: &[u8], primary_ts: i64, queue: &PlayQueue) {
1222        let Some((frames, nf)) = red::red_blocks(payload, primary_ts) else {
1223            return;
1224        };
1225
1226        if self.last_ts.is_none() {
1227            let (ts, start, len) = frames[nf - 1];
1228            if len > 0
1229                && let Some(pcm) = self.decode_to_pcm(&payload[start..start + len])
1230            {
1231                queue.push(pcm);
1232            }
1233            self.last_ts = Some(ts);
1234            return;
1235        }
1236        let mut last = self.last_ts.unwrap();
1237        for &(ts, start, len) in frames.iter().take(nf) {
1238            // RTP timestamps are 32-bit and wrap; compare serial-number style so a
1239            // wraparound isn't mistaken for "already played" (ts > last would fail
1240            // for every frame after the rollover).
1241            let newer = ((ts.wrapping_sub(last)) as i32) > 0;
1242            if len > 0 && newer {
1243                if let Some(pcm) = self.decode_to_pcm(&payload[start..start + len]) {
1244                    queue.push(pcm);
1245                }
1246                last = ts;
1247            }
1248        }
1249        self.last_ts = Some(last);
1250    }
1251}
1252
1253/// Per-`AudioPlayback` shared handle — the mirror of `Shared` for the playback path.
1254///
1255/// Reuses the capture lifecycle core on `Inner` (the `stop_state` protocol, the start
1256/// handshake, and the worker-tid re-entrancy guard); the Opus/silence settings mirrors on
1257/// `Inner` are unused here. Adds the bounded PCM `queue` and the always-Opus mic decoder.
1258struct PbShared {
1259    inner: Arc<Inner>,
1260    thread: Mutex<Option<JoinHandle<()>>>,
1261    queue: Arc<PlayQueue>,
1262    /// The mic uplink is always Opus; `write` / `write_red` decode each packet through this
1263    /// before enqueuing PCM. Set at `start()`; `None` only before a successful start.
1264    opus_dec: Mutex<Option<OpusPlaybackDecoder>>,
1265}
1266
1267/// Process-wide registry of live playbacks, swept by `stop_all` as captures are. Holds
1268/// `Weak` references so it keeps nothing alive on its own.
1269static PLAYBACK_REGISTRY: OnceLock<Mutex<Vec<Weak<PbShared>>>> = OnceLock::new();
1270/// Lazily initialize and return the playback registry.
1271fn playback_registry() -> &'static Mutex<Vec<Weak<PbShared>>> {
1272    PLAYBACK_REGISTRY.get_or_init(|| Mutex::new(Vec::new()))
1273}
1274
1275/// Run one bounded iteration of a PulseAudio standard mainloop:
1276/// `prepare(timeout_us)` → `poll` → `dispatch`. Returns `false` if any stage errors.
1277///
1278/// The `timeout_us` bound is what makes a pending stop observable within ~20 ms even when
1279/// the audio source delivers nothing, since every loop that calls this re-checks
1280/// `stop_pending()` between pumps.
1281fn pump(ml: &mut pulse::mainloop::standard::Mainloop, timeout_us: u64) -> bool {
1282    if ml.prepare(Some(MicroSeconds(timeout_us))).is_err() {
1283        return false;
1284    }
1285    if ml.poll().is_err() {
1286        return false;
1287    }
1288    if ml.dispatch().is_err() {
1289        return false;
1290    }
1291    true
1292}
1293
1294/// Chromium's multistream-Opus surround layout for a channel count, as
1295/// `(streams, coupled, mapping)`; `None` for anything but 5.1 (6) or 7.1 (8).
1296///
1297/// The same tables are advertised in the WebRTC SDP (`multiopus`), so the browser's decoder
1298/// inverts exactly the stream/coupling/mapping this encoder applies.
1299fn multiopus_layout(channels: i32) -> Option<(i32, i32, &'static [u8])> {
1300    match channels {
1301        6 => Some((4, 2, &[0, 4, 1, 2, 3, 5])),
1302        8 => Some((5, 3, &[0, 6, 1, 2, 3, 4, 5, 7])),
1303        _ => None,
1304    }
1305}
1306
1307/// The speaker positions the surround encoder takes its input channels as, in order, as a
1308/// PulseAudio channel map: Chromium's 5.1 and 7.1 orders (left, right, center, LFE, then the
1309/// surround pair, and at 7.1 the back pair before the side one), which its `multiopus`
1310/// decoder hands to the output layout. The record stream asks for this map, so the sound
1311/// server remixes the source's own layout into it. Without one, libpulse gives a stream its
1312/// AIFF default, which at six channels names front-left-of-center, front-right-of-center, and
1313/// rear-center instead of the surround pair and LFE, and at eight has no map at all, so the
1314/// stream cannot even be created. `None` for mono and stereo, whose defaults are right.
1315fn surround_channel_map(channels: i32) -> Option<&'static str> {
1316    match channels {
1317        6 => Some("front-left,front-right,front-center,lfe,rear-left,rear-right"),
1318        8 => Some(
1319            "front-left,front-right,front-center,lfe,rear-left,rear-right,side-left,side-right",
1320        ),
1321        _ => None,
1322    }
1323}
1324
1325/// Fold one surround frame (`surround_channel_map` order) to interleaved stereo, `dst`
1326/// holding the frame's samples per channel twice: each side takes its front channel at
1327/// unity and the center and its surround channels at -3 dB (ITU-R BS.775, the LFE left
1328/// out), saturating rather than wrapping, as a browser's own speaker downmix of the
1329/// surround stream sounds.
1330fn downmix_stereo(src: &[i16], channels: usize, dst: &mut [i16]) {
1331    const K: f32 = std::f32::consts::FRAC_1_SQRT_2;
1332    for (f, out) in dst.as_chunks_mut::<2>().0.iter_mut().enumerate() {
1333        let s = &src[f * channels..(f + 1) * channels];
1334        let center = K * f32::from(s[2]);
1335        let mut left = f32::from(s[0]) + center + K * f32::from(s[4]);
1336        let mut right = f32::from(s[1]) + center + K * f32::from(s[5]);
1337        if channels >= 8 {
1338            left += K * f32::from(s[6]);
1339            right += K * f32::from(s[7]);
1340        }
1341        out[0] = left.round().clamp(f32::from(i16::MIN), f32::from(i16::MAX)) as i16;
1342        out[1] = right
1343            .round()
1344            .clamp(f32::from(i16::MIN), f32::from(i16::MAX)) as i16;
1345    }
1346}
1347
1348/// One encode surface over both Opus APIs: the single-stream C encoder for mono/stereo, and
1349/// the multistream one for 6/8-channel surround.
1350enum PcmEncoder {
1351    Stereo(MonoOpus),
1352    Multi(MultiOpus),
1353}
1354
1355/// Owning wrapper over a raw `OpusEncoder` (the mono/stereo single-stream encoder).
1356///
1357/// Owned by the capture thread exactly as `MultiOpus` is; `Drop` destroys the C encoder.
1358struct MonoOpus {
1359    st: *mut opusic_sys::OpusEncoder,
1360}
1361
1362unsafe impl Send for MonoOpus {}
1363
1364impl Drop for MonoOpus {
1365    fn drop(&mut self) {
1366        unsafe { opusic_sys::opus_encoder_destroy(self.st) }
1367    }
1368}
1369
1370/// Owning wrapper over a raw `OpusMSEncoder` (the surround multistream encoder).
1371///
1372/// The raw pointer is only ever touched from the capture thread that owns the enclosing
1373/// `RunState`, which is what makes the `unsafe impl Send` below sound; `Drop` destroys the
1374/// C encoder.
1375struct MultiOpus {
1376    st: *mut opusic_sys::OpusMSEncoder,
1377}
1378
1379unsafe impl Send for MultiOpus {}
1380
1381impl Drop for MultiOpus {
1382    fn drop(&mut self) {
1383        unsafe { opusic_sys::opus_multistream_encoder_destroy(self.st) }
1384    }
1385}
1386
1387impl PcmEncoder {
1388    /// Build the Opus encoder for a channel count, selecting the API by width.
1389    ///
1390    /// - **Mono/stereo** (`channels <= 2`): the single-stream C encoder in
1391    ///   `RESTRICTED_LOWDELAY`; a failure to apply the initial bitrate or VBR mode is logged
1392    ///   but not fatal.
1393    /// - **Surround** (6/8): the raw multistream C encoder created from `multiopus_layout`
1394    ///   in `RESTRICTED_LOWDELAY`; an unsupported channel count is a hard error.
1395    ///
1396    /// Bitrate, VBR, and a `Some` complexity are applied at creation; `None` sends no complexity
1397    /// request, leaving libopus's default. Bitrate can be retuned live via `set_bitrate`.
1398    fn new(
1399        sample_rate: u32,
1400        channels: i32,
1401        vbr: bool,
1402        bitrate: i32,
1403        complexity: Option<i32>,
1404    ) -> Result<Self, String> {
1405        if channels <= 2 {
1406            let mut err = 0;
1407            let st = unsafe {
1408                opusic_sys::opus_encoder_create(
1409                    sample_rate as i32,
1410                    if channels == 1 { 1 } else { 2 },
1411                    opusic_sys::OPUS_APPLICATION_RESTRICTED_LOWDELAY,
1412                    &mut err,
1413                )
1414            };
1415            if st.is_null() || err != 0 {
1416                return Err(format!("opus_encoder_create() failed: {err}"));
1417            }
1418            let enc = MonoOpus { st };
1419            unsafe {
1420                if opusic_sys::opus_encoder_ctl(st, opusic_sys::OPUS_SET_BITRATE_REQUEST, bitrate)
1421                    != 0
1422                {
1423                    elog!("[pcmflux] WARNING: failed to apply initial bitrate");
1424                }
1425                if opusic_sys::opus_encoder_ctl(
1426                    st,
1427                    opusic_sys::OPUS_SET_VBR_REQUEST,
1428                    i32::from(vbr),
1429                ) != 0
1430                {
1431                    elog!("[pcmflux] WARNING: failed to apply VBR mode");
1432                }
1433                if let Some(c) = complexity
1434                    && opusic_sys::opus_encoder_ctl(st, opusic_sys::OPUS_SET_COMPLEXITY_REQUEST, c)
1435                        != 0
1436                {
1437                    elog!("[pcmflux] WARNING: failed to apply complexity");
1438                }
1439            }
1440            return Ok(PcmEncoder::Stereo(enc));
1441        }
1442        let (streams, coupled, mapping) = multiopus_layout(channels)
1443            .ok_or_else(|| format!("unsupported surround channel count {channels}"))?;
1444        unsafe {
1445            let mut err: i32 = 0;
1446            let st = opusic_sys::opus_multistream_encoder_create(
1447                sample_rate as i32,
1448                channels,
1449                streams,
1450                coupled,
1451                mapping.as_ptr(),
1452                opusic_sys::OPUS_APPLICATION_RESTRICTED_LOWDELAY,
1453                &mut err,
1454            );
1455            if st.is_null() || err != 0 {
1456                return Err(format!("opus_multistream_encoder_create() failed: {err}"));
1457            }
1458            if opusic_sys::opus_multistream_encoder_ctl(
1459                st,
1460                opusic_sys::OPUS_SET_BITRATE_REQUEST,
1461                bitrate,
1462            ) != 0
1463            {
1464                elog!("[pcmflux] WARNING: failed to apply initial surround bitrate");
1465            }
1466            if opusic_sys::opus_multistream_encoder_ctl(
1467                st,
1468                opusic_sys::OPUS_SET_VBR_REQUEST,
1469                i32::from(vbr),
1470            ) != 0
1471            {
1472                elog!("[pcmflux] WARNING: failed to apply surround VBR mode");
1473            }
1474            if let Some(c) = complexity
1475                && opusic_sys::opus_multistream_encoder_ctl(
1476                    st,
1477                    opusic_sys::OPUS_SET_COMPLEXITY_REQUEST,
1478                    c,
1479                ) != 0
1480            {
1481                elog!("[pcmflux] WARNING: failed to apply surround complexity");
1482            }
1483            Ok(PcmEncoder::Multi(MultiOpus { st }))
1484        }
1485    }
1486
1487    /// Encode one interleaved-PCM frame into `out`, returning the packet byte length.
1488    ///
1489    /// Dispatches to the `opus` crate (mono/stereo) or the raw multistream encode (surround,
1490    /// which needs the explicit `frame_size_per_channel`). Either error surfaces as a `String`.
1491    fn encode(
1492        &mut self,
1493        pcm: &[i16],
1494        frame_size_per_channel: usize,
1495        out: &mut [u8],
1496    ) -> Result<usize, String> {
1497        match self {
1498            PcmEncoder::Stereo(enc) => unsafe {
1499                let n = opusic_sys::opus_encode(
1500                    enc.st,
1501                    pcm.as_ptr(),
1502                    frame_size_per_channel as i32,
1503                    out.as_mut_ptr(),
1504                    out.len() as i32,
1505                );
1506                if n < 0 {
1507                    Err(format!("opus_encode() failed: {n}"))
1508                } else {
1509                    Ok(n as usize)
1510                }
1511            },
1512            PcmEncoder::Multi(ms) => unsafe {
1513                let n = opusic_sys::opus_multistream_encode(
1514                    ms.st,
1515                    pcm.as_ptr(),
1516                    frame_size_per_channel as i32,
1517                    out.as_mut_ptr(),
1518                    out.len() as i32,
1519                );
1520                if n < 0 {
1521                    Err(format!("opus_multistream_encode() failed: {n}"))
1522                } else {
1523                    Ok(n as usize)
1524                }
1525            },
1526        }
1527    }
1528
1529    /// The encoder's look-ahead in input samples: what a decoder discards first.
1530    fn lookahead(&mut self) -> i32 {
1531        match self {
1532            PcmEncoder::Stereo(enc) => unsafe {
1533                let mut value: i32 = 0;
1534                let ret = opusic_sys::opus_encoder_ctl(
1535                    enc.st,
1536                    opusic_sys::OPUS_GET_LOOKAHEAD_REQUEST,
1537                    &mut value as *mut i32,
1538                );
1539                if ret == 0 { value } else { 0 }
1540            },
1541            PcmEncoder::Multi(ms) => unsafe {
1542                let mut value: i32 = 0;
1543                let ret = opusic_sys::opus_multistream_encoder_ctl(
1544                    ms.st,
1545                    opusic_sys::OPUS_GET_LOOKAHEAD_REQUEST,
1546                    &mut value as *mut i32,
1547                );
1548                if ret == 0 { value } else { 0 }
1549            },
1550        }
1551    }
1552
1553    /// Retune the encoder's target bitrate live (bits/s), for either API.
1554    fn set_bitrate(&mut self, bits: i32) -> Result<(), String> {
1555        match self {
1556            PcmEncoder::Stereo(enc) => unsafe {
1557                let ret = opusic_sys::opus_encoder_ctl(
1558                    enc.st,
1559                    opusic_sys::OPUS_SET_BITRATE_REQUEST,
1560                    bits,
1561                );
1562                if ret != 0 {
1563                    Err(format!("ctl error {ret}"))
1564                } else {
1565                    Ok(())
1566                }
1567            },
1568            PcmEncoder::Multi(ms) => unsafe {
1569                let ret = opusic_sys::opus_multistream_encoder_ctl(
1570                    ms.st,
1571                    opusic_sys::OPUS_SET_BITRATE_REQUEST,
1572                    bits,
1573                );
1574                if ret != 0 {
1575                    Err(format!("ctl error {ret}"))
1576                } else {
1577                    Ok(())
1578                }
1579            },
1580        }
1581    }
1582}
1583
1584/// Backing store for the delivery ring: `Some(queue)` while open, `None` once closed
1585/// so `pop` wakes and returns `None` for a clean shutdown.
1586type FrameQueue = Option<VecDeque<(Vec<u8>, u64, u8)>>;
1587
1588/// Bounded, drop-oldest hand-off from the capture thread to the delivery thread that runs
1589/// the sink, so a slow or blocked sink can never stall the PulseAudio pump.
1590///
1591/// The capture thread `push`es encoded `(frame, pts)` pairs; the delivery thread blocks in
1592/// `pop`. Stale audio is worthless, so overflow past `capacity` (a few frames of slack)
1593/// discards the OLDEST frame and bumps `dropped`. `close` empties the queue to `None` and
1594/// wakes the consumer so it exits.
1595struct DeliveryRing {
1596    q: Mutex<FrameQueue>,
1597    cv: Condvar,
1598    dropped: AtomicU64,
1599    capacity: usize,
1600}
1601
1602impl DeliveryRing {
1603    /// Create an open ring pre-sized to `capacity` frames.
1604    fn new(capacity: usize) -> Self {
1605        Self {
1606            q: Mutex::new(Some(VecDeque::with_capacity(capacity))),
1607            cv: Condvar::new(),
1608            dropped: AtomicU64::new(0),
1609            capacity,
1610        }
1611    }
1612
1613    /// Enqueue one encoded frame, dropping the oldest (and bumping `dropped`) if the
1614    /// ring is at capacity, then wake the consumer. A no-op once closed.
1615    fn push(&self, data: Vec<u8>, pts: u64, channels: u8) -> Option<Vec<u8>> {
1616        let mut g = self.q.lock().unwrap_or_else(|e| e.into_inner());
1617        let Some(q) = g.as_mut() else {
1618            return Some(data);
1619        };
1620        if q.len() >= self.capacity {
1621            q.pop_front();
1622            self.dropped.fetch_add(1, Ordering::Relaxed);
1623        }
1624        q.push_back((data, pts, channels));
1625        self.cv.notify_one();
1626        None
1627    }
1628
1629    /// Block until a frame is available and return it, or return `None` once the ring
1630    /// is closed and drained — the delivery thread's loop condition.
1631    fn pop(&self) -> Option<(Vec<u8>, u64, u8)> {
1632        let mut g = self.q.lock().unwrap_or_else(|e| e.into_inner());
1633        loop {
1634            {
1635                let q = g.as_mut()?;
1636                if let Some(item) = q.pop_front() {
1637                    return Some(item);
1638                }
1639            }
1640            g = self.cv.wait(g).unwrap_or_else(|e| e.into_inner());
1641        }
1642    }
1643
1644    /// Close the ring: drop any queued frames and wake every waiter so `pop` returns
1645    /// `None`, and hand every later `push` its buffer back. Called during capture teardown
1646    /// to join the delivery thread, and up front by a run that has no callback.
1647    fn close(&self) {
1648        *self.q.lock().unwrap_or_else(|e| e.into_inner()) = None;
1649        self.cv.notify_all();
1650    }
1651}
1652
1653/// Owns the delivery thread for the lifetime of one capture run and tears it down on
1654/// `Drop`, so teardown also happens when the capture thread UNWINDS.
1655///
1656/// Closing the ring is the delivery thread's only wake-up: skip it and the thread parks
1657/// in `pop()` forever, pinning the sink and leaving `deliver_tid` set to a tid the OS may
1658/// hand to an unrelated thread (whose `stop` would then be mistaken for a re-entrant
1659/// self-stop and silently do nothing).
1660struct DeliveryThread<'a> {
1661    ring: Arc<DeliveryRing>,
1662    inner: &'a Inner,
1663    join: Option<JoinHandle<()>>,
1664}
1665
1666impl Drop for DeliveryThread<'_> {
1667    fn drop(&mut self) {
1668        self.ring.close();
1669        if let Some(j) = self.join.take() {
1670            let _ = j.join();
1671        }
1672        self.inner.deliver_tid.store(0, Ordering::Release);
1673    }
1674}
1675
1676/// Recycles outgoing frame buffers from dropped `AudioFrame`s back to the capture
1677/// thread, so the steady-state emit path allocates nothing.
1678///
1679/// INVARIANT: every buffer is born as `vec![0u8; buf_size]`, so bytes `[0, buf_size)` stay
1680/// initialized for the allocation's whole lifetime — `truncate` only shortens `len`, never
1681/// de-initializes memory. That is what makes `restore`'s `set_len` back to `buf_size` sound.
1682struct BufferPool {
1683    bufs: Mutex<Vec<Vec<u8>>>,
1684    buf_size: usize,
1685}
1686
1687impl BufferPool {
1688    /// Cap on pooled buffers. Outstanding frames rarely exceed the delivery-ring
1689    /// capacity plus a few the sink still holds; anything past this goes back to the
1690    /// allocator rather than growing the pool unboundedly.
1691    const MAX_POOLED: usize = 16;
1692
1693    /// Create an empty pool that hands out (and accepts) `buf_size`-byte buffers.
1694    fn new(buf_size: usize) -> Self {
1695        Self {
1696            bufs: Mutex::new(Vec::new()),
1697            buf_size,
1698        }
1699    }
1700
1701    /// Take a fully initialized buffer of exactly `buf_size` length, recycling a
1702    /// pooled one when available. The runtime path takes through `PoolTaker`; this direct,
1703    /// locking form serves the unit tests.
1704    #[cfg(test)]
1705    fn take(&self) -> Vec<u8> {
1706        let recycled = self.bufs.lock().unwrap_or_else(|e| e.into_inner()).pop();
1707        match recycled {
1708            Some(v) => self.restore(v),
1709            None => vec![0u8; self.buf_size],
1710        }
1711    }
1712
1713    /// Restore a recycled buffer to full `buf_size` length via `set_len`.
1714    ///
1715    /// Sound per the pool invariant: the bytes were written at allocation and truncation
1716    /// does not de-initialize them, so extending `len` back to `buf_size` never exposes
1717    /// uninitialized memory.
1718    fn restore(&self, mut v: Vec<u8>) -> Vec<u8> {
1719        debug_assert!(v.capacity() >= self.buf_size);
1720        unsafe { v.set_len(self.buf_size) };
1721        v
1722    }
1723
1724    /// Return a buffer to the pool, unless it is undersized or the pool is already at
1725    /// `MAX_POOLED` (in which case it is dropped to the allocator).
1726    fn put(&self, v: Vec<u8>) {
1727        if v.capacity() < self.buf_size {
1728            return;
1729        }
1730        let mut g = self.bufs.lock().unwrap_or_else(|e| e.into_inner());
1731        if g.len() < Self::MAX_POOLED {
1732            g.push(v);
1733        }
1734    }
1735
1736    /// Move every pooled buffer into `into` under a single lock — the batched refill
1737    /// for the sole-consumer `PoolTaker`, whose empty local stash is `into`.
1738    fn drain_into(&self, into: &mut Vec<Vec<u8>>) {
1739        let mut g = self.bufs.lock().unwrap_or_else(|e| e.into_inner());
1740        std::mem::swap(&mut *g, into);
1741    }
1742}
1743
1744/// Sole-consumer view over the shared `BufferPool` for the capture thread.
1745///
1746/// Refills are batched into a `local` stash, so the per-frame `take` is lock-free in the
1747/// steady state, while returns from the sink's side (`AudioFrame` drops) still go back
1748/// through the shared pool. Only the capture thread owns a `PoolTaker`.
1749struct PoolTaker {
1750    pool: Arc<BufferPool>,
1751    local: Vec<Vec<u8>>,
1752}
1753
1754impl PoolTaker {
1755    /// Wrap a shared pool with an empty local stash.
1756    fn new(pool: Arc<BufferPool>) -> Self {
1757        Self {
1758            pool,
1759            local: Vec::new(),
1760        }
1761    }
1762
1763    /// Take one `buf_size` buffer: pop from the local stash, batch-refilling it from
1764    /// the shared pool (one lock) only when empty, and allocating fresh when both are empty.
1765    fn take(&mut self) -> Vec<u8> {
1766        if self.local.is_empty() {
1767            self.pool.drain_into(&mut self.local);
1768        }
1769        match self.local.pop() {
1770            Some(v) => self.pool.restore(v),
1771            None => vec![0u8; self.pool.buf_size],
1772        }
1773    }
1774
1775    /// Return a buffer on an error path without locking — it stays in the local stash.
1776    fn put(&mut self, v: Vec<u8>) {
1777        if v.capacity() >= self.pool.buf_size && self.local.len() < BufferPool::MAX_POOLED {
1778            self.local.push(v);
1779        }
1780    }
1781}
1782
1783/// Per-run encode/deliver state, living on the capture thread's stack for the
1784/// lifetime of one capture. Holds the encoder, the frame-reassembly buffers, the outgoing
1785/// buffer recycler, the RED redundancy history, and the running debug-log counters.
1786struct RunState<'a> {
1787    inner: &'a Inner,
1788    ring: &'a DeliveryRing,
1789    encoder: PcmEncoder,
1790    frame_size_per_channel: usize,
1791    channels: usize,
1792    /// Reassembly buffer for exactly one Opus frame (`i16` samples, filled byte-wise from
1793    /// the incoming PulseAudio fragments).
1794    accum: Vec<i16>,
1795    /// A zeroed reference of the same length as `accum`; comparing `accum == silence_ref`
1796    /// lowers to a single vectorized memcmp for the silence gate, versus a scalar per-sample
1797    /// scan.
1798    silence_ref: Vec<i16>,
1799    pcm_fill_bytes: usize,
1800    /// Outgoing-buffer recycler, shared with delivered `AudioFrame`s whose drop refills it.
1801    pool: PoolTaker,
1802    /// RFC 2198 redundancy history: the last `red_distance` emitted `(opus, pts)` frames,
1803    /// oldest-first. Per-run — reset on start, and the frame size is fixed for a run.
1804    red_history: VecDeque<(Vec<u8>, u64)>,
1805    /// Retired `red_history` buffers, reused for the next entry so the steady state (a
1806    /// silence gap included) allocates nothing. Bounded by `red_distance`: every buffer
1807    /// is either in the history or here.
1808    red_spare: Vec<Vec<u8>>,
1809    red_distance: usize,
1810    /// Whether the last frame was emitted as sound, so the gate lets the silent frame after it
1811    /// through when that frame carries the end of the sound (always on a header capture, behind
1812    /// the bare `WS_QUIET` mark and marked itself; on a raw capture when `tail_sounding`), and a
1813    /// session that drops after it sends the bare mark once.
1814    sounding: bool,
1815    /// Whether that frame of sound held sound in its last `lookahead` samples, the part the
1816    /// encoder holds back until the next frame.
1817    tail_sounding: bool,
1818    /// The encoder's lookahead in samples per channel (`PcmEncoder::lookahead`).
1819    lookahead: usize,
1820    /// A surround capture's stereo encoder and its downmix scratch, for
1821    /// `Inner::stereo_companion`; `None` for mono and stereo captures.
1822    companion: Option<(PcmEncoder, Vec<i16>)>,
1823    /// The bitrate the companion encoder was last given; follows the capture's.
1824    companion_bitrate: i32,
1825    total_samples_processed: u64,
1826    /// The Ogg Opus stream on the output socket, and the 48 kHz samples one input
1827    /// sample is worth for its granule positions.
1828    ogg: Option<ogg_sink::OggSink>,
1829    ogg_scale: u64,
1830    first_sound_detected: bool,
1831    current_applied_bitrate: i32,
1832    chunks_read: u64,
1833    chunks_silent: u64,
1834    chunks_encoded: u64,
1835    bytes_encoded: u64,
1836}
1837
1838impl<'a> RunState<'a> {
1839    /// Feed one PulseAudio PCM fragment into the reassembly buffer, emitting a frame
1840    /// each time `accum` fills to exactly one Opus frame.
1841    ///
1842    /// Fragments arrive at arbitrary byte boundaries, so this copies from `src` into `accum`
1843    /// at `pcm_fill_bytes`, calling `emit_frame` (and resetting the fill cursor) whenever a
1844    /// full `frame_size_per_channel * channels * 2`-byte chunk accumulates, and loops until
1845    /// `src` is drained. Any partial remainder is carried into the next fragment.
1846    fn feed(&mut self, mut src: &[u8]) {
1847        let chunk_bytes = self.frame_size_per_channel * self.channels * 2;
1848        while !src.is_empty() {
1849            let want = chunk_bytes - self.pcm_fill_bytes;
1850            let take = want.min(src.len());
1851            {
1852                let dst: &mut [u8] = bytemuck::cast_slice_mut(&mut self.accum);
1853                dst[self.pcm_fill_bytes..self.pcm_fill_bytes + take].copy_from_slice(&src[..take]);
1854            }
1855            self.pcm_fill_bytes += take;
1856            src = &src[take..];
1857            if self.pcm_fill_bytes == chunk_bytes {
1858                self.emit_frame();
1859                self.pcm_fill_bytes = 0;
1860            }
1861        }
1862    }
1863
1864    /// Encode one reassembled frame and hand it to the delivery thread. The heart of
1865    /// the capture encode path.
1866    ///
1867    /// 1. **Dynamic bitrate**: re-reads the `opus_bitrate` mirror and reconfigures the encoder
1868    ///    only when it changed, so a live bitrate update costs nothing on unchanged frames.
1869    /// 2. **Timestamp**: `pts` is the running 48 kHz-domain sample count
1870    ///    (`total_samples_processed`) *before* this frame, then advanced by
1871    ///    `frame_size_per_channel` — a monotonic per-frame timestamp used for RED offsets and
1872    ///    client-side ordering.
1873    /// 3. **Silence gate**: when enabled, a frame equal to the zeroed `silence_ref` is counted
1874    ///    and dropped (no Opus is sent), so pure silence costs no bandwidth. The first one after
1875    ///    sound can carry the end of that sound, the part the encoder held back (its
1876    ///    lookahead). A header capture always sends it: the bare `WS_QUIET` mark goes first,
1877    ///    then that frame with `WS_QUIET` set. A raw Opus capture sends it only when the sound
1878    ///    reached into that lookahead (`tail_sounding`): a WebRTC receiver's jitter buffer
1879    ///    fades the sound after a pause in from what it concealed, and concealing from a frame
1880    ///    of silence faded more short sounds than concealing from the sound itself, while a
1881    ///    frame that ends a sound loses nothing of it. The first non-silent frame logs once.
1882    /// 4. **Encode in place**: `write_ws_prefix_into` writes the RFC 2198 RED framing prefix
1883    ///    (which depends only on `pts` + history) into a pooled buffer, and the Opus packet is
1884    ///    encoded DIRECTLY after it — no assembly copy, and the buffer recycles through the
1885    ///    pool, so the steady state allocates nothing. An encode error or a zero-length packet
1886    ///    returns the buffer to the pool and drops the frame.
1887    /// 5. **Retain redundancy**: with `red_distance > 0`, the just-encoded primary is copied
1888    ///    onto `red_history` (bounded, oldest-first) to serve as a future redundant copy,
1889    ///    into the buffer the retiring entry hands back.
1890    /// 6. **Hand off**: the truncated buffer is pushed to the `DeliveryRing`; the capture
1891    ///    thread itself never calls the sink.
1892    fn emit_frame(&mut self) {
1893        self.chunks_read += 1;
1894
1895        let requested = self.inner.opus_bitrate.load(Ordering::Relaxed);
1896        if requested != self.current_applied_bitrate {
1897            match self.encoder.set_bitrate(requested) {
1898                Ok(()) => {
1899                    plog!(
1900                        "[pcmflux] Dynamic Bitrate Update: {} -> {} kbps",
1901                        self.current_applied_bitrate / 1000,
1902                        requested / 1000
1903                    );
1904                    self.current_applied_bitrate = requested;
1905                }
1906                Err(e) => {
1907                    // current_applied_bitrate stays put, so the next frame retries the
1908                    // rejected value instead of latching it as if it had been applied.
1909                    elog!("[pcmflux] Failed to update bitrate ({requested}): {e:?}");
1910                }
1911            }
1912        }
1913
1914        let pts = self.total_samples_processed;
1915        self.total_samples_processed += self.frame_size_per_channel as u64;
1916
1917        let emit_header = self.inner.emit_audio_header.load(Ordering::Relaxed);
1918        let silent =
1919            self.inner.use_silence_gate.load(Ordering::Relaxed) && self.accum == self.silence_ref;
1920        if silent && !(self.sounding && (emit_header || self.tail_sounding)) {
1921            self.sounding = false;
1922            self.chunks_silent += 1;
1923            // Flush the RED backlog: if these pre-silence frames were kept, the first
1924            // packet after a long quiet stretch would ship minutes-old audio as
1925            // "redundant" data, and a receiver could reconstruct it into the gap. The
1926            // emptied buffers are kept for reuse, so a silence gap costs no allocations.
1927            self.red_spare
1928                .extend(self.red_history.drain(..).map(|(v, _)| v));
1929            return;
1930        }
1931        if !self.first_sound_detected {
1932            plog!("[pcmflux] First non-silent audio chunk detected! Encoding...");
1933            self.first_sound_detected = true;
1934        }
1935
1936        let n = self.frame_size_per_channel * self.channels;
1937        let mut data = self.pool.take();
1938        let prefix = write_ws_prefix_into(
1939            &mut data,
1940            pts,
1941            &self.red_history,
1942            self.red_distance,
1943            emit_header,
1944        );
1945        let encoded = match self.encoder.encode(
1946            &self.accum[..n],
1947            self.frame_size_per_channel,
1948            &mut data[prefix..],
1949        ) {
1950            Ok(b) => b,
1951            Err(e) => {
1952                elog!("[pcmflux] ERROR: {e}");
1953                self.pool.put(data);
1954                return;
1955            }
1956        };
1957        if encoded == 0 {
1958            self.pool.put(data);
1959            return;
1960        }
1961        self.sounding = !silent;
1962        let held = self.lookahead.min(self.frame_size_per_channel) * self.channels;
1963        self.tail_sounding = !silent && self.accum[n - held..n].iter().any(|&v| v != 0);
1964        self.chunks_encoded += 1;
1965        self.bytes_encoded += encoded as u64;
1966        if let Some(sink) = self.ogg.as_mut() {
1967            sink.write_packet(
1968                &data[prefix..prefix + encoded],
1969                self.total_samples_processed * self.ogg_scale,
1970            );
1971        }
1972        if self.red_distance > 0 {
1973            let mut slot = if self.red_history.len() >= self.red_distance {
1974                self.red_history
1975                    .pop_front()
1976                    .map(|(v, _)| v)
1977                    .unwrap_or_default()
1978            } else {
1979                self.red_spare.pop().unwrap_or_default()
1980            };
1981            slot.clear();
1982            slot.extend_from_slice(&data[prefix..prefix + encoded]);
1983            self.red_history.push_back((slot, pts));
1984        }
1985        data.truncate(prefix + encoded);
1986        if silent && emit_header {
1987            self.push_mark(pts);
1988            data[1] |= WS_QUIET;
1989        }
1990
1991        if let Some(data) = self.ring.push(data, pts, self.channels as u8) {
1992            self.pool.put(data);
1993        }
1994        if self.inner.stereo_companion.load(Ordering::Relaxed) {
1995            self.emit_companion(pts, emit_header, silent && emit_header);
1996        }
1997    }
1998
1999    /// Tell the delivery thread the stream pauses when the session drops after a frame of
2000    /// sound: a header capture pushes the bare `[0x01, WS_QUIET]` (stamped with the `pts` the
2001    /// pause starts at), since no frame is left to carry the mark, so a player plays out what
2002    /// it holds rather than waiting for more. A raw Opus capture has nothing to frame it with,
2003    /// and its RTP timestamps carry the pause already.
2004    fn emit_quiet(&mut self, pts: u64) {
2005        if std::mem::take(&mut self.sounding)
2006            && self.inner.emit_audio_header.load(Ordering::Relaxed)
2007        {
2008            self.push_mark(pts);
2009        }
2010    }
2011
2012    /// Push the bare `[0x01, WS_QUIET]` stamped `pts`.
2013    fn push_mark(&mut self, pts: u64) {
2014        let mut data = self.pool.take();
2015        data[0] = 0x01;
2016        data[1] = WS_QUIET;
2017        data.truncate(2);
2018        if let Some(data) = self.ring.push(data, pts, self.channels as u8) {
2019            self.pool.put(data);
2020        }
2021    }
2022
2023    /// Emit the stereo companion of the frame just emitted: the frame downmixed
2024    /// (`downmix_stereo`), encoded with the companion's own stereo encoder at the capture's
2025    /// bitrate, and handed to the delivery thread right after it with the same `pts` and
2026    /// `channels == 2`. On the wire it carries the plain two-byte header, never RED, which
2027    /// the surround stream's history serves, with `WS_QUIET` set when `ending` (the companion
2028    /// of the silent frame that ends a sound).
2029    fn emit_companion(&mut self, pts: u64, emit_header: bool, ending: bool) {
2030        let fpc = self.frame_size_per_channel;
2031        let channels = self.channels;
2032        let bitrate = self.current_applied_bitrate;
2033        let Some((encoder, pcm)) = self.companion.as_mut() else {
2034            return;
2035        };
2036        if self.companion_bitrate != bitrate && encoder.set_bitrate(bitrate).is_ok() {
2037            self.companion_bitrate = bitrate;
2038        }
2039        downmix_stereo(&self.accum[..fpc * channels], channels, pcm);
2040        let mut data = self.pool.take();
2041        let prefix = write_ws_prefix_into(&mut data, pts, &VecDeque::new(), 0, emit_header);
2042        match encoder.encode(pcm, fpc, &mut data[prefix..]) {
2043            Ok(n) if n > 0 => {
2044                data.truncate(prefix + n);
2045                if ending {
2046                    data[1] |= WS_QUIET;
2047                }
2048                if let Some(data) = self.ring.push(data, pts, 2) {
2049                    self.pool.put(data);
2050                }
2051            }
2052            Ok(_) => self.pool.put(data),
2053            Err(e) => {
2054                elog!("[pcmflux] ERROR: stereo companion: {e}");
2055                self.pool.put(data);
2056            }
2057        }
2058    }
2059}
2060
2061/// Own one whole capture run end to end on a dedicated thread — connect PulseAudio,
2062/// encode, and deliver — until stopped. It runs on its own thread because the PulseAudio
2063/// mainloop must be pumped continuously and independently of the caller: sharing the
2064/// caller's thread would tie capture cadence to it and let any stall starve the audio.
2065/// The body handed to `spawn_worker`.
2066///
2067/// Publishes `start_state` for the handshake (`RUNNING` on entering the hot loop, `FAILED`
2068/// with a `last_error` on any terminal error, `IDLE` on a clean stop) and returns when
2069/// `stop_state` leaves `STOP_NONE` or on a fatal error. The startup sequence, in order:
2070///
2071/// 1. **Seed the mirrors**: copies the settings snapshot (already validated by
2072///    `AudioCaptureSettings::validate`) into the `Inner` per-frame atomics.
2073/// 2. **Buffer attr / latency**: a configured `latency_ms` uses `ADJUST_LATENCY` with
2074///    `fragsize` set to that latency; otherwise `fragsize` is floored at ~20 ms, which yields
2075///    a prompt first frame and avoids PipeWire's ~2 s default fragment.
2076/// 3. **Connect + probe**: drives the context to `Ready` on the bounded pump (re-checking
2077///    `stop_pending` each turn), and up-front validates a NAMED device via an introspect
2078///    probe — an async `connect_record` would not fail synchronously on a bad name. The probe
2079///    closure is called from C inside mainloop dispatch, so its body is `catch_unwind`-guarded
2080///    to keep a panic from unwinding across the FFI boundary.
2081/// 4. **Encoder + record stream**: creates the `PcmEncoder` (mono/stereo or surround) and
2082///    drives the record stream to `Ready`.
2083/// 5. **Delivery thread**: spawns the delivery thread that pops from the `DeliveryRing` and
2084///    calls the sink there, so a stalled sink cannot back up the PA pump. The buffer pool is
2085///    sized to the worst-case body — RED prefix plus a max Opus packet, scaled by stream
2086///    count for surround (one self-delimited packet per stream). A run without a sink spawns
2087///    no delivery thread: its ring starts closed, so every encoded frame goes back to the
2088///    pool and only the output socket is served.
2089/// 6. **Hot loop**: `pump`s on the ~20 ms bound, then drains every buffered fragment via
2090///    peek/discard (a `Hole` is an xrun — the read index is just advanced), feeding each into
2091///    `RunState`. A stop is observed within the pump bound even when the source is wedged. On
2092///    exit it disconnects the stream, drops the encoder, closes and joins the delivery ring,
2093///    and reports any dropped stale frames.
2094///
2095/// One PulseAudio session for capture: mainloop, context, and the record stream,
2096/// all recreated together on reconnect.
2097/// Drop order matters (declaration order): the stream must die first, then its
2098/// owning context, then the mainloop both pulse threads pump — the reverse of
2099/// the build. A wrong order is a use-after-free on the libpulse side.
2100struct PaCaptureSession {
2101    stream: Stream,
2102    /// Must outlive the stream (the connection owns it); never read after open.
2103    #[allow(dead_code)]
2104    context: Context,
2105    mainloop: Mainloop,
2106}
2107
2108/// Why a session failed to open: drives the retry policy of the caller.
2109enum SessionOpenError {
2110    /// The named source is absent at startup (misconfiguration-ish); the caller gives it
2111    /// only its short bring-up window rather than the full startup retry budget.
2112    DeviceNotFound(String),
2113    /// Server down, busy, or a bring-up race: retryable.
2114    Transient(String),
2115    /// stop_pending observed while opening; caller must shut down cleanly.
2116    Aborted,
2117}
2118
2119/// Open a capture session: mainloop + context + record stream driven to `Ready` on the
2120/// bounded pump, honoring `stop_pending` at every turn. A NAMED device is validated by
2121/// an introspect probe on every call (an async connect_record would not fail
2122/// synchronously on a bad name, and on reconnect this is also what notices the device
2123/// reappearing after an outage). `device_was_present` distinguishes initial bring-up
2124/// from reconnect: a named device missing at startup is probably a misconfiguration, so
2125/// it is reported as `DeviceNotFound` and the caller spends only a short window on it;
2126/// the same device vanishing mid-run (PulseAudio/PipeWire restart kills every source) is
2127/// transient and must be retried or audio never comes back.
2128fn pa_capture_session_open(
2129    inner: &Inner,
2130    spec: &Spec,
2131    device: Option<&str>,
2132    attr: &BufferAttr,
2133    adjust_latency: bool,
2134    device_was_present: bool,
2135) -> Result<PaCaptureSession, SessionOpenError> {
2136    let tr = |e: &str| SessionOpenError::Transient(e.to_string());
2137    let mut mainloop = match Mainloop::new() {
2138        Some(m) => m,
2139        None => return Err(tr("pa_mainloop_new() failed")),
2140    };
2141    let mut context = match Context::new(&mainloop, "pcmflux") {
2142        Some(c) => c,
2143        None => return Err(tr("pa_context_new() failed")),
2144    };
2145    if context.connect(None, CtxFlags::NOFLAGS, None).is_err() {
2146        return Err(tr("pa_context_connect() failed"));
2147    }
2148    loop {
2149        let st = context.get_state();
2150        if st == pulse::context::State::Ready {
2151            break;
2152        }
2153        if !st.is_good() {
2154            return Err(tr("PulseAudio context connection failed"));
2155        }
2156        if inner.stop_pending() {
2157            return Err(SessionOpenError::Aborted);
2158        }
2159        if !pump(&mut mainloop, PUMP_TIMEOUT_US) {
2160            return Err(tr("mainloop iterate failed during connect"));
2161        }
2162    }
2163
2164    if let Some(dev) = device {
2165        let probe = Arc::new(Mutex::new((false, false)));
2166        let p2 = probe.clone();
2167        let op = context
2168            .introspect()
2169            .get_source_info_by_name(dev, move |res| {
2170                let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
2171                    let mut g = p2.lock().unwrap_or_else(|e| e.into_inner());
2172                    match res {
2173                        ListResult::Item(_) => g.0 = true,
2174                        ListResult::End | ListResult::Error => g.1 = true,
2175                    }
2176                }));
2177            });
2178        loop {
2179            if probe.lock().unwrap_or_else(|e| e.into_inner()).1 {
2180                break;
2181            }
2182            if inner.stop_pending() {
2183                drop(op);
2184                return Err(SessionOpenError::Aborted);
2185            }
2186            if !context.get_state().is_good() {
2187                drop(op);
2188                return Err(tr("context failed during source probe"));
2189            }
2190            if !pump(&mut mainloop, PUMP_TIMEOUT_US) {
2191                drop(op);
2192                return Err(tr("mainloop iterate failed during source probe"));
2193            }
2194        }
2195        drop(op);
2196        if !probe.lock().unwrap_or_else(|e| e.into_inner()).0 {
2197            let msg = format!("PulseAudio source not found: '{dev}'");
2198            return Err(if device_was_present {
2199                // Mid-run: the server was just restarted; its sources are all
2200                // gone for now, not misconfigured.
2201                SessionOpenError::Transient(msg)
2202            } else {
2203                SessionOpenError::DeviceNotFound(msg)
2204            });
2205        }
2206    }
2207
2208    let map = surround_channel_map(i32::from(spec.channels))
2209        .and_then(|m| ChannelMap::new_from_string(m).ok());
2210    let mut stream = match Stream::new(&mut context, "Audio Capture", spec, map.as_ref()) {
2211        Some(s) => s,
2212        None => return Err(tr("pa_stream_new() failed")),
2213    };
2214    let flags = if adjust_latency {
2215        StreamFlags::ADJUST_LATENCY
2216    } else {
2217        StreamFlags::NOFLAGS
2218    };
2219    if stream.connect_record(device, Some(attr), flags).is_err() {
2220        return Err(tr("pa_stream_connect_record() failed"));
2221    }
2222    loop {
2223        let st = stream.get_state();
2224        if st == pulse::stream::State::Ready {
2225            break;
2226        }
2227        if !st.is_good() {
2228            return Err(SessionOpenError::Transient(format!(
2229                "PulseAudio record stream failed (device '{}')",
2230                device.unwrap_or("default")
2231            )));
2232        }
2233        if inner.stop_pending() {
2234            return Err(SessionOpenError::Aborted);
2235        }
2236        if !pump(&mut mainloop, PUMP_TIMEOUT_US) {
2237            return Err(tr("mainloop iterate failed during stream connect"));
2238        }
2239    }
2240    Ok(PaCaptureSession {
2241        stream,
2242        context,
2243        mainloop,
2244    })
2245}
2246
2247fn capture_run(
2248    inner: &Arc<Inner>,
2249    settings: &AudioCaptureSettings,
2250    sink: Option<Arc<dyn AudioSink>>,
2251) {
2252    inner
2253        .opus_bitrate
2254        .store(settings.opus_bitrate, Ordering::Relaxed);
2255    inner
2256        .use_silence_gate
2257        .store(settings.use_silence_gate, Ordering::Relaxed);
2258    inner
2259        .debug_logging
2260        .store(settings.debug_logging, Ordering::Relaxed);
2261    inner
2262        .emit_audio_header
2263        .store(!settings.omit_audio_header, Ordering::Relaxed);
2264
2265    // Sample rate, channel count, and frame duration were validated by `validate`.
2266    let spec = Spec {
2267        format: Format::S16le,
2268        rate: settings.sample_rate,
2269        channels: settings.channels as u8,
2270    };
2271
2272    let mut attr = BufferAttr {
2273        maxlength: u32::MAX,
2274        tlength: u32::MAX,
2275        prebuf: u32::MAX,
2276        minreq: u32::MAX,
2277        fragsize: u32::MAX,
2278    };
2279    let adjust_latency = settings.latency_ms > 0;
2280    if adjust_latency {
2281        attr.fragsize = spec.usec_to_bytes(MicroSeconds(settings.latency_ms as u64 * 1000)) as u32;
2282    } else {
2283        attr.fragsize = spec.usec_to_bytes(MicroSeconds(20 * 1000)) as u32;
2284    }
2285
2286    let device = settings.device_name.as_deref();
2287
2288    let encoder = match PcmEncoder::new(
2289        settings.sample_rate,
2290        settings.channels,
2291        settings.use_vbr,
2292        settings.opus_bitrate,
2293        settings.opus_complexity,
2294    ) {
2295        Ok(e) => e,
2296        Err(e) => {
2297            inner.fail(e);
2298            return;
2299        }
2300    };
2301    plog!(
2302        "[pcmflux] SUCCESS: Opus encoder created ({} ch).",
2303        settings.channels
2304    );
2305
2306    let frame_size_per_channel =
2307        (f64::from(settings.sample_rate) * settings.frame_duration_ms / 1000.0) as usize;
2308    let channels = settings.channels as usize;
2309
2310    let ring = Arc::new(DeliveryRing::new(8));
2311    // Surround encodes one self-delimited packet per multistream stream (4 for 5.1, 5 for
2312    // 7.1), so the worst-case body scales with the stream count of the actual layout.
2313    let max_pkt = multiopus_layout(settings.channels).map_or(1, |(streams, _, _)| streams as usize)
2314        * MAX_OPUS_PACKET;
2315    let pool = Arc::new(BufferPool::new(RED_PREFIX_MAX + max_pkt));
2316    let delivery = match sink {
2317        None => {
2318            ring.close();
2319            None
2320        }
2321        Some(sink) => {
2322            let deliver_ring = Arc::clone(&ring);
2323            let deliver_pool = Arc::clone(&pool);
2324            let deliver_inner = Arc::clone(inner);
2325            let spawned = std::thread::Builder::new()
2326                .name("pcmflux-deliver".into())
2327                .spawn(move || {
2328                    unsafe {
2329                        let _ = libc::setpriority(libc::PRIO_PROCESS, gettid() as libc::id_t, -10);
2330                    }
2331                    deliver_inner.deliver_tid.store(gettid(), Ordering::Release);
2332                    while let Some((data, pts, channels)) = deliver_ring.pop() {
2333                        sink.frame(AudioFrame {
2334                            data,
2335                            pts,
2336                            channels,
2337                            pool: Some(Arc::clone(&deliver_pool)),
2338                        });
2339                    }
2340                    deliver_inner.deliver_tid.store(0, Ordering::Release);
2341                });
2342            match spawned {
2343                Ok(join) => Some(DeliveryThread {
2344                    ring: Arc::clone(&ring),
2345                    inner,
2346                    join: Some(join),
2347                }),
2348                Err(e) => {
2349                    inner.fail(format!("delivery thread spawn failed: {e}"));
2350                    return;
2351                }
2352            }
2353        }
2354    };
2355
2356    let ogg_scale = 48_000 / u64::from(settings.sample_rate.max(1));
2357    let mut encoder = encoder;
2358    let ogg = if settings.output_socket.is_empty() {
2359        None
2360    } else {
2361        match ogg_sink::OggSink::bind(
2362            &settings.output_socket,
2363            &ogg_sink::OpusHead {
2364                channels: channels as u8,
2365                pre_skip: (encoder.lookahead().max(0) as u64 * ogg_scale).min(u64::from(u16::MAX))
2366                    as u16,
2367                input_sample_rate: settings.sample_rate,
2368                mapping: multiopus_layout(channels as i32).map(|(streams, coupled, table)| {
2369                    (streams as u8, coupled as u8, table.to_vec())
2370                }),
2371            },
2372        ) {
2373            Ok(sink) => Some(sink),
2374            Err(e) => {
2375                inner.fail(e);
2376                return;
2377            }
2378        }
2379    };
2380    let lookahead = encoder.lookahead().max(0) as usize;
2381    let mut run = RunState {
2382        inner,
2383        ring: &ring,
2384        encoder,
2385        frame_size_per_channel,
2386        channels,
2387        accum: vec![0i16; frame_size_per_channel * channels],
2388        silence_ref: vec![0i16; frame_size_per_channel * channels],
2389        pcm_fill_bytes: 0,
2390        pool: PoolTaker::new(Arc::clone(&pool)),
2391        red_history: VecDeque::new(),
2392        red_spare: Vec::new(),
2393        red_distance: settings.red_distance.max(0) as usize,
2394        sounding: false,
2395        tail_sounding: false,
2396        lookahead,
2397        companion: if channels > 2 {
2398            match PcmEncoder::new(
2399                settings.sample_rate,
2400                2,
2401                settings.use_vbr,
2402                settings.opus_bitrate,
2403                settings.opus_complexity,
2404            ) {
2405                Ok(e) => Some((e, vec![0i16; frame_size_per_channel * 2])),
2406                Err(e) => {
2407                    elog!("[pcmflux] stereo companion unavailable: {e}");
2408                    None
2409                }
2410            }
2411        } else {
2412            None
2413        },
2414        companion_bitrate: settings.opus_bitrate,
2415        total_samples_processed: 0,
2416        ogg,
2417        ogg_scale,
2418        first_sound_detected: false,
2419        current_applied_bitrate: settings.opus_bitrate,
2420        chunks_read: 0,
2421        chunks_silent: 0,
2422        chunks_encoded: 0,
2423        bytes_encoded: 0,
2424    };
2425
2426    let mut last_log = Instant::now();
2427
2428    // Session loop: the record stream CAN die mid-run (PulseAudio/PipeWire restart,
2429    // source unplugged) and a plain `break` there leaves audio dead until some
2430    // unrelated settings change restarts the capture. Reopen with backoff instead.
2431    // Three retry budgets, shortest first:
2432    //   - DEVICE_WAIT_TRIES: a start that finds the NAMED source missing. The sink whose
2433    //     monitor is being recorded may still be materializing (container bring-up, or a
2434    //     capture start that raced a server restart), but a misconfigured name must still
2435    //     surface quickly, so this window is only a few seconds.
2436    //   - START_TRIES: any other failure to bring the first session up.
2437    //   - RECONNECT_TRIES: a mid-run reconnect, which has to outlast a whole
2438    //     PulseAudio/PipeWire restart or audio never comes back.
2439    const DEVICE_WAIT_TRIES: u32 = 6;
2440    const START_TRIES: u32 = 12;
2441    const RECONNECT_TRIES: u32 = 40;
2442    let mut session: Option<PaCaptureSession> = None;
2443    let mut ever_connected = false;
2444    let mut tries: u32 = 0;
2445    let mut backoff_ms: u64 = 250;
2446    let mut terminal_error: Option<String> = None;
2447
2448    loop {
2449        if inner.stop_pending() {
2450            break;
2451        }
2452        if session.is_none() {
2453            let opened = pa_capture_session_open(
2454                inner,
2455                &spec,
2456                device,
2457                &attr,
2458                adjust_latency,
2459                ever_connected,
2460            );
2461            let cap = match (&opened, ever_connected) {
2462                (Err(SessionOpenError::DeviceNotFound(_)), _) => DEVICE_WAIT_TRIES,
2463                (_, true) => RECONNECT_TRIES,
2464                (_, false) => START_TRIES,
2465            };
2466            match opened {
2467                Ok(s) => {
2468                    session = Some(s);
2469                    tries = 0;
2470                    backoff_ms = 250;
2471                    if !ever_connected {
2472                        ever_connected = true;
2473                        inner.started_ok.store(true, Ordering::Release);
2474                        inner.start_state.store(ST_RUNNING, Ordering::Release);
2475                        plog!(
2476                            "[pcmflux] Capture loop started. Device: {}, Rate: {}, Channels: {}, Bitrate: {} kbps, \
2477                             VBR: {}, Silence Gate: {}",
2478                            device.unwrap_or("system_default"),
2479                            settings.sample_rate,
2480                            settings.channels,
2481                            settings.opus_bitrate / 1000,
2482                            if settings.use_vbr { "On" } else { "Off" },
2483                            if settings.use_silence_gate {
2484                                "On"
2485                            } else {
2486                                "Off"
2487                            }
2488                        );
2489                    } else {
2490                        plog!("[pcmflux] audio capture reconnected; resuming.");
2491                    }
2492                }
2493                Err(SessionOpenError::Aborted) => break,
2494                Err(SessionOpenError::DeviceNotFound(e)) | Err(SessionOpenError::Transient(e)) => {
2495                    tries += 1;
2496                    if tries >= cap {
2497                        terminal_error = Some(e);
2498                        break;
2499                    }
2500                    elog!(
2501                        "[pcmflux] audio capture open failed ({e}); retry {tries}/{cap} in {backoff_ms}ms"
2502                    );
2503                    let mut slept = 0u64;
2504                    while slept < backoff_ms && !inner.stop_pending() {
2505                        std::thread::sleep(Duration::from_millis(50));
2506                        slept += 50;
2507                    }
2508                    backoff_ms = (backoff_ms * 2).min(5000);
2509                    continue;
2510                }
2511            }
2512        }
2513        let s = session.as_mut().expect("session checked above");
2514        if !pump(&mut s.mainloop, PUMP_TIMEOUT_US) {
2515            elog!("[pcmflux] ERROR: mainloop iterate failed; reopening the session.");
2516            session = None;
2517            // Drop the partially reassembled frame: the next fragments come from after
2518            // the outage, and stitching them onto pre-outage PCM would emit one frame
2519            // with a discontinuity in the middle, charged to the wrong pts.
2520            run.pcm_fill_bytes = 0;
2521            let at = run.total_samples_processed;
2522            run.emit_quiet(at);
2523            continue;
2524        }
2525        let sstate = s.stream.get_state();
2526        if sstate != pulse::stream::State::Ready {
2527            elog!("[pcmflux] record stream lost; reopening the session.");
2528            session = None;
2529            run.pcm_fill_bytes = 0;
2530            let at = run.total_samples_processed;
2531            run.emit_quiet(at);
2532            continue;
2533        }
2534
2535        loop {
2536            let mut discard = false;
2537            let mut done = false;
2538            match s.stream.peek() {
2539                Ok(PeekResult::Empty) => done = true,
2540                Ok(PeekResult::Hole(_)) => discard = true,
2541                Ok(PeekResult::Data(buf)) => {
2542                    run.feed(buf);
2543                    discard = true;
2544                }
2545                Err(_) => {
2546                    elog!("[pcmflux] ERROR: pa_stream_peek() failed.");
2547                    done = true;
2548                }
2549            }
2550            if discard {
2551                let _ = s.stream.discard();
2552            }
2553            if done {
2554                break;
2555            }
2556        }
2557
2558        if run.inner.debug_logging.load(Ordering::Relaxed) {
2559            let elapsed = last_log.elapsed();
2560            if elapsed >= Duration::from_secs(2) {
2561                let secs = elapsed.as_secs_f64();
2562                let kbps = (run.bytes_encoded * 8) as f64 / (secs * 1000.0);
2563                let silent_pct = if run.chunks_read > 0 {
2564                    100.0 * run.chunks_silent as f64 / run.chunks_read as f64
2565                } else {
2566                    0.0
2567                };
2568                plog!(
2569                    "[pcmflux] Status | Read: {}, Silent: {} ({:.1}%), Encoded: {}, Rate: {:.2} kbps",
2570                    run.chunks_read,
2571                    run.chunks_silent,
2572                    silent_pct,
2573                    run.chunks_encoded,
2574                    kbps
2575                );
2576                last_log = Instant::now();
2577                run.chunks_read = 0;
2578                run.chunks_silent = 0;
2579                run.chunks_encoded = 0;
2580                run.bytes_encoded = 0;
2581            }
2582        }
2583    }
2584
2585    if let Some(e) = terminal_error {
2586        inner.fail(format!(
2587            "audio capture could not {} (last error: {e}); stopping.",
2588            if ever_connected {
2589                "stay connected"
2590            } else {
2591                "connect"
2592            }
2593        ));
2594    } else {
2595        plog!("[pcmflux] Stop requested. Cleaning up capture loop...");
2596        inner.started_ok.store(false, Ordering::Release);
2597        // A stop before the first session came up must also resolve the startup
2598        // handshake, or the waiting `start_capture` polls out with the run still STARTING.
2599        inner.start_state.store(ST_IDLE, Ordering::Release);
2600    }
2601    if let Some(s) = session.as_mut() {
2602        let _ = s.stream.disconnect();
2603    }
2604    drop(session);
2605    drop(run);
2606    drop(delivery);
2607    let dropped = ring.dropped.load(Ordering::Relaxed);
2608    if dropped > 0 {
2609        plog!("[pcmflux] Delivery ring dropped {dropped} stale frame(s) to a slow consumer.");
2610    }
2611    plog!("[pcmflux] Audio capture loop finished. Resources released.");
2612}
2613
2614/// One PulseAudio session for playback: mainloop, context, and the playback stream, all
2615/// recreated together on reconnect — the mirror of `PaCaptureSession`, with the same
2616/// drop-order requirement (stream first, then its context, then the mainloop).
2617struct PaPlaybackSession {
2618    stream: Stream,
2619    /// Must outlive the stream (the connection owns it); never read after open.
2620    #[allow(dead_code)]
2621    context: Context,
2622    mainloop: Mainloop,
2623}
2624
2625/// Open a playback session: mainloop + context + playback stream driven to `Ready` on the
2626/// bounded pump, honoring `stop_pending` at every turn. The mirror of
2627/// `pa_capture_session_open`.
2628///
2629/// Every failure is `Transient`: `connect_playback` resolves a sink name asynchronously,
2630/// so a wrong device name and a server that is still coming up are the same failed stream
2631/// state here, and the caller's retry budget is what bounds either one.
2632fn pa_playback_session_open(
2633    inner: &Inner,
2634    spec: &Spec,
2635    device: Option<&str>,
2636    attr: &BufferAttr,
2637) -> Result<PaPlaybackSession, SessionOpenError> {
2638    let tr = |e: &str| SessionOpenError::Transient(e.to_string());
2639    let mut mainloop = match Mainloop::new() {
2640        Some(m) => m,
2641        None => return Err(tr("pa_mainloop_new() failed (playback)")),
2642    };
2643    let mut context = match Context::new(&mainloop, "pcmflux") {
2644        Some(c) => c,
2645        None => return Err(tr("pa_context_new() failed (playback)")),
2646    };
2647    if context.connect(None, CtxFlags::NOFLAGS, None).is_err() {
2648        return Err(tr("pa_context_connect() failed (playback)"));
2649    }
2650    loop {
2651        let st = context.get_state();
2652        if st == pulse::context::State::Ready {
2653            break;
2654        }
2655        if !st.is_good() {
2656            return Err(tr("PulseAudio context connection failed (playback)"));
2657        }
2658        if inner.stop_pending() {
2659            return Err(SessionOpenError::Aborted);
2660        }
2661        if !pump(&mut mainloop, PUMP_TIMEOUT_US) {
2662            return Err(tr("mainloop iterate failed during connect (playback)"));
2663        }
2664    }
2665
2666    let mut stream = match Stream::new(&mut context, "Microphone Playback", spec, None) {
2667        Some(s) => s,
2668        None => return Err(tr("pa_stream_new() failed (playback)")),
2669    };
2670    if stream
2671        .connect_playback(device, Some(attr), StreamFlags::ADJUST_LATENCY, None, None)
2672        .is_err()
2673    {
2674        return Err(SessionOpenError::Transient(format!(
2675            "pa_stream_connect_playback() failed (device '{}')",
2676            device.unwrap_or("default")
2677        )));
2678    }
2679    loop {
2680        let st = stream.get_state();
2681        if st == pulse::stream::State::Ready {
2682            break;
2683        }
2684        if !st.is_good() {
2685            return Err(SessionOpenError::Transient(format!(
2686                "PulseAudio playback stream failed (device '{}')",
2687                device.unwrap_or("default")
2688            )));
2689        }
2690        if inner.stop_pending() {
2691            return Err(SessionOpenError::Aborted);
2692        }
2693        if !pump(&mut mainloop, PUMP_TIMEOUT_US) {
2694            return Err(tr(
2695                "mainloop iterate failed during stream connect (playback)",
2696            ));
2697        }
2698    }
2699    Ok(PaPlaybackSession {
2700        stream,
2701        context,
2702        mainloop,
2703    })
2704}
2705
2706/// Drive one whole mic-playback run on the playback thread. The body handed to
2707/// `spawn_worker`; the mirror of `capture_run` for the uplink.
2708///
2709/// This thread solely owns the PA playback stream, so writes are serialized structurally
2710/// with no executor. It mirrors `capture_run`'s lifecycle: `start_state` goes `RUNNING`
2711/// once the first session is up, `FAILED` (with a `last_error`) when the run gives up, and
2712/// `IDLE` on a clean stop; it returns when `stop_state` leaves `STOP_NONE` or the retry
2713/// budget is spent.
2714///
2715/// **Session loop**: the sink can die under a live stream (PulseAudio/PipeWire restart,
2716/// sink removed). Breaking out there would leave the mic uplink dead until something
2717/// upstream noticed and restarted the whole playback, losing every packet in between, so
2718/// the session is reopened with the same backoff and budgets capture uses.
2719///
2720/// **Buffer sizing and the prebuf timing rule** (load-bearing): `tlength` is the target
2721/// latency in bytes, and `prebuf` is a quarter of it, floored to one frame. `prebuf` must
2722/// NOT be zero: with `prebuf == 0` PulseAudio starts playback instantly, the realtime read
2723/// pointer then runs ahead of the write index, and every `SeekMode::Relative` write lands
2724/// "in the past" — the server silently discards it forever (observed as bytes flowing at
2725/// exactly realtime rate while the sink monitor stayed silent). A quarter-buffer prebuf makes
2726/// the stream wait for data before starting and re-prebuffer after each underrun, so a late
2727/// chunk plays slightly delayed instead of vanishing.
2728///
2729/// **Hot loop**: `pump`s on the ~20 ms bound, then, whenever the server is writable, drains
2730/// that many bytes from the `PlayQueue` (clamped and frame-aligned) and writes them with
2731/// `free_cb = None`, so PA copies the bytes and the `scratch` buffer is reused next
2732/// iteration. Newly queued bytes are picked up on the next pump — no cross-thread wakeup is
2733/// needed, mirroring capture's poll style — and a stop is observed within the pump bound.
2734/// Each drain feeds `StandingDepth`, and depth that stood through a whole window is
2735/// spliced out of the queue's head, so the uplink's delay returns to the sink's own
2736/// buffer after a burst and does not grow with a client clock running fast.
2737fn playback_run(inner: &Inner, settings: &AudioPlaybackSettings, queue: &PlayQueue) {
2738    inner
2739        .debug_logging
2740        .store(settings.debug_logging, Ordering::Relaxed);
2741
2742    // Sample rate and channel count were validated by `validate`.
2743    let spec = Spec {
2744        format: Format::S16le,
2745        rate: settings.sample_rate,
2746        channels: settings.channels as u8,
2747    };
2748
2749    let device = settings.device_name.as_deref();
2750    plog!(
2751        "[pcmflux] Attempting to connect playback to PulseAudio device: {} (latency {}ms)",
2752        device.unwrap_or("system_default"),
2753        settings.latency_ms
2754    );
2755
2756    let tlength = spec.usec_to_bytes(MicroSeconds(settings.latency_ms.max(0) as u64 * 1000)) as u32;
2757    let attr = BufferAttr {
2758        maxlength: u32::MAX,
2759        tlength,
2760        prebuf: (tlength / 4).max(spec.frame_size() as u32),
2761        minreq: u32::MAX,
2762        fragsize: u32::MAX,
2763    };
2764
2765    // Retry budgets, matching capture: a start gets a short window, a mid-run reconnect
2766    // one long enough to outlast a whole PulseAudio/PipeWire restart.
2767    const START_TRIES: u32 = 12;
2768    const RECONNECT_TRIES: u32 = 40;
2769    let mut session: Option<PaPlaybackSession> = None;
2770    let mut ever_connected = false;
2771    let mut tries: u32 = 0;
2772    let mut backoff_ms: u64 = 250;
2773    let mut terminal_error: Option<String> = None;
2774
2775    let mut scratch: Vec<u8> = Vec::new();
2776    let mut bytes_written: u64 = 0;
2777    let mut bytes_cut: u64 = 0;
2778    let mut writable_hits: u64 = 0;
2779    let mut last_pb_log = Instant::now();
2780    let mut standing = StandingDepth::new(spec.bytes_per_second(), spec.frame_size());
2781
2782    loop {
2783        if inner.stop_pending() {
2784            break;
2785        }
2786        if session.is_none() {
2787            match pa_playback_session_open(inner, &spec, device, &attr) {
2788                Ok(s) => {
2789                    session = Some(s);
2790                    tries = 0;
2791                    backoff_ms = 250;
2792                    if !ever_connected {
2793                        ever_connected = true;
2794                        inner.started_ok.store(true, Ordering::Release);
2795                        inner.start_state.store(ST_RUNNING, Ordering::Release);
2796                        plog!(
2797                            "[pcmflux] Playback loop started. Device: {}, Rate: {}, Channels: {}, Latency: {}ms",
2798                            device.unwrap_or("system_default"),
2799                            settings.sample_rate,
2800                            settings.channels,
2801                            settings.latency_ms
2802                        );
2803                    } else {
2804                        // Mic audio queued during the outage is stale; playing it out
2805                        // would only push that much extra latency into the uplink.
2806                        queue.clear();
2807                        standing.reset();
2808                        plog!("[pcmflux] audio playback reconnected; resuming.");
2809                    }
2810                }
2811                Err(SessionOpenError::Aborted) => break,
2812                Err(SessionOpenError::DeviceNotFound(e)) | Err(SessionOpenError::Transient(e)) => {
2813                    tries += 1;
2814                    let cap = if ever_connected {
2815                        RECONNECT_TRIES
2816                    } else {
2817                        START_TRIES
2818                    };
2819                    if tries >= cap {
2820                        terminal_error = Some(e);
2821                        break;
2822                    }
2823                    elog!(
2824                        "[pcmflux] audio playback open failed ({e}); retry {tries}/{cap} in {backoff_ms}ms"
2825                    );
2826                    let mut slept = 0u64;
2827                    while slept < backoff_ms && !inner.stop_pending() {
2828                        std::thread::sleep(Duration::from_millis(50));
2829                        slept += 50;
2830                    }
2831                    backoff_ms = (backoff_ms * 2).min(5000);
2832                    continue;
2833                }
2834            }
2835        }
2836        let s = session.as_mut().expect("session checked above");
2837        if !pump(&mut s.mainloop, PUMP_TIMEOUT_US) {
2838            elog!("[pcmflux] ERROR: mainloop iterate failed; reopening the playback session.");
2839            session = None;
2840            continue;
2841        }
2842        if s.stream.get_state() != pulse::stream::State::Ready {
2843            elog!("[pcmflux] playback stream lost; reopening the session.");
2844            session = None;
2845            continue;
2846        }
2847        if let Some(can) = s.stream.writable_size()
2848            && can > 0
2849        {
2850            writable_hits += 1;
2851            let left = queue.drain_upto(can, &mut scratch);
2852            if !scratch.is_empty() {
2853                if let Err(e) = s
2854                    .stream
2855                    .write(&scratch, None, 0, pulse::stream::SeekMode::Relative)
2856                {
2857                    elog!("[pcmflux] ERROR: pa_stream_write() failed: {e:?}");
2858                } else {
2859                    bytes_written += scratch.len() as u64;
2860                }
2861            }
2862            if let Some(cut) = standing.after_drain(scratch.len(), left) {
2863                queue.splice_head(cut, standing.keep);
2864                bytes_cut += cut as u64;
2865            }
2866        }
2867        if inner.debug_logging.load(Ordering::Relaxed) && last_pb_log.elapsed().as_secs() >= 1 {
2868            plog!(
2869                "[pcmflux] Playback | writable_hits: {writable_hits}, bytes_written: {bytes_written}, queued: {}, standing depth cut: {bytes_cut}",
2870                queue.buf.lock().map(|q| q.len()).unwrap_or(0)
2871            );
2872            last_pb_log = Instant::now();
2873        }
2874    }
2875
2876    if let Some(e) = terminal_error {
2877        inner.fail(format!(
2878            "audio playback could not {} (last error: {e}); stopping.",
2879            if ever_connected {
2880                "stay connected"
2881            } else {
2882                "connect"
2883            }
2884        ));
2885    } else {
2886        plog!("[pcmflux] Stop requested. Cleaning up playback loop...");
2887        inner.started_ok.store(false, Ordering::Release);
2888        // A stop before the first session came up must also resolve the startup
2889        // handshake, so `worker_alive` stops reporting a STARTING run that will never run.
2890        inner.start_state.store(ST_IDLE, Ordering::Release);
2891    }
2892    if let Some(s) = session.as_mut() {
2893        let _ = s.stream.disconnect();
2894    }
2895    drop(session);
2896    plog!("[pcmflux] Audio playback loop finished. Resources released.");
2897}
2898
2899/// A capture: one PulseAudio record stream encoded to Opus and delivered to an
2900/// `AudioSink`. Owns the `Shared` lifecycle state; `start` / `stop` /
2901/// `update_audio_bitrate` / `set_stereo_companion` drive it, and `is_capturing` / `state` /
2902/// `last_error` report it. Dropping the handle stops the capture.
2903pub struct AudioCapture {
2904    shared: Arc<Shared>,
2905}
2906
2907impl Default for AudioCapture {
2908    fn default() -> Self {
2909        Self::new()
2910    }
2911}
2912
2913impl AudioCapture {
2914    /// An idle capture; nothing runs until `start`.
2915    pub fn new() -> Self {
2916        AudioCapture {
2917            shared: Arc::new(Shared {
2918                inner: Arc::new(Inner::new()),
2919                thread: Mutex::new(None),
2920            }),
2921        }
2922    }
2923
2924    fn inner(&self) -> &Arc<Inner> {
2925        &self.shared.inner
2926    }
2927
2928    /// Start (or restart) audio capture, delivering encoded frames to `sink`; with no sink
2929    /// the run serves only its `output_socket` and no frame is delivered.
2930    ///
2931    /// 1. **Re-entrancy guard**: if called on one of the run's own threads — the delivery
2932    ///    thread (where the sink executes) or the capture thread — it cannot join/recreate
2933    ///    the run it is part of (the capture thread joins the delivery thread on teardown,
2934    ///    so a join from either closes a cycle), so it just undoes a nested SELF-stop and
2935    ///    returns. That undo is a compare-exchange that clears the stop ONLY if this thread
2936    ///    still owns it — if an external stop stored `STOP_EXTERNAL` meanwhile, the CAS
2937    ///    fails and that stop stands (clearing it would strand its in-flight join forever).
2938    /// 2. **Validate**: `AudioCaptureSettings::validate` refuses with `Error::Settings`
2939    ///    what the worker could only fail on later, before any thread is touched.
2940    /// 3. **Spawn**: `spawn_worker` stops/joins any prior thread and spawns the new one.
2941    ///    The stop/clear ordering (the lost-stop invariant) lives in `spawn_worker`; a
2942    ///    join here waits for the sink's in-flight call, so a caller holding a lock that
2943    ///    call needs releases it first (the Python bridge releases the GIL).
2944    /// 4. **Register** the handle for `stop_all` (best-effort), pruning dead weaks.
2945    /// 5. **Startup handshake** (`await_start`): waits up to ~2 s for the thread to
2946    ///    publish `RUNNING` or `FAILED`, returning `Ok` while it is still `STARTING` — the
2947    ///    retry ladder can run longer than the window, so a later failure is observed
2948    ///    through `state` / `last_error`. On `FAILED`, `join_failed_start` tears down ONLY
2949    ///    the thread this call spawned (identity-checked) — a concurrent start may already
2950    ///    own the slot with a live run that must survive — and `last_error` is returned as
2951    ///    `Error::Start`.
2952    pub fn start(
2953        &self,
2954        settings: &AudioCaptureSettings,
2955        sink: Option<Arc<dyn AudioSink>>,
2956    ) -> Result<(), Error> {
2957        let inner = self.inner().clone();
2958
2959        let me = gettid();
2960        if inner.is_own_thread(me) {
2961            inner.undo_self_stop(me);
2962            return Ok(());
2963        }
2964
2965        let parsed = settings.validate()?;
2966
2967        let t_inner = inner.clone();
2968        let body = move || capture_run(&t_inner, &parsed, sink);
2969        let my_thread = spawn_worker(&self.shared.thread, &inner, "pcmflux-capture", body)
2970            .ok_or_else(|| Error::Start("capture thread spawn failed".to_string()))?;
2971
2972        if let Ok(mut reg) = registry().lock() {
2973            reg.retain(|w| w.strong_count() > 0);
2974            reg.push(Arc::downgrade(&self.shared));
2975        }
2976
2977        await_start(&self.shared.thread, &inner, my_thread, "audio capture")
2978    }
2979
2980    /// Stop audio capture, joining the capture thread.
2981    ///
2982    /// A re-entrant stop from one of the run's own threads — the delivery thread (where the
2983    /// sink executes) or the capture thread — only records a self-stop: a join from inside
2984    /// the run would cycle (the capture thread joins the delivery thread on teardown). It
2985    /// must not clobber an external stop already in effect, which has to win the join.
2986    /// Otherwise it takes the lifecycle lock and joins; the authoritative external stop is
2987    /// set INSIDE the lock immediately before the join, so it wins over any concurrent
2988    /// self-stop. The join waits for the sink's in-flight call, so a caller holding a lock
2989    /// that call needs releases it first (the Python bridge releases the GIL).
2990    pub fn stop(&self) {
2991        let inner = self.inner();
2992        let me = gettid();
2993        if inner.is_own_thread(me) {
2994            inner.request_self_stop(me);
2995            return;
2996        }
2997        stop_and_join(&self.shared.thread, inner);
2998    }
2999
3000    /// Set the live Opus target bitrate (bits/s) via the atomic mirror; the capture
3001    /// loop applies it on the next frame, without a restart. Values are clamped to the
3002    /// valid Opus range so an out-of-range request can never wedge the encoder. The value
3003    /// does not persist into the next `start`, which re-seeds it from its settings.
3004    pub fn update_audio_bitrate(&self, bps: i32) {
3005        let clamped = bps.clamp(OPUS_BITRATE_MIN, OPUS_BITRATE_MAX);
3006        self.inner().opus_bitrate.store(clamped, Ordering::Relaxed);
3007    }
3008
3009    /// Have a surround capture also deliver every frame downmixed to stereo, live: each
3010    /// surround frame is followed by its companion, the same `pts` and `channels == 2`,
3011    /// encoded by a stereo encoder of its own at the capture's bitrate, for consumers
3012    /// that decode no multistream Opus. Off by default, it keeps its setting across
3013    /// restarts, and a mono or stereo capture ignores it.
3014    pub fn set_stereo_companion(&self, enabled: bool) {
3015        self.inner()
3016            .stereo_companion
3017            .store(enabled, Ordering::Relaxed);
3018    }
3019
3020    /// True while a capture worker is connected and running with no stop pending; false
3021    /// while still starting and after a failure — see `state` to tell those apart.
3022    pub fn is_capturing(&self) -> bool {
3023        self.inner().running()
3024    }
3025
3026    /// Lifecycle phase. A run that fails after `start` returned (its retry ladder gave up,
3027    /// or a mid-run reconnect budget was spent) reads `Failed` with the reason in
3028    /// `last_error`.
3029    pub fn state(&self) -> State {
3030        self.inner().state()
3031    }
3032
3033    /// Why the last run failed, or `None` while no run has failed since the last start.
3034    pub fn last_error(&self) -> Option<String> {
3035        self.inner().last_error()
3036    }
3037}
3038
3039impl Drop for AudioCapture {
3040    /// Best-effort stop: the re-entrant case (running on the run's own delivery or
3041    /// capture thread) records a self-stop only (never clobbering a pending external
3042    /// stop); otherwise it takes the lifecycle lock and joins the capture thread, as `stop`.
3043    fn drop(&mut self) {
3044        self.stop();
3045    }
3046}
3047
3048/// A mic-uplink playback, symmetric to `AudioCapture`: the same lifecycle protocol, but a
3049/// PulseAudio playback stream instead of a record stream, and a bounded drop-oldest queue
3050/// fed by `write` / `write_red` instead of a sink. The caller never holds the stream —
3051/// only the playback thread touches it — so a close-versus-inflight-write use-after-free
3052/// is structurally impossible here. Dropping the handle stops the playback.
3053pub struct AudioPlayback {
3054    shared: Arc<PbShared>,
3055}
3056
3057impl Default for AudioPlayback {
3058    fn default() -> Self {
3059        Self::new()
3060    }
3061}
3062
3063impl AudioPlayback {
3064    /// An idle playback; nothing runs until `start`.
3065    pub fn new() -> Self {
3066        AudioPlayback {
3067            shared: Arc::new(PbShared {
3068                inner: Arc::new(Inner::new()),
3069                thread: Mutex::new(None),
3070                queue: Arc::new(PlayQueue::new()),
3071                opus_dec: Mutex::new(None),
3072            }),
3073        }
3074    }
3075
3076    fn inner(&self) -> &Arc<Inner> {
3077        &self.shared.inner
3078    }
3079
3080    /// Run `decode` on this run's Opus decoder with `packet`. The shared body of `write`
3081    /// and `write_red`.
3082    ///
3083    /// Gated on `worker_alive`: it fails with `Error::NotRunning` once no playback thread
3084    /// services the queue (start failure, stop, or a PA outage the session loop could not
3085    /// reconnect through), so the caller's reopen-on-error path engages instead of the
3086    /// audio being swallowed silently. A reconnect in progress stays "alive" and keeps
3087    /// queueing. The decode holds the decoder's lock for one packet and nothing else.
3088    fn decode_packet(
3089        &self,
3090        packet: &[u8],
3091        decode: impl FnOnce(&mut OpusPlaybackDecoder, &[u8], &PlayQueue),
3092    ) -> Result<(), Error> {
3093        if !self.inner().worker_alive() {
3094            return Err(Error::NotRunning);
3095        }
3096        let mut dec = self
3097            .shared
3098            .opus_dec
3099            .lock()
3100            .unwrap_or_else(|e| e.into_inner());
3101        if let Some(d) = dec.as_mut() {
3102            decode(d, packet, &self.shared.queue);
3103        }
3104        Ok(())
3105    }
3106
3107    /// Start (or restart) mic playback into the virtual sink. The playback mirror of
3108    /// `AudioCapture::start`.
3109    ///
3110    /// Same shape as capture: a re-entrant start from the playback thread just undoes a
3111    /// nested self-stop; the settings are validated (`AudioPlaybackSettings::validate`);
3112    /// the worker is spawned (the stop/clear ordering lives in `spawn_worker`); the handle
3113    /// is registered for `stop_all`; and the ~2 s `await_start` handshake returns a
3114    /// `FAILED` start as `Error::Start` (with `last_error`) after tearing down only the
3115    /// thread THIS call spawned (identity-checked, sparing a concurrent winner), while a
3116    /// start still in its retry ladder returns `Ok` and is watched through `state` /
3117    /// `last_error`. Before spawning, it applies this run's byte bound + frame alignment to
3118    /// the queue (dropping any stale audio) and creates the Opus decoder up front, since
3119    /// the mic uplink is always Opus and `write` / `write_red` decode packets to PCM on the
3120    /// writer's thread for this same run.
3121    pub fn start(&self, settings: &AudioPlaybackSettings) -> Result<(), Error> {
3122        let inner = self.inner().clone();
3123
3124        let me = gettid();
3125        if inner.capture_tid.load(Ordering::Acquire) == me {
3126            inner.undo_self_stop(me);
3127            return Ok(());
3128        }
3129
3130        let parsed = settings.validate()?;
3131        let frame_bytes = (parsed.channels.max(1) as usize) * 2;
3132        self.shared
3133            .queue
3134            .configure(parsed.max_buffer_bytes, frame_bytes);
3135
3136        let decoder = OpusPlaybackDecoder::new(parsed.sample_rate, parsed.channels);
3137        if decoder.is_none() {
3138            return Err(Error::Start(
3139                "failed to create Opus decoder for playback".to_string(),
3140            ));
3141        }
3142        *self
3143            .shared
3144            .opus_dec
3145            .lock()
3146            .unwrap_or_else(|e| e.into_inner()) = decoder;
3147
3148        let queue = self.shared.queue.clone();
3149        let t_inner = inner.clone();
3150        let body = move || playback_run(&t_inner, &parsed, &queue);
3151        let my_thread = spawn_worker(&self.shared.thread, &inner, "pcmflux-playback", body)
3152            .ok_or_else(|| Error::Start("playback thread spawn failed".to_string()))?;
3153
3154        if let Ok(mut reg) = playback_registry().lock() {
3155            reg.retain(|w| w.strong_count() > 0);
3156            reg.push(Arc::downgrade(&self.shared));
3157        }
3158
3159        await_start(&self.shared.thread, &inner, my_thread, "audio playback")
3160    }
3161
3162    /// Push one Opus mic packet for playback. The steady-state hot path.
3163    ///
3164    /// See `decode_packet` for the liveness gate. A bad packet is dropped rather than
3165    /// corrupting the stream, and the call never blocks on PA (drop-oldest happens inside
3166    /// `PlayQueue::push`).
3167    pub fn write(&self, packet: &[u8]) -> Result<(), Error> {
3168        self.decode_packet(packet, |dec, packet, queue| {
3169            if let Some(pcm) = dec.decode_to_pcm(packet) {
3170                queue.push(pcm);
3171            }
3172        })
3173    }
3174
3175    /// Play one RFC 2198 RED mic frame from the WebRTC/UDP uplink, recovering across any
3176    /// packet loss on the way in. The lossy-transport counterpart of `write`.
3177    ///
3178    /// The payload is de-framed, loss-recovered, and decoded by `decode_red_into_queue`
3179    /// (see there for why RED exists). `primary_ts` is the packet's monotonic RTP
3180    /// timestamp; the redundant blocks carry offsets back from it. Gated on `worker_alive`
3181    /// exactly like `write` (see `decode_packet`).
3182    pub fn write_red(&self, packet: &[u8], primary_ts: i64) -> Result<(), Error> {
3183        self.decode_packet(packet, move |dec, packet, queue| {
3184            dec.decode_red_into_queue(packet, primary_ts, queue);
3185        })
3186    }
3187
3188    /// Stop mic playback, joining the playback thread.
3189    ///
3190    /// A re-entrant stop from the playback thread records a self-stop only (it cannot
3191    /// self-join) and never clobbers an external stop already in effect. Otherwise it
3192    /// joins; `stop` returns only once the thread is joined and the sink is released.
3193    pub fn stop(&self) {
3194        let inner = self.inner();
3195        let me = gettid();
3196        if inner.capture_tid.load(Ordering::Acquire) == me {
3197            inner.request_self_stop(me);
3198            return;
3199        }
3200        stop_and_join(&self.shared.thread, inner);
3201    }
3202
3203    /// True while a playback worker is connected and running with no stop pending; false
3204    /// while still starting and after a failure — see `state` to tell those apart.
3205    pub fn is_running(&self) -> bool {
3206        self.inner().running()
3207    }
3208
3209    /// Lifecycle phase, the playback mirror of `AudioCapture::state`.
3210    pub fn state(&self) -> State {
3211        self.inner().state()
3212    }
3213
3214    /// Why the last run failed, or `None` while no run has failed since the last start.
3215    pub fn last_error(&self) -> Option<String> {
3216        self.inner().last_error()
3217    }
3218}
3219
3220impl Drop for AudioPlayback {
3221    /// Best-effort stop; symmetric to `AudioCapture::drop`.
3222    fn drop(&mut self) {
3223        self.stop();
3224    }
3225}
3226
3227/// Stop and join every live capture and playback, so no worker thread outlives the
3228/// program's teardown: snapshots the two `Weak` registries into strong references
3229/// (skipping any already dropped), then hands each to `stop_and_join`. The Python bridge
3230/// registers it on `atexit`.
3231pub fn stop_all() {
3232    let snapshot: Vec<Arc<Shared>> = match registry().lock() {
3233        Ok(reg) => reg.iter().filter_map(|w| w.upgrade()).collect(),
3234        Err(_) => Vec::new(),
3235    };
3236    for shared in snapshot {
3237        stop_and_join(&shared.thread, &shared.inner);
3238    }
3239    let pb_snapshot: Vec<Arc<PbShared>> = match playback_registry().lock() {
3240        Ok(reg) => reg.iter().filter_map(|w| w.upgrade()).collect(),
3241        Err(_) => Vec::new(),
3242    };
3243    for shared in pb_snapshot {
3244        stop_and_join(&shared.thread, &shared.inner);
3245    }
3246}
3247
3248#[cfg(test)]
3249mod tests {
3250    use super::*;
3251
3252    /// A lifecycle lock poisoned by an unrelated panic must not be what leaves a worker
3253    /// thread running into process exit: `stop_and_join` takes the lock anyway,
3254    /// so the handle is still taken and joined. The join itself would hang if the stop were
3255    /// not set before it.
3256    #[test]
3257    fn stop_and_join_takes_a_poisoned_lifecycle_lock() {
3258        use std::sync::Arc;
3259        let inner = Arc::new(Inner::new());
3260        let inner_c = inner.clone();
3261        let worker = std::thread::spawn(move || {
3262            while !inner_c.stop_pending() {
3263                std::thread::yield_now();
3264            }
3265        });
3266        let slot = Arc::new(Mutex::new(Some(worker)));
3267        let poisoner = slot.clone();
3268        let _ = std::thread::spawn(move || {
3269            let _guard = poisoner.lock().unwrap();
3270            panic!("poison");
3271        })
3272        .join();
3273        assert!(slot.is_poisoned());
3274        stop_and_join(&slot, &inner);
3275        assert!(slot.lock().unwrap_or_else(|e| e.into_inner()).is_none());
3276        assert_eq!(inner.capture_tid.load(Ordering::Acquire), 0);
3277    }
3278
3279    /// Timestamps that wrap the 32-bit RTP range still decode in order — the
3280    /// post-rollover frame is not mistaken for an already-played duplicate.
3281    #[test]
3282    fn red_playback_timestamp_wraparound() {
3283        let f = opus_frames(3);
3284        let mut dec = OpusPlaybackDecoder::new(24000, 1).unwrap();
3285        let q = PlayQueue::new();
3286        q.configure(1 << 20, 2);
3287        let wrap = i64::from(u32::MAX) - 100;
3288        dec.decode_red_into_queue(&build_red_payload(&[], &f[0]), wrap, &q);
3289        // One 20 ms step past the 32-bit rollover (mod 2^32): ts is numerically far
3290        // BELOW `wrap`, so a plain `ts > last` treats it as an already-played frame.
3291        let next = (wrap.wrapping_add(480)) & 0xFFFF_FFFF;
3292        dec.decode_red_into_queue(&build_red_payload(&[(480, &f[0])], &f[1]), next, &q);
3293        let mut out = Vec::new();
3294        q.drain_upto(1 << 20, &mut out);
3295        assert_eq!(
3296            out.len(),
3297            2 * FRAME_PCM_BYTES,
3298            "frame after the 32-bit wrap was dropped as a duplicate"
3299        );
3300    }
3301
3302    /// The re-entrancy guard must recognize BOTH of a run's own threads: the
3303    /// capture worker AND the delivery thread — the sink executes on the
3304    /// delivery thread, so a stop/start it issues arrives with the delivery tid, and
3305    /// treating it as external would join into the capture→delivery join cycle and
3306    /// deadlock.
3307    #[test]
3308    fn reentrancy_guard_matches_delivery_thread() {
3309        let inner = Inner::new();
3310        let me = gettid();
3311        assert!(
3312            !inner.is_own_thread(me),
3313            "no run live: nothing should match"
3314        );
3315        inner.deliver_tid.store(me, Ordering::Release);
3316        assert!(
3317            inner.is_own_thread(me),
3318            "delivery tid must short-circuit the guard"
3319        );
3320        inner.deliver_tid.store(0, Ordering::Release);
3321        inner.capture_tid.store(me, Ordering::Release);
3322        assert!(
3323            inner.is_own_thread(me),
3324            "capture tid must still short-circuit the guard"
3325        );
3326    }
3327
3328    /// Encode the same noisy PCM with `complexity` and return the concatenated packets.
3329    fn encode_noise(channels: i32, complexity: Option<i32>) -> Vec<u8> {
3330        let ch = channels as usize;
3331        let frame = 960usize;
3332        let mut enc = PcmEncoder::new(48000, channels, true, 96000, complexity).expect("encoder");
3333        let mut seed = 0x2545_f491u32;
3334        let mut bytes = Vec::new();
3335        for _ in 0..8 {
3336            let pcm: Vec<i16> = (0..frame * ch)
3337                .map(|_| {
3338                    seed = seed.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
3339                    ((seed >> 16) as i16) / 4
3340                })
3341                .collect();
3342            let mut out = vec![0u8; 4 * MAX_OPUS_PACKET];
3343            let n = enc.encode(&pcm, frame, &mut out).expect("encode");
3344            bytes.extend_from_slice(&out[..n]);
3345        }
3346        bytes
3347    }
3348
3349    /// The complexity reaches both encoder APIs: 0 and 10 produce different packets from the
3350    /// same input, and leaving it unset produces exactly what libopus's default of 9 does, so
3351    /// the default sends no request.
3352    #[test]
3353    fn opus_complexity_reaches_the_encoder() {
3354        for channels in [2, 6] {
3355            let low = encode_noise(channels, Some(0));
3356            let high = encode_noise(channels, Some(10));
3357            assert_ne!(
3358                low, high,
3359                "complexity 0 and 10 encoded identically ({channels} ch)"
3360            );
3361            assert_eq!(
3362                encode_noise(channels, None),
3363                encode_noise(channels, Some(9))
3364            );
3365        }
3366    }
3367
3368    /// `opus_complexity` is `None` by default, accepts 0 through 10, and rejects anything
3369    /// else as a settings error.
3370    #[test]
3371    fn opus_complexity_is_validated() {
3372        let mut settings = AudioCaptureSettings::default();
3373        assert_eq!(settings.validate().unwrap().opus_complexity, None);
3374        for ok in [0, 5, 10] {
3375            settings.opus_complexity = Some(ok);
3376            assert_eq!(settings.validate().unwrap().opus_complexity, Some(ok));
3377        }
3378        for bad in [-1, 11] {
3379            settings.opus_complexity = Some(bad);
3380            assert!(matches!(settings.validate(), Err(Error::Settings(_))));
3381        }
3382    }
3383
3384    /// The defaults validate unchanged on both settings, `validate` normalizes what the
3385    /// run reads (the bitrate and RED distance clamped, an empty device name the default),
3386    /// and every refused field is an `Error::Settings` carrying its reason, with a NUL in
3387    /// the device name refused on both.
3388    #[test]
3389    fn settings_validate_in_one_place() {
3390        let defaults = AudioCaptureSettings::default();
3391        assert_eq!(defaults.validate().unwrap(), defaults);
3392        let pb_defaults = AudioPlaybackSettings::default();
3393        assert_eq!(pb_defaults.validate().unwrap(), pb_defaults);
3394
3395        let loud = AudioCaptureSettings {
3396            device_name: Some(String::new()),
3397            opus_bitrate: 1_000_000,
3398            red_distance: 9,
3399            ..defaults.clone()
3400        };
3401        let parsed = loud.validate().unwrap();
3402        assert_eq!(parsed.device_name, None);
3403        assert_eq!(parsed.opus_bitrate, OPUS_BITRATE_MAX);
3404        assert_eq!(parsed.red_distance, RED_MAX_DISTANCE);
3405
3406        let refused = |settings: AudioCaptureSettings, field: &str| {
3407            let message = match settings.validate() {
3408                Err(Error::Settings(message)) => message,
3409                other => panic!("{field}: {other:?}"),
3410            };
3411            assert!(message.contains(field), "{message}");
3412        };
3413        refused(
3414            AudioCaptureSettings {
3415                sample_rate: 44100,
3416                ..defaults.clone()
3417            },
3418            "sample_rate",
3419        );
3420        refused(
3421            AudioCaptureSettings {
3422                frame_duration_ms: 30.0,
3423                ..defaults.clone()
3424            },
3425            "frame_duration_ms",
3426        );
3427        refused(
3428            AudioCaptureSettings {
3429                channels: 4,
3430                ..defaults.clone()
3431            },
3432            "channels",
3433        );
3434        refused(
3435            AudioCaptureSettings {
3436                latency_ms: -1,
3437                ..defaults.clone()
3438            },
3439            "latency_ms",
3440        );
3441        refused(
3442            AudioCaptureSettings {
3443                device_name: Some("a\0b".to_string()),
3444                ..defaults
3445            },
3446            "device_name",
3447        );
3448
3449        let pb_refused = |settings: AudioPlaybackSettings, field: &str| {
3450            let message = match settings.validate() {
3451                Err(Error::Settings(message)) => message,
3452                other => panic!("{field}: {other:?}"),
3453            };
3454            assert!(message.contains(field), "{message}");
3455        };
3456        pb_refused(
3457            AudioPlaybackSettings {
3458                channels: 6,
3459                ..pb_defaults.clone()
3460            },
3461            "channels",
3462        );
3463        pb_refused(
3464            AudioPlaybackSettings {
3465                latency_ms: 0,
3466                ..pb_defaults.clone()
3467            },
3468            "latency_ms",
3469        );
3470        pb_refused(
3471            AudioPlaybackSettings {
3472                max_buffer_bytes: 0,
3473                ..pb_defaults.clone()
3474            },
3475            "max_buffer_bytes",
3476        );
3477        pb_refused(
3478            AudioPlaybackSettings {
3479                device_name: Some("in\0put".to_string()),
3480                ..pb_defaults
3481            },
3482            "device_name",
3483        );
3484        assert_eq!(
3485            AudioPlaybackSettings {
3486                device_name: Some(String::new()),
3487                ..pb_defaults
3488            }
3489            .validate()
3490            .unwrap()
3491            .device_name,
3492            None
3493        );
3494    }
3495
3496    /// A playback that was never started refuses a write with `Error::NotRunning`, whose
3497    /// message is the one the Python bridge raises, and a closure is an `AudioSink`.
3498    #[test]
3499    fn idle_playback_refuses_writes() {
3500        let playback = AudioPlayback::new();
3501        assert_eq!(playback.state(), State::Idle);
3502        assert_eq!(playback.write(&[0xFC, 0xFF, 0xFE]), Err(Error::NotRunning));
3503        assert_eq!(playback.write_red(&[0x00], 0), Err(Error::NotRunning));
3504        assert_eq!(
3505            Error::NotRunning.to_string(),
3506            "audio playback is not running (stream failed, stopped, or never started)"
3507        );
3508        let delivered = Arc::new(AtomicUsize::new(0));
3509        let counter = Arc::clone(&delivered);
3510        let sink: Arc<dyn AudioSink> = Arc::new(move |frame: AudioFrame| {
3511            assert_eq!(frame.as_bytes(), [0x01, 0x00]);
3512            counter.fetch_add(1, Ordering::Relaxed);
3513        });
3514        sink.frame(AudioFrame {
3515            data: vec![0x01, 0x00],
3516            pts: 0,
3517            channels: 2,
3518            pool: None,
3519        });
3520        assert_eq!(delivered.load(Ordering::Relaxed), 1);
3521    }
3522
3523    /// Encode 5.1 with a tone only on FC (input channel 2), decode with the same
3524    /// layout, and verify the energy comes back on that same channel — proving the
3525    /// `multiopus_layout` tables are self-consistent end to end.
3526    #[test]
3527    fn multiopus_surround_roundtrip() {
3528        let channels = 6usize;
3529        let frame = 480usize;
3530        let mut enc = PcmEncoder::new(48000, channels as i32, true, 256000, None).expect("encoder");
3531        let mut pcm = vec![0i16; frame * channels];
3532        for i in 0..frame {
3533            let v =
3534                (8000.0 * (2.0 * std::f64::consts::PI * 440.0 * i as f64 / 48000.0).sin()) as i16;
3535            pcm[i * channels + 2] = v;
3536        }
3537        let mut out = vec![0u8; 4 * MAX_OPUS_PACKET];
3538        let mut n = 0;
3539        for _ in 0..3 {
3540            n = enc.encode(&pcm, frame, &mut out).expect("encode");
3541        }
3542        assert!(n > 0, "surround encode produced no bytes");
3543
3544        unsafe {
3545            let (streams, coupled, mapping) = multiopus_layout(channels as i32).unwrap();
3546            let mut err = 0;
3547            let dec = opusic_sys::opus_multistream_decoder_create(
3548                48000,
3549                channels as i32,
3550                streams,
3551                coupled,
3552                mapping.as_ptr(),
3553                &mut err,
3554            );
3555            assert!(!dec.is_null() && err == 0, "decoder create failed: {err}");
3556            let mut decoded = vec![0i16; frame * channels];
3557            let got = opusic_sys::opus_multistream_decode(
3558                dec,
3559                out.as_ptr(),
3560                n as i32,
3561                decoded.as_mut_ptr(),
3562                frame as i32,
3563                0,
3564            );
3565            opusic_sys::opus_multistream_decoder_destroy(dec);
3566            assert_eq!(got, frame as i32, "decode length mismatch");
3567            let mut rms = vec![0f64; channels];
3568            for i in 0..frame {
3569                for (c, r) in rms.iter_mut().enumerate() {
3570                    let s = f64::from(decoded[i * channels + c]);
3571                    *r += s * s;
3572                }
3573            }
3574            let loudest = rms
3575                .iter()
3576                .enumerate()
3577                .max_by(|a, b| a.1.partial_cmp(b.1).unwrap())
3578                .unwrap()
3579                .0;
3580            assert_eq!(loudest, 2, "tone did not come back on FC: rms={rms:?}");
3581        }
3582    }
3583
3584    /// The stereo fold: the fronts pass at unity to their own side, the center and each
3585    /// surround channel at -3 dB to theirs, the LFE nowhere, and a sum past full scale
3586    /// saturates instead of wrapping.
3587    #[test]
3588    fn downmix_stereo_follows_bs775() {
3589        let one = |ch: usize, pos: usize, v: i16| {
3590            let mut src = vec![0i16; ch];
3591            src[pos] = v;
3592            let mut dst = [0i16; 2];
3593            downmix_stereo(&src, ch, &mut dst);
3594            dst
3595        };
3596        assert_eq!(one(6, 0, 10000), [10000, 0]);
3597        assert_eq!(one(6, 1, 10000), [0, 10000]);
3598        assert_eq!(one(6, 2, 10000), [7071, 7071]);
3599        assert_eq!(one(6, 3, 10000), [0, 0]);
3600        assert_eq!(one(6, 4, 10000), [7071, 0]);
3601        assert_eq!(one(6, 5, 10000), [0, 7071]);
3602        assert_eq!(one(8, 6, 10000), [7071, 0]);
3603        assert_eq!(one(8, 7, 10000), [0, 7071]);
3604        let mut dst = [0i16; 2];
3605        downmix_stereo(&[30000, -30000, 0, 0, 30000, -30000], 6, &mut dst);
3606        assert_eq!(dst, [i16::MAX, i16::MIN]);
3607    }
3608
3609    /// With the companion on, a surround capture hands every frame over twice: the
3610    /// multistream packet with the capture's channel count, then its stereo fold with the
3611    /// same pts, which a plain stereo decoder plays with the center tone on both sides; with
3612    /// it off, only the surround frame goes. The fold of the silent frame that ends a sound
3613    /// carries that frame's quiet bit.
3614    #[test]
3615    fn stereo_companion_follows_each_surround_frame() {
3616        let inner = Inner::new();
3617        let ring = DeliveryRing::new(64);
3618        let frame = 480usize;
3619        let pool = Arc::new(BufferPool::new(RED_PREFIX_MAX + 4 * MAX_OPUS_PACKET));
3620        let mut run = RunState {
3621            inner: &inner,
3622            ring: &ring,
3623            encoder: PcmEncoder::new(48000, 6, true, 256000, None).expect("encoder"),
3624            frame_size_per_channel: frame,
3625            channels: 6,
3626            accum: vec![0i16; frame * 6],
3627            silence_ref: vec![0i16; frame * 6],
3628            pcm_fill_bytes: 0,
3629            pool: PoolTaker::new(Arc::clone(&pool)),
3630            red_history: VecDeque::new(),
3631            red_spare: Vec::new(),
3632            red_distance: 0,
3633            sounding: false,
3634            tail_sounding: false,
3635            lookahead: 120,
3636            companion: Some((
3637                PcmEncoder::new(48000, 2, true, 256000, None).expect("stereo"),
3638                vec![0i16; frame * 2],
3639            )),
3640            companion_bitrate: 256000,
3641            total_samples_processed: 0,
3642            ogg: None,
3643            ogg_scale: 1,
3644            first_sound_detected: true,
3645            current_applied_bitrate: 256000,
3646            chunks_read: 0,
3647            chunks_silent: 0,
3648            chunks_encoded: 0,
3649            bytes_encoded: 0,
3650        };
3651        let mut pcm = vec![0i16; frame * 6];
3652        for i in 0..frame {
3653            pcm[i * 6 + 2] =
3654                ((2.0 * std::f64::consts::PI * 440.0 * i as f64 / 48000.0).sin() * 8000.0) as i16;
3655        }
3656        run.feed(bytemuck::cast_slice(&pcm));
3657        inner.stereo_companion.store(true, Ordering::Relaxed);
3658        for _ in 0..4 {
3659            run.feed(bytemuck::cast_slice(&pcm));
3660        }
3661        let tone_frames = ring.q.lock().unwrap().as_ref().expect("ring open").len();
3662        run.feed(bytemuck::cast_slice(&vec![0i16; frame * 6]));
3663        let queued = ring.q.lock().unwrap();
3664        let frames: Vec<(Vec<u8>, u64, u8)> = queued
3665            .as_ref()
3666            .expect("ring open")
3667            .iter()
3668            .cloned()
3669            .collect();
3670        let tags: Vec<(u64, u8, bool)> = frames
3671            .iter()
3672            .map(|(d, p, c)| (*p, *c, d[1] & WS_QUIET != 0))
3673            .collect();
3674        assert_eq!(
3675            tags,
3676            vec![
3677                (0, 6, false),
3678                (480, 6, false),
3679                (480, 2, false),
3680                (960, 6, false),
3681                (960, 2, false),
3682                (1440, 6, false),
3683                (1440, 2, false),
3684                (1920, 6, false),
3685                (1920, 2, false),
3686                (2400, 6, true),
3687                (2400, 6, true),
3688                (2400, 2, true)
3689            ]
3690        );
3691        let mut dec = OpusPlaybackDecoder::new(48000, 2).expect("decoder");
3692        let mut last = Vec::new();
3693        for (data, _, c) in &frames[..tone_frames] {
3694            if *c == 2 {
3695                last = dec.decode_to_pcm(&data[2..]).expect("decodes").to_vec();
3696            }
3697        }
3698        let samples: &[i16] = bytemuck::cast_slice(&last);
3699        let rms = |ch: usize| {
3700            (samples
3701                .iter()
3702                .skip(ch)
3703                .step_by(2)
3704                .map(|&v| f64::from(v).powi(2))
3705                .sum::<f64>()
3706                / frame as f64)
3707                .sqrt()
3708        };
3709        assert!(
3710            rms(0) > 2000.0 && rms(1) > 2000.0,
3711            "center tone on both sides: {} {}",
3712            rms(0),
3713            rms(1)
3714        );
3715    }
3716
3717    /// Every surround layout the encoder takes has a channel map libpulse parses, with one
3718    /// position per channel and the front pair, center, and LFE where the encoder reads them.
3719    #[test]
3720    fn surround_channel_maps_parse() {
3721        use pulse::channelmap::Position;
3722        for channels in [6, 8] {
3723            let map = ChannelMap::new_from_string(surround_channel_map(channels).unwrap())
3724                .expect("parses");
3725            assert_eq!(i32::from(map.len()), channels);
3726            let pos = map.get();
3727            assert_eq!(
3728                &pos[..4],
3729                &[
3730                    Position::FrontLeft,
3731                    Position::FrontRight,
3732                    Position::FrontCenter,
3733                    Position::Lfe
3734                ]
3735            );
3736        }
3737        assert!(surround_channel_map(2).is_none() && surround_channel_map(1).is_none());
3738    }
3739
3740    /// `valid_opus_duration` accepts exactly the six legal Opus frame durations and
3741    /// rejects everything else (including the near-misses 3, 15, 25, 30 ms).
3742    #[test]
3743    fn opus_durations() {
3744        for ms in [2.5, 5.0, 10.0, 20.0, 40.0, 60.0] {
3745            assert!(valid_opus_duration(ms));
3746        }
3747        for ms in [0.0, 1.0, 3.0, 15.0, 25.0, 30.0, 50.0, 100.0] {
3748            assert!(!valid_opus_duration(ms));
3749        }
3750    }
3751
3752    /// The Opus rates, refused up front rather than at encoder creation: 44.1 kHz is the
3753    /// one a caller reaches for that Opus has never run at.
3754    #[test]
3755    fn opus_sample_rates() {
3756        for rate in [8000, 12000, 16000, 24000, 48000] {
3757            assert!(check_opus_sample_rate(rate).is_ok());
3758        }
3759        for rate in [0, 11025, 22050, 44100, 96000] {
3760            assert!(check_opus_sample_rate(rate).is_err());
3761        }
3762    }
3763
3764    /// The samples-per-channel and PCM-byte arithmetic matches the wire cases:
3765    /// 48 kHz / 20 ms / stereo is 960 samples/ch and 3840 bytes, and 24 kHz / 10 ms / mono
3766    /// is 240 samples and 480 bytes.
3767    #[test]
3768    fn frame_geometry() {
3769        let fspc = (48000usize * 20) / 1000;
3770        assert_eq!(fspc, 960);
3771        assert_eq!(fspc * 2 * 2, 3840);
3772        let m = (24000usize * 10) / 1000;
3773        assert_eq!(m, 240);
3774        assert_eq!(m * 2, 480);
3775    }
3776
3777    /// `red_distance == 0` produces exactly the 2-byte `[0x01, 0x00]` + opus framing,
3778    /// and the omit-header path returns the raw opus with no prefix at all.
3779    #[test]
3780    fn red_zero_is_byte_identical() {
3781        let opus = vec![0xDE, 0xAD, 0xBE, 0xEF, 0x42];
3782        let hist: VecDeque<(Vec<u8>, u64)> = VecDeque::new();
3783
3784        let legacy_expected = {
3785            let mut v = vec![0x01u8, 0x00];
3786            v.extend_from_slice(&opus);
3787            v
3788        };
3789        assert_eq!(build_ws_body(&opus, 4096, &hist, 0, true), legacy_expected);
3790        assert_eq!(build_ws_body(&opus, 4096, &hist, 0, false), opus);
3791    }
3792
3793    /// `red_distance == 2`: parse the emitted body back (`n_red` 4-byte headers, the
3794    /// 1-byte primary header, block data split by their lengths) and assert the primary and
3795    /// the two redundant blocks round-trip with the expected oldest-first offsets 1920 & 960.
3796    #[test]
3797    fn red_two_roundtrips() {
3798        let f_n2 = vec![0xA0, 0xA1, 0xA2];
3799        let f_n1 = vec![0xB0, 0xB1, 0xB2, 0xB3];
3800        let primary = vec![0xC0, 0xC1];
3801        let mut hist: VecDeque<(Vec<u8>, u64)> = VecDeque::new();
3802        hist.push_back((f_n2.clone(), 0));
3803        hist.push_back((f_n1.clone(), 960));
3804
3805        let body = build_ws_body(&primary, 1920, &hist, 2, true);
3806        assert_eq!(body[0], 0x01);
3807        let n_red = body[1] as usize;
3808        assert_eq!(n_red, 2);
3809        assert_eq!(
3810            u32::from_be_bytes([body[2], body[3], body[4], body[5]]),
3811            1920
3812        );
3813
3814        let mut idx = 6;
3815        let mut offsets = Vec::new();
3816        let mut lens = Vec::new();
3817        for _ in 0..n_red {
3818            assert_eq!(body[idx] & 0x80, 0x80, "redundant header F bit must be set");
3819            let word = (u32::from(body[idx + 1]) << 16)
3820                | (u32::from(body[idx + 2]) << 8)
3821                | u32::from(body[idx + 3]);
3822            offsets.push((word >> 10) & 0x3FFF);
3823            lens.push((word & 0x3FF) as usize);
3824            idx += 4;
3825        }
3826        assert_eq!(body[idx] & 0x80, 0x00, "primary header F bit must be clear");
3827        idx += 1;
3828
3829        assert_eq!(offsets, vec![1920, 960]);
3830        assert_eq!(lens, vec![f_n2.len(), f_n1.len()]);
3831
3832        let b0 = &body[idx..idx + lens[0]];
3833        idx += lens[0];
3834        let b1 = &body[idx..idx + lens[1]];
3835        idx += lens[1];
3836        let prim = &body[idx..];
3837        assert_eq!(b0, &f_n2[..]);
3838        assert_eq!(b1, &f_n1[..]);
3839        assert_eq!(prim, &primary[..]);
3840    }
3841
3842    /// Test helper: build an RFC 2198 RED payload — redundant blocks oldest-first,
3843    /// each with a 14-bit timestamp offset back from the primary, then the primary. Mirrors
3844    /// the wire format `decode_red_into_queue` parses (the mic-uplink counterpart of
3845    /// `build_ws_body`).
3846    fn build_red_payload(reds: &[(u64, &[u8])], primary: &[u8]) -> Vec<u8> {
3847        let mut v = Vec::new();
3848        for (off, blk) in reds {
3849            let field = (((*off as u32) & 0x3FFF) << 10) | ((blk.len() as u32) & 0x3FF);
3850            v.push(0x80 | (RED_BLOCK_PT & 0x7F));
3851            v.push((field >> 16) as u8);
3852            v.push((field >> 8) as u8);
3853            v.push(field as u8);
3854        }
3855        v.push(RED_BLOCK_PT & 0x7F);
3856        for (_, blk) in reds {
3857            v.extend_from_slice(blk);
3858        }
3859        v.extend_from_slice(primary);
3860        v
3861    }
3862
3863    /// Test helper: `n` distinct valid 20 ms mono Opus packets at 24 kHz
3864    /// (480 samples/frame).
3865    fn opus_frames(n: usize) -> Vec<Vec<u8>> {
3866        let mut enc = PcmEncoder::new(24000, 1, true, 24000, None).unwrap();
3867        (0..n)
3868            .map(|s| {
3869                let pcm: Vec<i16> = (0..480)
3870                    .map(|k| ((k * (s as i32 + 1)) % 4000 - 2000) as i16)
3871                    .collect();
3872                let mut out = vec![0u8; 4000];
3873                let len = enc.encode(&pcm, 480, &mut out).unwrap();
3874                out.truncate(len);
3875                out
3876            })
3877            .collect()
3878    }
3879
3880    /// Test constant: each decoded 20 ms mono frame is 480 samples * 2 bytes.
3881    const FRAME_PCM_BYTES: usize = 480 * 2;
3882
3883    /// A dropped middle packet is recovered from the next packet's redundancy: the
3884    /// redundant copy of the gap frame is decoded, while the redundant copy of an
3885    /// already-played frame is not (timestamp dedup). Exercises the RED playback path
3886    /// end to end — anchor on packet 1 (ts 1000), drop packet 2 (ts 1480), then packet 3
3887    /// (ts 1960) carries redundant copies of 1000 and 1480, so the output is exactly the
3888    /// three frames 1000 + 1480 + 1960.
3889    #[test]
3890    fn red_playback_recovers_lost_frame() {
3891        let f = opus_frames(3);
3892        let mut dec = OpusPlaybackDecoder::new(24000, 1).unwrap();
3893        let q = PlayQueue::new();
3894        q.configure(1 << 20, 2);
3895
3896        dec.decode_red_into_queue(&build_red_payload(&[], &f[0]), 1000, &q);
3897        let pkt3 = build_red_payload(&[(960, &f[0]), (480, &f[1])], &f[2]);
3898        dec.decode_red_into_queue(&pkt3, 1960, &q);
3899
3900        let mut out = Vec::new();
3901        q.drain_upto(1 << 20, &mut out);
3902        assert_eq!(out.len(), 3 * FRAME_PCM_BYTES);
3903        assert_eq!(dec.last_ts, Some(1960));
3904    }
3905
3906    /// With no loss, redundancy is pure overhead: every frame decodes exactly once and
3907    /// the redundant copies are dropped, so three packets yield exactly three frames.
3908    #[test]
3909    fn red_playback_no_double_decode() {
3910        let f = opus_frames(3);
3911        let mut dec = OpusPlaybackDecoder::new(24000, 1).unwrap();
3912        let q = PlayQueue::new();
3913        q.configure(1 << 20, 2);
3914
3915        dec.decode_red_into_queue(&build_red_payload(&[], &f[0]), 1000, &q);
3916        dec.decode_red_into_queue(&build_red_payload(&[(480, &f[0])], &f[1]), 1480, &q);
3917        dec.decode_red_into_queue(&build_red_payload(&[(480, &f[1])], &f[2]), 1960, &q);
3918
3919        let mut out = Vec::new();
3920        q.drain_upto(1 << 20, &mut out);
3921        assert_eq!(out.len(), 3 * FRAME_PCM_BYTES);
3922        assert_eq!(dec.last_ts, Some(1960));
3923    }
3924
3925    /// A too-old block (offset > 16383, overflowing the 14-bit field) and an oversize
3926    /// block (len > 1023, overflowing the 10-bit field) are both skipped, so `n_red` counts
3927    /// only the one in-range block that fit the RFC 2198 fields.
3928    #[test]
3929    fn red_skips_oversize_and_too_old() {
3930        let too_old = vec![0x11u8; 3];
3931        let oversize = vec![0x22u8; 1100];
3932        let good = vec![0x33u8; 5];
3933        let primary = vec![0x44u8; 2];
3934        let primary_pts = 100_000u64;
3935
3936        let mut hist: VecDeque<(Vec<u8>, u64)> = VecDeque::new();
3937        hist.push_back((too_old, primary_pts - 20_000));
3938        hist.push_back((oversize, primary_pts - 1920));
3939        hist.push_back((good.clone(), primary_pts - 960));
3940
3941        let body = build_ws_body(&primary, primary_pts, &hist, 4, true);
3942        assert_eq!(body[0], 0x01);
3943        assert_eq!(body[1], 1, "only the in-range block survives");
3944        assert_eq!(
3945            u32::from_be_bytes([body[2], body[3], body[4], body[5]]),
3946            primary_pts as u32
3947        );
3948
3949        let word = (u32::from(body[7]) << 16) | (u32::from(body[8]) << 8) | u32::from(body[9]);
3950        assert_eq!((word >> 10) & 0x3FFF, 960);
3951        let len = (word & 0x3FF) as usize;
3952        assert_eq!(len, good.len());
3953        assert_eq!(
3954            body[10] & 0x80,
3955            0x00,
3956            "primary header follows the one redundant header"
3957        );
3958        assert_eq!(&body[11..11 + len], &good[..]);
3959        assert_eq!(&body[11 + len..], &primary[..]);
3960    }
3961
3962    /// `red_distance > 0` with no usable history (e.g. the first frame after a
3963    /// (re)start) collapses to exactly the 2-byte `[0x01, 0x00]` + opus framing — the same
3964    /// bytes as `n_red == 0`, not a primary-only RED header. The client's `n_red == 0` path
3965    /// strips exactly 2 bytes, so emitting a lone primary-only RED header here would be
3966    /// mis-stripped and corrupt the frame; the body is asserted to be exactly those 2 bytes
3967    /// plus the opus.
3968    #[test]
3969    fn red_empty_history_collapses_to_bare_header() {
3970        let opus = vec![0x77u8; 4];
3971        let hist: VecDeque<(Vec<u8>, u64)> = VecDeque::new();
3972        let body = build_ws_body(&opus, 960, &hist, 2, true);
3973        assert_eq!(body[0], 0x01);
3974        assert_eq!(body[1], 0x00);
3975        assert_eq!(&body[2..], &opus[..]);
3976        assert_eq!(body.len(), 2 + opus.len());
3977    }
3978
3979    /// The emit path pauses a header stream exactly once per gated run: frames of sound
3980    /// around a stretch of digital silence go out with their Opus, then the bare
3981    /// `[0x01, WS_QUIET]` where the sound ends, then the first silent frame (it carries the end
3982    /// of the sound) with `WS_QUIET` set too, the frames after it send nothing, and sound
3983    /// resumes with the plain header (RED on or off, since the gate empties the history). A raw
3984    /// Opus capture sends the same frames with no marker, the silent one because the tone ran
3985    /// into the encoder's lookahead.
3986    #[test]
3987    fn gated_silence_sends_one_quiet_frame() {
3988        for (red, header) in [(0usize, true), (2, true), (0, false)] {
3989            let inner = Inner::new();
3990            inner.emit_audio_header.store(header, Ordering::Relaxed);
3991            let ring = DeliveryRing::new(64);
3992            let frame = 480usize;
3993            let pool = Arc::new(BufferPool::new(RED_PREFIX_MAX + MAX_OPUS_PACKET));
3994            let mut run = RunState {
3995                inner: &inner,
3996                ring: &ring,
3997                encoder: PcmEncoder::new(48000, 2, true, 64000, None).expect("encoder"),
3998                frame_size_per_channel: frame,
3999                channels: 2,
4000                accum: vec![0i16; frame * 2],
4001                silence_ref: vec![0i16; frame * 2],
4002                pcm_fill_bytes: 0,
4003                pool: PoolTaker::new(Arc::clone(&pool)),
4004                red_history: VecDeque::new(),
4005                red_spare: Vec::new(),
4006                red_distance: red,
4007                sounding: false,
4008                tail_sounding: false,
4009                lookahead: 120,
4010                companion: None,
4011                companion_bitrate: 64000,
4012                total_samples_processed: 0,
4013                ogg: None,
4014                ogg_scale: 1,
4015                first_sound_detected: true,
4016                current_applied_bitrate: 64000,
4017                chunks_read: 0,
4018                chunks_silent: 0,
4019                chunks_encoded: 0,
4020                bytes_encoded: 0,
4021            };
4022            let tone: Vec<i16> = (0..frame * 2)
4023                .map(|i| ((i as f64 * 0.3).sin() * 8000.0) as i16)
4024                .collect();
4025            let quiet = vec![0i16; frame * 2];
4026            for pcm in [&quiet, &tone, &tone, &quiet, &quiet, &quiet, &tone, &tone] {
4027                run.feed(bytemuck::cast_slice(pcm));
4028            }
4029            let queued = ring.q.lock().unwrap();
4030            let frames = queued.as_ref().expect("ring open");
4031            let pts: Vec<u64> = frames.iter().map(|(_, p, _)| *p).collect();
4032            let quiet_frames: Vec<&Vec<u8>> = frames
4033                .iter()
4034                .map(|(d, _, _)| d)
4035                .filter(|d| d.len() == 2)
4036                .collect();
4037            if header {
4038                assert_eq!(pts, vec![480, 960, 1440, 1440, 2880, 3360], "red={red}");
4039                assert_eq!(quiet_frames, vec![&vec![0x01, WS_QUIET]], "red={red}");
4040                assert_eq!(
4041                    frames[2].0.len(),
4042                    2,
4043                    "the bare mark goes where the sound ends"
4044                );
4045                assert!(
4046                    frames[3].0.len() > 2 && frames[3].0[1] & WS_QUIET != 0,
4047                    "the silent frame behind it carries the mark too"
4048                );
4049                assert!(
4050                    frames
4051                        .iter()
4052                        .enumerate()
4053                        .all(|(i, (d, _, _))| i == 2 || i == 3 || d[1] & WS_QUIET == 0)
4054                );
4055                assert_eq!(frames[4].0[1], 0x00, "sound resumes with the plain header");
4056            } else {
4057                assert_eq!(pts, vec![480, 960, 1440, 2880, 3360]);
4058                assert!(quiet_frames.is_empty() && frames.iter().all(|(d, _, _)| d.len() > 2));
4059            }
4060        }
4061    }
4062
4063    /// A sound in the last 2.5 ms of the frame before the gate closes reaches a header
4064    /// capture's decoder: the encoder holds that much back until the next frame, so the frame
4065    /// that ends the sound is sent, behind the bare mark and marked itself.
4066    #[test]
4067    fn a_header_capture_sends_the_tail_of_a_sound_before_the_gate() {
4068        let inner = Inner::new();
4069        inner.emit_audio_header.store(true, Ordering::Relaxed);
4070        let ring = DeliveryRing::new(64);
4071        let frame = 480usize;
4072        let pool = Arc::new(BufferPool::new(RED_PREFIX_MAX + MAX_OPUS_PACKET));
4073        let mut run = RunState {
4074            inner: &inner,
4075            ring: &ring,
4076            encoder: PcmEncoder::new(48000, 2, true, 128000, None).expect("encoder"),
4077            frame_size_per_channel: frame,
4078            channels: 2,
4079            accum: vec![0i16; frame * 2],
4080            silence_ref: vec![0i16; frame * 2],
4081            pcm_fill_bytes: 0,
4082            pool: PoolTaker::new(Arc::clone(&pool)),
4083            red_history: VecDeque::new(),
4084            red_spare: Vec::new(),
4085            red_distance: 0,
4086            sounding: false,
4087            tail_sounding: false,
4088            lookahead: 120,
4089            companion: None,
4090            companion_bitrate: 128000,
4091            total_samples_processed: 0,
4092            ogg: None,
4093            ogg_scale: 1,
4094            first_sound_detected: true,
4095            current_applied_bitrate: 128000,
4096            chunks_read: 0,
4097            chunks_silent: 0,
4098            chunks_encoded: 0,
4099            bytes_encoded: 0,
4100        };
4101        let mut click = vec![0i16; frame * 2];
4102        for i in frame - 96..frame {
4103            let v =
4104                ((i as f64 * 2.0 * std::f64::consts::PI * 1500.0 / 48000.0).sin() * 16000.0) as i16;
4105            click[i * 2] = v;
4106            click[i * 2 + 1] = v;
4107        }
4108        let quiet = vec![0i16; frame * 2];
4109        for pcm in [&quiet, &click, &quiet, &quiet, &quiet] {
4110            run.feed(bytemuck::cast_slice(pcm));
4111        }
4112        let queued = ring.q.lock().unwrap();
4113        let marked: Vec<(u64, usize)> = queued
4114            .as_ref()
4115            .expect("ring open")
4116            .iter()
4117            .filter(|(d, _, _)| d[1] & WS_QUIET != 0)
4118            .map(|(d, p, _)| (*p, d.len().min(3)))
4119            .collect();
4120        assert_eq!(
4121            marked,
4122            vec![(960, 2), (960, 3)],
4123            "the bare mark, then the frame that ends the sound"
4124        );
4125        let mut decoder = OpusPlaybackDecoder::new(48000, 2).expect("decoder");
4126        let mut peak = 0i32;
4127        for (data, _, _) in queued.as_ref().expect("ring open") {
4128            if data.len() <= 2 {
4129                continue;
4130            }
4131            let pcm: &[i16] =
4132                bytemuck::cast_slice(decoder.decode_to_pcm(&data[2..]).expect("decode"));
4133            peak = peak.max(pcm.iter().map(|&v| i32::from(v).abs()).max().unwrap_or(0));
4134        }
4135        assert!(peak > 8000, "the sound's tail decodes at {peak}");
4136    }
4137
4138    /// A raw capture sends the silent frame after a sound only when the sound reached into the
4139    /// encoder's lookahead, the part that frame carries: a burst in the last 2 ms of a frame is
4140    /// followed by the silent frame and decodes whole, and a burst that ended before the
4141    /// lookahead is not followed by it.
4142    #[test]
4143    fn a_raw_capture_sends_the_tail_only_when_the_sound_reached_the_lookahead() {
4144        for late in [true, false] {
4145            let inner = Inner::new();
4146            inner.emit_audio_header.store(false, Ordering::Relaxed);
4147            let ring = DeliveryRing::new(64);
4148            let frame = 480usize;
4149            let pool = Arc::new(BufferPool::new(RED_PREFIX_MAX + MAX_OPUS_PACKET));
4150            let mut run = RunState {
4151                inner: &inner,
4152                ring: &ring,
4153                encoder: PcmEncoder::new(48000, 2, true, 128000, None).expect("encoder"),
4154                frame_size_per_channel: frame,
4155                channels: 2,
4156                accum: vec![0i16; frame * 2],
4157                silence_ref: vec![0i16; frame * 2],
4158                pcm_fill_bytes: 0,
4159                pool: PoolTaker::new(Arc::clone(&pool)),
4160                red_history: VecDeque::new(),
4161                red_spare: Vec::new(),
4162                red_distance: 0,
4163                sounding: false,
4164                tail_sounding: false,
4165                lookahead: 120,
4166                companion: None,
4167                companion_bitrate: 128000,
4168                total_samples_processed: 0,
4169                ogg: None,
4170                ogg_scale: 1,
4171                first_sound_detected: true,
4172                current_applied_bitrate: 128000,
4173                chunks_read: 0,
4174                chunks_silent: 0,
4175                chunks_encoded: 0,
4176                bytes_encoded: 0,
4177            };
4178            let mut click = vec![0i16; frame * 2];
4179            let burst = if late { frame - 96..frame } else { 96..192 };
4180            for i in burst {
4181                let v = ((i as f64 * 2.0 * std::f64::consts::PI * 1500.0 / 48000.0).sin() * 16000.0)
4182                    as i16;
4183                click[i * 2] = v;
4184                click[i * 2 + 1] = v;
4185            }
4186            let quiet = vec![0i16; frame * 2];
4187            for pcm in [&quiet, &click, &quiet, &quiet, &quiet] {
4188                run.feed(bytemuck::cast_slice(pcm));
4189            }
4190            let queued = ring.q.lock().unwrap();
4191            let frames = queued.as_ref().expect("ring open");
4192            let pts: Vec<u64> = frames.iter().map(|(_, p, _)| *p).collect();
4193            if !late {
4194                assert_eq!(
4195                    pts,
4196                    vec![480],
4197                    "a burst that ended before the lookahead needs no tail"
4198                );
4199                continue;
4200            }
4201            assert_eq!(
4202                pts,
4203                vec![480, 960],
4204                "the silent frame carrying the burst's end follows it"
4205            );
4206            let mut decoder = OpusPlaybackDecoder::new(48000, 2).expect("decoder");
4207            let mut peak = 0i32;
4208            for (data, _, _) in frames {
4209                let pcm: &[i16] =
4210                    bytemuck::cast_slice(decoder.decode_to_pcm(data).expect("decode"));
4211                peak = peak.max(pcm.iter().map(|&v| i32::from(v).abs()).max().unwrap_or(0));
4212            }
4213            assert!(peak > 8000, "the burst decodes at {peak}");
4214        }
4215    }
4216
4217    /// A session that drops after sound leaves no frame to carry the mark, so a header capture
4218    /// sends the bare `[0x01, WS_QUIET]` once; one that drops in silence, or a raw capture,
4219    /// sends nothing.
4220    #[test]
4221    fn a_dropped_session_after_sound_sends_the_bare_mark_once() {
4222        for header in [true, false] {
4223            let inner = Inner::new();
4224            inner.emit_audio_header.store(header, Ordering::Relaxed);
4225            let ring = DeliveryRing::new(64);
4226            let frame = 480usize;
4227            let pool = Arc::new(BufferPool::new(RED_PREFIX_MAX + MAX_OPUS_PACKET));
4228            let mut run = RunState {
4229                inner: &inner,
4230                ring: &ring,
4231                encoder: PcmEncoder::new(48000, 2, true, 64000, None).expect("encoder"),
4232                frame_size_per_channel: frame,
4233                channels: 2,
4234                accum: vec![0i16; frame * 2],
4235                silence_ref: vec![0i16; frame * 2],
4236                pcm_fill_bytes: 0,
4237                pool: PoolTaker::new(Arc::clone(&pool)),
4238                red_history: VecDeque::new(),
4239                red_spare: Vec::new(),
4240                red_distance: 0,
4241                sounding: false,
4242                tail_sounding: false,
4243                lookahead: 120,
4244                companion: None,
4245                companion_bitrate: 64000,
4246                total_samples_processed: 0,
4247                ogg: None,
4248                ogg_scale: 1,
4249                first_sound_detected: true,
4250                current_applied_bitrate: 64000,
4251                chunks_read: 0,
4252                chunks_silent: 0,
4253                chunks_encoded: 0,
4254                bytes_encoded: 0,
4255            };
4256            run.emit_quiet(0);
4257            let tone: Vec<i16> = (0..frame * 2)
4258                .map(|i| ((i as f64 * 0.3).sin() * 8000.0) as i16)
4259                .collect();
4260            run.feed(bytemuck::cast_slice(&tone));
4261            run.emit_quiet(480);
4262            run.emit_quiet(480);
4263            let queued = ring.q.lock().unwrap();
4264            let bare: Vec<&Vec<u8>> = queued
4265                .as_ref()
4266                .expect("ring open")
4267                .iter()
4268                .map(|(d, _, _)| d)
4269                .filter(|d| d.len() == 2)
4270                .collect();
4271            if header {
4272                assert_eq!(bare, vec![&vec![0x01, WS_QUIET]]);
4273            } else {
4274                assert!(bare.is_empty());
4275            }
4276        }
4277    }
4278
4279    /// The all-zero comparison behind the silence gate: an all-zero buffer reads as
4280    /// silent, and a single non-zero sample makes it non-silent.
4281    #[test]
4282    fn silence_detection() {
4283        let silent = vec![0i16; 960 * 2];
4284        assert!(silent.iter().all(|&s| s == 0));
4285        let mut not = silent;
4286        not[123] = 7;
4287        assert!(!not.iter().all(|&s| s == 0));
4288    }
4289
4290    /// Deterministic lost-stop probe against the real `stop_state` protocol.
4291    ///
4292    /// A stand-in "capture thread" hammers `request_self_stop` + `undo_self_stop` (the
4293    /// re-entrant callback pattern) while another thread issues `request_external_stop` and
4294    /// waits for the loop's `stop_pending()` to observe it. The external stop must never be
4295    /// cleared by a self-start, so the thread always observes `STOP_EXTERNAL` and the join
4296    /// returns (no hang). The bounded spin count is the in-test watchdog; 5000 iterations
4297    /// shake out the race.
4298    #[test]
4299    fn external_stop_never_lost_to_self_restart() {
4300        use std::sync::Arc;
4301        let me: i64 = 987654;
4302        for _ in 0..5000 {
4303            let inner = Arc::new(Inner::new());
4304            let inner_c = inner.clone();
4305            let observed = Arc::new(AtomicBool::new(false));
4306            let observed_c = observed.clone();
4307            let h = std::thread::spawn(move || {
4308                let mut spins: u64 = 0;
4309                loop {
4310                    inner_c.request_self_stop(me);
4311                    inner_c.undo_self_stop(me);
4312                    if inner_c.stop_pending()
4313                        && inner_c.stop_state.load(Ordering::Acquire) == STOP_EXTERNAL
4314                    {
4315                        observed_c.store(true, Ordering::Release);
4316                        return;
4317                    }
4318                    spins += 1;
4319                    assert!(
4320                        spins < 50_000_000,
4321                        "external stop was lost (would hang the join)"
4322                    );
4323                }
4324            });
4325            inner.request_external_stop();
4326            h.join().unwrap();
4327            assert!(observed.load(Ordering::Acquire));
4328            assert_eq!(inner.stop_state.load(Ordering::Acquire), STOP_EXTERNAL);
4329            assert!(inner.stop_pending());
4330        }
4331    }
4332
4333    /// Pushing past the byte bound drops the OLDEST bytes, keeping the newest window:
4334    /// an 8-byte bound fed 12 bytes retains the last 8, and a second drain comes back empty.
4335    #[test]
4336    fn playqueue_drop_oldest_keeps_newest() {
4337        let q = PlayQueue::new();
4338        q.configure(8, 2);
4339        q.push(&[1, 2, 3, 4, 5, 6]);
4340        q.push(&[7, 8, 9, 10, 11, 12]);
4341        let mut out = Vec::new();
4342        q.drain_upto(100, &mut out);
4343        assert_eq!(out, vec![5, 6, 7, 8, 9, 10, 11, 12]);
4344        q.drain_upto(100, &mut out);
4345        assert!(out.is_empty());
4346    }
4347
4348    /// `drain_upto` clamps to the requested count AND floors to a whole frame, so a PA
4349    /// write never gets a partial frame: with 4-byte frames, a request of 7 yields 4 bytes,
4350    /// the next drain yields the next 4, and the trailing 2 bytes are withheld as a partial
4351    /// frame.
4352    #[test]
4353    fn playqueue_drain_is_frame_aligned() {
4354        let q = PlayQueue::new();
4355        q.configure(1000, 4);
4356        q.push(&[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
4357        let mut out = Vec::new();
4358        q.drain_upto(7, &mut out);
4359        assert_eq!(out, vec![0, 1, 2, 3]);
4360        q.drain_upto(100, &mut out);
4361        assert_eq!(out, vec![4, 5, 6, 7]);
4362        q.drain_upto(100, &mut out);
4363        assert!(out.is_empty());
4364    }
4365
4366    /// `configure()` applies the new bounds and drops stale audio from a prior run, so
4367    /// bytes queued before it are gone afterward.
4368    #[test]
4369    fn playqueue_configure_resets() {
4370        let q = PlayQueue::new();
4371        q.push(&[1, 2, 3, 4]);
4372        q.configure(96000, 2);
4373        let mut out = Vec::new();
4374        q.drain_upto(100, &mut out);
4375        assert!(out.is_empty(), "configure must clear stale audio");
4376    }
4377
4378    /// A byte bound that is not a whole-frame multiple must not let overflow drops
4379    /// split a sample frame — a mid-frame trim would phase-shift every later drain
4380    /// into interleaved garbage. The bound floors to whole frames and drops are made
4381    /// in whole frames.
4382    #[test]
4383    fn playqueue_misaligned_bound_never_splits_frames() {
4384        let q = PlayQueue::new();
4385        // A 9-byte bound over 4-byte frames floors to 8, which is two whole frames.
4386        q.configure(9, 4);
4387        q.push(&[0, 1, 2, 3]);
4388        q.push(&[4, 5, 6, 7]);
4389        // With 12 bytes queued against a bound of 8, exactly the oldest frame is dropped.
4390        q.push(&[8, 9, 10, 11]);
4391        let mut out = Vec::new();
4392        q.drain_upto(100, &mut out);
4393        assert_eq!(out, vec![4, 5, 6, 7, 8, 9, 10, 11]);
4394    }
4395
4396    /// A splice drops exactly the cut, blends the head into the audio after the cut over
4397    /// the fade (first blended sample next to the head, last next to the tail), leaves the
4398    /// rest untouched, and does nothing when the queue cannot hold the cut and the fade.
4399    #[test]
4400    fn playqueue_splice_crossfades_the_seam() {
4401        let q = PlayQueue::new();
4402        q.configure(1 << 20, 2);
4403        let head: Vec<i16> = vec![1000; 48];
4404        let tail: Vec<i16> = (0..200).map(|i| -2000 + i).collect();
4405        q.push(bytemuck::cast_slice(&head));
4406        q.push(bytemuck::cast_slice(&[0i16; 52]));
4407        q.push(bytemuck::cast_slice(&tail));
4408        q.splice_head(200, 96);
4409        let mut out = Vec::new();
4410        assert_eq!(q.drain_upto(1 << 20, &mut out), 0);
4411        let got: Vec<i16> = bytemuck::cast_slice::<u8, i16>(&out).to_vec();
4412        assert_eq!(got.len(), 200);
4413        assert!(
4414            (got[0] - 1000).abs() < 70,
4415            "first sample stays near the head: {}",
4416            got[0]
4417        );
4418        assert!(
4419            (got[47] - tail[47]).abs() < 70,
4420            "last blended sample reaches the tail: {}",
4421            got[47]
4422        );
4423        assert!(
4424            got.windows(2).take(48).all(|w| (w[1] - w[0]).abs() < 70),
4425            "no step inside the fade"
4426        );
4427        assert_eq!(&got[48..], &tail[48..]);
4428
4429        let short = PlayQueue::new();
4430        short.configure(1 << 20, 2);
4431        short.push(&[1, 0, 2, 0, 3, 0]);
4432        short.splice_head(4, 4);
4433        let mut out = Vec::new();
4434        short.drain_upto(100, &mut out);
4435        assert_eq!(out, vec![1, 0, 2, 0, 3, 0]);
4436    }
4437
4438    /// The queue against the real sink cadence, simulated: 20 ms packets arrive on a
4439    /// client clock, the sink drains 10 ms whenever it has room, and `StandingDepth` cuts
4440    /// what stood through a window. A 500 ms stall followed by its burst is shed within two
4441    /// windows, and a client clock 0.1 % fast (1 ms more per second than the sink plays)
4442    /// never lets the depth past the 10 ms cut threshold and a packet over ten minutes;
4443    /// without the cut both would hold their excess (the burst) or grow without bound.
4444    #[test]
4445    fn standing_depth_is_shed_after_bursts_and_drift() {
4446        fn run(stall: bool, skew: f64, seconds: f64, cut: bool) -> (usize, usize) {
4447            let (rate, fb) = (24_000usize, 2usize);
4448            let q = PlayQueue::new();
4449            q.configure(96_000, fb);
4450            let mut standing = StandingDepth::new(rate * fb, fb);
4451            let packet = vec![0u8; 960];
4452            let mut out = Vec::new();
4453            let (mut t, mut next_arrival, mut k) = (0.0f64, 0.0f64, 0u64);
4454            let (mut worst_late, mut end) = (0usize, 0usize);
4455            let mut held = 0u64;
4456            while t < seconds {
4457                while next_arrival <= t {
4458                    let in_stall = stall && (5.0..5.5).contains(&next_arrival);
4459                    if in_stall {
4460                        held += 1;
4461                    } else {
4462                        for _ in 0..=held {
4463                            q.push(&packet);
4464                        }
4465                        held = 0;
4466                    }
4467                    k += 1;
4468                    next_arrival = k as f64 * 0.020 / (1.0 + skew);
4469                }
4470                let left = q.drain_upto(480, &mut out);
4471                if cut && let Some(n) = standing.after_drain(out.len(), left) {
4472                    q.splice_head(n, standing.keep);
4473                }
4474                let depth = q.buf.lock().unwrap().len();
4475                if t > 8.0 {
4476                    worst_late = worst_late.max(depth);
4477                }
4478                end = depth;
4479                t += 0.010;
4480            }
4481            (worst_late, end)
4482        }
4483        let (late, _) = run(true, 0.0, 30.0, true);
4484        assert!(
4485            late <= 960 + 480,
4486            "burst shed by 8 s: {late} bytes still standing"
4487        );
4488        let (_, held) = run(true, 0.0, 30.0, false);
4489        assert!(held >= 20_000, "without the cut the burst stands: {held}");
4490        let (drift, _) = run(false, 0.001, 600.0, true);
4491        assert!(drift <= 480 + 960 + 96, "drift bounded: {drift} bytes");
4492        let (_, grown) = run(false, 0.001, 600.0, false);
4493        assert!(grown >= 25_000, "without the cut drift grows: {grown}");
4494    }
4495
4496    /// `worker_alive` (which gates `AudioPlayback::write`) tracks the lifecycle: it is
4497    /// false before any worker, true through the startup handshake and the healthy run, and
4498    /// goes false the moment the hot loop's error exit clears `started_ok` — even with no stop
4499    /// pending and `start_state` still `RUNNING` (the silent mid-run death case). A pending
4500    /// external stop also reads as not-alive.
4501    #[test]
4502    fn worker_alive_tracks_loop_error_exit() {
4503        let inner = Inner::new();
4504        assert!(!inner.worker_alive(), "no worker yet");
4505
4506        inner.start_state.store(ST_STARTING, Ordering::Release);
4507        assert!(inner.worker_alive(), "startup handshake counts as alive");
4508
4509        inner.started_ok.store(true, Ordering::Release);
4510        inner.start_state.store(ST_RUNNING, Ordering::Release);
4511        assert!(inner.worker_alive());
4512
4513        inner.started_ok.store(false, Ordering::Release);
4514        assert_eq!(inner.stop_state.load(Ordering::Acquire), STOP_NONE);
4515        assert!(!inner.worker_alive(), "dead loop must be observable");
4516
4517        inner.started_ok.store(true, Ordering::Release);
4518        inner.request_external_stop();
4519        assert!(!inner.worker_alive());
4520    }
4521
4522    /// `state` / `last_error` follow the lifecycle the getters expose: idle before any
4523    /// run, starting through the handshake, running once connected, and failed — with the
4524    /// reason recorded BEFORE the state flips — after `fail`. A new run armed by
4525    /// `spawn_worker` forgets the previous failure. The phases spell as the Python getters
4526    /// do.
4527    #[test]
4528    fn state_and_last_error_track_lifecycle() {
4529        let inner = Arc::new(Inner::new());
4530        assert_eq!(inner.state(), State::Idle);
4531        assert_eq!(inner.state().as_str(), "idle");
4532        assert_eq!(inner.last_error(), None);
4533
4534        inner.start_state.store(ST_STARTING, Ordering::Release);
4535        assert_eq!(inner.state(), State::Starting);
4536        assert_eq!(inner.state().as_str(), "starting");
4537        assert!(!inner.running());
4538
4539        inner.started_ok.store(true, Ordering::Release);
4540        inner.start_state.store(ST_RUNNING, Ordering::Release);
4541        assert_eq!(inner.state(), State::Running);
4542        assert_eq!(inner.state().to_string(), "running");
4543        assert!(inner.running());
4544
4545        inner.request_external_stop();
4546        assert_eq!(
4547            inner.state(),
4548            State::Idle,
4549            "a pending stop is no longer running"
4550        );
4551        inner.clear_stop();
4552
4553        inner.fail("source vanished".to_string());
4554        assert_eq!(inner.state(), State::Failed);
4555        assert_eq!(inner.state().as_str(), "failed");
4556        assert_eq!(inner.last_error().as_deref(), Some("source vanished"));
4557        assert!(!inner.running());
4558        assert!(!inner.worker_alive());
4559
4560        let slot: Mutex<Option<JoinHandle<()>>> = Mutex::new(None);
4561        let wi = inner.clone();
4562        spawn_worker(&slot, &inner, "fresh", move || {
4563            wi.started_ok.store(false, Ordering::Release);
4564            wi.start_state.store(ST_IDLE, Ordering::Release);
4565        })
4566        .unwrap();
4567        slot.lock().unwrap().take().unwrap().join().unwrap();
4568        assert_eq!(
4569            inner.last_error(),
4570            None,
4571            "a new run must start with no stale error"
4572        );
4573        assert_eq!(inner.state(), State::Idle, "a clean stop reads idle again");
4574    }
4575
4576    /// A worker body that panics is caught by `spawn_worker`, which marks the run failed
4577    /// and records the panic message as `last_error`, so the death is observable instead
4578    /// of leaving a silently dead capture.
4579    #[test]
4580    fn worker_panic_records_last_error() {
4581        let inner = Arc::new(Inner::new());
4582        let slot: Mutex<Option<JoinHandle<()>>> = Mutex::new(None);
4583        spawn_worker(&slot, &inner, "panicky", || panic!("boom")).unwrap();
4584        slot.lock().unwrap().take().unwrap().join().unwrap();
4585        assert_eq!(inner.state(), State::Failed);
4586        assert_eq!(
4587            inner.last_error().as_deref(),
4588            Some("worker thread panicked: boom")
4589        );
4590        assert!(!inner.worker_alive());
4591        assert_eq!(inner.capture_tid.load(Ordering::Acquire), 0);
4592    }
4593
4594    /// A LOSING start's failed-start cleanup must never tear down a WINNING start's
4595    /// freshly spawned thread.
4596    ///
4597    /// Drives the bad interleaving directly: loser L's worker fails, winner W takes the slot
4598    /// over (joins dead L, spawns live W) BEFORE L runs its `ST_FAILED` cleanup. That late
4599    /// `join_failed_start` must be an identity-mismatch no-op, leaving W running and still
4600    /// tear-down-able through the ordinary external stop path.
4601    #[test]
4602    fn failed_start_cleanup_spares_concurrent_winner() {
4603        let inner = Arc::new(Inner::new());
4604        let slot: Mutex<Option<JoinHandle<()>>> = Mutex::new(None);
4605
4606        let li = inner.clone();
4607        let l_id = spawn_worker(&slot, &inner, "loser", move || {
4608            li.started_ok.store(false, Ordering::Release);
4609            li.start_state.store(ST_FAILED, Ordering::Release);
4610        })
4611        .unwrap();
4612        while inner.start_state.load(Ordering::Acquire) != ST_FAILED {
4613            std::thread::yield_now();
4614        }
4615
4616        let wi = inner.clone();
4617        let w_id = spawn_worker(&slot, &inner, "winner", move || {
4618            wi.started_ok.store(true, Ordering::Release);
4619            wi.start_state.store(ST_RUNNING, Ordering::Release);
4620            while !wi.stop_pending() {
4621                std::thread::sleep(Duration::from_millis(1));
4622            }
4623            wi.started_ok.store(false, Ordering::Release);
4624        })
4625        .unwrap();
4626        assert_ne!(l_id, w_id);
4627        while inner.start_state.load(Ordering::Acquire) != ST_RUNNING {
4628            std::thread::yield_now();
4629        }
4630
4631        join_failed_start(&slot, &inner, l_id);
4632        assert!(
4633            slot.lock().unwrap().is_some(),
4634            "winner's handle must survive"
4635        );
4636        assert_eq!(inner.stop_state.load(Ordering::Acquire), STOP_NONE);
4637        assert!(inner.worker_alive(), "winner must still be running");
4638
4639        {
4640            let mut g = slot.lock().unwrap();
4641            let h = g.take().expect("winner handle present");
4642            inner.request_external_stop();
4643            h.join().unwrap();
4644        }
4645        assert!(!inner.worker_alive());
4646    }
4647
4648    /// Two threads race the full start sequence (`spawn_worker` + handshake poll +
4649    /// conditional failed-start cleanup), 200 times.
4650    ///
4651    /// `spawn_worker` joins the prior worker before spawning, so the bodies run in spawn
4652    /// order: the first fails, the second serves until stopped. Whatever the interleaving,
4653    /// the second run must end `RUNNING` with no stray stop — a loser cleanup that killed the
4654    /// winner would leave an empty slot and a `STOP_EXTERNAL` behind.
4655    #[test]
4656    fn concurrent_start_loser_never_kills_winner() {
4657        for _ in 0..200 {
4658            let inner = Arc::new(Inner::new());
4659            let slot = Arc::new(Mutex::new(None::<JoinHandle<()>>));
4660            let runs = Arc::new(AtomicUsize::new(0));
4661
4662            let starter = |name: &'static str| {
4663                let inner = inner.clone();
4664                let slot = slot.clone();
4665                let runs = runs.clone();
4666                std::thread::spawn(move || {
4667                    let bi = inner.clone();
4668                    let bruns = runs.clone();
4669                    let id = spawn_worker(&slot, &inner, name, move || {
4670                        if bruns.fetch_add(1, Ordering::AcqRel) == 0 {
4671                            bi.started_ok.store(false, Ordering::Release);
4672                            bi.start_state.store(ST_FAILED, Ordering::Release);
4673                        } else {
4674                            bi.started_ok.store(true, Ordering::Release);
4675                            bi.start_state.store(ST_RUNNING, Ordering::Release);
4676                            let mut spins: u64 = 0;
4677                            while !bi.stop_pending() {
4678                                std::thread::sleep(Duration::from_millis(1));
4679                                spins += 1;
4680                                assert!(spins < 10_000, "external stop was lost");
4681                            }
4682                            bi.started_ok.store(false, Ordering::Release);
4683                        }
4684                    })
4685                    .unwrap();
4686                    let mut state = inner.start_state.load(Ordering::Acquire);
4687                    let mut tries = 0;
4688                    while state == ST_STARTING && tries < 2000 {
4689                        std::thread::sleep(Duration::from_millis(1));
4690                        state = inner.start_state.load(Ordering::Acquire);
4691                        tries += 1;
4692                    }
4693                    if state == ST_FAILED {
4694                        join_failed_start(&slot, &inner, id);
4695                    }
4696                })
4697            };
4698            let a = starter("start-a");
4699            let b = starter("start-b");
4700            a.join().unwrap();
4701            b.join().unwrap();
4702
4703            assert_eq!(runs.load(Ordering::Acquire), 2);
4704            assert!(
4705                slot.lock().unwrap().is_some(),
4706                "winner's thread must survive"
4707            );
4708            assert_eq!(inner.start_state.load(Ordering::Acquire), ST_RUNNING);
4709            assert!(
4710                inner.worker_alive(),
4711                "winner must still be alive after both starts"
4712            );
4713
4714            {
4715                let mut g = slot.lock().unwrap();
4716                let h = g.take().expect("winner handle present");
4717                inner.request_external_stop();
4718                h.join().unwrap();
4719            }
4720            assert!(!inner.worker_alive());
4721        }
4722    }
4723
4724    /// The in-place `write_ws_prefix_into` + appended primary is byte-identical to the
4725    /// copy-based `build_ws_body` reference across the full matrix — empty vs mixed history
4726    /// (including one block aged out of the 14-bit offset at high pts and one oversized block
4727    /// that is always skipped), every `red_distance`, header on/off, and several pts values.
4728    #[test]
4729    fn prefix_writer_matches_build_ws_body() {
4730        let primary: Vec<u8> = (0u8..200).collect();
4731        let mut mixed: VecDeque<(Vec<u8>, u64)> = VecDeque::new();
4732        mixed.push_back((vec![1u8; 100], 0));
4733        mixed.push_back((vec![2u8; RED_MAX_LEN + 1], 960));
4734        mixed.push_back((vec![3u8; 50], 1440));
4735        mixed.push_back((vec![4u8; 900], 1900));
4736        for hist in [VecDeque::new(), mixed] {
4737            for red in [0usize, 1, 2, 4] {
4738                for hdr in [true, false] {
4739                    for pts in [960u64, 3840, 20000] {
4740                        let reference = build_ws_body(&primary, pts, &hist, red, hdr);
4741                        let mut buf = vec![0u8; RED_PREFIX_MAX + MAX_OPUS_PACKET];
4742                        let prefix = write_ws_prefix_into(&mut buf, pts, &hist, red, hdr);
4743                        buf[prefix..prefix + primary.len()].copy_from_slice(&primary);
4744                        buf.truncate(prefix + primary.len());
4745                        assert_eq!(buf, reference, "red={red} hdr={hdr} pts={pts}");
4746                    }
4747                }
4748            }
4749        }
4750    }
4751
4752    /// A truncated buffer returned to the pool comes back as the same allocation
4753    /// (recycled) restored to full `buf_size` length, and an undersized foreign buffer is
4754    /// rejected rather than pooled.
4755    #[test]
4756    fn buffer_pool_recycles_and_restores_length() {
4757        let pool = BufferPool::new(64);
4758        let mut a = pool.take();
4759        assert_eq!(a.len(), 64);
4760        let ptr = a.as_ptr() as usize;
4761        a.truncate(7);
4762        pool.put(a);
4763        let b = pool.take();
4764        assert_eq!(b.as_ptr() as usize, ptr, "buffer must be recycled");
4765        assert_eq!(b.len(), 64, "length must be restored");
4766        pool.put(Vec::new());
4767        assert_eq!(pool.take().len(), 64);
4768    }
4769
4770    /// Dropping an `AudioFrame` whose `pool` is set returns its buffer to that pool,
4771    /// so the next `take` hands back the same allocation.
4772    #[test]
4773    fn audio_frame_drop_refills_pool() {
4774        let pool = Arc::new(BufferPool::new(32));
4775        let buf = pool.take();
4776        let ptr = buf.as_ptr() as usize;
4777        drop(AudioFrame {
4778            data: buf,
4779            pts: 0,
4780            channels: 2,
4781            pool: Some(Arc::clone(&pool)),
4782        });
4783        let recycled = pool.take();
4784        assert_eq!(recycled.as_ptr() as usize, ptr);
4785    }
4786
4787    /// Micro-benchmark (not a correctness test) isolating the emit-path assembly cost:
4788    /// the copy-based `build_ws_body` + per-frame alloc versus the pooled in-place prefix,
4789    /// with the encoder stubbed to a memcpy.
4790    ///
4791    /// `#[ignore]`d by default; run with
4792    /// `cargo test --release bench_emit_assembly -- --ignored --nocapture`. The pooled arm
4793    /// circulates buffers at the delivery-ring depth (>8 in flight) so refill batching engages
4794    /// as it does live — several returns per drain, not one.
4795    #[test]
4796    #[ignore]
4797    fn bench_emit_assembly() {
4798        use std::hint::black_box;
4799        use std::time::Instant;
4800
4801        const ITERS: u32 = 500_000;
4802        const PAYLOAD: usize = 200;
4803        let src = vec![0xA5u8; PAYLOAD];
4804        let mut hist: VecDeque<(Vec<u8>, u64)> = VecDeque::new();
4805        hist.push_back((vec![6u8; 180], 0));
4806        hist.push_back((vec![7u8; 180], 480));
4807
4808        for (red, label) in [(0usize, "red=0"), (2usize, "red=2")] {
4809            let old = Instant::now();
4810            let mut out = vec![0u8; MAX_OPUS_PACKET];
4811            for i in 0..ITERS {
4812                out[..PAYLOAD].copy_from_slice(&src);
4813                let data = build_ws_body(&out[..PAYLOAD], 960 + u64::from(i), &hist, red, true);
4814                black_box(&data);
4815            }
4816            let old_ns = old.elapsed().as_nanos() / u128::from(ITERS);
4817
4818            let pool = Arc::new(BufferPool::new(RED_PREFIX_MAX + MAX_OPUS_PACKET));
4819            let mut taker = PoolTaker::new(Arc::clone(&pool));
4820            let mut inflight: VecDeque<Vec<u8>> = VecDeque::new();
4821            let new = Instant::now();
4822            for i in 0..ITERS {
4823                let mut data = taker.take();
4824                let prefix = write_ws_prefix_into(&mut data, 960 + u64::from(i), &hist, red, true);
4825                data[prefix..prefix + PAYLOAD].copy_from_slice(&src);
4826                data.truncate(prefix + PAYLOAD);
4827                black_box(&data);
4828                inflight.push_back(data);
4829                if inflight.len() > 8 {
4830                    pool.put(inflight.pop_front().unwrap());
4831                }
4832            }
4833            let new_ns = new.elapsed().as_nanos() / u128::from(ITERS);
4834            println!("{label}: old {old_ns} ns/frame -> pooled in-place {new_ns} ns/frame");
4835        }
4836    }
4837}