use std::collections::HashMap;
use std::sync::{Arc, Mutex, OnceLock};
use firewheel::{
channel_config::{ChannelConfig, ChannelCount},
diff::{Diff, Patch},
event::ProcEvents,
node::{
AudioNode, AudioNodeInfo, AudioNodeProcessor, ConstructProcessorContext, ProcBuffers,
ProcExtra, ProcInfo, ProcessStatus,
},
};
pub const KERNEL_LEN: usize = 256;
const CHUNK: usize = 256;
const NUM_AZIMUTHS: usize = 24; const NUM_ELEVATIONS: usize = 10;
const NUM_RESPONSES: usize = NUM_AZIMUTHS * NUM_ELEVATIONS;
const SOURCE_RATE: u32 = 44100;
const ELEVATION_STEP: f32 = 15.0;
const XFADE_LEN: u32 = 128;
static COMPOSITE_FLAC: &[u8] = include_bytes!("../../assets/hrtf/Composite.flac");
fn elevation_index(el_deg: f32) -> usize {
if el_deg < 0.0 {
(7.0 + (el_deg + 45.0) / ELEVATION_STEP) as usize } else {
(el_deg / ELEVATION_STEP) as usize }
}
pub struct HrtfDatabase {
kernels: Vec<f32>,
}
impl HrtfDatabase {
pub fn for_rate(rate: u32) -> Option<Arc<HrtfDatabase>> {
static CACHE: OnceLock<Mutex<HashMap<u32, Option<Arc<HrtfDatabase>>>>> = OnceLock::new();
let cache = CACHE.get_or_init(Default::default);
let mut map = cache.lock().unwrap();
map.entry(rate)
.or_insert_with(|| Self::load(rate).map(Arc::new))
.clone()
}
fn load(rate: u32) -> Option<HrtfDatabase> {
let decoded = super::audio::decode_bytes(COMPOSITE_FLAC.to_vec(), None).ok()?;
if decoded.data.len() != 2
|| decoded.sample_rate != SOURCE_RATE
|| decoded.data[0].len() != NUM_RESPONSES * KERNEL_LEN
{
return None;
}
let ratio = rate as f64 / SOURCE_RATE as f64;
let mut kernels = vec![0.0f32; NUM_RESPONSES * 2 * KERNEL_LEN];
for resp in 0..NUM_RESPONSES {
for ear in 0..2 {
let src = &decoded.data[ear][resp * KERNEL_LEN..(resp + 1) * KERNEL_LEN];
let dst = &mut kernels[(resp * 2 + ear) * KERNEL_LEN..][..KERNEL_LEN];
resample_linear(src, dst, ratio);
}
}
Some(HrtfDatabase { kernels })
}
fn response(&self, az_index: usize, el_index: usize, ear: usize) -> &[f32] {
let resp = az_index * NUM_ELEVATIONS + el_index;
&self.kernels[(resp * 2 + ear) * KERNEL_LEN..][..KERNEL_LEN]
}
pub fn kernels_for(&self, azimuth_deg: f32, elevation_deg: f32, out_l: &mut [f32], out_r: &mut [f32]) {
let az = (-azimuth_deg).rem_euclid(360.0);
let azf = az / (360.0 / NUM_AZIMUTHS as f32);
let a1 = (azf as usize) % NUM_AZIMUTHS;
let a2 = (a1 + 1) % NUM_AZIMUTHS;
let ab = azf.fract();
let el = elevation_deg.clamp(-45.0, 90.0);
let e_low = (el / ELEVATION_STEP).floor() * ELEVATION_STEP;
let e_high = (e_low + ELEVATION_STEP).min(90.0);
let eb = if e_high > e_low { (el - e_low) / ELEVATION_STEP } else { 0.0 };
let e1 = elevation_index(e_low);
let e2 = elevation_index(e_high);
let w11 = (1.0 - ab) * (1.0 - eb);
let w12 = (1.0 - ab) * eb;
let w21 = ab * (1.0 - eb);
let w22 = ab * eb;
for (ear, out) in [out_l, out_r].into_iter().enumerate() {
let k11 = self.response(a1, e1, ear);
let k12 = self.response(a1, e2, ear);
let k21 = self.response(a2, e1, ear);
let k22 = self.response(a2, e2, ear);
for i in 0..KERNEL_LEN {
out[i] = k11[i] * w11 + k12[i] * w12 + k21[i] * w21 + k22[i] * w22;
}
}
}
}
fn resample_linear(src: &[f32], dst: &mut [f32], ratio: f64) {
for (i, d) in dst.iter_mut().enumerate() {
let pos = i as f64 / ratio;
let i0 = pos as usize;
let frac = (pos - i0 as f64) as f32;
let a = src.get(i0).copied().unwrap_or(0.0);
let b = src.get(i0 + 1).copied().unwrap_or(0.0);
*d = a + (b - a) * frac;
}
}
struct EarConv {
cur: [f32; KERNEL_LEN],
new: [f32; KERNEL_LEN],
scratch: [f32; KERNEL_LEN - 1 + CHUNK],
}
impl EarConv {
fn new() -> Self {
Self {
cur: [0.0; KERNEL_LEN],
new: [0.0; KERNEL_LEN],
scratch: [0.0; KERNEL_LEN - 1 + CHUNK],
}
}
fn begin_block(&mut self, input: &[f32]) {
self.scratch[KERNEL_LEN - 1..KERNEL_LEN - 1 + input.len()].copy_from_slice(input);
}
fn end_block(&mut self, n: usize) {
self.scratch.copy_within(n..n + KERNEL_LEN - 1, 0);
}
#[inline]
fn convolve(&self, i: usize, kernel: &[f32; KERNEL_LEN]) -> f32 {
self.scratch[i..i + KERNEL_LEN]
.iter()
.zip(kernel.iter())
.map(|(x, k)| x * k)
.sum()
}
}
pub struct PannerDsp {
db: Option<Arc<HrtfDatabase>>,
left: EarConv,
right: EarConv,
xfade_left: u32,
have_kernels: bool,
smoothed_gain: f32,
smoothed_az: f32,
smooth_coef: f32,
}
impl PannerDsp {
pub fn new(db: Option<Arc<HrtfDatabase>>, sample_rate: f32) -> Self {
Self {
db,
left: EarConv::new(),
right: EarConv::new(),
xfade_left: 0,
have_kernels: false,
smoothed_gain: 1.0,
smoothed_az: 0.0,
smooth_coef: 1.0 - (-1.0 / (0.015 * sample_rate.max(1.0))).exp(),
}
}
pub fn has_hrtf(&self) -> bool {
self.db.is_some()
}
#[cfg(test)]
fn kill_smoothing(&mut self) {
self.smooth_coef = 1.0;
}
pub fn set_direction(&mut self, azimuth_deg: f32, elevation_deg: f32) {
let Some(db) = &self.db else { return };
let mut kl = [0.0f32; KERNEL_LEN];
let mut kr = [0.0f32; KERNEL_LEN];
db.kernels_for(azimuth_deg, elevation_deg, &mut kl, &mut kr);
kl.reverse();
kr.reverse();
if self.have_kernels {
self.left.new = kl;
self.right.new = kr;
self.xfade_left = XFADE_LEN;
} else {
self.left.cur = kl;
self.right.cur = kr;
self.have_kernels = true;
}
}
pub fn render(
&mut self,
hrtf: bool,
azimuth_deg: f32,
gain: f32,
in_l: &[f32],
in_r: &[f32],
out_l: &mut [f32],
out_r: &mut [f32],
) {
let n = in_l.len();
debug_assert!(n <= CHUNK && in_r.len() == n);
let stereo = !core::ptr::eq(in_l.as_ptr(), in_r.as_ptr()) && in_l != in_r;
if hrtf && self.have_kernels {
self.left.begin_block(in_l);
self.right.begin_block(in_r);
for i in 0..n {
self.smoothed_gain += (gain - self.smoothed_gain) * self.smooth_coef;
let mut l = self.left.convolve(i, &self.left.cur);
let mut r = self.right.convolve(i, &self.right.cur);
if self.xfade_left > 0 {
let t = 1.0 - self.xfade_left as f32 / XFADE_LEN as f32;
l += (self.left.convolve(i, &self.left.new) - l) * t;
r += (self.right.convolve(i, &self.right.new) - r) * t;
self.xfade_left -= 1;
if self.xfade_left == 0 {
self.left.cur = self.left.new;
self.right.cur = self.right.new;
}
}
out_l[i] = l * self.smoothed_gain;
out_r[i] = r * self.smoothed_gain;
}
self.left.end_block(n);
self.right.end_block(n);
} else {
for i in 0..n {
self.smoothed_gain += (gain - self.smoothed_gain) * self.smooth_coef;
self.smoothed_az += (azimuth_deg - self.smoothed_az) * self.smooth_coef;
let g = self.smoothed_gain;
let mut az = self.smoothed_az.clamp(-180.0, 180.0);
if az < -90.0 {
az = -180.0 - az;
} else if az > 90.0 {
az = 180.0 - az;
}
if stereo {
let x = if az <= 0.0 { (az + 90.0) / 90.0 } else { az / 90.0 };
let phase = x * core::f32::consts::FRAC_PI_2;
let (gl, gr) = (phase.cos(), phase.sin());
if az <= 0.0 {
out_l[i] = (in_l[i] + in_r[i] * gl) * g;
out_r[i] = in_r[i] * gr * g;
} else {
out_l[i] = in_l[i] * gl * g;
out_r[i] = (in_r[i] + in_l[i] * gr) * g;
}
} else {
let phase = (az + 90.0) / 180.0 * core::f32::consts::FRAC_PI_2;
out_l[i] = in_l[i] * phase.cos() * g;
out_r[i] = in_l[i] * phase.sin() * g;
}
}
}
}
}
#[derive(Diff, Patch, Debug, Clone, Copy, PartialEq)]
pub struct WebPannerNode {
pub azimuth: f32,
pub elevation: f32,
pub gain: f32,
pub hrtf: bool,
}
impl Default for WebPannerNode {
fn default() -> Self {
Self { azimuth: 0.0, elevation: 0.0, gain: 1.0, hrtf: false }
}
}
#[derive(Default)]
pub struct WebPannerConfig {
pub db: Option<Arc<HrtfDatabase>>,
}
impl AudioNode for WebPannerNode {
type Configuration = WebPannerConfig;
fn info(&self, _config: &Self::Configuration) -> AudioNodeInfo {
AudioNodeInfo::new()
.debug_name("webaudio_panner")
.channel_config(ChannelConfig {
num_inputs: ChannelCount::new(2).unwrap(),
num_outputs: ChannelCount::new(2).unwrap(),
})
}
fn construct_processor(
&self,
config: &Self::Configuration,
cx: ConstructProcessorContext,
) -> impl AudioNodeProcessor {
let mut dsp = PannerDsp::new(config.db.clone(), cx.stream_info.sample_rate.get() as f32);
if self.hrtf {
dsp.set_direction(self.azimuth, self.elevation);
}
WebPannerProcessor { params: *self, dsp }
}
}
struct WebPannerProcessor {
params: WebPannerNode,
dsp: PannerDsp,
}
impl AudioNodeProcessor for WebPannerProcessor {
fn process(
&mut self,
info: &ProcInfo,
buffers: ProcBuffers,
events: &mut ProcEvents,
_extra: &mut ProcExtra,
) -> ProcessStatus {
let before = self.params;
for patch in events.drain_patches::<WebPannerNode>() {
self.params.apply(patch);
}
if self.params.hrtf
&& (!before.hrtf
|| before.azimuth != self.params.azimuth
|| before.elevation != self.params.elevation)
{
self.dsp.set_direction(self.params.azimuth, self.params.elevation);
}
let l_silent = info.in_silence_mask.is_channel_silent(0);
let r_silent = buffers.inputs.len() < 2 || info.in_silence_mask.is_channel_silent(1);
let (out_l_slot, rest) = buffers.outputs.split_at_mut(1);
let out_l = &mut *out_l_slot[0];
let out_r = &mut *rest[0];
let silent = [0.0f32; CHUNK];
let mut off = 0usize;
while off < info.frames {
let n = (info.frames - off).min(CHUNK);
let in_l: &[f32] = if l_silent { &silent[..n] } else { &buffers.inputs[0][off..off + n] };
let in_r: &[f32] = if r_silent { in_l } else { &buffers.inputs[1][off..off + n] };
self.dsp.render(
self.params.hrtf,
self.params.azimuth,
self.params.gain,
in_l,
in_r,
&mut out_l[off..off + n],
&mut out_r[off..off + n],
);
off += n;
}
ProcessStatus::OutputsModified
}
}
#[cfg(test)]
mod tests {
use super::*;
fn energy(samples: &[f32]) -> f32 {
samples.iter().map(|s| s * s).sum()
}
fn peak_index(samples: &[f32]) -> usize {
let mut best = 0;
for (i, s) in samples.iter().enumerate() {
if s.abs() > samples[best].abs() {
best = i;
}
}
best
}
fn db() -> Arc<HrtfDatabase> {
HrtfDatabase::for_rate(48000).expect("embedded HRTF database must decode")
}
fn render_impulse(azimuth: f32, elevation: f32) -> (Vec<f32>, Vec<f32>) {
let mut dsp = PannerDsp::new(Some(db()), 48000.0);
dsp.kill_smoothing();
dsp.set_direction(azimuth, elevation);
let mut input = vec![0.0f32; KERNEL_LEN * 2];
input[0] = 1.0;
let mut l = vec![0.0f32; input.len()];
let mut r = vec![0.0f32; input.len()];
for off in (0..input.len()).step_by(CHUNK) {
let n = (input.len() - off).min(CHUNK);
let (in_chunk, _) = input[off..].split_at(n);
let (l_chunk, r_chunk) = (&mut l[off..off + n], &mut r[off..off + n]);
dsp.render(true, azimuth, 1.0, in_chunk, in_chunk, l_chunk, r_chunk);
}
(l, r)
}
#[test]
fn database_loads_and_is_energetic() {
let db = db();
let mut l = [0.0f32; KERNEL_LEN];
let mut r = [0.0f32; KERNEL_LEN];
db.kernels_for(0.0, 0.0, &mut l, &mut r);
assert!(energy(&l) > 0.01 && energy(&r) > 0.01, "front kernels silent");
let ratio = energy(&l) / energy(&r);
assert!((0.5..2.0).contains(&ratio), "front L/R asymmetry: {ratio}");
}
#[test]
fn elevation_blend_is_bilinear() {
let db = db();
let mut mid_l = [0.0f32; KERNEL_LEN];
let mut mid_r = [0.0f32; KERNEL_LEN];
db.kernels_for(0.0, 7.5, &mut mid_l, &mut mid_r);
let mut lo_l = [0.0f32; KERNEL_LEN];
let mut lo_r = [0.0f32; KERNEL_LEN];
db.kernels_for(0.0, 0.0, &mut lo_l, &mut lo_r);
let mut hi_l = [0.0f32; KERNEL_LEN];
let mut hi_r = [0.0f32; KERNEL_LEN];
db.kernels_for(0.0, 15.0, &mut hi_l, &mut hi_r);
for i in 0..KERNEL_LEN {
let expect = (lo_l[i] + hi_l[i]) * 0.5;
assert!((mid_l[i] - expect).abs() < 1e-6, "tap {i}: {} vs {expect}", mid_l[i]);
}
db.kernels_for(0.0, -45.0, &mut lo_l, &mut lo_r);
assert!(energy(&lo_l) > 0.01, "-45° kernels silent");
}
#[test]
fn hrtf_right_source_favors_right_ear_and_leads() {
let (l, r) = render_impulse(90.0, 0.0);
let (el, er) = (energy(&l), energy(&r));
assert!(er > el * 2.0, "right source should be louder right: L={el} R={er}");
assert!(peak_index(&r) < peak_index(&l), "right ear should lead: L@{} R@{}", peak_index(&l), peak_index(&r));
}
#[test]
fn hrtf_left_source_mirrors() {
let (l, r) = render_impulse(-90.0, 0.0);
assert!(energy(&l) > energy(&r) * 2.0, "left source should be louder left");
assert!(peak_index(&l) < peak_index(&r), "left ear should lead");
}
#[test]
fn hrtf_stereo_keeps_channels_on_their_ears() {
let mut dsp = PannerDsp::new(Some(db()), 48000.0);
dsp.kill_smoothing();
dsp.set_direction(0.0, 0.0);
let mut in_l = vec![0.0f32; KERNEL_LEN];
let in_r = vec![0.0f32; KERNEL_LEN];
in_l[0] = 1.0;
let mut l = vec![0.0f32; KERNEL_LEN];
let mut r = vec![0.0f32; KERNEL_LEN];
dsp.render(true, 0.0, 1.0, &in_l, &in_r, &mut l, &mut r);
assert!(energy(&l) > 0.01, "left ear should render the left channel");
assert!(energy(&r) < 1e-9, "right ear must stay silent for a silent right channel");
}
#[test]
fn equalpower_gains_match_spec() {
let mut dsp = PannerDsp::new(None, 48000.0);
dsp.kill_smoothing();
let input = [1.0f32; 4];
let mut l = [0.0f32; 4];
let mut r = [0.0f32; 4];
let inv_sqrt2 = core::f32::consts::FRAC_1_SQRT_2;
dsp.render(false, 0.0, 1.0, &input, &input, &mut l, &mut r); assert!((l[3] - r[3]).abs() < 1e-3, "center should be symmetric");
assert!((l[3] - inv_sqrt2).abs() < 1e-3, "center gain should be cos(45°)");
dsp.render(false, 90.0, 1.0, &input, &input, &mut l, &mut r); assert!(l[3].abs() < 1e-3 && (r[3] - 1.0).abs() < 1e-3, "hard right: L={} R={}", l[3], r[3]);
dsp.render(false, 180.0, 1.0, &input, &input, &mut l, &mut r);
assert!((l[3] - inv_sqrt2).abs() < 1e-3, "rear fold should re-center");
}
#[test]
fn equalpower_stereo_law() {
let mut dsp = PannerDsp::new(None, 48000.0);
dsp.kill_smoothing();
let in_l = [1.0f32; 4];
let in_r = [0.5f32; 4];
let mut l = [0.0f32; 4];
let mut r = [0.0f32; 4];
dsp.render(false, 0.0, 1.0, &in_l, &in_r, &mut l, &mut r);
assert!((l[3] - 1.0).abs() < 1e-3 && (r[3] - 0.5).abs() < 1e-3, "stereo center should pass through: L={} R={}", l[3], r[3]);
dsp.render(false, 90.0, 1.0, &in_l, &in_r, &mut l, &mut r);
assert!(l[3].abs() < 1e-3, "hard-right stereo: left should be empty");
assert!((r[3] - 1.5).abs() < 1e-3, "hard-right stereo: R = inR + inL, got {}", r[3]);
dsp.render(false, -90.0, 1.0, &in_l, &in_r, &mut l, &mut r);
assert!((l[3] - 1.5).abs() < 1e-3, "hard-left stereo: L = inL + inR, got {}", l[3]);
assert!(r[3].abs() < 1e-3, "hard-left stereo: right should be empty");
}
#[test]
fn hrtf_mode_survives_missing_database() {
let mut dsp = PannerDsp::new(None, 48000.0);
dsp.kill_smoothing();
dsp.set_direction(90.0, 0.0);
let input = [1.0f32; 4];
let mut l = [0.0f32; 4];
let mut r = [0.0f32; 4];
dsp.render(true, 90.0, 1.0, &input, &input, &mut l, &mut r);
assert!((r[3] - 1.0).abs() < 1e-3, "fallback should pan equal-power");
}
}