@driftengine/audio 3.61.0

package/src/registry.ts

@@ -0,0 +1,167 @@
+/**
+ * Named sound slots, resolved once at load: real file if present, synthesised
+ * buffer if not.
+ *
+ * Synthesis is a placeholder, never the destination. Addressing every sound by
+ * slot means dropping a file into the assets folder replaces it — no code
+ * change, no graph rebuild, no registration step. Until then the game is
+ * audible rather than silent, so development is never blocked on assets
+ * existing.
+ *
+ * Game-agnostic on purpose: this knows slots and buffers, not that one of them
+ * is a footstep.
+ */
+export type SoundSlot = string;
+
+export interface SoundSource {
+  /**
+   * Candidate locations, tried in order; the first that loads wins.
+   *
+   * A list rather than one path so a slot can accept whatever format the sound
+   * actually arrives in. Asking a composer to transcode before they can hear
+   * their track in the game is friction with nothing on the other side of it —
+   * the browser decodes all of these natively.
+   */
+  urls: readonly string[];
+  /** Built only when no candidate is present or usable. */
+  synth: (ctx: BaseAudioContext) => AudioBuffer;
+}
+
+/** How a slot ended up being filled. Useful in dev to see what is still synth. */
+export type SoundOrigin = 'file' | 'synth';
+
+/** Injectable so the resolution rules can be tested without a network. */
+export type FetchLike = (url: string) => Promise<Response>;
+
+export class SoundRegistry {
+  private readonly sources = new Map<SoundSlot, SoundSource>();
+  private readonly buffers = new Map<SoundSlot, AudioBuffer>();
+  private readonly origins = new Map<SoundSlot, SoundOrigin>();
+  /** Slots whose stand-in threw. Empty is the normal state; see `unbuilt`. */
+  private readonly failed = new Map<SoundSlot, string>();
+
+  constructor(private readonly fetchImpl: FetchLike = (url) => fetch(url)) {}
+
+  register(slot: SoundSlot, source: SoundSource): void {
+    this.sources.set(slot, source);
+  }
+
+  /** Which slots exist, so callers can pick among them (e.g. a daily track). */
+  get slots(): readonly SoundSlot[] {
+    return [...this.sources.keys()];
+  }
+
+  /**
+   * Slots whose stand-in threw, and what it said.
+   *
+   * Empty is the normal state. A consumer with a dev overlay should show this: a silent slot is
+   * otherwise indistinguishable from one nobody triggered.
+   */
+  get unbuilt(): ReadonlyMap<SoundSlot, string> {
+    return this.failed;
+  }
+
+  get resolved(): ReadonlyMap<SoundSlot, SoundOrigin> {
+    return this.origins;
+  }
+
+  /**
+   * Adopt already-decoded buffers, skipping every fetch and decode.
+   *
+   * For building a second graph over the same sounds — an offline render of a mix that
+   * is already loaded. An `AudioBuffer` is PCM and a sample rate, not a handle onto the
+   * context that made it, so it can be used by any context running at the same rate;
+   * decoding the library again would cost the whole payload a second time and, worse,
+   * could resolve a slot differently from the mix being reproduced.
+   */
+  adopt(from: SoundRegistry): void {
+    for (const [slot, buffer] of from.buffers) this.buffers.set(slot, buffer);
+    for (const [slot, origin] of from.origins) this.origins.set(slot, origin);
+    for (const [slot, source] of from.sources) {
+      if (!this.sources.has(slot)) this.sources.set(slot, source);
+    }
+  }
+
+  get(slot: SoundSlot): AudioBuffer | undefined {
+    return this.buffers.get(slot);
+  }
+
+  /**
+   * Resolve every slot: the files in parallel, then the stand-ins one at a time.
+   *
+   * Slots settle independently: one missing or corrupt asset must not silence
+   * the rest of the game, which is the likeliest real failure once assets are
+   * being dropped in by hand. Every failure mode — network error, HTTP status,
+   * undecodable bytes — lands on the same fallback, because from the player's
+   * side they are the same event.
+   *
+   * **The two halves are separated because they cost completely different
+   * things.** Fetching is waiting, and twenty slots should wait together.
+   * Synthesis is arithmetic on the main thread — an ambience bed is seven
+   * seconds of filtered noise at the context's sample rate — and twenty of those
+   * settling together lands as one block of work.
+   *
+   * Which is exactly what it did. Traced on 2026-08-07 on a game that starts its
+   * audio at boot, the fallbacks arrived as microtask blocks of 11, 14, 14, 21
+   * and 34 ms while the player was already running, and the frame loop went
+   * 125 ms between frames because the vsync deadline kept landing inside one.
+   * So each stand-in gets its own task. The work is the same; what changes is
+   * that a frame can be drawn between any two of them.
+   *
+   * The yield is a timer rather than a microtask, and that is the whole point —
+   * a microtask would rejoin the block it is trying to leave. Whatever the
+   * browser clamps the delay to only spaces the work further.
+   */
+  async load(ctx: BaseAudioContext): Promise<void> {
+    const entries = [...this.sources.entries()];
+    await Promise.allSettled(entries.map(([slot, source]) => this.loadFile(ctx, slot, source)));
+
+    for (const [slot, source] of entries) {
+      if (this.buffers.has(slot)) continue;
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, 0);
+      });
+      /*
+       * **Each stand-in settles on its own, which is what the paragraph above already promised
+       * and what this loop did not deliver.** File failures land on `allSettled` and every one of
+       * them is contained; a *synth* that threw took the whole `load` down with it — so every slot
+       * after it in registration order was left with no buffer, and `play` returns silently on an
+       * undefined one. The symptom is a game where the first few sounds work and the rest do not,
+       * with nothing in the console after the one throw, and the boundary falling wherever the
+       * consumer happened to register the bad slot.
+       *
+       * Caught rather than rethrown for the same reason a missing file is: from the player's side
+       * a slot that cannot be built and one that cannot be fetched are the same event, and neither
+       * is worth the rest of the game's audio.
+       */
+      try {
+        this.buffers.set(slot, source.synth(ctx));
+        this.origins.set(slot, 'synth');
+      } catch (error) {
+        this.failed.set(slot, error instanceof Error ? error.message : String(error));
+      }
+    }
+  }
+
+  /** The first candidate that loads and decodes wins; none of them is normal. */
+  private async loadFile(
+    ctx: BaseAudioContext,
+    slot: SoundSlot,
+    source: SoundSource,
+  ): Promise<void> {
+    for (const url of source.urls) {
+      try {
+        const response = await this.fetchImpl(url);
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const bytes = await response.arrayBuffer();
+        const buffer = await ctx.decodeAudioData(bytes);
+        this.buffers.set(slot, buffer);
+        this.origins.set(slot, 'file');
+        return;
+      } catch {
+        // Try the next format. A missing candidate is the normal case, not
+        // an error: most slots will only ever have one of these present.
+      }
+    }
+  }
+}

package/src/rhythm/bands.ts

@@ -0,0 +1,45 @@
+/**
+ * The frequency bands every rhythm detector in the engine reads.
+ *
+ * One definition, shared by the offline analyser and the live detector, so
+ * "a kick" means the same thing whether it is being found ahead of time for an
+ * edit or reacted to in the moment for a light. Two sets of numbers that
+ * drifted apart would produce a replay whose cuts disagreed with the lights in
+ * the very footage they are cutting.
+ *
+ * The split is finer than "bass / mid / treble" because the hard problem is not
+ * finding low energy, it is telling a *kick* apart from a sustained bassline
+ * sitting in nearly the same octave. `sub`/`punch`/`sweet` are the kick;
+ * `bassline`/`mud` are what has to be subtracted from it.
+ */
+export interface Band {
+  readonly lowHz: number;
+  readonly highHz: number;
+}
+
+export const RHYTHM_BANDS = {
+  sub: { lowHz: 40, highHz: 60 },
+  punch: { lowHz: 60, highHz: 100 },
+  sweet: { lowHz: 75, highHz: 110 },
+  bassline: { lowHz: 95, highHz: 180 },
+  mud: { lowHz: 180, highHz: 420 },
+  lowMid: { lowHz: 500, highHz: 2500 },
+  high: { lowHz: 5000, highHz: 12000 },
+} as const satisfies Record<string, Band>;
+
+export type BandName = keyof typeof RHYTHM_BANDS;
+
+/** Energy in each band, 0–1, filled in place so nothing allocates per hop. */
+export interface BandEnergies {
+  sub: number;
+  punch: number;
+  sweet: number;
+  bassline: number;
+  mud: number;
+  lowMid: number;
+  high: number;
+}
+
+export function createBandEnergies(): BandEnergies {
+  return { sub: 0, punch: 0, sweet: 0, bassline: 0, mud: 0, lowMid: 0, high: 0 };
+}

package/src/rhythm/beatGrid.ts

@@ -0,0 +1,106 @@
+import type { BeatMap } from './beatMap.ts';
+
+/**
+ * A beat map from a tempo the player supplies rather than one we detected.
+ *
+ * The reason this exists is the workflow, not the maths. On TikTok and Reels
+ * the trending sound is added *in the app*, replacing whatever audio the clip
+ * arrived with — so the thing that has to line up is not our audio against
+ * theirs, it is our *cuts* against their sound. A player who taps along to the
+ * track they intend to use gets an edit that fits it, and it works with any
+ * song in existence precisely because we never touch the song.
+ *
+ * The output is an ordinary `BeatMap`, so nothing downstream needs to know
+ * where its beats came from.
+ */
+export function beatGrid(bpm: number, offsetSec: number, durationSec: number): BeatMap {
+  const safeBpm = Number.isFinite(bpm) && bpm > 0 ? bpm : 120;
+  const period = 60 / safeBpm;
+  const length = Math.max(0, Number.isFinite(durationSec) ? durationSec : 0);
+
+  /*
+   * Wrapped into the first beat. A player nudging the offset will run it past a
+   * whole beat without thinking about it, and a grid that then started a second
+   * in would silently lose the opening cut.
+   */
+  const raw = Number.isFinite(offsetSec) ? offsetSec : 0;
+  const first = ((raw % period) + period) % period;
+
+  const count = length <= 0 ? 0 : Math.max(0, Math.floor((length - first) / period) + 1);
+  const beats = new Float32Array(count);
+  const strength = new Float32Array(count);
+  for (let i = 0; i < count; i++) {
+    beats[i] = first + i * period;
+    // Every fourth beat is the downbeat. Not detected — asserted, because that
+    // is what a player tapping four to the bar means by it.
+    strength[i] = i % 4 === 0 ? 1 : 0.6;
+  }
+
+  return {
+    beats,
+    strength,
+    bpm: safeBpm,
+    bpmConfidence: 1,
+    energy: new Float32Array([1]),
+    energyHz: 10,
+    durationSec: length,
+  };
+}
+
+/** Taps this far apart are two separate attempts, not one tempo. */
+const STALE_MS = 3000;
+/** Below four taps there are too few intervals to reject a fumble. */
+const MIN_TAPS = 4;
+const MAX_TAPS = 8;
+/** Outside this a "tempo" is a double-tap or somebody who wandered off. */
+const MIN_BPM = 60;
+const MAX_BPM = 200;
+
+/**
+ * Tempo and phase, from somebody tapping along.
+ *
+ * Phase is the part that matters. A player could type a BPM; what they cannot
+ * type is *where the downbeat falls* in the sound they are about to add, and a
+ * grid at the right tempo with the wrong phase is off by up to half a beat
+ * everywhere — worse than not syncing at all.
+ */
+export class TapTempo {
+  private readonly taps: number[] = [];
+
+  tap(nowMs: number): void {
+    const previous = this.taps[this.taps.length - 1];
+    // A gap means they stopped and started again. Averaging across it would
+    // produce a tempo of a couple of beats a minute.
+    if (previous !== undefined && nowMs - previous > STALE_MS) this.taps.length = 0;
+    this.taps.push(nowMs);
+    if (this.taps.length > MAX_TAPS) this.taps.shift();
+  }
+
+  /** Null until there is enough to be sure, and for anything implausible. */
+  get bpm(): number | null {
+    if (this.taps.length < MIN_TAPS) return null;
+
+    const intervals: number[] = [];
+    for (let i = 1; i < this.taps.length; i++) {
+      intervals.push((this.taps[i] ?? 0) - (this.taps[i - 1] ?? 0));
+    }
+    // Median, not mean: anybody tapping along will fumble one, and a mean turns
+    // a single 400 ms stumble into a double-digit BPM error.
+    intervals.sort((a, b) => a - b);
+    const median = intervals[intervals.length >> 1] ?? 0;
+    if (median <= 0) return null;
+
+    const bpm = 60_000 / median;
+    if (bpm < MIN_BPM || bpm > MAX_BPM) return null;
+    return bpm;
+  }
+
+  /** Seconds, from the same clock the taps were given in. */
+  get offsetSec(): number {
+    return (this.taps[this.taps.length - 1] ?? 0) / 1000;
+  }
+
+  reset(): void {
+    this.taps.length = 0;
+  }
+}