Skip to main content

qualia_core_db/audio/dsp/
envelope.rs

1//! ADSR envelope — attack, decay, sustain, release.
2//!
3//! Generates amplitude envelopes for note shaping. The envelope progresses
4//! through four stages:
5//! - Attack: 0 → 1 over `attack` seconds
6//! - Decay: 1 → `sustain` over `decay` seconds
7//! - Sustain: holds at `sustain` level until release
8//! - Release: current → 0 over `release` seconds
9
10/// Envelope stage.
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub enum EnvStage {
13    /// Not running — output is 0.
14    Idle,
15    /// Ramping 0 → 1 over `attack` seconds.
16    Attack,
17    /// Falling 1 → `sustain` over `decay` seconds.
18    Decay,
19    /// Holding at `sustain` until `note_off`.
20    Sustain,
21    /// Falling to 0 over `release` seconds, then `Idle`.
22    Release,
23}
24
25/// ADSR envelope generator.
26#[derive(Debug, Clone)]
27pub struct AdsrEnvelope {
28    /// Attack time in seconds.
29    pub attack: f64,
30    /// Decay time in seconds.
31    pub decay: f64,
32    /// Sustain level `[0, 1]` (clamped at construction).
33    pub sustain: f64,
34    /// Release time in seconds.
35    pub release: f64,
36    /// Sample rate the stage times are evaluated against.
37    pub sample_rate: f64,
38    stage: EnvStage,
39    value: f64,
40    samples_in_stage: u64,
41}
42
43impl AdsrEnvelope {
44    /// Create an idle envelope; times in seconds, `sustain` clamped to
45    /// `[0, 1]`.
46    pub fn new(attack: f64, decay: f64, sustain: f64, release: f64, sample_rate: f64) -> Self {
47        Self {
48            attack,
49            decay,
50            sustain: sustain.clamp(0.0, 1.0),
51            release,
52            sample_rate,
53            stage: EnvStage::Idle,
54            value: 0.0,
55            samples_in_stage: 0,
56        }
57    }
58
59    /// Start note-on (trigger attack).
60    pub fn note_on(&mut self) {
61        self.stage = EnvStage::Attack;
62        self.samples_in_stage = 0;
63    }
64
65    /// Start note-off (trigger release).
66    pub fn note_off(&mut self) {
67        self.stage = EnvStage::Release;
68        self.samples_in_stage = 0;
69    }
70
71    /// Current stage.
72    pub fn stage(&self) -> EnvStage {
73        self.stage
74    }
75
76    /// Current envelope value.
77    pub fn value(&self) -> f64 {
78        self.value
79    }
80
81    /// Advance one sample and return the envelope value.
82    pub fn tick(&mut self) -> f64 {
83        let sr = self.sample_rate;
84        match self.stage {
85            EnvStage::Idle => {
86                self.value = 0.0;
87            }
88            EnvStage::Attack => {
89                let attack_samples = (self.attack * sr).max(1.0);
90                self.value = self.samples_in_stage as f64 / attack_samples;
91                self.samples_in_stage += 1;
92                if self.samples_in_stage as f64 >= attack_samples {
93                    self.stage = EnvStage::Decay;
94                    self.samples_in_stage = 0;
95                    self.value = 1.0;
96                }
97            }
98            EnvStage::Decay => {
99                let decay_samples = (self.decay * sr).max(1.0);
100                let t = self.samples_in_stage as f64 / decay_samples;
101                self.value = 1.0 - t * (1.0 - self.sustain);
102                self.samples_in_stage += 1;
103                if self.samples_in_stage as f64 >= decay_samples {
104                    self.stage = EnvStage::Sustain;
105                    self.samples_in_stage = 0;
106                    self.value = self.sustain;
107                }
108            }
109            EnvStage::Sustain => {
110                self.value = self.sustain;
111            }
112            EnvStage::Release => {
113                let release_samples = (self.release * sr).max(1.0);
114                let start_value = if self.samples_in_stage == 0 {
115                    self.value
116                } else {
117                    self.value
118                };
119                let t = self.samples_in_stage as f64 / release_samples;
120                self.value = start_value * (1.0 - t);
121                self.samples_in_stage += 1;
122                if self.samples_in_stage as f64 >= release_samples {
123                    self.stage = EnvStage::Idle;
124                    self.value = 0.0;
125                }
126            }
127        }
128        self.value
129    }
130
131    /// Render `n` samples into `out`.
132    pub fn render(&mut self, out: &mut [f64]) {
133        for s in out.iter_mut() {
134            *s = self.tick();
135        }
136    }
137
138    /// Reset to idle.
139    pub fn reset(&mut self) {
140        self.stage = EnvStage::Idle;
141        self.value = 0.0;
142        self.samples_in_stage = 0;
143    }
144}
145
146#[cfg(test)]
147mod tests {
148    use super::*;
149
150    #[test]
151    fn adsr_attack_stage() {
152        let mut env = AdsrEnvelope::new(0.01, 0.01, 0.5, 0.01, 44100.0);
153        env.note_on();
154        assert_eq!(env.stage(), EnvStage::Attack);
155        // After enough samples, should move to decay.
156        for _ in 0..500 {
157            env.tick();
158        }
159        assert_eq!(env.stage(), EnvStage::Decay);
160    }
161
162    #[test]
163    fn adsr_sustain_level() {
164        let mut env = AdsrEnvelope::new(0.001, 0.001, 0.7, 0.01, 44100.0);
165        env.note_on();
166        // Skip attack + decay.
167        for _ in 0..200 {
168            env.tick();
169        }
170        assert_eq!(env.stage(), EnvStage::Sustain);
171        let v = env.tick();
172        assert!((v - 0.7).abs() < 0.01);
173    }
174
175    #[test]
176    fn adsr_release_stage() {
177        let mut env = AdsrEnvelope::new(0.001, 0.001, 0.8, 0.01, 44100.0);
178        env.note_on();
179        for _ in 0..200 {
180            env.tick();
181        }
182        env.note_off();
183        assert_eq!(env.stage(), EnvStage::Release);
184        // After release time, should be idle.
185        for _ in 0..500 {
186            env.tick();
187        }
188        assert_eq!(env.stage(), EnvStage::Idle);
189    }
190
191    #[test]
192    fn adsr_idle_is_zero() {
193        let mut env = AdsrEnvelope::new(0.01, 0.01, 0.5, 0.01, 44100.0);
194        let v = env.tick();
195        assert_eq!(v, 0.0);
196    }
197
198    #[test]
199    fn adsr_attack_ramps_up() {
200        let mut env = AdsrEnvelope::new(0.1, 0.1, 0.5, 0.1, 44100.0);
201        env.note_on();
202        let v1 = env.tick();
203        let v2 = env.tick();
204        assert!(v2 > v1);
205    }
206
207    #[test]
208    fn adsr_reset() {
209        let mut env = AdsrEnvelope::new(0.01, 0.01, 0.5, 0.01, 44100.0);
210        env.note_on();
211        for _ in 0..100 {
212            env.tick();
213        }
214        env.reset();
215        assert_eq!(env.stage(), EnvStage::Idle);
216        assert_eq!(env.value(), 0.0);
217    }
218
219    #[test]
220    fn adsr_sustain_clamped() {
221        let env = AdsrEnvelope::new(0.01, 0.01, 1.5, 0.01, 44100.0);
222        assert_eq!(env.sustain, 1.0);
223    }
224}