threejs-sound-sim/test/physics.test.ts

import { describe, expect, it } from 'vitest';
import {
  airAbsorptionCutoff,
  coneGain,
  distanceGain,
  dopplerRatio,
  gainToDb,
  inverseDistanceGain,
  linearDistanceGain,
  occlusionResponse,
  offAxisAngle,
  ratioToCents,
  smoothingAlpha,
} from '../src/physics';

const at = (x: number, y = 0, z = 0) => ({ x, y, z });
const params = { refDistance: 1, maxDistance: 100, rolloffFactor: 1 };

describe('distance attenuation', () => {
  it('holds unity gain inside the reference distance', () => {
    expect(inverseDistanceGain(0, params)).toBe(1);
    expect(inverseDistanceGain(0.5, params)).toBe(1);
    expect(inverseDistanceGain(1, params)).toBe(1);
  });

  it('loses 6 dB per doubling of distance, the inverse-distance law', () => {
    const near = gainToDb(inverseDistanceGain(4, params));
    const far = gainToDb(inverseDistanceGain(8, params));
    expect(near - far).toBeCloseTo(6.02, 1);
  });

  it('never attenuates when rolloff is zero', () => {
    const flat = { ...params, rolloffFactor: 0 };
    expect(inverseDistanceGain(50, flat)).toBe(1);
  });

  it('reaches silence at maxDistance under the linear model', () => {
    expect(linearDistanceGain(100, params)).toBe(0);
    expect(linearDistanceGain(1000, params)).toBe(0);
  });

  it('degrades gracefully when maxDistance is below refDistance', () => {
    const inverted = { refDistance: 10, maxDistance: 2, rolloffFactor: 1 };
    expect(linearDistanceGain(1, inverted)).toBe(1);
    expect(linearDistanceGain(5, inverted)).toBe(0);
  });

  it('stays within [0, 1] for every model across a wide sweep', () => {
    for (const model of ['inverse', 'exponential', 'linear'] as const) {
      for (const d of [0, 0.001, 1, 7, 99, 1e4]) {
        for (const rolloff of [0, 1, 5]) {
          const gain = distanceGain(d, model, { ...params, rolloffFactor: rolloff });
          expect(gain).toBeGreaterThanOrEqual(0);
          expect(gain).toBeLessThanOrEqual(1);
          expect(Number.isFinite(gain)).toBe(true);
        }
      }
    }
  });

  it('decreases monotonically with distance', () => {
    for (const model of ['inverse', 'exponential', 'linear'] as const) {
      let previous = Infinity;
      for (let d = 0; d <= 60; d += 2) {
        const gain = distanceGain(d, model, params);
        expect(gain).toBeLessThanOrEqual(previous + 1e-12);
        previous = gain;
      }
    }
  });
});

describe('air absorption', () => {
  it('is transparent at zero strength or zero distance', () => {
    expect(airAbsorptionCutoff(50, 0)).toBe(22050);
    expect(airAbsorptionCutoff(0, 4)).toBe(22050);
  });

  it('rolls the cutoff down as distance grows', () => {
    const near = airAbsorptionCutoff(5, 1);
    const far = airAbsorptionCutoff(80, 1);
    expect(far).toBeLessThan(near);
    expect(far).toBeGreaterThan(200);
  });

  it('is barely audible at realistic strength across a room', () => {
    // Real air costs very little treble over 20 m; the default must reflect that.
    expect(airAbsorptionCutoff(20, 1)).toBeGreaterThan(15000);
  });

  it('never falls below the floor even at extreme strength', () => {
    expect(airAbsorptionCutoff(1000, 8)).toBeGreaterThanOrEqual(200);
  });
});

describe('directivity cone', () => {
  const cone = { innerAngle: 60, outerAngle: 180, outerGain: 0.1 };
  const source = at(0, 0, 0);
  const forward = at(0, 0, -1);

  it('is at full level dead ahead', () => {
    expect(coneGain(source, forward, at(0, 0, -5), cone)).toBe(1);
  });

  it('is at full level anywhere inside the inner cone', () => {
    // 25° off-axis, inside the 30° inner half-angle.
    const listener = at(Math.sin(0.436) * 5, 0, -Math.cos(0.436) * 5);
    expect(coneGain(source, forward, listener, cone)).toBe(1);
  });

  it('falls to the floor gain directly behind the source', () => {
    expect(coneGain(source, forward, at(0, 0, 5), cone)).toBeCloseTo(0.1, 6);
  });

  it('interpolates across the transition band', () => {
    // 60° off-axis: past the 30° inner half-angle, short of the 90° outer one.
    const listener = at(Math.sin(Math.PI / 3) * 5, 0, -Math.cos(Math.PI / 3) * 5);
    const gain = coneGain(source, forward, listener, cone);
    expect(gain).toBeGreaterThan(0.1);
    expect(gain).toBeLessThan(1);
  });

  it('reaches the floor exactly at the outer half-angle', () => {
    expect(coneGain(source, forward, at(5, 0, 0), cone)).toBeCloseTo(0.1, 6);
  });

  it('falls monotonically as the listener swings off-axis', () => {
    let previous = Infinity;
    for (let deg = 0; deg <= 180; deg += 10) {
      const rad = (deg * Math.PI) / 180;
      const listener = at(Math.sin(rad) * 5, 0, -Math.cos(rad) * 5);
      const gain = coneGain(source, forward, listener, cone);
      expect(gain).toBeLessThanOrEqual(previous + 1e-9);
      previous = gain;
    }
  });

  it('is omnidirectional at 360 degrees', () => {
    const omni = { innerAngle: 360, outerAngle: 360, outerGain: 0 };
    for (const listener of [at(5), at(-5), at(0, 5), at(0, 0, 5)]) {
      expect(coneGain(source, forward, listener, omni)).toBe(1);
    }
  });

  it('treats a coincident listener as on-axis rather than dividing by zero', () => {
    expect(coneGain(source, forward, source, cone)).toBe(1);
  });

  it('survives a degenerate forward vector', () => {
    const gain = coneGain(source, at(0, 0, 0), at(0, 0, -5), cone);
    expect(Number.isFinite(gain)).toBe(true);
  });

  it('reports the off-axis angle in degrees', () => {
    expect(offAxisAngle(source, forward, at(0, 0, -5))).toBeCloseTo(0, 6);
    expect(offAxisAngle(source, forward, at(5, 0, 0))).toBeCloseTo(90, 6);
    expect(offAxisAngle(source, forward, at(0, 0, 5))).toBeCloseTo(180, 6);
  });
});

describe('doppler', () => {
  const still = at(0, 0, 0);

  it('is unity when nothing moves', () => {
    expect(dopplerRatio(at(0), still, at(10), still)).toBe(1);
  });

  it('raises pitch when the source approaches', () => {
    // Source at origin, listener at +10 x, source moving towards it.
    expect(dopplerRatio(at(0), at(30), at(10), still)).toBeGreaterThan(1);
  });

  it('lowers pitch when the source recedes', () => {
    expect(dopplerRatio(at(0), at(-30), at(10), still)).toBeLessThan(1);
  });

  it('lowers pitch when the listener flees', () => {
    expect(dopplerRatio(at(0), still, at(10), at(30))).toBeLessThan(1);
  });

  it('matches the textbook ratio for an approaching source', () => {
    // f'/f = c / (c - v) = 343 / (343 - 34.3) = 1.1111…
    expect(dopplerRatio(at(0), at(34.3), at(10), still, 343)).toBeCloseTo(1.1111, 3);
  });

  it('ignores motion perpendicular to the line of sight', () => {
    expect(dopplerRatio(at(0), at(0, 0, 40), at(10), still)).toBeCloseTo(1, 6);
  });

  it('stays finite and bounded at and beyond the speed of sound', () => {
    for (const v of [343, 400, 5000]) {
      const ratio = dopplerRatio(at(0), at(v), at(10), still, 343);
      expect(Number.isFinite(ratio)).toBe(true);
      expect(ratio).toBeLessThanOrEqual(4);
      expect(ratio).toBeGreaterThanOrEqual(0.25);
    }
  });

  it('falls back to a sane medium when given a nonsense speed of sound', () => {
    expect(dopplerRatio(at(0), still, at(10), still, 0)).toBe(1);
  });

  it('returns unity for a coincident source and listener', () => {
    expect(dopplerRatio(at(5), at(10), at(5), still)).toBe(1);
  });
});

describe('occlusion', () => {
  it('is transparent with a clear line of sight', () => {
    const clear = occlusionResponse(0);
    expect(clear.gain).toBe(1);
    expect(clear.cutoff).toBeCloseTo(22050, 0);
  });

  it('muffles but does not silence a fully blocked path', () => {
    const blocked = occlusionResponse(1);
    expect(blocked.cutoff).toBeCloseTo(350, 0);
    expect(blocked.gain).toBeGreaterThan(0);
    expect(blocked.gain).toBeLessThan(0.3);
  });

  it('sweeps the cutoff monotonically and geometrically', () => {
    let previous = Infinity;
    for (let t = 0; t <= 1; t += 0.1) {
      const { cutoff } = occlusionResponse(t);
      expect(cutoff).toBeLessThan(previous);
      previous = cutoff;
    }
    // Geometric interpolation puts the halfway point at the geometric mean,
    // which is what keeps the sweep sounding even.
    expect(occlusionResponse(0.5).cutoff).toBeCloseTo(Math.sqrt(350 * 22050), 0);
  });

  it('clamps out-of-range input', () => {
    expect(occlusionResponse(-3).gain).toBe(1);
    expect(occlusionResponse(9).gain).toBeCloseTo(occlusionResponse(1).gain, 12);
  });
});

describe('unit helpers', () => {
  it('converts gain to decibels', () => {
    expect(gainToDb(1)).toBeCloseTo(0, 9);
    expect(gainToDb(0.5)).toBeCloseTo(-6.02, 2);
    expect(gainToDb(0)).toBe(-120);
  });

  it('converts frequency ratios to cents', () => {
    expect(ratioToCents(1)).toBeCloseTo(0, 9);
    expect(ratioToCents(2)).toBeCloseTo(1200, 6);
    expect(ratioToCents(0.5)).toBeCloseTo(-1200, 6);
  });

  it('produces frame-rate independent smoothing', () => {
    // Two 8 ms steps must land where one 16 ms step lands.
    const single = smoothingAlpha(0.016, 0.1);
    const a = smoothingAlpha(0.008, 0.1);
    const twice = 1 - (1 - a) * (1 - a);
    expect(twice).toBeCloseTo(single, 9);
  });
});