qualia_audio/midi/synth/
adsr.rs1#[derive(Clone, Copy, PartialEq, Eq, Debug)]
8enum Stage {
9 Idle,
10 Attack,
11 Decay,
12 Sustain,
13 Release,
14}
15
16#[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 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 pub fn note_on(&mut self) {
72 self.stage = Stage::Attack;
73 }
74
75 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 #[inline]
85 pub fn is_active(&self) -> bool {
86 self.stage != Stage::Idle
87 }
88
89 #[inline]
91 pub fn sustain_level(&self) -> f32 {
92 self.sustain_level
93 }
94
95 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 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 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 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 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 env.note_off();
199 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}