1use crate::{Animated, TrackId};
2use alpha2_time::{MediaTime, TICKS_PER_SECOND};
3use serde::{Deserialize, Serialize};
4
5pub(crate) const TICKS_PER_MS: u32 = 120;
6const _: () = assert!(TICKS_PER_SECOND == 1_000 * TICKS_PER_MS as i64);
7
8pub const MAX_GAIN: f32 = 16.0;
10
11pub const MAX_AUDIO_EFFECTS: usize = 8_192;
15
16pub const MAX_AUDIO_DELAY_MS: u32 = 120_000;
20
21pub const AUDIO_EFFECT_STATE_MARGIN_MS: u32 = 1_100;
26
27pub const REVERB_DELAY_MS: u32 = 160;
30
31pub const MAX_EQ_GAIN_DB: f32 = 36.0;
33
34pub const EQ_Q_RANGE: std::ops::RangeInclusive<f32> = 0.05..=50.0;
36
37pub const EQ_FREQUENCY_RANGE_HZ: std::ops::RangeInclusive<f32> = 10.0..=47_040.0;
41
42pub const MAX_COMPRESSOR_RATIO: f32 = 100.0;
44
45pub const MAX_CHAIN_EFFECTS: usize = 16;
47
48pub const MAX_EQ_BANDS: usize = 16;
50
51pub const MIN_LEVEL_DB: f32 = -96.0;
53
54pub const MAX_LOOKAHEAD_MS: f32 = 100.0;
56
57pub const MAX_ENVELOPE_MS: f32 = 10_000.0;
59
60#[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
62#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
63#[serde(rename_all = "snake_case")]
64pub enum EqBandKind {
65 Peaking,
67 LowPass,
69 HighPass,
71}
72
73#[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
75#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
76#[serde(deny_unknown_fields)]
77pub struct EqBand {
78 pub kind: EqBandKind,
80 pub frequency_hz: f32,
82 pub q: f32,
84 #[serde(default)]
87 pub gain_db: f32,
88}
89
90impl EqBand {
91 fn is_valid(self) -> bool {
92 EQ_FREQUENCY_RANGE_HZ.contains(&self.frequency_hz)
93 && EQ_Q_RANGE.contains(&self.q)
94 && self.gain_db.is_finite()
95 && self.gain_db.abs() <= MAX_EQ_GAIN_DB
96 }
97}
98
99#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
103#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
104#[serde(deny_unknown_fields)]
105#[serde(tag = "type", rename_all = "snake_case")]
106pub enum AudioEffect {
107 Eq {
109 #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_EQ_BANDS }>")]
111 #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_EQ_BANDS)))]
112 bands: Vec<EqBand>,
113 },
114 Compressor {
116 threshold_db: f32,
118 ratio: f32,
120 attack_ms: f32,
122 release_ms: f32,
124 #[serde(default)]
126 lookahead_ms: f32,
127 },
128 Reverb {
130 room_size: f32,
132 damping: f32,
134 mix: f32,
136 },
137}
138
139impl AudioEffect {
140 #[must_use]
143 pub fn delay_ticks(&self) -> u64 {
144 match self {
145 Self::Eq { .. } => 0,
146 Self::Compressor { .. } => self.lookahead_ticks(),
147 Self::Reverb { .. } => u64::from(REVERB_DELAY_MS) * u64::from(TICKS_PER_MS),
148 }
149 }
150
151 #[must_use]
154 pub fn lookahead_ticks(&self) -> u64 {
155 match self {
156 #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
158 Self::Compressor { lookahead_ms, .. } if *lookahead_ms > 0.0 => {
159 (f64::from(*lookahead_ms) * f64::from(TICKS_PER_MS)).ceil() as u64
160 }
161 _ => 0,
162 }
163 }
164
165 pub(crate) fn is_valid(&self) -> bool {
166 match self {
167 Self::Eq { bands } => {
168 !bands.is_empty()
169 && bands.len() <= MAX_EQ_BANDS
170 && bands.iter().copied().all(EqBand::is_valid)
171 }
172 Self::Compressor {
173 threshold_db,
174 ratio,
175 attack_ms,
176 release_ms,
177 lookahead_ms,
178 } => {
179 threshold_db.is_finite()
180 && (MIN_LEVEL_DB..=0.0).contains(threshold_db)
181 && (1.0..=MAX_COMPRESSOR_RATIO).contains(ratio)
182 && positive_ms(*attack_ms)
183 && positive_ms(*release_ms)
184 && lookahead_ms.is_finite()
185 && (0.0..=MAX_LOOKAHEAD_MS).contains(lookahead_ms)
186 }
187 Self::Reverb {
188 room_size,
189 damping,
190 mix,
191 } => unit(*room_size) && unit(*damping) && unit(*mix),
192 }
193 }
194}
195
196#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
198#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
199#[serde(deny_unknown_fields)]
200pub struct Ducking {
201 pub sidechain_track: TrackId,
203 pub threshold: f32,
205 pub depth_db: f32,
207 pub attack_ms: f32,
209 pub release_ms: f32,
211}
212
213impl Ducking {
214 fn is_valid(&self) -> bool {
215 self.threshold.is_finite()
216 && self.threshold > 0.0
217 && self.depth_db.is_finite()
218 && (MIN_LEVEL_DB..=0.0).contains(&self.depth_db)
219 && positive_ms(self.attack_ms)
220 && positive_ms(self.release_ms)
221 }
222}
223
224#[derive(Copy, Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
226#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
227#[serde(rename_all = "snake_case")]
228pub enum FadeShape {
229 #[default]
231 Linear,
232 EqualPower,
234}
235
236impl FadeShape {
237 #[must_use]
239 pub fn amplitude(self, progress: f32) -> f32 {
240 let progress = progress.clamp(0.0, 1.0);
241 match self {
242 Self::Linear => progress,
243 Self::EqualPower => libm::sinf(progress * core::f32::consts::FRAC_PI_2),
244 }
245 }
246}
247
248#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
250#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
251#[serde(deny_unknown_fields)]
252pub struct AudioProperties {
253 #[serde(default = "unit_gain")]
255 pub gain: Animated<f32>,
256 #[serde(default = "center_pan")]
258 pub pan: Animated<f32>,
259 #[serde(default)]
261 pub fade_in: MediaTime,
262 #[serde(default)]
264 pub fade_out: MediaTime,
265 #[serde(default)]
267 pub fade_shape: FadeShape,
268 #[serde(default)]
270 pub muted: bool,
271 #[serde(default)]
273 #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_CHAIN_EFFECTS }>")]
274 #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_CHAIN_EFFECTS)))]
275 pub effects: Vec<AudioEffect>,
276 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
279 pub preserve_pitch: bool,
280 #[serde(default, skip_serializing_if = "Option::is_none")]
283 pub stream: Option<u32>,
284 #[serde(default, skip_serializing_if = "Option::is_none")]
288 #[serde(
289 deserialize_with = "crate::bounded::option_seq::<_, _, { crate::MAX_SELECTED_CHANNELS }>"
290 )]
291 #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_SELECTED_CHANNELS)))]
292 pub channels: Option<Vec<u32>>,
293}
294
295pub const MAX_SELECTED_CHANNELS: usize = 2;
297
298impl Default for AudioProperties {
299 fn default() -> Self {
300 Self {
301 gain: unit_gain(),
302 pan: center_pan(),
303 fade_in: MediaTime::ZERO,
304 fade_out: MediaTime::ZERO,
305 fade_shape: FadeShape::Linear,
306 muted: false,
307 effects: Vec::new(),
308 preserve_pitch: false,
309 stream: None,
310 channels: None,
311 }
312 }
313}
314
315impl AudioProperties {
316 #[must_use]
318 pub fn is_audible(&self) -> bool {
319 !self.muted
320 && match &self.gain {
321 Animated::Constant { value } => *value > 0.0,
322 Animated::Keyframes { keyframes } => {
323 keyframes.iter().any(|keyframe| keyframe.value > 0.0)
324 }
325 Animated::Data(_) => true,
326 }
327 }
328
329 pub(crate) fn validate(&self) -> bool {
330 valid_gain(&self.gain)
331 && valid_pan(&self.pan)
332 && self.fade_in.ticks() >= 0
333 && self.fade_out.ticks() >= 0
334 && self.effects.len() <= MAX_CHAIN_EFFECTS
335 && self.effects.iter().all(AudioEffect::is_valid)
336 && self.channels.as_deref().is_none_or(valid_channel_selection)
337 }
338}
339
340fn valid_channel_selection(channels: &[u32]) -> bool {
341 (1..=MAX_SELECTED_CHANNELS).contains(&channels.len())
342 && channels
343 .iter()
344 .all(|&channel| (channel as usize) < alpha2_media::MAX_AUDIO_CHANNELS)
345 && channels.first() != channels.get(1)
346}
347
348#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
350#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
351#[serde(deny_unknown_fields)]
352pub struct TrackAudio {
353 #[serde(default = "unit_gain")]
355 pub gain: Animated<f32>,
356 #[serde(default = "center_pan")]
358 pub pan: Animated<f32>,
359 #[serde(default)]
361 pub muted: bool,
362 #[serde(default)]
364 pub solo: bool,
365 #[serde(default)]
368 #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_CHAIN_EFFECTS }>")]
369 #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_CHAIN_EFFECTS)))]
370 pub effects: Vec<AudioEffect>,
371 #[serde(default)]
373 pub ducking: Option<Ducking>,
374}
375
376impl Default for TrackAudio {
377 fn default() -> Self {
378 Self {
379 gain: unit_gain(),
380 pan: center_pan(),
381 muted: false,
382 solo: false,
383 effects: Vec::new(),
384 ducking: None,
385 }
386 }
387}
388
389impl TrackAudio {
390 #[must_use]
393 pub const fn is_silenced(&self, any_solo: bool) -> bool {
394 self.muted || (any_solo && !self.solo)
395 }
396
397 pub(crate) fn validate(&self) -> bool {
398 valid_gain(&self.gain)
399 && valid_pan(&self.pan)
400 && self.effects.len() <= MAX_CHAIN_EFFECTS
401 && self.effects.iter().all(AudioEffect::is_valid)
402 && self.ducking.as_ref().is_none_or(Ducking::is_valid)
403 }
404}
405
406#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
408#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
409#[serde(deny_unknown_fields)]
410pub struct MasterAudio {
411 #[serde(default = "unit_gain")]
413 pub gain: Animated<f32>,
414 #[serde(default)]
417 #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_CHAIN_EFFECTS }>")]
418 #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_CHAIN_EFFECTS)))]
419 pub effects: Vec<AudioEffect>,
420 #[serde(default = "default_limiter")]
423 pub limiter: Option<Limiter>,
424}
425
426impl Default for MasterAudio {
427 fn default() -> Self {
428 Self {
429 gain: unit_gain(),
430 effects: Vec::new(),
431 limiter: default_limiter(),
432 }
433 }
434}
435
436impl MasterAudio {
437 pub(crate) fn validate(&self) -> bool {
438 valid_gain(&self.gain)
439 && self.effects.len() <= MAX_CHAIN_EFFECTS
440 && self.effects.iter().all(AudioEffect::is_valid)
441 && self.limiter.is_none_or(Limiter::is_valid)
442 }
443}
444
445#[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
447#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
448#[serde(deny_unknown_fields)]
449pub struct Limiter {
450 pub threshold: f32,
452 pub release_ms: f32,
454}
455
456impl Default for Limiter {
457 fn default() -> Self {
458 Self {
459 threshold: 1.0,
460 release_ms: 50.0,
461 }
462 }
463}
464
465impl Limiter {
466 fn is_valid(self) -> bool {
467 self.threshold.is_finite()
468 && self.threshold > 0.0
469 && self.threshold <= MAX_GAIN
470 && positive_ms(self.release_ms)
471 }
472}
473
474#[allow(clippy::unnecessary_wraps)]
476fn default_limiter() -> Option<Limiter> {
477 Some(Limiter::default())
478}
479
480fn unit_gain() -> Animated<f32> {
481 Animated::Constant { value: 1.0 }
482}
483
484fn center_pan() -> Animated<f32> {
485 Animated::Constant { value: 0.0 }
486}
487
488fn unit(value: f32) -> bool {
489 value.is_finite() && (0.0..=1.0).contains(&value)
490}
491
492fn positive_ms(value: f32) -> bool {
493 value.is_finite() && value > 0.0 && value <= MAX_ENVELOPE_MS
494}
495
496fn valid_gain(gain: &Animated<f32>) -> bool {
497 valid_range(gain, crate::Domain::GAIN)
498}
499
500fn valid_pan(pan: &Animated<f32>) -> bool {
501 valid_range(pan, crate::Domain::PAN)
502}
503
504fn valid_range(animation: &Animated<f32>, domain: crate::Domain) -> bool {
505 let valid = |value: f32| domain.contains(value);
506 match animation {
507 Animated::Constant { value } => valid(*value),
508 Animated::Keyframes { keyframes } => {
509 crate::animation::valid_keyframes(keyframes)
510 && keyframes.iter().all(|keyframe| valid(keyframe.value))
511 }
512 Animated::Data(_) => true,
513 }
514}