@driftengine/audio 3.61.0

package/dist/synth.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Placeholder buffer synthesis: the stand-in a sound slot uses until a real
+ * file exists for it.
+ *
+ * Deliberately plain, and generic to any game. These exist so a build is
+ * audible and its timing can be felt while the real sounds are being made —
+ * they are not an attempt at the final thing, and treating them as one is the
+ * mistake the whole slot arrangement is designed to prevent.
+ */
+export declare function noiseBuffer(ctx: BaseAudioContext, seconds: number, decay: number, colour: (t: number) => number): AudioBuffer;
+/** A pitched blip: a sine sweep, for anything that should read as a signal. */
+export declare function toneBuffer(ctx: BaseAudioContext, seconds: number, fromHz: number, toHz: number, decay: number): AudioBuffer;
+/**
+ * A struck metal ring: inharmonic partials over a bright transient.
+ *
+ * The one thing that separates metal from every other synthesised hit is that its
+ * partials are **not** whole multiples of the fundamental. A harmonic stack reads as a
+ * bell at best and an organ at worst; detuning the partials by irrational-ish ratios
+ * is what makes the ear hear a struck bar. The ratios below are near a free bar's own
+ * modes rather than exact, which keeps it from ringing like a tuned instrument.
+ *
+ * Each partial decays at its own rate, faster the higher it is, because that is what
+ * real metal does and it is most of why a synthesised clang usually sounds like a
+ * synthesiser: hold the top partials as long as the bottom and you get a chime.
+ *
+ * @param seconds Total length. Metal rings on; too short and it is a click.
+ * @param baseHz The fundamental the partials are built off.
+ * @param decay How fast the whole thing dies away.
+ */
+export declare function metalBuffer(ctx: BaseAudioContext, seconds: number, baseHz: number, decay: number): AudioBuffer;
+/** Silence, for a slot whose only honest placeholder is nothing at all. */
+export declare function silentBuffer(ctx: BaseAudioContext): AudioBuffer;
+/**
+ * A continuous environmental bed, built to loop without a seam.
+ *
+ * Three things make a loop audible as a loop, and all three are handled here.
+ * The filters are warmed up before anything is recorded, so the buffer does not
+ * begin at silence and fade in. The join is crossfaded with equal-power
+ * weights, so the wrap has neither a click nor the ~3 dB hole a linear
+ * crossfade of noise leaves in the middle. And any slow swell is placed at a
+ * whole number of cycles per loop — the same reason the wind field uses integer
+ * harmonics — so it arrives back exactly where it started instead of turning
+ * the wrap into a lurch far more noticeable than the noise it rides on.
+ */
+export interface AmbienceOptions {
+    /** Loop length. Longer costs memory but takes longer to recognise. */
+    seconds: number;
+    /** One-pole low-pass coefficient, 0–1. Lower is darker. */
+    colour: number;
+    /**
+     * Second, slower follower subtracted from the first — a high-pass. Removes
+     * the rumble that otherwise dominates any heavily filtered noise.
+     */
+    bodyCut?: number;
+    /** Slow level movement: how deep, 0–1, and how many whole cycles per loop. */
+    swellDepth?: number;
+    swellCycles?: number;
+    /** Sharp transients per second, and how fast each one decays. */
+    transientRate?: number;
+    transientDecay?: number;
+    /** Peak amplitude of the finished bed. */
+    gain?: number;
+}
+export declare function ambienceBuffer(ctx: BaseAudioContext, options: AmbienceOptions): AudioBuffer;
+/**
+ * Fire: a broadband hiss with sparks over it.
+ *
+ * The hiss alone reads as static; the sparks are what make it fire, and they
+ * have to be irregular — anything periodic turns a hearth into a machine.
+ */
+export declare function fireLoopBuffer(ctx: BaseAudioContext, seconds?: number): AudioBuffer;
+/**
+ * Water: a slow, dark wash that breathes.
+ *
+ * Nearly all the energy is low, and the swell is the part carrying the meaning
+ * — flat filtered noise at this darkness is indistinguishable from a fan.
+ */
+export declare function waterLoopBuffer(ctx: BaseAudioContext, seconds?: number): AudioBuffer;
+/** Wind: mid-heavy rush, swelling harder and faster than water. */
+export declare function windLoopBuffer(ctx: BaseAudioContext, seconds?: number): AudioBuffer;
+/**
+ * A skate scrape: the sound of an edge losing its bite.
+ *
+ * Bright filtered noise with a slow chatter in it, so it reads as *grinding*
+ * rather than as hiss. The caller sweeps its playback rate with the drift's
+ * charge, which is what turns a texture into a meter you can hear — the pitch
+ * rising under you is the drift telling you how long you have held it.
+ *
+ * Loops without a seam: the chatter completes a whole number of cycles across
+ * the buffer, and the tail crossfades into the head.
+ */
+export declare function driftScrapeBuffer(ctx: BaseAudioContext, seconds?: number): AudioBuffer;

package/dist/synth.js

@@ -0,0 +1,282 @@
+/**
+ * Placeholder buffer synthesis: the stand-in a sound slot uses until a real
+ * file exists for it.
+ *
+ * Deliberately plain, and generic to any game. These exist so a build is
+ * audible and its timing can be felt while the real sounds are being made —
+ * they are not an attempt at the final thing, and treating them as one is the
+ * mistake the whole slot arrangement is designed to prevent.
+ */
+/** A short noise burst shaped by an envelope — the workhorse placeholder. */
+/**
+ * Makeup gain for the three-pole cascade below.
+ *
+ * **Why three poles and not one.** Every filtered-noise sound in this engine ran
+ * through a single pole, and a single pole is only 6 dB per octave — so at three or
+ * four octaves above its own cutoff it has taken off barely twenty decibels, and what
+ * survives is still broadband. Which is exactly what a listener hears: white noise
+ * everywhere, a waterfall that sounds like static. Lowering the cutoff did not fix it
+ * and could not — the leak is the slope, not the corner.
+ *
+ * Three poles in series is 18 dB per octave, which is a filter you can actually hear
+ * working. A landing becomes a thud, a slide becomes a scrape, and a waterfall becomes
+ * water rather than static with a swell on it — and every existing caller gets it
+ * without changing a single one of their numbers, because the corner frequency they
+ * each chose is unchanged. Only the slope past it moved.
+ *
+ * The cascade costs amplitude — each stage takes another bite out of the noise's own
+ * power — so this puts the level back. Measured to bring a mid-range colour term out
+ * at roughly what one pole used to.
+ */
+const POLE_MAKEUP = 2.6;
+export function noiseBuffer(ctx, seconds, decay, colour) {
+    const rate = ctx.sampleRate;
+    const length = Math.max(1, Math.floor(rate * seconds));
+    const buffer = ctx.createBuffer(1, length, rate);
+    const data = buffer.getChannelData(0);
+    let p1 = 0;
+    let p2 = 0;
+    let p3 = 0;
+    for (let i = 0; i < length; i++) {
+        const t = i / length;
+        const white = Math.random() * 2 - 1;
+        const c = colour(t);
+        // Three poles, not one. See POLE_MAKEUP.
+        p1 += (white - p1) * c;
+        p2 += (p1 - p2) * c;
+        p3 += (p2 - p3) * c;
+        data[i] = p3 * POLE_MAKEUP * (1 - t) ** decay;
+    }
+    return buffer;
+}
+/** A pitched blip: a sine sweep, for anything that should read as a signal. */
+export function toneBuffer(ctx, seconds, fromHz, toHz, decay) {
+    const rate = ctx.sampleRate;
+    const length = Math.max(1, Math.floor(rate * seconds));
+    const buffer = ctx.createBuffer(1, length, rate);
+    const data = buffer.getChannelData(0);
+    let phase = 0;
+    for (let i = 0; i < length; i++) {
+        const t = i / length;
+        const hz = fromHz + (toHz - fromHz) * t;
+        phase += (hz / rate) * Math.PI * 2;
+        data[i] = Math.sin(phase) * (1 - t) ** decay * 0.6;
+    }
+    return buffer;
+}
+/**
+ * A struck metal ring: inharmonic partials over a bright transient.
+ *
+ * The one thing that separates metal from every other synthesised hit is that its
+ * partials are **not** whole multiples of the fundamental. A harmonic stack reads as a
+ * bell at best and an organ at worst; detuning the partials by irrational-ish ratios
+ * is what makes the ear hear a struck bar. The ratios below are near a free bar's own
+ * modes rather than exact, which keeps it from ringing like a tuned instrument.
+ *
+ * Each partial decays at its own rate, faster the higher it is, because that is what
+ * real metal does and it is most of why a synthesised clang usually sounds like a
+ * synthesiser: hold the top partials as long as the bottom and you get a chime.
+ *
+ * @param seconds Total length. Metal rings on; too short and it is a click.
+ * @param baseHz The fundamental the partials are built off.
+ * @param decay How fast the whole thing dies away.
+ */
+export function metalBuffer(ctx, seconds, baseHz, decay) {
+    const rate = ctx.sampleRate;
+    const length = Math.max(1, Math.floor(rate * seconds));
+    const buffer = ctx.createBuffer(1, length, rate);
+    const data = buffer.getChannelData(0);
+    // Inharmonic on purpose. Whole multiples of these would be a bell.
+    const partials = [1, 2.76, 5.4, 8.93, 13.34, 18.64];
+    const phases = new Float64Array(partials.length);
+    for (let i = 0; i < length; i++) {
+        const t = i / length;
+        let sample = 0;
+        for (let p = 0; p < partials.length; p++) {
+            const ratio = partials[p] ?? 1;
+            phases[p] = (phases[p] ?? 0) + ((baseHz * ratio) / rate) * Math.PI * 2;
+            // Higher partials die first, which is the whole difference between struck
+            // metal and a chime.
+            const fade = (1 - t) ** (decay * (1 + p * 0.55));
+            sample += (Math.sin(phases[p] ?? 0) * fade) / (1 + p * 0.9);
+        }
+        // A short noise transient: the strike itself, before anything has begun to ring.
+        const strike = t < 0.012 ? (Math.random() * 2 - 1) * (1 - t / 0.012) * 0.7 : 0;
+        // Body over transient: the ring is the part that says *metal*, so it is weighted
+        // above the strike rather than under it.
+        data[i] = (sample * 0.52 + strike) * (1 - t) ** 0.6;
+    }
+    return buffer;
+}
+/** Silence, for a slot whose only honest placeholder is nothing at all. */
+export function silentBuffer(ctx) {
+    return ctx.createBuffer(1, 1, ctx.sampleRate);
+}
+export function ambienceBuffer(ctx, options) {
+    const rate = ctx.sampleRate;
+    const length = Math.max(1, Math.floor(rate * options.seconds));
+    // Fade over an eighth of the loop: long enough to hide the join in noise,
+    // short enough that most of the buffer is still unblended material.
+    const fade = Math.max(1, Math.min(Math.floor(length / 8), Math.floor(rate * 0.35)));
+    const colour = options.colour;
+    const bodyCut = options.bodyCut ?? 0;
+    const transientRate = options.transientRate ?? 0;
+    const transientDecay = options.transientDecay ?? 60;
+    const transientChance = transientRate / rate;
+    let p1 = 0;
+    let p2 = 0;
+    let low = 0;
+    let body = 0;
+    let transient = 0;
+    const step = () => {
+        const white = Math.random() * 2 - 1;
+        // Three poles, as in `noiseBuffer` and for the same reason.
+        p1 += (white - p1) * colour;
+        p2 += (p1 - p2) * colour;
+        low += (p2 - low) * colour;
+        body += (low - body) * bodyCut;
+        // A spark is a step that decays away, not a tone.
+        if (transientChance > 0 && Math.random() < transientChance) {
+            transient = (Math.random() * 2 - 1) * 0.9;
+        }
+        transient -= transient * (transientDecay / rate);
+        return (low - body) * POLE_MAKEUP + transient;
+    };
+    /*
+     * Settle the filters first. Both start at zero, and the slow one — the
+     * high-pass follower — takes a second or more of signal to reach its working
+     * point. Recording from cold puts an audible swell at the head of the buffer
+     * that the crossfade then smears across the join.
+     */
+    const slowest = Math.max(Math.min(bodyCut > 0 ? bodyCut : colour, colour), 1e-4);
+    const warmup = Math.min(Math.ceil(5 / slowest), rate * 3);
+    for (let i = 0; i < warmup; i++)
+        step();
+    const raw = new Float32Array(length + fade);
+    for (let i = 0; i < raw.length; i++)
+        raw[i] = step();
+    const buffer = ctx.createBuffer(1, length, rate);
+    const data = buffer.getChannelData(0);
+    const gain = options.gain ?? 1;
+    const swellDepth = options.swellDepth ?? 0;
+    const swellCycles = Math.max(0, Math.round(options.swellCycles ?? 0));
+    for (let i = 0; i < length; i++) {
+        let sample = raw[i] ?? 0;
+        if (i < fade) {
+            // Equal power, so noise keeps its level straight through the join.
+            const t = i / fade;
+            sample = sample * Math.sqrt(t) + (raw[length + i] ?? 0) * Math.sqrt(1 - t);
+        }
+        const swell = swellCycles > 0
+            ? 1 -
+                swellDepth +
+                swellDepth * (0.5 + 0.5 * Math.sin((i / length) * swellCycles * Math.PI * 2))
+            : 1;
+        data[i] = sample * swell * gain;
+    }
+    return buffer;
+}
+/**
+ * Fire: a broadband hiss with sparks over it.
+ *
+ * The hiss alone reads as static; the sparks are what make it fire, and they
+ * have to be irregular — anything periodic turns a hearth into a machine.
+ */
+export function fireLoopBuffer(ctx, seconds = 4) {
+    return ambienceBuffer(ctx, {
+        seconds,
+        colour: 0.22,
+        bodyCut: 0.004,
+        swellDepth: 0.25,
+        swellCycles: 3,
+        transientRate: 26,
+        transientDecay: 900,
+        gain: 0.5,
+    });
+}
+/**
+ * Water: a slow, dark wash that breathes.
+ *
+ * Nearly all the energy is low, and the swell is the part carrying the meaning
+ * — flat filtered noise at this darkness is indistinguishable from a fan.
+ */
+export function waterLoopBuffer(ctx, seconds = 6) {
+    return ambienceBuffer(ctx, {
+        seconds,
+        colour: 0.05,
+        bodyCut: 0.0015,
+        swellDepth: 0.55,
+        swellCycles: 2,
+        gain: 0.85,
+    });
+}
+/** Wind: mid-heavy rush, swelling harder and faster than water. */
+export function windLoopBuffer(ctx, seconds = 5) {
+    return ambienceBuffer(ctx, {
+        seconds,
+        colour: 0.1,
+        bodyCut: 0.02,
+        swellDepth: 0.7,
+        swellCycles: 3,
+        gain: 0.6,
+    });
+}
+/**
+ * A skate scrape: the sound of an edge losing its bite.
+ *
+ * Bright filtered noise with a slow chatter in it, so it reads as *grinding*
+ * rather than as hiss. The caller sweeps its playback rate with the drift's
+ * charge, which is what turns a texture into a meter you can hear — the pitch
+ * rising under you is the drift telling you how long you have held it.
+ *
+ * Loops without a seam: the chatter completes a whole number of cycles across
+ * the buffer, and the tail crossfades into the head.
+ */
+export function driftScrapeBuffer(ctx, seconds = 1.6) {
+    const rate = ctx.sampleRate;
+    const length = Math.max(1, Math.floor(seconds * rate));
+    const buffer = ctx.createBuffer(1, length, rate);
+    const data = buffer.getChannelData(0);
+    /*
+     * Two poles of a resonant band, run over white noise.
+     *
+     * `f` sets where the band sits and is the whole difference between a scrape and a
+     * hiss. It was 0.34 — high enough that most of what survived the filter was still
+     * broadband top end, so a slide read as plain white noise. Down at 0.15 the band is
+     * in the low mids where a hard wheel on
+     * stone actually lives, and the tighter `q` narrows it further, so what comes
+     * through reads as a *material* being dragged rather than as noise being played.
+     */
+    let low = 0;
+    let band = 0;
+    const f = 0.15;
+    const q = 0.14;
+    /** Whole cycles across the buffer, so the chatter meets itself at the loop. */
+    const chatterCycles = 11;
+    let seed = 0x2f6e2b1;
+    const noise = () => {
+        seed = (Math.imul(seed, 1664525) + 1013904223) | 0;
+        return (seed / 0x7fffffff) % 1;
+    };
+    for (let i = 0; i < length; i++) {
+        const t = i / length;
+        const chatter = 0.62 + 0.38 * Math.abs(Math.sin(Math.PI * chatterCycles * t));
+        const input = noise();
+        low += f * band;
+        band += f * (input - low - q * band);
+        // Louder per unit of noise than before, because a narrower band passes far less
+        // through: the same 0.55 on this filter is a slide nobody can hear.
+        data[i] = band * chatter * 1.5;
+    }
+    // Equal-power crossfade of the tail into the head.
+    const fade = Math.min(Math.floor(rate * 0.04), Math.floor(length / 4));
+    for (let i = 0; i < fade; i++) {
+        const t = i / fade;
+        const a = Math.cos(t * Math.PI * 0.5);
+        const b = Math.sin(t * Math.PI * 0.5);
+        const head = data[i] ?? 0;
+        const tail = data[length - fade + i] ?? 0;
+        data[i] = head * b + tail * a;
+    }
+    return buffer;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@driftengine/audio",
+  "version": "3.61.0",
+  "description": "Layered stems, synthesis, rhythm analysis and positional placement",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/audio"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "web-audio",
+    "spatial-audio",
+    "dsp",
+    "synthesis"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/ambientLoop.ts

@@ -0,0 +1,101 @@
+/**
+ * A continuous environmental sound: a looping buffer whose level and stereo
+ * position are driven every frame by whatever the game decides is nearby.
+ *
+ * Not a full spatial audio node. A panner per source with an HRTF would be the
+ * general answer, but the sources this is for — a fire, a shoreline, wind —
+ * are diffuse and often several at once, and what actually communicates them is
+ * "how close" and "which side". Those are two numbers, and paying for a panner
+ * graph per brazier to produce them would be the expensive way to get the same
+ * result.
+ *
+ * Both setters are change-gated. They are called once per frame, and scheduling
+ * an `AudioParam` ramp sixty times a second for a value that has not moved is
+ * work the audio thread does not need.
+ */
+const RAMP = 0.12;
+/** Below this the ramp is inaudible; above it, skipping the update is not. */
+const EPSILON = 0.004;
+
+/**
+ * Where "now" comes from, for work this loop schedules.
+ *
+ * Supplied rather than read off the context, because a *rendered* mix has no
+ * "now": an `OfflineAudioContext` holds `currentTime` at zero for as long as the
+ * caller is describing the timeline, so a loop reading it directly would stack
+ * every level change a clip ever makes onto instant zero and play the last one
+ * for the whole file. A fire the character sprints past would sit at its parting
+ * distance from the opening frame.
+ *
+ * The graph that owns the loop already has exactly one answer to this question
+ * for exactly this reason; this is how a loop gets to share it.
+ */
+export type ScheduleClock = () => number;
+
+export class AmbientLoop {
+  private lastGain = 0;
+  private lastPan = 0;
+  private stopped = false;
+
+  /**
+   * @param scheduleAt the instant this loop's changes land on. See `ScheduleClock`.
+   * @param source the looping buffer source, already started.
+   * @param gainNode its level, initially silent.
+   * @param panNode present only where the browser supports stereo panning.
+   */
+  constructor(
+    private readonly scheduleAt: ScheduleClock,
+    private readonly source: AudioBufferSourceNode,
+    private readonly gainNode: GainNode,
+    private readonly panNode: StereoPannerNode | null,
+  ) {}
+
+  private rate = 1;
+
+  /** 0 is silent, 1 is the buffer at its authored level. */
+  setGain(gain: number): void {
+    const next = Number.isFinite(gain) ? Math.min(Math.max(gain, 0), 1) : 0;
+    if (Math.abs(next - this.lastGain) < EPSILON) return;
+    this.lastGain = next;
+    this.ramp(this.gainNode.gain, next);
+  }
+
+  /**
+   * Pitch the bed, for a loop whose *state* should be audible.
+   *
+   * Ramped like gain and pan rather than set, because a stepped playback rate
+   * on a continuous source is a click. Change-gated by the same rule: a rate
+   * written every frame would schedule sixty ramps a second.
+   */
+  setRate(rate: number): void {
+    const next = Math.max(0.05, rate);
+    if (Math.abs(next - this.rate) < 0.005) return;
+    this.rate = next;
+    this.ramp(this.source.playbackRate, next);
+  }
+
+  /** -1 hard left, 0 centre, 1 hard right. A no-op without stereo panning. */
+  setPan(pan: number): void {
+    if (this.panNode === null) return;
+    const next = Number.isFinite(pan) ? Math.min(Math.max(pan, -1), 1) : 0;
+    if (Math.abs(next - this.lastPan) < EPSILON) return;
+    this.lastPan = next;
+    this.ramp(this.panNode.pan, next);
+  }
+
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    try {
+      this.source.stop();
+    } catch {
+      // Never started, or already stopped. Nothing to undo.
+    }
+  }
+
+  private ramp(param: AudioParam, value: number): void {
+    const at = this.scheduleAt();
+    param.cancelScheduledValues(at);
+    param.setTargetAtTime(value, at, RAMP);
+  }
+}