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}