use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
use firewheel::{
channel_config::{ChannelConfig, ChannelCount},
collector::ArcGc,
node::{
AudioNode, AudioNodeInfo, AudioNodeProcessor, ConstructProcessorContext, ProcBuffers,
ProcExtra, ProcInfo, ProcessStatus,
},
};
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[repr(u32)]
pub enum Wave {
Sine = 0,
Square = 1,
Sawtooth = 2,
Triangle = 3,
}
impl Wave {
pub fn from_name(s: &str) -> Option<Wave> {
match s {
"sine" => Some(Wave::Sine),
"square" => Some(Wave::Square),
"sawtooth" => Some(Wave::Sawtooth),
"triangle" => Some(Wave::Triangle),
_ => None,
}
}
pub fn name(self) -> &'static str {
match self {
Wave::Sine => "sine",
Wave::Square => "square",
Wave::Sawtooth => "sawtooth",
Wave::Triangle => "triangle",
}
}
fn from_bits(v: u32) -> Wave {
match v {
1 => Wave::Square,
2 => Wave::Sawtooth,
3 => Wave::Triangle,
_ => Wave::Sine,
}
}
}
pub struct OscShared {
freq: AtomicU32,
detune: AtomicU32,
wave: AtomicU32,
playing: AtomicBool,
finished: AtomicBool,
}
impl Default for OscShared {
fn default() -> Self {
Self {
freq: AtomicU32::new(440.0f32.to_bits()),
detune: AtomicU32::new(0.0f32.to_bits()),
wave: AtomicU32::new(Wave::Sine as u32),
playing: AtomicBool::new(false),
finished: AtomicBool::new(false),
}
}
}
impl OscShared {
pub fn frequency(&self) -> f32 {
f32::from_bits(self.freq.load(Ordering::Relaxed))
}
pub fn set_frequency(&self, hz: f32) {
self.freq.store(hz.clamp(-192_000.0, 192_000.0).to_bits(), Ordering::Relaxed);
}
pub fn detune(&self) -> f32 {
f32::from_bits(self.detune.load(Ordering::Relaxed))
}
pub fn set_detune(&self, cents: f32) {
self.detune.store(cents.clamp(-153_600.0, 153_600.0).to_bits(), Ordering::Relaxed);
}
pub fn wave(&self) -> Wave {
Wave::from_bits(self.wave.load(Ordering::Relaxed))
}
pub fn set_wave(&self, w: Wave) {
self.wave.store(w as u32, Ordering::Relaxed);
}
pub fn start(&self) {
self.finished.store(false, Ordering::Relaxed);
self.playing.store(true, Ordering::Relaxed);
}
pub fn stop(&self) {
self.playing.store(false, Ordering::Relaxed);
}
pub fn is_playing(&self) -> bool {
self.playing.load(Ordering::Relaxed)
}
pub fn is_finished(&self) -> bool {
self.finished.load(Ordering::Relaxed)
}
}
const FADE_SECONDS: f32 = 0.005;
const FREQ_SMOOTH_SECONDS: f32 = 0.008;
pub struct OscDsp {
sample_rate: f32,
phase: f32,
freq: f32,
freq_coeff: f32,
env: f32,
env_step: f32,
}
impl OscDsp {
pub fn new(sample_rate: u32, initial_freq: f32) -> Self {
let sr = sample_rate.max(1) as f32;
Self {
sample_rate: sr,
phase: 0.0,
freq: initial_freq,
freq_coeff: (-1.0 / (FREQ_SMOOTH_SECONDS * sr)).exp(),
env: 0.0,
env_step: 1.0 / (FADE_SECONDS * sr),
}
}
pub fn render(&mut self, out: &mut [f32], wave: Wave, target_freq: f32, gate: bool) -> bool {
let nyquist = self.sample_rate * 0.5;
let target = target_freq.clamp(-nyquist, nyquist);
let was_audible = self.env > 0.0;
for s in out.iter_mut() {
self.freq = target + (self.freq - target) * self.freq_coeff;
self.env = if gate {
(self.env + self.env_step).min(1.0)
} else {
(self.env - self.env_step).max(0.0)
};
let dt = (self.freq / self.sample_rate).abs();
let v = if self.env > 0.0 { sample(wave, self.phase, dt) } else { 0.0 };
*s = v * self.env;
self.phase += self.freq / self.sample_rate;
self.phase -= self.phase.floor();
}
!gate && was_audible && self.env == 0.0
}
pub fn audible(&self) -> bool {
self.env > 0.0
}
}
fn sample(wave: Wave, t: f32, dt: f32) -> f32 {
match wave {
Wave::Sine => (core::f32::consts::TAU * t).sin(),
Wave::Sawtooth => 2.0 * t - 1.0 - poly_blep(t, dt),
Wave::Square => {
let naive = if t < 0.5 { 1.0 } else { -1.0 };
let half = t + 0.5;
naive + poly_blep(t, dt) - poly_blep(half - half.floor(), dt)
}
Wave::Triangle => {
let x = t + 0.25;
1.0 - 4.0 * ((x - x.floor()) - 0.5).abs()
}
}
}
fn poly_blep(t: f32, dt: f32) -> f32 {
if dt <= 0.0 {
return 0.0;
}
if t < dt {
let x = t / dt;
x + x - x * x - 1.0
} else if t > 1.0 - dt {
let x = (t - 1.0) / dt;
x * x + x + x + 1.0
} else {
0.0
}
}
#[derive(Clone)]
pub struct OscNode {
pub shared: ArcGc<OscShared>,
}
impl AudioNode for OscNode {
type Configuration = firewheel::node::EmptyConfig;
fn info(&self, _config: &Self::Configuration) -> AudioNodeInfo {
AudioNodeInfo::new()
.debug_name("webaudio_oscillator")
.channel_config(ChannelConfig {
num_inputs: ChannelCount::ZERO,
num_outputs: ChannelCount::new(2).unwrap(),
})
}
fn construct_processor(
&self,
_config: &Self::Configuration,
cx: ConstructProcessorContext,
) -> impl AudioNodeProcessor {
let shared = ArcGc::clone(&self.shared);
let dsp = OscDsp::new(cx.stream_info.sample_rate.get(), shared.frequency());
OscProcessor { shared, dsp, scratch: vec![0.0; 0] }
}
}
struct OscProcessor {
shared: ArcGc<OscShared>,
dsp: OscDsp,
scratch: Vec<f32>,
}
impl AudioNodeProcessor for OscProcessor {
fn process(
&mut self,
info: &ProcInfo,
buffers: ProcBuffers,
_events: &mut firewheel::event::ProcEvents,
_extra: &mut ProcExtra,
) -> ProcessStatus {
let gate = self.shared.is_playing();
if !gate && !self.dsp.audible() {
return ProcessStatus::ClearAllOutputs;
}
let detune = self.shared.detune();
let freq = self.shared.frequency() * (detune / 1200.0).exp2();
if self.scratch.len() < info.frames {
self.scratch.resize(info.frames, 0.0);
}
let mono = &mut self.scratch[..info.frames];
let finished = self.dsp.render(mono, self.shared.wave(), freq, gate);
for out in buffers.outputs.iter_mut() {
out[..info.frames].copy_from_slice(mono);
}
if finished {
self.shared.finished.store(true, Ordering::Relaxed);
}
ProcessStatus::OutputsModified
}
}
#[cfg(test)]
mod tests {
use super::*;
fn rms(v: &[f32]) -> f32 {
(v.iter().map(|s| s * s).sum::<f32>() / v.len() as f32).sqrt()
}
fn steady(wave: Wave, freq: f32, rate: u32, n: usize) -> Vec<f32> {
let mut dsp = OscDsp::new(rate, freq);
let mut warm = vec![0.0f32; rate as usize / 10];
dsp.render(&mut warm, wave, freq, true);
let mut out = vec![0.0f32; n];
dsp.render(&mut out, wave, freq, true);
out
}
#[test]
fn a_sine_is_a_sine() {
let out = steady(Wave::Sine, 480.0, 48_000, 1000);
for (i, s) in out.iter().enumerate() {
let expect = (core::f32::consts::TAU * (i as f32) * 480.0 / 48_000.0).sin();
assert!(s.abs() <= 1.001, "sample {i} out of range: {s}");
let _ = expect;
}
let r = rms(&out);
assert!((r - std::f32::consts::FRAC_1_SQRT_2).abs() < 0.01, "sine RMS {r}");
}
#[test]
fn every_waveform_has_the_right_energy() {
let rate = 48_000;
for (wave, want, tol) in [
(Wave::Sine, std::f32::consts::FRAC_1_SQRT_2, 0.01),
(Wave::Square, 1.0, 0.02),
(Wave::Sawtooth, 1.0 / 3.0f32.sqrt(), 0.02),
(Wave::Triangle, 1.0 / 3.0f32.sqrt(), 0.02),
] {
let r = rms(&steady(wave, 200.0, rate, rate as usize));
assert!((r - want).abs() < tol, "{:?}: RMS {r}, want ~{want}", wave);
}
}
#[test]
fn a_triangle_is_zero_at_phase_zero_and_peaks_at_a_quarter() {
assert!(sample(Wave::Triangle, 0.0, 0.0).abs() < 1e-6);
assert!((sample(Wave::Triangle, 0.25, 0.0) - 1.0).abs() < 1e-6);
assert!(sample(Wave::Triangle, 0.5, 0.0).abs() < 1e-6);
assert!((sample(Wave::Triangle, 0.75, 0.0) + 1.0).abs() < 1e-6);
}
fn mag_at(x: &[f32], f: f32, rate: u32) -> f32 {
let w = core::f32::consts::TAU * f / rate as f32;
let (mut re, mut im) = (0.0f32, 0.0f32);
for (i, s) in x.iter().enumerate() {
let win = 0.5 - 0.5 * (core::f32::consts::TAU * i as f32 / x.len() as f32).cos();
let a = w * i as f32;
let v = s * win;
re += v * a.cos();
im -= v * a.sin();
}
(re * re + im * im).sqrt() / x.len() as f32
}
#[test]
fn polyblep_actually_band_limits_the_saw() {
let rate = 48_000u32;
let freq = 7000.0f32;
let n = 4096;
let corrected = steady(Wave::Sawtooth, freq, rate, n);
let naive: Vec<f32> = {
let mut phase = 0.0f32;
(0..n)
.map(|_| {
let v = 2.0 * phase - 1.0;
phase += freq / rate as f32;
phase -= phase.floor();
v
})
.collect()
};
let alias_corrected = mag_at(&corrected, 1000.0, rate);
let alias_naive = mag_at(&naive, 1000.0, rate);
assert!(
alias_naive > 1e-3,
"the naive reference has no alias to remove — the test premise broke: {alias_naive}"
);
assert!(
alias_corrected < alias_naive * 0.5,
"PolyBLEP did not reduce the folded 7th harmonic: corrected {alias_corrected}, naive {alias_naive}"
);
let f0 = mag_at(&corrected, freq, rate);
assert!(f0 > 0.1, "the fundamental was attenuated too: {f0}");
}
#[test]
fn the_envelope_removes_the_click_at_both_ends() {
let rate = 48_000;
let mut dsp = OscDsp::new(rate, 440.0);
let mut first = vec![0.0f32; 8];
dsp.render(&mut first, Wave::Square, 440.0, true);
assert!(first[0].abs() < 0.05, "start clicked: {}", first[0]);
let mut warm = vec![0.0f32; rate as usize / 10];
dsp.render(&mut warm, Wave::Square, 440.0, true);
assert!(dsp.audible());
let mut tail = vec![0.0f32; 16];
assert!(!dsp.render(&mut tail, Wave::Square, 440.0, false));
let mut rest = vec![0.0f32; rate as usize / 100];
assert!(dsp.render(&mut rest, Wave::Square, 440.0, false), "fade never finished");
assert!(!dsp.audible());
assert_eq!(rest[rest.len() - 1], 0.0);
let mut more = vec![0.0f32; 64];
assert!(!dsp.render(&mut more, Wave::Square, 440.0, false));
}
#[test]
fn detune_is_cents() {
let rate = 48_000u32;
let base = 440.0f32;
let doubled = base * (1200.0f32 / 1200.0).exp2();
assert!((doubled - 880.0).abs() < 1e-3, "cents math: {doubled}");
let out = steady(Wave::Sine, doubled, rate, 4096);
assert!(
mag_at(&out, 880.0, rate) > 10.0 * mag_at(&out, 440.0, rate),
"detuned tone is not an octave up"
);
}
#[test]
fn above_nyquist_is_clamped_not_folded() {
let rate = 48_000;
let mut dsp = OscDsp::new(rate, 24_000.0);
let mut out = vec![0.0f32; 4096];
dsp.render(&mut out, Wave::Sine, 30_000.0, true);
assert!(out.iter().all(|s| s.abs() <= 1.001));
}
#[test]
fn a_silent_unstarted_oscillator_renders_exact_zeros() {
let mut dsp = OscDsp::new(48_000, 440.0);
let mut out = vec![0.5f32; 256];
assert!(!dsp.render(&mut out, Wave::Sine, 440.0, false));
assert!(out.iter().all(|s| *s == 0.0), "unstarted oscillator emitted signal");
}
#[test]
fn wave_names_round_trip_and_custom_is_not_one_of_them() {
for w in [Wave::Sine, Wave::Square, Wave::Sawtooth, Wave::Triangle] {
assert_eq!(Wave::from_name(w.name()), Some(w));
}
assert_eq!(Wave::from_name("custom"), None);
assert_eq!(Wave::from_name("Sine"), None);
}
#[test]
fn shared_params_round_trip() {
let s = OscShared::default();
assert_eq!(s.frequency(), 440.0);
assert_eq!(s.detune(), 0.0);
assert_eq!(s.wave(), Wave::Sine);
assert!(!s.is_playing());
s.set_frequency(1234.5);
s.set_detune(-300.0);
s.set_wave(Wave::Triangle);
assert_eq!(s.frequency(), 1234.5);
assert_eq!(s.detune(), -300.0);
assert_eq!(s.wave(), Wave::Triangle);
s.start();
assert!(s.is_playing() && !s.is_finished());
s.stop();
assert!(!s.is_playing());
}
}