Skip to main content

qualia_audio/features/spectral/
panning.rs

1//! Stereo panning coefficient from a left/right pair (energy ratio).
2
3use crate::types::AudioError;
4
5/// Panning coefficient of a stereo pair from its channel energy balance.
6///
7/// `left` and `right` are matching-length slices — either time-domain samples
8/// or magnitude-spectrum bins of the two channels. With
9/// `E_L = Σ left[i]^2` and `E_R = Σ right[i]^2`, the coefficient is
10///
11/// ```text
12/// pan = (E_R - E_L) / (E_R + E_L)
13/// ```
14///
15/// It lies in `[-1, 1]`: `-1` = hard left, `0` = centred (equal energy),
16/// `+1` = hard right.
17///
18/// Zero-heap: single pass, scalar result.
19///
20/// # Errors
21/// - [`AudioError::InvalidParameter`] if the slices are empty, differ in
22///   length, or carry no energy at all (silence — panning is undefined).
23pub fn panning(left: &[f32], right: &[f32]) -> Result<f32, AudioError> {
24    if left.is_empty() || left.len() != right.len() {
25        return Err(AudioError::InvalidParameter);
26    }
27    let mut el = 0.0f64;
28    let mut er = 0.0f64;
29    for i in 0..left.len() {
30        el += left[i] as f64 * left[i] as f64;
31        er += right[i] as f64 * right[i] as f64;
32    }
33    let total = el + er;
34    if total == 0.0 {
35        return Err(AudioError::InvalidParameter);
36    }
37    Ok(((er - el) / total) as f32)
38}
39
40#[cfg(test)]
41mod tests {
42    use super::*;
43
44    #[test]
45    fn centred_is_zero() {
46        let l = [1.0f32, -1.0, 0.5];
47        let r = [1.0f32, -1.0, 0.5];
48        let p = panning(&l, &r).expect("pan");
49        assert!(p.abs() < 1e-6, "pan={p}");
50    }
51
52    #[test]
53    fn hard_left_is_minus_one() {
54        let l = [1.0f32, 1.0, 1.0];
55        let r = [0.0f32, 0.0, 0.0];
56        let p = panning(&l, &r).expect("pan");
57        assert!((p + 1.0).abs() < 1e-6, "pan={p}");
58    }
59
60    #[test]
61    fn hard_right_is_plus_one() {
62        let l = [0.0f32, 0.0, 0.0];
63        let r = [2.0f32, 2.0, 2.0];
64        let p = panning(&l, &r).expect("pan");
65        assert!((p - 1.0).abs() < 1e-6, "pan={p}");
66    }
67
68    #[test]
69    fn skewed_right_is_positive() {
70        // E_L = 1, E_R = 4 -> (4-1)/(4+1) = 0.6
71        let l = [1.0f32];
72        let r = [2.0f32];
73        let p = panning(&l, &r).expect("pan");
74        assert!((p - 0.6).abs() < 1e-5, "pan={p}");
75    }
76
77    #[test]
78    fn rejects_silence_and_mismatch() {
79        assert_eq!(
80            panning(&[0.0, 0.0], &[0.0, 0.0]),
81            Err(AudioError::InvalidParameter)
82        );
83        assert_eq!(
84            panning(&[1.0], &[1.0, 2.0]),
85            Err(AudioError::InvalidParameter)
86        );
87        assert_eq!(panning(&[], &[]), Err(AudioError::InvalidParameter));
88    }
89}