Skip to main content

qualia_audio/midi/synth/
adsr.rs

1//! ADSR amplitude envelope — sample-rate based, linear segments, zero-alloc.
2//!
3//! `process_sample()` advances the envelope by one sample and returns the current
4//! gain in `0.0..=1.0`. All state is inline (`Copy`); no heap, no locks, no FS.
5
6/// Envelope segment.
7#[derive(Clone, Copy, PartialEq, Eq, Debug)]
8enum Stage {
9    Idle,
10    Attack,
11    Decay,
12    Sustain,
13    Release,
14}
15
16/// A four-stage attack/decay/sustain/release amplitude envelope.
17///
18/// Segment lengths are stored in samples (derived from seconds × sample-rate at
19/// construction). Attack ramps `0 → 1`, decay ramps `1 → sustain`, sustain holds,
20/// and release ramps the level captured at `note_off()` down to `0`.
21#[derive(Clone, Copy, Debug)]
22pub struct AdsrEnvelope {
23    attack_samples: f32,
24    decay_samples: f32,
25    sustain_level: f32,
26    release_samples: f32,
27    stage: Stage,
28    level: f32,
29    release_start_level: f32,
30}
31
32impl AdsrEnvelope {
33    /// Build an envelope. Times are in seconds; `sustain` is a `0..=1` level.
34    /// Non-finite / negative inputs are clamped to safe values.
35    pub fn new(
36        sample_rate: f32,
37        attack_s: f32,
38        decay_s: f32,
39        sustain: f32,
40        release_s: f32,
41    ) -> Self {
42        let sr = if sample_rate.is_finite() && sample_rate > 0.0 {
43            sample_rate
44        } else {
45            1.0
46        };
47        let to_samples = |secs: f32| -> f32 {
48            if secs.is_finite() && secs > 0.0 {
49                secs * sr
50            } else {
51                0.0
52            }
53        };
54        let sustain_level = if sustain.is_finite() {
55            sustain.clamp(0.0, 1.0)
56        } else {
57            0.0
58        };
59        Self {
60            attack_samples: to_samples(attack_s),
61            decay_samples: to_samples(decay_s),
62            sustain_level,
63            release_samples: to_samples(release_s),
64            stage: Stage::Idle,
65            level: 0.0,
66            release_start_level: 0.0,
67        }
68    }
69
70    /// Trigger the envelope: enter the attack stage (rising from the current level).
71    pub fn note_on(&mut self) {
72        self.stage = Stage::Attack;
73    }
74
75    /// Release the envelope: ramp the current level down to zero over the release time.
76    pub fn note_off(&mut self) {
77        if self.stage != Stage::Idle {
78            self.release_start_level = self.level;
79            self.stage = Stage::Release;
80        }
81    }
82
83    /// `true` while the envelope is producing (or will produce) a non-zero contribution.
84    #[inline]
85    pub fn is_active(&self) -> bool {
86        self.stage != Stage::Idle
87    }
88
89    /// Current sustain level (`0..=1`).
90    #[inline]
91    pub fn sustain_level(&self) -> f32 {
92        self.sustain_level
93    }
94
95    /// Advance one sample and return the current gain in `0.0..=1.0`.
96    pub fn process_sample(&mut self) -> f32 {
97        match self.stage {
98            Stage::Idle => {
99                self.level = 0.0;
100            }
101            Stage::Attack => {
102                if self.attack_samples <= 0.0 {
103                    self.level = 1.0;
104                    self.stage = Stage::Decay;
105                } else {
106                    self.level += 1.0 / self.attack_samples;
107                    if self.level >= 1.0 {
108                        self.level = 1.0;
109                        self.stage = Stage::Decay;
110                    }
111                }
112            }
113            Stage::Decay => {
114                if self.decay_samples <= 0.0 {
115                    self.level = self.sustain_level;
116                    self.stage = Stage::Sustain;
117                } else {
118                    self.level -= (1.0 - self.sustain_level) / self.decay_samples;
119                    if self.level <= self.sustain_level {
120                        self.level = self.sustain_level;
121                        self.stage = Stage::Sustain;
122                    }
123                }
124            }
125            Stage::Sustain => {
126                self.level = self.sustain_level;
127            }
128            Stage::Release => {
129                if self.release_samples <= 0.0 {
130                    self.level = 0.0;
131                    self.stage = Stage::Idle;
132                } else {
133                    self.level -= self.release_start_level / self.release_samples;
134                    if self.level <= 0.0 {
135                        self.level = 0.0;
136                        self.stage = Stage::Idle;
137                    }
138                }
139            }
140        }
141        self.level
142    }
143}
144
145#[cfg(test)]
146mod tests {
147    use super::*;
148
149    const SR: f32 = 48_000.0;
150
151    #[test]
152    fn attack_rises_monotonically_from_near_zero() {
153        // 10 ms attack = 480 samples at 48 kHz.
154        let mut env = AdsrEnvelope::new(SR, 0.010, 0.010, 0.5, 0.010);
155        env.note_on();
156        let mut prev = env.process_sample();
157        assert!(
158            prev > 0.0 && prev < 0.01,
159            "first attack gain ~0, got {prev}"
160        );
161        // Stay within the attack region (< 480 samples) and assert strict rise.
162        for _ in 0..460 {
163            let g = env.process_sample();
164            assert!(g > prev, "attack must rise monotonically: {g} !> {prev}");
165            assert!(g <= 1.0 + 1e-6, "gain bounded by 1.0, got {g}");
166            prev = g;
167        }
168    }
169
170    #[test]
171    fn sustain_holds_at_sustain_level() {
172        let mut env = AdsrEnvelope::new(SR, 0.010, 0.010, 0.5, 0.010);
173        env.note_on();
174        // Run well past attack+decay (480+480) into sustain.
175        let mut g = 0.0;
176        for _ in 0..2_000 {
177            g = env.process_sample();
178        }
179        assert!(
180            (g - 0.5).abs() < 1e-3,
181            "sustain should hold at 0.5, got {g}"
182        );
183        // Continues to hold.
184        for _ in 0..1_000 {
185            g = env.process_sample();
186        }
187        assert!((g - 0.5).abs() < 1e-3, "sustain still 0.5, got {g}");
188    }
189
190    #[test]
191    fn release_falls_to_zero_within_release_time() {
192        let mut env = AdsrEnvelope::new(SR, 0.010, 0.010, 0.5, 0.010);
193        env.note_on();
194        for _ in 0..2_000 {
195            env.process_sample();
196        }
197        // At sustain (~0.5) now release.
198        env.note_off();
199        // 10 ms release = 480 samples; give a small margin.
200        let mut g = 1.0;
201        for _ in 0..500 {
202            g = env.process_sample();
203        }
204        assert!(
205            g <= 1e-3,
206            "release should reach ~0 within release time, got {g}"
207        );
208        assert!(!env.is_active(), "envelope idle after release completes");
209    }
210
211    #[test]
212    fn instant_attack_and_release_are_safe() {
213        let mut env = AdsrEnvelope::new(SR, 0.0, 0.0, 0.7, 0.0);
214        env.note_on();
215        let g = env.process_sample();
216        assert!((g - 1.0).abs() < 1e-6 || (g - 0.7).abs() < 1e-6);
217        env.note_off();
218        let g2 = env.process_sample();
219        assert_eq!(g2, 0.0);
220        assert!(!env.is_active());
221    }
222}