Add audio controls and focused hotkeys

src/audio/eq.rs

@@ -0,0 +1,316 @@
+//! Per-peer listener-side voice EQ.
+//!
+//! The EQ is deliberately small and local: three RBJ cookbook biquads at fixed
+//! voice-oriented frequencies, with only gain exposed to the UI. State lives per
+//! peer in the playout mixer so filter delay registers are continuous across 20ms
+//! Opus frames; flat settings are treated as bypass so the default path is cheap
+//! and sample-exact.
+
+use serde::{Deserialize, Serialize};
+
+const DEFAULT_SAMPLE_RATE: f32 = 48_000.0;
+const LOW_SHELF_HZ: f32 = 160.0;
+const MID_PEAK_HZ: f32 = 2_400.0;
+const HIGH_SHELF_HZ: f32 = 6_500.0;
+const MID_Q: f32 = 1.0;
+const SHELF_Q: f32 = std::f32::consts::FRAC_1_SQRT_2;
+const FLAT_EPSILON_DB: f32 = 0.001;
+
+/// UI and config clamp for each band. Wide enough to be useful for voice, narrow
+/// enough that a peer cannot accidentally make the listener-side limiter do all
+/// the work.
+pub const EQ_GAIN_DB_MIN: f32 = -12.0;
+pub const EQ_GAIN_DB_MAX: f32 = 12.0;
+
+/// Persisted per-peer EQ gains, in decibels. `Default` is flat/bypassed.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
+pub struct EqSettings {
+    #[serde(default)]
+    pub low_gain_db: f32,
+    #[serde(default)]
+    pub mid_gain_db: f32,
+    #[serde(default)]
+    pub high_gain_db: f32,
+}
+
+impl Default for EqSettings {
+    fn default() -> Self {
+        Self {
+            low_gain_db: 0.0,
+            mid_gain_db: 0.0,
+            high_gain_db: 0.0,
+        }
+    }
+}
+
+impl EqSettings {
+    pub fn flat() -> Self {
+        Self::default()
+    }
+
+    /// Clamp all public gains to the supported UI/DSP range.
+    pub fn clamped(self) -> Self {
+        Self {
+            low_gain_db: self.low_gain_db.clamp(EQ_GAIN_DB_MIN, EQ_GAIN_DB_MAX),
+            mid_gain_db: self.mid_gain_db.clamp(EQ_GAIN_DB_MIN, EQ_GAIN_DB_MAX),
+            high_gain_db: self.high_gain_db.clamp(EQ_GAIN_DB_MIN, EQ_GAIN_DB_MAX),
+        }
+    }
+
+    /// True when the EQ should be bypassed entirely.
+    pub fn is_flat(self) -> bool {
+        self.low_gain_db.abs() <= FLAT_EPSILON_DB
+            && self.mid_gain_db.abs() <= FLAT_EPSILON_DB
+            && self.high_gain_db.abs() <= FLAT_EPSILON_DB
+    }
+}
+
+/// A stateful three-band EQ. One instance belongs to one decoded peer stream.
+pub struct Eq {
+    settings: EqSettings,
+    low: Biquad,
+    mid: Biquad,
+    high: Biquad,
+}
+
+impl Eq {
+    /// Build an EQ at the application's audio rate (48 kHz).
+    pub fn new(settings: EqSettings) -> Self {
+        Self::with_sample_rate(settings, DEFAULT_SAMPLE_RATE)
+    }
+
+    fn with_sample_rate(settings: EqSettings, sample_rate: f32) -> Self {
+        let settings = settings.clamped();
+        Self {
+            settings,
+            low: Biquad::low_shelf(sample_rate, LOW_SHELF_HZ, settings.low_gain_db, SHELF_Q),
+            mid: Biquad::peaking(sample_rate, MID_PEAK_HZ, settings.mid_gain_db, MID_Q),
+            high: Biquad::high_shelf(sample_rate, HIGH_SHELF_HZ, settings.high_gain_db, SHELF_Q),
+        }
+    }
+
+    pub fn settings(&self) -> EqSettings {
+        self.settings
+    }
+
+    /// Process one mono PCM frame in place. Flat settings are sample-exact bypass.
+    pub fn process_frame(&mut self, frame: &mut [i16]) {
+        if self.settings.is_flat() {
+            return;
+        }
+        for sample in frame {
+            let x = *sample as f32;
+            let y = self.high.process(self.mid.process(self.low.process(x)));
+            *sample = y.round().clamp(i16::MIN as f32, i16::MAX as f32) as i16;
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+struct Coeffs {
+    b0: f32,
+    b1: f32,
+    b2: f32,
+    a1: f32,
+    a2: f32,
+}
+
+impl Coeffs {
+    fn normalized(b0: f32, b1: f32, b2: f32, a0: f32, a1: f32, a2: f32) -> Self {
+        let inv_a0 = 1.0 / a0;
+        Self {
+            b0: b0 * inv_a0,
+            b1: b1 * inv_a0,
+            b2: b2 * inv_a0,
+            a1: a1 * inv_a0,
+            a2: a2 * inv_a0,
+        }
+    }
+
+    fn all_finite(self) -> bool {
+        self.b0.is_finite()
+            && self.b1.is_finite()
+            && self.b2.is_finite()
+            && self.a1.is_finite()
+            && self.a2.is_finite()
+    }
+}
+
+/// Direct Form II transposed biquad. The two delay registers are the state that
+/// must survive across frames.
+struct Biquad {
+    coeffs: Coeffs,
+    z1: f32,
+    z2: f32,
+}
+
+impl Biquad {
+    fn new(coeffs: Coeffs) -> Self {
+        debug_assert!(coeffs.all_finite());
+        Self {
+            coeffs,
+            z1: 0.0,
+            z2: 0.0,
+        }
+    }
+
+    fn low_shelf(sample_rate: f32, freq: f32, gain_db: f32, q: f32) -> Self {
+        let (a, cos_w0, alpha) = rbj_terms(sample_rate, freq, gain_db, q);
+        let sqrt_a = a.sqrt();
+        let b0 = a * ((a + 1.0) - (a - 1.0) * cos_w0 + 2.0 * sqrt_a * alpha);
+        let b1 = 2.0 * a * ((a - 1.0) - (a + 1.0) * cos_w0);
+        let b2 = a * ((a + 1.0) - (a - 1.0) * cos_w0 - 2.0 * sqrt_a * alpha);
+        let a0 = (a + 1.0) + (a - 1.0) * cos_w0 + 2.0 * sqrt_a * alpha;
+        let a1 = -2.0 * ((a - 1.0) + (a + 1.0) * cos_w0);
+        let a2 = (a + 1.0) + (a - 1.0) * cos_w0 - 2.0 * sqrt_a * alpha;
+        Self::new(Coeffs::normalized(b0, b1, b2, a0, a1, a2))
+    }
+
+    fn peaking(sample_rate: f32, freq: f32, gain_db: f32, q: f32) -> Self {
+        let (a, cos_w0, alpha) = rbj_terms(sample_rate, freq, gain_db, q);
+        let b0 = 1.0 + alpha * a;
+        let b1 = -2.0 * cos_w0;
+        let b2 = 1.0 - alpha * a;
+        let a0 = 1.0 + alpha / a;
+        let a1 = -2.0 * cos_w0;
+        let a2 = 1.0 - alpha / a;
+        Self::new(Coeffs::normalized(b0, b1, b2, a0, a1, a2))
+    }
+
+    fn high_shelf(sample_rate: f32, freq: f32, gain_db: f32, q: f32) -> Self {
+        let (a, cos_w0, alpha) = rbj_terms(sample_rate, freq, gain_db, q);
+        let sqrt_a = a.sqrt();
+        let b0 = a * ((a + 1.0) + (a - 1.0) * cos_w0 + 2.0 * sqrt_a * alpha);
+        let b1 = -2.0 * a * ((a - 1.0) + (a + 1.0) * cos_w0);
+        let b2 = a * ((a + 1.0) + (a - 1.0) * cos_w0 - 2.0 * sqrt_a * alpha);
+        let a0 = (a + 1.0) - (a - 1.0) * cos_w0 + 2.0 * sqrt_a * alpha;
+        let a1 = 2.0 * ((a - 1.0) - (a + 1.0) * cos_w0);
+        let a2 = (a + 1.0) - (a - 1.0) * cos_w0 - 2.0 * sqrt_a * alpha;
+        Self::new(Coeffs::normalized(b0, b1, b2, a0, a1, a2))
+    }
+
+    fn process(&mut self, x: f32) -> f32 {
+        let y = self.coeffs.b0 * x + self.z1;
+        self.z1 = self.coeffs.b1 * x - self.coeffs.a1 * y + self.z2;
+        self.z2 = self.coeffs.b2 * x - self.coeffs.a2 * y;
+
+        // Avoid carrying denormal-sized state forever on long quiet tails.
+        if self.z1.abs() < 1.0e-20 {
+            self.z1 = 0.0;
+        }
+        if self.z2.abs() < 1.0e-20 {
+            self.z2 = 0.0;
+        }
+        y
+    }
+}
+
+fn rbj_terms(sample_rate: f32, freq: f32, gain_db: f32, q: f32) -> (f32, f32, f32) {
+    let sr = sample_rate.max(1.0);
+    let f = freq.clamp(1.0, sr * 0.49);
+    let w0 = 2.0 * std::f32::consts::PI * f / sr;
+    let a = 10.0f32.powf(gain_db / 40.0);
+    let alpha = w0.sin() / (2.0 * q.max(0.001));
+    (a, w0.cos(), alpha)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sine(freq: f32, len: usize, amp: f32) -> Vec<i16> {
+        (0..len)
+            .map(|n| {
+                let t = n as f32 / DEFAULT_SAMPLE_RATE;
+                (amp * (2.0 * std::f32::consts::PI * freq * t).sin()).round() as i16
+            })
+            .collect()
+    }
+
+    fn rms(frame: &[i16]) -> f32 {
+        let sum: f32 = frame.iter().map(|&s| (s as f32).powi(2)).sum();
+        (sum / frame.len().max(1) as f32).sqrt()
+    }
+
+    #[test]
+    fn flat_eq_is_sample_exact_identity() {
+        let mut eq = Eq::new(EqSettings::flat());
+        let mut frame: Vec<i16> = (-480..480).map(|n| (n * 31) as i16).collect();
+        let original = frame.clone();
+        eq.process_frame(&mut frame);
+        assert_eq!(frame, original);
+    }
+
+    #[test]
+    fn low_shelf_boost_raises_low_frequency_energy() {
+        let mut eq = Eq::new(EqSettings {
+            low_gain_db: 9.0,
+            ..EqSettings::flat()
+        });
+        let mut low = sine(100.0, 48_000, 3_000.0);
+        let before = rms(&low);
+        eq.process_frame(&mut low);
+        let after = rms(&low);
+        assert!(after > before * 1.6, "low shelf should boost low RMS: {before} -> {after}");
+    }
+
+    #[test]
+    fn high_shelf_boost_raises_high_frequency_energy() {
+        let mut eq = Eq::new(EqSettings {
+            high_gain_db: 9.0,
+            ..EqSettings::flat()
+        });
+        let mut high = sine(8_000.0, 48_000, 3_000.0);
+        let before = rms(&high);
+        eq.process_frame(&mut high);
+        let after = rms(&high);
+        assert!(after > before * 1.6, "high shelf should boost high RMS: {before} -> {after}");
+    }
+
+    #[test]
+    fn coefficients_are_finite_across_supported_gain_range() {
+        for gain in [EQ_GAIN_DB_MIN, -6.0, 0.0, 6.0, EQ_GAIN_DB_MAX] {
+            for b in [
+                Biquad::low_shelf(DEFAULT_SAMPLE_RATE, LOW_SHELF_HZ, gain, SHELF_Q),
+                Biquad::peaking(DEFAULT_SAMPLE_RATE, MID_PEAK_HZ, gain, MID_Q),
+                Biquad::high_shelf(DEFAULT_SAMPLE_RATE, HIGH_SHELF_HZ, gain, SHELF_Q),
+            ] {
+                assert!(b.coeffs.all_finite(), "coefficients must be finite at {gain} dB");
+            }
+        }
+    }
+
+    #[test]
+    fn hot_signal_does_not_nan_or_wrap() {
+        let mut eq = Eq::new(EqSettings {
+            low_gain_db: 12.0,
+            mid_gain_db: 12.0,
+            high_gain_db: 12.0,
+        });
+        let mut frame = sine(1_000.0, 48_000, 30_000.0);
+        eq.process_frame(&mut frame);
+        let peak = frame
+            .iter()
+            .map(|&s| i32::from(s).abs())
+            .max()
+            .unwrap_or(0);
+        assert!(peak > 1_000, "processed signal should retain audible energy");
+        assert!(
+            frame.iter().any(|&s| s > 0) && frame.iter().any(|&s| s < 0),
+            "a boosted sine should retain both polarities"
+        );
+    }
+
+    #[test]
+    fn settings_are_clamped() {
+        let s = EqSettings {
+            low_gain_db: -99.0,
+            mid_gain_db: 2.0,
+            high_gain_db: 99.0,
+        }
+        .clamped();
+        assert_eq!(s.low_gain_db, EQ_GAIN_DB_MIN);
+        assert_eq!(s.mid_gain_db, 2.0);
+        assert_eq!(s.high_gain_db, EQ_GAIN_DB_MAX);
+    }
+}

src/audio/mod.rs

@@ -1,17 +1,22 @@
-use std::sync::mpsc::{Sender, Receiver};
+use std::sync::mpsc::{Receiver, Sender};
 use std::sync::Arc;
 use std::sync::atomic::AtomicUsize;
 use thiserror::Error;
 
-/// Target depth of the playback ring buffer, in samples (48kHz mono).
+/// Playback output channel count. Capture/encode/network remain mono; only the
+/// listener-side playout bus is stereo.
+pub const PLAYBACK_CHANNELS: usize = 2;
+
+/// Target depth of the playback ring buffer, in interleaved samples (48kHz
+/// stereo).
 ///
 /// The playout chain is paced to keep the ring near this level: production is
 /// driven by how fast PipeWire actually drains the ring (the hardware clock),
 /// not by a fixed software timer — which is what eliminates the producer/
 /// consumer beat that otherwise churns ~20% of audio into drops + silence.
-/// 2880 = 60ms = 3×20ms frames, comfortably above the 2048-sample max quantum
+/// 5760 = 60ms = 3×20ms stereo frames, comfortably above the 2048-frame max quantum
 /// so a single hardware pull can never empty the ring before the mixer refills.
-pub const PLAYBACK_TARGET_SAMPLES: usize = 2880;
+pub const PLAYBACK_TARGET_SAMPLES: usize = 2880 * PLAYBACK_CHANNELS;
 
 #[derive(Error, Debug)]
 pub enum AudioError {
@@ -52,9 +57,11 @@ pub trait AudioBackend: Send + Sync {
 }
 
 pub mod echo_cancel;
+pub mod eq;
 pub mod gate;
 pub mod limiter;
 pub mod multitrack;
+pub mod pan;
 pub mod pipewire_impl;
 pub mod pw_cli;
 pub mod recorder;

src/audio/pan.rs

@@ -0,0 +1,77 @@
+//! Listener-side stereo pan law.
+//!
+//! Capture, Opus, and the network stay mono. These helpers are used only after a
+//! peer has been decoded locally, just before the playout mix is written to the
+//! stereo playback bus.
+
+/// Clamp and compute constant-power pan gains for `pan` in `[-1.0, 1.0]`.
+///
+/// - `-1.0` is hard left `(1, 0)`
+/// - `0.0` is center `(sqrt(1/2), sqrt(1/2))`
+/// - `1.0` is hard right `(0, 1)`
+pub fn pan_gains(pan: f32) -> (f32, f32) {
+    let pan = pan.clamp(-1.0, 1.0);
+    let theta = (pan + 1.0) * std::f32::consts::FRAC_PI_4;
+    (theta.cos(), theta.sin())
+}
+
+/// Gains used by the legacy-compatible playback mixer.
+///
+/// The pure law above is constant-power. The existing application, however, was
+/// mono and users heard the full old mono signal in both ears. Scaling by sqrt(2)
+/// makes `pan = 0` exactly dual-mono `(1, 1)`, preserving the default sound while
+/// still following the same equal-power curve as a peer is moved away from center.
+pub fn playback_pan_gains(pan: f32) -> (f32, f32) {
+    let (left, right) = pan_gains(pan);
+    (left * std::f32::consts::SQRT_2, right * std::f32::consts::SQRT_2)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const EPS: f32 = 1.0e-6;
+
+    #[test]
+    fn hard_left_and_right_are_endpoints() {
+        assert_eq!(pan_gains(-1.0), (1.0, 0.0));
+        let (l, r) = pan_gains(1.0);
+        assert!(l.abs() < EPS, "left at hard-right should be zero-ish, got {l}");
+        assert!((r - 1.0).abs() < EPS, "right at hard-right should be one, got {r}");
+    }
+
+    #[test]
+    fn center_is_equal_and_power_preserving() {
+        let (l, r) = pan_gains(0.0);
+        assert!((l - r).abs() < EPS);
+        assert!((l - std::f32::consts::FRAC_1_SQRT_2).abs() < EPS);
+        assert!(((l * l + r * r) - 1.0).abs() < EPS);
+    }
+
+    #[test]
+    fn gains_move_monotonically() {
+        let pans = [-1.0, -0.5, 0.0, 0.5, 1.0];
+        let mut prev_l = f32::INFINITY;
+        let mut prev_r = f32::NEG_INFINITY;
+        for pan in pans {
+            let (l, r) = pan_gains(pan);
+            assert!(l <= prev_l + EPS, "left gain must not rise as pan moves right");
+            assert!(r >= prev_r - EPS, "right gain must not fall as pan moves right");
+            prev_l = l;
+            prev_r = r;
+        }
+    }
+
+    #[test]
+    fn playback_center_preserves_legacy_dual_mono() {
+        let (l, r) = playback_pan_gains(0.0);
+        assert!((l - 1.0).abs() < EPS);
+        assert!((r - 1.0).abs() < EPS);
+    }
+
+    #[test]
+    fn input_is_clamped() {
+        assert_eq!(pan_gains(-9.0), pan_gains(-1.0));
+        assert_eq!(pan_gains(9.0), pan_gains(1.0));
+    }
+}

src/audio/pipewire_impl.rs

@@ -283,8 +283,9 @@ fn run_playback(
     let core = context.connect_rc(None)
         .map_err(|e| AudioError::Init(e.to_string()))?;
 
-    // Ring buffer setup: 9600 samples (200ms capacity for mono 48kHz).
-    const RING_CAPACITY: usize = 9600;
+    // Ring buffer setup: 19200 interleaved samples (200ms capacity for stereo
+    // 48kHz).
+    const RING_CAPACITY: usize = 9600 * crate::audio::PLAYBACK_CHANNELS;
     let rb = HeapRb::<i16>::new(RING_CAPACITY);
     let (mut producer, consumer) = rb.split();
 
@@ -371,7 +372,7 @@ fn run_playback(
                     let data = &mut datas[0];
                     let mut total_size = 0;
                     if let Some(slice) = data.data() {
-                        let stride = 2; // S16LE Mono = 2 bytes per frame
+                        let stride = 2 * crate::audio::PLAYBACK_CHANNELS; // S16LE stereo
                         // Fill exactly what the graph asked for this cycle (with
                         // a safe fallback), never the whole mapped slice — that
                         // over-pull past the ring depth was the original crackle.
@@ -383,17 +384,20 @@ fn run_playback(
                         user_data.callback_count.fetch_add(1, Ordering::Relaxed);
                         let mut starved = 0u64;
                         for i in 0..n_frames {
-                            let val = match user_data.consumer.try_pop() {
-                                Some(v) => v,
-                                None => {
-                                    starved += 1;
-                                    0
-                                }
-                            };
-                            let bytes = val.to_le_bytes();
                             let start = i * stride;
-                            slice[start] = bytes[0];
-                            slice[start + 1] = bytes[1];
+                            for ch in 0..crate::audio::PLAYBACK_CHANNELS {
+                                let val = match user_data.consumer.try_pop() {
+                                    Some(v) => v,
+                                    None => {
+                                        starved += 1;
+                                        0
+                                    }
+                                };
+                                let bytes = val.to_le_bytes();
+                                let offset = start + ch * 2;
+                                slice[offset] = bytes[0];
+                                slice[offset + 1] = bytes[1];
+                            }
                         }
                         if starved > 0 {
                             // One wait-free atomic add per quantum — RT-safe.
@@ -403,7 +407,8 @@ fn run_playback(
                         // actually pulled (excluding underruns, which removed
                         // nothing) so the mixer paces against true ring depth.
                         // Wait-free fetch_sub, RT-safe.
-                        let popped = n_frames - starved as usize;
+                        let requested_samples = n_frames * crate::audio::PLAYBACK_CHANNELS;
+                        let popped = requested_samples - starved as usize;
                         if popped > 0 {
                             user_data.fill_gauge.fetch_sub(popped, Ordering::Relaxed);
                         }
@@ -411,7 +416,7 @@ fn run_playback(
                     }
                     let chunk = data.chunk_mut();
                     *chunk.offset_mut() = 0;
-                    *chunk.stride_mut() = 2;
+                    *chunk.stride_mut() = (2 * crate::audio::PLAYBACK_CHANNELS) as _;
                     *chunk.size_mut() = total_size as _;
                 }
             }
@@ -422,7 +427,7 @@ fn run_playback(
     let mut audio_info = spa::param::audio::AudioInfoRaw::new();
     audio_info.set_format(spa::param::audio::AudioFormat::S16LE);
     audio_info.set_rate(48000);
-    audio_info.set_channels(1); // Mono
+    audio_info.set_channels(crate::audio::PLAYBACK_CHANNELS as u32); // Stereo playback
 
     let obj = pw::spa::pod::Object {
         type_: pw::spa::utils::SpaTypes::ObjectParamFormat.as_raw(),
@@ -450,7 +455,7 @@ fn run_playback(
     // `frames_to_produce`). `requested()`, not the buffer size, now governs
     // per-cycle output, so this is a generous max rather than a hard pin.
     const MAX_QUANTUM_FRAMES: i32 = 8192;
-    const STRIDE: i32 = 2; // S16LE mono = 2 bytes/frame
+    const STRIDE: i32 = 2 * crate::audio::PLAYBACK_CHANNELS as i32; // S16LE stereo
     let buffers_obj = pw::spa::pod::Object {
         type_: pw::spa::utils::SpaTypes::ObjectParamBuffers.as_raw(),
         id: pw::spa::param::ParamType::Buffers.as_raw(),
@@ -555,7 +560,7 @@ fn run_playback(
             if verbose || du > 0 || dd > 0 {
                 crate::log_msg(&format!(
                     "playout-health: fill={fill} samples (~{}ms) | underrun +{du} samples/s (total {u}) | dropped +{dd} frames/s (total {d}) | quantum={q} frames, {dc} callbacks/s",
-                    fill / 48,
+                    fill / (48 * crate::audio::PLAYBACK_CHANNELS),
                 ));
             }
         }