naad 1.2.5

naad — Audio synthesis primitives: oscillators, filters, envelopes, modulation, wavetables, effects
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Stereo panning utilities.
//!
//! Provides equal-power and linear panning laws for stereo signal placement.

use serde::{Deserialize, Serialize};

/// Panning law used for stereo positioning.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub enum PanLaw {
    /// Equal-power (constant-power) panning using sin/cos.
    /// Preserves perceived loudness across the stereo field.
    EqualPower,
    /// Linear panning. Simple but perceived loudness dips at center.
    Linear,
}

/// Stereo panning gains (left and right channel multipliers).
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct PanGains {
    /// Left channel gain.
    pub left: f32,
    /// Right channel gain.
    pub right: f32,
}

/// Compute stereo panning gains for a given pan position.
///
/// `pan` ranges from -1.0 (full left) to +1.0 (full right), with 0.0 = center.
#[inline]
#[must_use]
pub fn pan_gains(pan: f32, law: PanLaw) -> PanGains {
    let p = pan.clamp(-1.0, 1.0);
    // Map -1..+1 to 0..1
    let t = (p + 1.0) * 0.5;

    match law {
        PanLaw::EqualPower => {
            let angle = t * std::f32::consts::FRAC_PI_2;
            PanGains {
                left: angle.cos(),
                right: angle.sin(),
            }
        }
        PanLaw::Linear => PanGains {
            left: 1.0 - t,
            right: t,
        },
    }
}

/// Apply panning to a mono sample, returning (left, right).
#[inline]
#[must_use]
pub fn pan_mono(sample: f32, pan: f32, law: PanLaw) -> (f32, f32) {
    let g = pan_gains(pan, law);
    (sample * g.left, sample * g.right)
}

/// Stereo balance: attenuate one channel to shift the image.
///
/// `balance` ranges from -1.0 (left only) to +1.0 (right only).
#[inline]
#[must_use]
pub fn stereo_balance(left: f32, right: f32, balance: f32) -> (f32, f32) {
    let b = balance.clamp(-1.0, 1.0);
    if b < 0.0 {
        // Attenuate right
        (left, right * (1.0 + b))
    } else {
        // Attenuate left
        (left * (1.0 - b), right)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_center_equal_power() {
        let g = pan_gains(0.0, PanLaw::EqualPower);
        // At center, both channels should be equal (~0.707)
        assert!((g.left - g.right).abs() < 0.01);
        // Power should sum to ~1.0
        assert!((g.left * g.left + g.right * g.right - 1.0).abs() < 0.01);
    }

    #[test]
    fn test_full_left() {
        let g = pan_gains(-1.0, PanLaw::EqualPower);
        assert!((g.left - 1.0).abs() < 0.01);
        assert!(g.right.abs() < 0.01);
    }

    #[test]
    fn test_full_right() {
        let g = pan_gains(1.0, PanLaw::EqualPower);
        assert!(g.left.abs() < 0.01);
        assert!((g.right - 1.0).abs() < 0.01);
    }

    #[test]
    fn test_linear_center() {
        let g = pan_gains(0.0, PanLaw::Linear);
        assert!((g.left - 0.5).abs() < f32::EPSILON);
        assert!((g.right - 0.5).abs() < f32::EPSILON);
    }

    #[test]
    fn test_pan_mono() {
        let (l, r) = pan_mono(1.0, -1.0, PanLaw::EqualPower);
        assert!((l - 1.0).abs() < 0.01);
        assert!(r.abs() < 0.01);
    }

    #[test]
    fn test_stereo_balance() {
        let (l, r) = stereo_balance(1.0, 1.0, -1.0);
        assert!((l - 1.0).abs() < f32::EPSILON);
        assert!(r.abs() < f32::EPSILON);
    }

    #[test]
    fn test_serde_roundtrip() {
        let g = pan_gains(0.3, PanLaw::EqualPower);
        let json = serde_json::to_string(&g).unwrap();
        let back: PanGains = serde_json::from_str(&json).unwrap();
        assert!((g.left - back.left).abs() < f32::EPSILON);
    }
}