@driftengine/audio 3.61.0

package/src/mix/defaultLayout.ts

@@ -0,0 +1,118 @@
+import type { MixLevels } from '../graph.ts';
+import type { MixBus } from './bus.ts';
+import type { MixConsole } from './console.ts';
+import {
+  liftInsert,
+  masterFilterInsert,
+  slamInsert,
+  type LiftInsert,
+  type MasterFilterInsert,
+  type SlamInsert,
+} from './inserts.ts';
+import { convolverInsert, delayInsert, type DelayInsert } from './returns.ts';
+
+/**
+ * The mix as it has always been, expressed in buses and inserts.
+ *
+ * ```
+ *   music ─ [lift] ─ tap ─ [slam] ─┐
+ *     └─ sends from tap ───────────┼→ master ─ [master lowpass] ─ out ─→ destination
+ *   effects ─────────────────────── ┘                                    ↑
+ *   reverb · longReverb · delay ────────────────────────────────────────┘
+ * ```
+ *
+ * **This is a transcription and it is meant to stay one.** Every level, every frequency and every
+ * connection order is the one `AudioGraph`'s constructor had, because the gate on this file is that
+ * an offline render through it is sample-identical to a render frozen before it existed. An
+ * improvement to the mix cannot be made here without breaking that gate — deliberately, so that a
+ * change to how the mix sounds arrives in its own commit where a diff attributes it.
+ *
+ * **The three returns are parented to nothing and wired straight to `out`.** They join the mix
+ * downstream of the master filter, which is what the mix has always done: a reverb tail put through
+ * a low-pass the dry signal has already passed reads as a duller room rather than as a room.
+ */
+export interface DefaultLayout {
+  readonly music: MixBus;
+  readonly effects: MixBus;
+  readonly reverb: MixBus;
+  readonly longReverb: MixBus;
+  readonly delay: MixBus;
+  readonly lift: LiftInsert;
+  readonly slam: SlamInsert;
+  readonly masterFilter: MasterFilterInsert;
+  readonly delayLine: DelayInsert;
+}
+
+/**
+ * The long tail: seconds of impulse, and how fast it decays inside them.
+ *
+ * Long enough to carry a whole airborne moment — a jump is under a second, a glide several — and
+ * decaying slowly enough that the music is *spread out* rather than merely echoed. Beyond about
+ * eight seconds it stops sounding like a space and starts sounding like a stuck effect.
+ */
+const LONG_REVERB_SECONDS = 6;
+const LONG_REVERB_DECAY = 1.5;
+/** The short one: the room the music is played in, rather than where it goes. */
+const SHORT_REVERB_SECONDS = 2.4;
+const SHORT_REVERB_DECAY = 2.6;
+/** Baseline delay feedback: one clear repeat, not a rhythm of its own. */
+const DELAY_FEEDBACK = 0.34;
+
+export function defaultLayout(mix: MixConsole, levels: MixLevels): DefaultLayout {
+  const masterFilter = masterFilterInsert(mix.context, () => mix.scheduleAt());
+  mix.master.insert(masterFilter);
+
+  /*
+   * Music and effects have their own bus because players expect to turn them down independently —
+   * muting the score while keeping the game audible is the single most-used audio setting there is.
+   */
+  const music = mix.bus('music', { level: levels.music });
+  const lift = liftInsert(mix.context, () => mix.scheduleAt());
+  music.insert(lift);
+  const slam = slamInsert(mix.context, () => mix.scheduleAt());
+  /*
+   * Below the tap, so the sends never hear it: a six-second convolution of a clipped bass hit is a
+   * mess, and it would still be arriving three gates later.
+   */
+  music.insert(slam, { postSend: true });
+  // And its wet band is taken from the music as it arrives, upstream of the lift's high-pass. See
+  // `SlamInsert.wetInput` for why that is the one wiring mistake this stage can make.
+  music.feedFromInput(slam.wetInput);
+
+  const effects = mix.bus('effects', { level: levels.effects });
+
+  /*
+   * **The sends are fed from the music alone.** They hung off the shared bus first, which put
+   * reverb and delay on every sound the game made when only the score should carry them. A footstep
+   * with a six-second tail on it is not atmosphere, it is a bug, and the effects that carry the
+   * world's own sound need to stay dry and immediate to be legible.
+   */
+  const reverb = mix.bus('reverb', { parent: null });
+  reverb.insert(
+    convolverInsert(mix.context, SHORT_REVERB_SECONDS, SHORT_REVERB_DECAY, () => mix.random()),
+  );
+  reverb.output.connect(mix.out);
+
+  /*
+   * A second, much longer reverb, on its own return rather than a swappable impulse: building one
+   * allocates and costs milliseconds, and doing that on a jump would put both on the input path.
+   * Two convolvers cost two returns and nothing else.
+   */
+  const longReverb = mix.bus('longReverb', { parent: null });
+  longReverb.insert(
+    convolverInsert(mix.context, LONG_REVERB_SECONDS, LONG_REVERB_DECAY, () => mix.random()),
+  );
+  longReverb.output.connect(mix.out);
+
+  const delay = mix.bus('delay', { parent: null });
+  const delayLine = delayInsert(mix.context, () => mix.scheduleAt(), { feedback: DELAY_FEEDBACK });
+  delay.insert(delayLine);
+  delay.output.connect(mix.out);
+
+  // At zero, so an idle graph is exactly the dry mix. Every send is opened by a caller.
+  music.send(reverb, 0);
+  music.send(longReverb, 0);
+  music.send(delay, 0);
+
+  return { music, effects, reverb, longReverb, delay, lift, slam, masterFilter, delayLine };
+}

package/src/mix/inserts.ts

@@ -0,0 +1,242 @@
+import type { ScheduleClock } from '../ambientLoop.ts';
+import {
+  LIFT_FLOOR_HZ,
+  SLAM_ATTACK_SEC,
+  SLAM_CLIP_KNEE,
+  SLAM_CLOSED_HZ,
+  SLAM_DECAY_SEC,
+  SLAM_DRIVE,
+  SLAM_DUCK,
+  SLAM_OPEN_HZ,
+  SLAM_SHELF_DB,
+  SLAM_SHELF_HZ,
+  clamp01,
+  cutoffForSpeed,
+  liftFrequencyHz,
+  liftGainFor,
+} from '../filters.ts';
+import type { MixInsert } from './bus.ts';
+
+/**
+ * The stages a bus can carry, as things rather than as lines in one constructor.
+ *
+ * **These are transcriptions and they are meant to stay transcriptions.** Every node, every
+ * constant and every connection order came out of `AudioGraph`'s constructor unchanged, because
+ * the gate on the layout that uses them is that a render through it is sample-identical to one
+ * frozen before any of this existed. An improvement made in passing here is a gate failure
+ * somebody spends an hour attributing to the wrong thing.
+ */
+
+const RAMP = 0.08;
+
+/** Ramp a parameter on the mix's clock. The same shape every stage here uses. */
+function ramp(param: AudioParam, value: number, scheduleAt: ScheduleClock): void {
+  const at = scheduleAt();
+  param.cancelScheduledValues(at);
+  param.setTargetAtTime(value, at, RAMP);
+}
+
+export interface MasterFilterInsert extends MixInsert {
+  setCutoff(hz: number): void;
+  setResonance(amount: number): void;
+  readonly filter: BiquadFilterNode;
+}
+
+/**
+ * The master low-pass: everything the player hears, including the world's own sound.
+ *
+ * Deliberately across the whole mix rather than the score alone — going under water muffles the
+ * world, not only the music.
+ */
+export function masterFilterInsert(
+  context: BaseAudioContext,
+  scheduleAt: ScheduleClock,
+): MasterFilterInsert {
+  const filter = context.createBiquadFilter();
+  filter.type = 'lowpass';
+  filter.frequency.value = cutoffForSpeed(0, 1);
+  filter.Q.value = 0.7;
+  return {
+    input: filter,
+    output: filter,
+    filter,
+    setCutoff(hz: number): void {
+      ramp(filter.frequency, Math.min(Math.max(hz, 40), 20000), scheduleAt);
+    },
+    /*
+     * Not a second filter in the chain: the master low-pass is already there and already ramped, so
+     * resonance raises its Q instead. A sweep then *colours* the music — the same whistle a DJ
+     * filter makes — where an added layer would only sit on top of it. Zero restores the flat
+     * response exactly.
+     */
+    setResonance(amount: number): void {
+      ramp(filter.Q, 0.0001 + Math.max(0, Math.min(amount, 1)) * 12, scheduleAt);
+    },
+  };
+}
+
+export interface LiftInsert extends MixInsert {
+  setAmount(amount: number): void;
+}
+
+/**
+ * The lift: a high-pass and a duck, in series.
+ *
+ * This is the airborne effect proper, and it is a different idea from adding reverb on top of a
+ * full-level track. The reference is the lift familiar from dance production, which does three
+ * things at once — thins the low end, pulls the level down, and lets the wet through — and the
+ * *thinning* is what reads as leaving the ground. Weight lives in the bass; take it away and the
+ * track is suspended.
+ *
+ * Which is also why an earlier attempt to duck read as "the music going away" instead: it closed
+ * the *low-pass*, and losing the treble is what distance sounds like, not what height sounds like.
+ *
+ * A bus's sends listen from the tap, and the layout puts this above it, so the tail is thin too.
+ * Reverb fed from the unfiltered signal would put the bass back in the one place it cannot be
+ * pushed out of again.
+ */
+export function liftInsert(context: BaseAudioContext, scheduleAt: ScheduleClock): LiftInsert {
+  const highpass = context.createBiquadFilter();
+  highpass.type = 'highpass';
+  highpass.frequency.value = LIFT_FLOOR_HZ;
+  highpass.Q.value = 0.7;
+  const gain = context.createGain();
+  highpass.connect(gain);
+  return {
+    input: highpass,
+    output: gain,
+    /*
+     * One call for the whole airborne effect, because its three parts have to move together: the
+     * low end thins, the dry level ducks, and what is left is mostly the sends. Splitting them
+     * across three game-side calls is how they end up disagreeing, and a half-ducked, un-thinned
+     * track is just quieter music.
+     */
+    setAmount(amount: number): void {
+      ramp(highpass.frequency, liftFrequencyHz(amount), scheduleAt);
+      ramp(gain.gain, liftGainFor(amount), scheduleAt);
+    },
+  };
+}
+
+export interface SlamInsert extends MixInsert {
+  /**
+   * Where the driven band is taken from, which is **not** this insert's series input.
+   *
+   * The layout connects the bus's own pre-insert signal here. Any low-cut ahead of the tap has to
+   * be bypassed or the effect disappears exactly when the player is in the air: the lift *is* a
+   * high-pass, so a slam taken from after it would be boosting a shelf on a band that had already
+   * been removed, and would be at its weakest where half the gates are taken.
+   */
+  readonly wetInput: AudioNode;
+  /** The dry path's duck and the wet path's blend, exposed so a test can assert an idle stage. */
+  readonly dryGain: GainNode;
+  readonly wetGain: GainNode;
+  strike(amount: number): void;
+}
+
+/**
+ * The slam: a parallel band of driven low end, blended in for a fraction of a second and gone.
+ *
+ * For the instant a body passes a marker in the world: boost the low end of the score alone, and
+ * hard-clip it a little. Which is parallel bass saturation, a production move rather than a game
+ * one, and it lands in exactly the register a bass-led score leaves room in.
+ *
+ * **Parallel rather than in-line, and that is the load-bearing decision.** A shaper sitting in the
+ * music path colours the score for the whole run — a track mastered near full scale is already
+ * touching any knee low enough to be useful — so the effect would stop being an event and become
+ * the sound of the game. With a dry path at unity and a wet path at zero, an idle graph is
+ * sample-identical to one without this stage in it, which is what lets the identity gate pass
+ * across a rewrite that moved it into a bus.
+ */
+export function slamInsert(context: BaseAudioContext, scheduleAt: ScheduleClock): SlamInsert {
+  const dry = context.createGain();
+  dry.gain.value = 1;
+  const output = context.createGain();
+  dry.connect(output);
+
+  const shelf = context.createBiquadFilter();
+  shelf.type = 'lowshelf';
+  shelf.frequency.value = SLAM_SHELF_HZ;
+  shelf.gain.value = 0;
+  /*
+   * And a low-pass across the driven band: boosted bass plus a low-pass reads better than
+   * saturation on its own, because saturation alone is a *timbre* change that a listener has to be
+   * paying attention to the score to notice. Closing a filter is a change in the whole shape of the
+   * sound, and it is the move every dance record uses to mark a moment precisely because it works
+   * on somebody who is not listening for it.
+   */
+  const lowpass = context.createBiquadFilter();
+  lowpass.type = 'lowpass';
+  lowpass.frequency.value = SLAM_OPEN_HZ;
+  lowpass.Q.value = 1.1;
+  const drive = context.createGain();
+  drive.gain.value = 1;
+  const shaper = context.createWaveShaper();
+  shaper.curve = softClipCurve();
+  // The clip generates harmonics well above the band it came from; without oversampling those
+  // alias back down as grit that does not belong to the hit.
+  shaper.oversample = '4x';
+  const wet = context.createGain();
+  wet.gain.value = 0;
+
+  shelf.connect(lowpass);
+  lowpass.connect(drive);
+  drive.connect(shaper);
+  shaper.connect(wet);
+  wet.connect(output);
+
+  return {
+    input: dry,
+    output,
+    wetInput: shelf,
+    dryGain: dry,
+    wetGain: wet,
+    /**
+     * Slam the low end for an instant, hard enough to clip.
+     *
+     * Everything about the shape says *event*: twelve milliseconds of attack so it lands on the
+     * tick rather than swelling into it, then an exponential decay back to nothing over about a
+     * third of a second. Scheduled on the audio clock rather than eased from the frame loop, so the
+     * envelope is sample-accurate and a dropped frame cannot stretch it.
+     */
+    strike(amount: number): void {
+      const hit = clamp01(amount);
+      if (hit < 0.05) return;
+      const at = scheduleAt();
+      const strikeParam = (param: AudioParam, idle: number, peak: number): void => {
+        param.cancelScheduledValues(at);
+        // From wherever the last slam left it, so gates a stride apart stack rather than each one
+        // restarting the envelope from silence.
+        param.setValueAtTime(param.value, at);
+        param.linearRampToValueAtTime(peak, at + SLAM_ATTACK_SEC);
+        param.setTargetAtTime(idle, at + SLAM_ATTACK_SEC, SLAM_DECAY_SEC);
+      };
+      strikeParam(wet.gain, 0, hit);
+      strikeParam(dry.gain, 1, 1 - hit * SLAM_DUCK);
+      strikeParam(shelf.gain, 0, hit * SLAM_SHELF_DB);
+      strikeParam(drive.gain, 1, 1 + hit * SLAM_DRIVE);
+      // Down to the sub band and back open. The filter is most of the effect now.
+      strikeParam(lowpass.frequency, SLAM_OPEN_HZ, SLAM_CLOSED_HZ);
+    },
+  };
+}
+
+/**
+ * A soft clipper, transparent until it is driven and saturating hard after.
+ *
+ * `tanh` rather than a hard corner: a hard clip of a bass note is a square wave, and a square
+ * wave's odd harmonics march all the way up the spectrum as buzz. `tanh` rounds the corner, so what
+ * comes out is the second and third harmonic — which is what "driven" sounds like as opposed to
+ * "broken".
+ *
+ * Odd-length so there is a sample exactly at zero, which keeps silence silent.
+ */
+function softClipCurve(): Float32Array<ArrayBuffer> {
+  const samples = 2049;
+  const curve = new Float32Array(new ArrayBuffer(2049 * 4));
+  for (let i = 0; i < samples; i++) {
+    const x = (i / (samples - 1)) * 2 - 1;
+    curve[i] = Math.tanh(x * SLAM_CLIP_KNEE) / Math.tanh(SLAM_CLIP_KNEE);
+  }
+  return curve;
+}

package/src/mix/returns.ts

@@ -0,0 +1,114 @@
+import type { ScheduleClock } from '../ambientLoop.ts';
+import type { MixInsert } from './bus.ts';
+
+/**
+ * The stages a *return* bus carries: a reverb, and an echo.
+ *
+ * Separate from `inserts.ts` because they answer a different question. Those are stages a source
+ * bus puts in its own path; these are what a bus at the end of a send is made of, and a consumer
+ * building a return reaches for exactly one of them.
+ */
+
+const RAMP = 0.08;
+
+/**
+ * A synthesised impulse response: exponentially decaying noise.
+ *
+ * Not a real hall — a real one is a file, and files are what the registry is for. This exists so
+ * reverb works before any asset has been recorded, on the same principle as every other sound here.
+ *
+ * **`random` is a parameter rather than `Math.random`**, and that is what makes a reverb tail
+ * assertable at all: an unseeded generator builds a different hall every construction, so no render
+ * carrying wet signal can be compared to another. Defaulting it here would have hidden that.
+ */
+export function impulseResponse(
+  context: BaseAudioContext,
+  seconds: number,
+  decay: number,
+  random: () => number,
+): AudioBuffer {
+  const rate = context.sampleRate;
+  const length = Math.max(1, Math.floor(rate * seconds));
+  const buffer = context.createBuffer(2, length, rate);
+  for (let channel = 0; channel < 2; channel++) {
+    const data = buffer.getChannelData(channel);
+    for (let i = 0; i < length; i++) {
+      data[i] = (random() * 2 - 1) * (1 - i / length) ** decay;
+    }
+  }
+  return buffer;
+}
+
+/**
+ * A convolver, built once at registration.
+ *
+ * **Never on entry to anything.** Building an impulse allocates a stereo buffer and fills it sample
+ * by sample, which costs milliseconds; doing that when a player crosses a threshold would put both
+ * the allocation and the cost on the input path at the exact moment something is supposed to happen.
+ */
+export function convolverInsert(
+  context: BaseAudioContext,
+  seconds: number,
+  decay: number,
+  random: () => number,
+): MixInsert {
+  const convolver = context.createConvolver();
+  convolver.buffer = impulseResponse(context, seconds, decay, random);
+  return { input: convolver, output: convolver };
+}
+
+export interface DelayInsert extends MixInsert {
+  setTime(seconds: number): void;
+  setFeedback(amount: number): void;
+  readonly timeSec: number;
+}
+
+/**
+ * A delay line that feeds itself, at a level that must decay.
+ *
+ * The interval is worth exposing rather than fixing at a pleasant-sounding constant, because an
+ * echo either lands *with* the music or against it, and which one depends on the tempo of whatever
+ * is playing: a 0.28 s repeat under a 150 BPM track falls between the beats and reads as smear,
+ * where a half-beat repeat reads as the room the track is in.
+ */
+export function delayInsert(
+  context: BaseAudioContext,
+  scheduleAt: ScheduleClock,
+  { time = 0.28, feedback = 0.34 } = {},
+): DelayInsert {
+  const delay = context.createDelay(1);
+  delay.delayTime.value = time;
+  const loop = context.createGain();
+  loop.gain.value = feedback;
+  delay.connect(loop);
+  loop.connect(delay);
+
+  const ramp = (param: AudioParam, value: number): void => {
+    const at = scheduleAt();
+    param.cancelScheduledValues(at);
+    param.setTargetAtTime(value, at, RAMP);
+  };
+
+  return {
+    input: delay,
+    output: delay,
+    get timeSec(): number {
+      return delay.delayTime.value;
+    },
+    setTime(seconds: number): void {
+      if (!Number.isFinite(seconds)) return;
+      // Clamped to the line's own capacity.
+      ramp(delay.delayTime, Math.min(Math.max(seconds, 0.02), 0.98));
+    },
+    /**
+     * How much of each repeat feeds the next.
+     *
+     * Clamped below 1, because a feedback path that does not decay is a drone that grows until it
+     * clips — and one the caller cannot undo by turning the send down, since the energy is already
+     * circulating.
+     */
+    setFeedback(amount: number): void {
+      ramp(loop.gain, Math.min(Math.max(amount, 0), 0.88));
+    },
+  };
+}

package/src/mix/snapshot.ts

@@ -0,0 +1,75 @@
+import type { MixBus } from './bus.ts';
+import type { MixConsole } from './console.ts';
+
+/**
+ * A mix, remembered: every fader, every mute and every send, at one instant.
+ *
+ * **Insert parameters are deliberately absent**, and that is the whole design decision here. The
+ * master filter's cutoff is written every frame from whatever the game is doing; a snapshot that
+ * captured it would fight that writer, and the winner would be whichever wrote last — which is
+ * heard as a filter that sometimes sticks and cannot be reproduced on purpose.
+ *
+ * Cost: "underwater" as a snapshot carries its levels and its sends but not its filter, so a
+ * consumer wanting both recalls the snapshot and sets the cutoff itself. What would make this wrong
+ * is an insert parameter no per-frame code ever touches, which is when capturing it costs nothing;
+ * this clause is what to revisit if one arrives.
+ */
+export interface MixSnapshot {
+  readonly levels: ReadonlyMap<string, number>;
+  readonly mutes: ReadonlyMap<string, boolean>;
+  /** Per bus name, per return bus name, the amount that bus was sending. */
+  readonly sends: ReadonlyMap<string, ReadonlyMap<string, number>>;
+}
+
+export function captureSnapshot(mix: MixConsole): MixSnapshot {
+  const levels = new Map<string, number>();
+  const mutes = new Map<string, boolean>();
+  const sends = new Map<string, ReadonlyMap<string, number>>();
+  for (const bus of mix.all) {
+    levels.set(bus.name, bus.level);
+    mutes.set(bus.name, bus.muted);
+    const perTarget = new Map<string, number>();
+    for (const target of bus.sendTargets) perTarget.set(target.name, bus.sendAmount(target));
+    if (perTarget.size > 0) sends.set(bus.name, perTarget);
+  }
+  return { levels, mutes, sends };
+}
+
+/**
+ * Move the mix back to a captured one, over `seconds`.
+ *
+ * **A bus the snapshot never saw is left alone**, rather than reset to a default. A snapshot is a
+ * record of what was, not an assertion about what must be, and silencing a bus that did not exist
+ * when it was taken is a recall destroying state it knows nothing about — a reverb zone registered
+ * after a mix was captured, say, going silent the first time anybody recalls it.
+ */
+export function recallSnapshot(mix: MixConsole, snapshot: MixSnapshot, seconds: number): void {
+  for (const [name, level] of snapshot.levels) {
+    const bus = mix.find(name);
+    if (bus === undefined) continue;
+    applyLevel(bus, level, seconds);
+    bus.setMute(snapshot.mutes.get(name) ?? false);
+  }
+  for (const [name, perTarget] of snapshot.sends) {
+    const bus = mix.find(name);
+    if (bus === undefined) continue;
+    for (const [targetName, amount] of perTarget) {
+      const target = mix.find(targetName);
+      if (target !== undefined) bus.send(target, amount);
+    }
+  }
+}
+
+/**
+ * `seconds` is the crossfade, and zero means immediately.
+ *
+ * A bus's own `setLevel` ramps at the mix's standard smoothing, which is right for a fader and
+ * wrong for a scene change: a snapshot recalled over three seconds has to take three seconds.
+ */
+function applyLevel(bus: MixBus, level: number, seconds: number): void {
+  if (seconds <= 0) {
+    bus.setLevel(level);
+    return;
+  }
+  bus.fadeLevel(level, seconds);
+}

package/src/positional.ts

@@ -0,0 +1,47 @@
+/**
+ * Placing a sound in the world: how loud a source is from here, and which side
+ * of the head it is on.
+ *
+ * Two small functions rather than a panner graph per emitter. A full HRTF node
+ * is the general answer and the right one for a game where a footstep behind
+ * you is information; for environmental sources — a fire, a waterfall, a storm
+ * column — what a player actually reads is "how close" and "which way", and
+ * these produce exactly those two numbers at no per-frame node cost.
+ *
+ * Both are pure, so a game can compute a whole scene's mix inside its render
+ * pass without touching the audio thread until the values have settled.
+ */
+
+/**
+ * Level for a source `distance` away, reaching exactly zero at `radius`.
+ *
+ * Zero at the edge is the part that matters. Physical falloff is `1/d²`, which
+ * never quite arrives — and a route carrying a dozen braziers then sums into a
+ * permanent hiss the player can neither identify nor walk away from. A curve
+ * that ends is worth more here than one that is correct.
+ *
+ * `curve` shapes the approach: 1 is linear, 2 concentrates the change near the
+ * source, which is where a player's own movement makes it legible.
+ */
+export function distanceGain(distance: number, radius: number, curve = 2): number {
+  if (!(radius > 0) || !Number.isFinite(distance)) return 0;
+  const t = 1 - Math.min(Math.max(distance / radius, 0), 1);
+  return curve === 1 ? t : t ** curve;
+}
+
+/**
+ * Where a source sits across the stereo field, from a listener facing `yaw`.
+ *
+ * -1 hard left, 0 centre or directly ahead/behind, 1 hard right. Yaw 0 faces
+ * −Z, matching the convention the rest of the engine's cameras and controls
+ * use, so the listener's right is `(cos yaw, 0, sin yaw)`.
+ *
+ * Horizontal only. Height is deliberately ignored: stereo cannot express it,
+ * and folding it in would quietly pull a source overhead toward the centre for
+ * no reason a listener could interpret.
+ */
+export function stereoPan(dx: number, dz: number, yaw: number): number {
+  const horizontal = Math.hypot(dx, dz);
+  if (horizontal < 1e-4) return 0;
+  return (dx * Math.cos(yaw) + dz * Math.sin(yaw)) / horizontal;
+}