@datamoc/mw_games 0.43.0 → 0.44.2

package/dist/audio/Sfx.d.ts

@@ -0,0 +1,148 @@
+/**
+ * A sound effect described as data and voiced by a synthesis backend instead of read from a
+ * file. mwg owns the shape the game and the mixer need (an id, a priority, what a second
+ * trigger does, a caption); whatever else a backend wants (chip, voices, curves) rides along
+ * untouched, so a retro-instrument package can carry its own `SfxDefinition` through unchanged.
+ */
+export interface SfxDefinition {
+    id: string;
+    /** higher cuts lower when the mixer is full; 0 when omitted */
+    priority?: number;
+    /** what a second trigger does while the first still sounds: `'restart'` (the default), `'ignore'`, or `'layer'` */
+    retrigger?: 'restart' | 'ignore' | 'layer';
+    /** shown by a captioning overlay each time the effect plays */
+    caption?: string;
+    [backendData: string]: unknown;
+}
+/** what a play carries into the backend: the mix mwg computed and a seed that makes any randomness reproducible */
+export interface SfxPlayOptions {
+    /** 0 to 1, after distance and the sound's own volume */
+    gain: number;
+    /** -1 (left) to 1 (right) */
+    pan: number;
+    /** playback ratio, 1 unchanged */
+    pitch: number;
+    /** the only source of chance an effect may use */
+    seed: number;
+}
+/** one effect sounding on a backend */
+export interface SfxVoice {
+    stop(): void;
+    /** false once it has finished by itself or been stopped */
+    readonly active: boolean;
+}
+/** the synthesis side: a chip engine that can voice an effect, wherever it keeps its voices */
+export interface SfxBackend {
+    /** returns null when it cannot voice the effect (no free channel, unknown chip), which is not an error */
+    play(definition: SfxDefinition, options: SfxPlayOptions): SfxVoice | null;
+}
+/** effects by id, so a sound can be made from an id the content named */
+export declare class SfxBank {
+    private readonly definitions;
+    constructor(definitions?: Iterable<SfxDefinition>);
+    define(definition: SfxDefinition): void;
+    has(id: string): boolean;
+    get(id: string): SfxDefinition;
+    ids(): string[];
+}
+/** a granted slot in the arbiter; `release` frees it */
+export interface SfxGrant {
+    release(): void;
+}
+/**
+ * The shared voice limit between chip effects and the bus's `'se'` jingles: both ask here before
+ * they sound, and when the limit is reached the lowest-priority voice (the oldest among equals)
+ * is cut for a new one of equal or higher priority; a new one below everything sounding is
+ * refused. One arbiter handed to a bus and to every `SfxSound` makes them a single pool.
+ *
+ * @example
+ * ```ts
+ * import { SfxArbiter } from '@datamoc/mw_games/audio';
+ *
+ * const arbiter = new SfxArbiter({ maxVoices: 2 });
+ * const a = arbiter.request(1, () => console.log('a cut'));
+ * arbiter.request(1, () => console.log('b cut'));
+ * arbiter.request(5, () => console.log('c cut')); // cuts a, the oldest of the lowest priority
+ * a?.release();
+ * ```
+ */
+export declare class SfxArbiter {
+    private readonly maxVoices;
+    private readonly voices;
+    constructor(options?: {
+        maxVoices?: number;
+    });
+    get active(): number;
+    /**
+     * Asks for a slot. `stop` cuts the voice when a better one needs its place; `active` says
+     * whether it still sounds, so a voice that ended by itself frees its slot for any asker, not
+     * only for the sound that owned it.
+     */
+    request(priority: number, stop: () => void, active?: () => boolean): SfxGrant | null;
+}
+/**
+ * A reproducible seed for an effect: the same id on the same game frame (and the same ordinal
+ * within that frame) always gives the same number, so a replay or a lockstep peer hears exactly
+ * what the original run heard, and audio never perturbs the simulation.
+ *
+ * @example
+ * ```ts
+ * import { sfxSeed } from '@datamoc/mw_games/audio';
+ *
+ * sfxSeed('arrow', 120) === sfxSeed('arrow', 120); // true
+ * ```
+ */
+export declare function sfxSeed(id: string, frame: number, ordinal?: number): number;
+export interface SfxSoundOptions {
+    /** where an effect given by id is looked up */
+    bank?: SfxBank;
+    /** the shared voice limit; none means a voice is never cut for another */
+    arbiter?: SfxArbiter;
+    /** the game's own frame counter, never the wall clock, so seeds repeat across runs; 0 when omitted */
+    frame?: () => number;
+    /** shown with each play when the definition has no caption of its own */
+    caption?: string;
+    /** level, 0 to 1; 1 when omitted */
+    volume?: number;
+}
+/**
+ * The data-driven counterpart of `Sound`: it plays an `SfxDefinition` (or the id of one in a
+ * bank) through a backend, with the same `play(gain, pitch)` shape so a `SoundSource` can
+ * attenuate it, and a pan on top. It applies the definition's retrigger rule, asks the shared
+ * arbiter for a voice, fires the caption, and hands the backend a deterministic seed.
+ *
+ * @example
+ * ```ts
+ * import { SfxArbiter, SfxBank, SfxSound, SoundSource, AudioListener, type SfxBackend } from '@datamoc/mw_games/audio';
+ *
+ * declare const chip: SfxBackend;
+ *
+ * const bank = new SfxBank([{ id: 'arrow', priority: 5, caption: 'an arrow flies' }]);
+ * const arrow = new SfxSound(chip, 'arrow', { bank, arbiter: new SfxArbiter(), frame: () => 0 });
+ * new SoundSource(arrow, { x: 3, y: 4 }).playFor(new AudioListener());
+ * ```
+ */
+export declare class SfxSound {
+    volume: number;
+    /** how many plays reached the backend, for a test to assert on without a speaker */
+    plays: number;
+    private readonly backend;
+    private readonly definition;
+    private readonly options;
+    private readonly live;
+    private suspended_;
+    private lastFrame;
+    private ordinal;
+    constructor(backend: SfxBackend, effect: SfxDefinition | string, options?: SfxSoundOptions);
+    get isSuspended(): boolean;
+    /** voices that still sound */
+    get activeVoices(): number;
+    /** plays the effect; returns false when it was ignored, refused by the arbiter or the backend had no voice */
+    play(gain?: number, pitch?: number, pan?: number): boolean;
+    stopAll(): void;
+    suspend(): void;
+    resume(): void;
+    /** drops voices that finished by themselves, returning their arbiter slots */
+    private prune;
+}
+//# sourceMappingURL=Sfx.d.ts.map

package/dist/audio/Sfx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sfx.d.ts","sourceRoot":"","sources":["../../src/audio/Sfx.ts"],"names":[],"mappings":"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"}

package/dist/audio/Sfx.js

@@ -0,0 +1,213 @@
+import { onCaption } from './Captions.js';
+/** effects by id, so a sound can be made from an id the content named */
+export class SfxBank {
+    constructor(definitions = []) {
+        this.definitions = new Map();
+        for (const definition of definitions)
+            this.define(definition);
+    }
+    define(definition) {
+        if (!definition.id)
+            throw new Error('a sound effect needs an id');
+        this.definitions.set(definition.id, definition);
+    }
+    has(id) {
+        return this.definitions.has(id);
+    }
+    get(id) {
+        const definition = this.definitions.get(id);
+        if (!definition)
+            throw new Error(`no sound effect "${id}" in the bank`);
+        return definition;
+    }
+    ids() {
+        return [...this.definitions.keys()];
+    }
+}
+/**
+ * The shared voice limit between chip effects and the bus's `'se'` jingles: both ask here before
+ * they sound, and when the limit is reached the lowest-priority voice (the oldest among equals)
+ * is cut for a new one of equal or higher priority; a new one below everything sounding is
+ * refused. One arbiter handed to a bus and to every `SfxSound` makes them a single pool.
+ *
+ * @example
+ * ```ts
+ * import { SfxArbiter } from '@datamoc/mw_games/audio';
+ *
+ * const arbiter = new SfxArbiter({ maxVoices: 2 });
+ * const a = arbiter.request(1, () => console.log('a cut'));
+ * arbiter.request(1, () => console.log('b cut'));
+ * arbiter.request(5, () => console.log('c cut')); // cuts a, the oldest of the lowest priority
+ * a?.release();
+ * ```
+ */
+export class SfxArbiter {
+    constructor(options = {}) {
+        this.voices = [];
+        this.maxVoices = Math.max(1, Math.floor(options.maxVoices ?? 8));
+    }
+    get active() {
+        return this.voices.length;
+    }
+    /**
+     * Asks for a slot. `stop` cuts the voice when a better one needs its place; `active` says
+     * whether it still sounds, so a voice that ended by itself frees its slot for any asker, not
+     * only for the sound that owned it.
+     */
+    request(priority, stop, active = () => true) {
+        for (let i = this.voices.length - 1; i >= 0; i--)
+            if (!this.voices[i].active())
+                this.voices.splice(i, 1);
+        if (this.voices.length >= this.maxVoices) {
+            let victim = 0;
+            for (let i = 1; i < this.voices.length; i++) {
+                if (this.voices[i].priority < this.voices[victim].priority)
+                    victim = i;
+            }
+            if (this.voices[victim].priority > priority)
+                return null;
+            const [cut] = this.voices.splice(victim, 1);
+            cut.stop();
+        }
+        const entry = { priority, stop, active };
+        this.voices.push(entry);
+        return {
+            release: () => {
+                const at = this.voices.indexOf(entry);
+                if (at !== -1)
+                    this.voices.splice(at, 1);
+            },
+        };
+    }
+}
+/**
+ * A reproducible seed for an effect: the same id on the same game frame (and the same ordinal
+ * within that frame) always gives the same number, so a replay or a lockstep peer hears exactly
+ * what the original run heard, and audio never perturbs the simulation.
+ *
+ * @example
+ * ```ts
+ * import { sfxSeed } from '@datamoc/mw_games/audio';
+ *
+ * sfxSeed('arrow', 120) === sfxSeed('arrow', 120); // true
+ * ```
+ */
+export function sfxSeed(id, frame, ordinal = 0) {
+    let hash = 0x811c9dc5;
+    const mix = (value) => {
+        hash = Math.imul(hash ^ (value & 0xff), 0x01000193);
+        hash = Math.imul(hash ^ ((value >>> 8) & 0xff), 0x01000193);
+        hash = Math.imul(hash ^ ((value >>> 16) & 0xff), 0x01000193);
+        hash = Math.imul(hash ^ ((value >>> 24) & 0xff), 0x01000193);
+    };
+    for (let i = 0; i < id.length; i++)
+        mix(id.charCodeAt(i));
+    mix(Math.floor(frame));
+    mix(ordinal);
+    return hash >>> 0;
+}
+/**
+ * The data-driven counterpart of `Sound`: it plays an `SfxDefinition` (or the id of one in a
+ * bank) through a backend, with the same `play(gain, pitch)` shape so a `SoundSource` can
+ * attenuate it, and a pan on top. It applies the definition's retrigger rule, asks the shared
+ * arbiter for a voice, fires the caption, and hands the backend a deterministic seed.
+ *
+ * @example
+ * ```ts
+ * import { SfxArbiter, SfxBank, SfxSound, SoundSource, AudioListener, type SfxBackend } from '@datamoc/mw_games/audio';
+ *
+ * declare const chip: SfxBackend;
+ *
+ * const bank = new SfxBank([{ id: 'arrow', priority: 5, caption: 'an arrow flies' }]);
+ * const arrow = new SfxSound(chip, 'arrow', { bank, arbiter: new SfxArbiter(), frame: () => 0 });
+ * new SoundSource(arrow, { x: 3, y: 4 }).playFor(new AudioListener());
+ * ```
+ */
+export class SfxSound {
+    constructor(backend, effect, options = {}) {
+        /** how many plays reached the backend, for a test to assert on without a speaker */
+        this.plays = 0;
+        this.live = [];
+        this.suspended_ = false;
+        this.lastFrame = Number.NaN;
+        this.ordinal = 0;
+        this.backend = backend;
+        this.options = options;
+        this.volume = options.volume ?? 1;
+        if (typeof effect === 'string') {
+            if (!options.bank)
+                throw new Error(`a sound effect given by id ("${effect}") needs a bank`);
+            this.definition = options.bank.get(effect);
+        }
+        else {
+            this.definition = effect;
+        }
+    }
+    get isSuspended() {
+        return this.suspended_;
+    }
+    /** voices that still sound */
+    get activeVoices() {
+        this.prune();
+        return this.live.length;
+    }
+    /** plays the effect; returns false when it was ignored, refused by the arbiter or the backend had no voice */
+    play(gain = 1, pitch = 1, pan = 0) {
+        if (this.suspended_)
+            return false;
+        this.prune();
+        const rule = this.definition.retrigger ?? 'restart';
+        if (this.live.length > 0 && rule === 'ignore')
+            return false;
+        if (this.live.length > 0 && rule === 'restart')
+            this.stopAll();
+        const frame = this.options.frame?.() ?? 0;
+        this.ordinal = frame === this.lastFrame ? this.ordinal + 1 : 0;
+        this.lastFrame = frame;
+        let voice = null;
+        const grant = this.options.arbiter?.request(this.definition.priority ?? 0, () => {
+            voice?.stop();
+        }, () => voice?.active ?? true) ?? null;
+        if (this.options.arbiter && !grant)
+            return false;
+        voice = this.backend.play(this.definition, {
+            gain: Math.max(0, Math.min(1, gain * this.volume)),
+            pan: Math.max(-1, Math.min(1, pan)),
+            pitch,
+            seed: sfxSeed(this.definition.id, frame, this.ordinal),
+        });
+        if (!voice) {
+            grant?.release();
+            return false;
+        }
+        this.live.push({ voice, grant });
+        this.plays++;
+        const caption = this.definition.caption ?? this.options.caption;
+        if (caption)
+            onCaption.dispatch({ text: caption });
+        return true;
+    }
+    stopAll() {
+        for (const { voice, grant } of this.live.splice(0)) {
+            voice.stop();
+            grant?.release();
+        }
+    }
+    suspend() {
+        this.suspended_ = true;
+        this.stopAll();
+    }
+    resume() {
+        this.suspended_ = false;
+    }
+    /** drops voices that finished by themselves, returning their arbiter slots */
+    prune() {
+        for (let i = this.live.length - 1; i >= 0; i--) {
+            if (!this.live[i].voice.active) {
+                this.live[i].grant?.release();
+                this.live.splice(i, 1);
+            }
+        }
+    }
+}
+//# sourceMappingURL=Sfx.js.map

package/dist/audio/Sfx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sfx.js","sourceRoot":"","sources":["../../src/audio/Sfx.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AA4C1C,yEAAyE;AACzE,MAAM,OAAO,OAAO;IAGnB,YAAY,WAAW,GAA4B,EAAE;QAFpC,gBAAW,GAAG,IAAI,GAAG,EAAyB,CAAC;QAG/D,KAAK,MAAM,UAAU,IAAI,WAAW;YAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,CAAC,UAAyB;QAC/B,IAAI,CAAC,UAAU,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAClE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC;IAED,GAAG,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,GAAG,CAAC,EAAU;QACb,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC;QACxE,OAAO,UAAU,CAAC;IACnB,CAAC;IAED,GAAG;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;CACD;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,UAAU;IAItB,YAAY,OAAO,GAA2B,EAAE;QAF/B,WAAM,GAAoE,EAAE,CAAC;QAG7F,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,QAAgB,EAAE,IAAgB,EAAE,MAAM,GAAkB,GAAG,EAAE,CAAC,IAAI;QAC7E,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;YAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACzG,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC1C,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7C,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ;oBAAE,MAAM,GAAG,CAAC,CAAC;YACxE,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,GAAG,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACzD,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAC5C,GAAG,CAAC,IAAI,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,KAAK,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO;YACN,OAAO,EAAE,GAAG,EAAE;gBACb,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACtC,IAAI,EAAE,KAAK,CAAC,CAAC;oBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YAC1C,CAAC;SACD,CAAC;IACH,CAAC;CACD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAC,EAAU,EAAE,KAAa,EAAE,OAAO,GAAG,CAAC;IAC7D,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,MAAM,GAAG,GAAG,CAAC,KAAa,EAAQ,EAAE;QACnC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;QACpD,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;QAC5D,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;QAC7D,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;IAC9D,CAAC,CAAC;IACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IACvB,GAAG,CAAC,OAAO,CAAC,CAAC;IACb,OAAO,IAAI,KAAK,CAAC,CAAC;AACnB,CAAC;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,QAAQ;IAapB,YAAY,OAAmB,EAAE,MAA8B,EAAE,OAAO,GAAoB,EAAE;QAX9F,oFAAoF;QACpF,UAAK,GAAG,CAAC,CAAC;QAKO,SAAI,GAAkD,EAAE,CAAC;QAClE,eAAU,GAAG,KAAK,CAAC;QACnB,cAAS,GAAG,MAAM,CAAC,GAAG,CAAC;QACvB,YAAO,GAAG,CAAC,CAAC;QAGnB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAChC,IAAI,CAAC,OAAO,CAAC,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,MAAM,iBAAiB,CAAC,CAAC;YAC5F,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC;QAC1B,CAAC;IACF,CAAC;IAED,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;IAED,8BAA8B;IAC9B,IAAI,YAAY;QACf,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IACzB,CAAC;IAED,8GAA8G;IAC9G,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC;QAChC,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,IAAI,SAAS,CAAC;QACpD,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5D,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAE/D,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,GAAG,KAAK,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/D,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QAEvB,IAAI,KAAK,GAAoB,IAAI,CAAC;QAClC,MAAM,KAAK,GACV,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAC5B,IAAI,CAAC,UAAU,CAAC,QAAQ,IAAI,CAAC,EAC7B,GAAG,EAAE;YACJ,KAAK,EAAE,IAAI,EAAE,CAAC;QACf,CAAC,EACD,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,IAAI,CAC3B,IAAI,IAAI,CAAC;QACX,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACjD,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE;YAC1C,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;YAClD,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YACnC,KAAK;YACL,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;SACtD,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,KAAK,EAAE,OAAO,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACd,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;QAChE,IAAI,OAAO;YAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,OAAO;QACN,KAAK,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,KAAK,CAAC,IAAI,EAAE,CAAC;YACb,KAAK,EAAE,OAAO,EAAE,CAAC;QAClB,CAAC;IACF,CAAC;IAED,OAAO;QACN,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;IAED,MAAM;QACL,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IACzB,CAAC;IAED,8EAA8E;IACtE,KAAK;QACZ,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;gBAChC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;gBAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACxB,CAAC;QACF,CAAC;IACF,CAAC;CACD"}

package/dist/audio/SpectralDistance.d.ts

@@ -0,0 +1,34 @@
+import { type StereoFrames } from './Resample.ts';
+export interface SpectralDistanceOptions {
+    /** analysis window in frames, a power of two; 2048 when omitted */
+    windowSize?: number;
+    /** frames between windows; half the window when omitted */
+    hop?: number;
+    /** bins quieter than this many dB below the loudest are ignored as noise floor; 80 when omitted */
+    floorDb?: number;
+}
+export interface SpectralDistanceResult {
+    /** mean absolute difference of the log spectra in decibels: 0 for identical audio, a few dB for the same timbre played slightly differently */
+    decibels: number;
+    /** windows compared */
+    windows: number;
+}
+/**
+ * How far apart two renders sound, as the mean absolute difference of their log spectra: the
+ * number to watch when one synthesis engine is tuned toward another's reference, or when a change
+ * must not alter a render. Both are folded to mono and brought to the first one's sample rate; the
+ * shorter is padded with silence. Bins more than `floorDb` below the loudest of the pair do not
+ * count, so inaudible noise cannot dominate the figure.
+ *
+ * @example
+ * ```ts
+ * import { spectralDistance } from '@datamoc/mw_games/audio';
+ *
+ * declare const reference: { sampleRate: number; left: Float32Array; right: Float32Array };
+ * declare const candidate: { sampleRate: number; left: Float32Array; right: Float32Array };
+ *
+ * console.log(spectralDistance(reference, candidate).decibels);
+ * ```
+ */
+export declare function spectralDistance(a: StereoFrames, b: StereoFrames, options?: SpectralDistanceOptions): SpectralDistanceResult;
+//# sourceMappingURL=SpectralDistance.d.ts.map

package/dist/audio/SpectralDistance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpectralDistance.d.ts","sourceRoot":"","sources":["../../src/audio/SpectralDistance.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAElE,MAAM,WAAW,uBAAuB;IACvC,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mGAAmG;IACnG,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACtC,+IAA+I;IAC/I,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;CAChB;AAgBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC/B,CAAC,EAAE,YAAY,EACf,CAAC,EAAE,YAAY,EACf,OAAO,GAAE,uBAA4B,GACnC,sBAAsB,CA0BxB"}

package/dist/audio/SpectralDistance.js

@@ -0,0 +1,64 @@
+import { fft } from './Fft.js';
+import { resampleStereo } from './Resample.js';
+/** the Hann-windowed magnitude spectrum, in dB, of one mono window starting at `start` (zero padded past the end) */
+function logSpectrum(samples, start, size) {
+    const re = new Float64Array(size);
+    const im = new Float64Array(size);
+    for (let i = 0; i < size; i++) {
+        const sample = start + i < samples.length ? samples[start + i] : 0;
+        re[i] = sample * (0.5 - 0.5 * Math.cos((2 * Math.PI * i) / (size - 1)));
+    }
+    fft(re, im);
+    const bins = new Float64Array(size / 2);
+    for (let k = 0; k < bins.length; k++)
+        bins[k] = 20 * Math.log10(Math.hypot(re[k], im[k]) + 1e-12);
+    return bins;
+}
+/**
+ * How far apart two renders sound, as the mean absolute difference of their log spectra: the
+ * number to watch when one synthesis engine is tuned toward another's reference, or when a change
+ * must not alter a render. Both are folded to mono and brought to the first one's sample rate; the
+ * shorter is padded with silence. Bins more than `floorDb` below the loudest of the pair do not
+ * count, so inaudible noise cannot dominate the figure.
+ *
+ * @example
+ * ```ts
+ * import { spectralDistance } from '@datamoc/mw_games/audio';
+ *
+ * declare const reference: { sampleRate: number; left: Float32Array; right: Float32Array };
+ * declare const candidate: { sampleRate: number; left: Float32Array; right: Float32Array };
+ *
+ * console.log(spectralDistance(reference, candidate).decibels);
+ * ```
+ */
+export function spectralDistance(a, b, options = {}) {
+    const size = options.windowSize ?? 2048;
+    if (size < 4 || (size & (size - 1)) !== 0)
+        throw new Error('window size must be a power of two of at least 4');
+    const hop = Math.max(1, Math.floor(options.hop ?? size / 2));
+    const floor = options.floorDb ?? 80;
+    const matched = resampleStereo(b, a.sampleRate);
+    const mono = (frames) => frames.left.map((value, i) => (value + frames.right[i]) / 2);
+    const first = mono(a);
+    const second = mono(matched);
+    const length = Math.max(first.length, second.length);
+    let total = 0;
+    let counted = 0;
+    let windows = 0;
+    for (let start = 0; start === 0 || start + size / 2 < length; start += hop) {
+        const x = logSpectrum(first, start, size);
+        const y = logSpectrum(second, start, size);
+        let peak = -Infinity;
+        for (let k = 0; k < x.length; k++)
+            peak = Math.max(peak, x[k], y[k]);
+        for (let k = 0; k < x.length; k++) {
+            if (Math.max(x[k], y[k]) < peak - floor)
+                continue;
+            total += Math.abs(x[k] - y[k]);
+            counted++;
+        }
+        windows++;
+    }
+    return { decibels: counted === 0 ? 0 : total / counted, windows };
+}
+//# sourceMappingURL=SpectralDistance.js.map

package/dist/audio/SpectralDistance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpectralDistance.js","sourceRoot":"","sources":["../../src/audio/SpectralDistance.ts"],"names":[],"mappings":"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"}

package/dist/audio/StreamChannel.d.ts

@@ -0,0 +1,150 @@
+import { Signal } from '../core/Signal.ts';
+import type { LoopRegion } from './Channels.ts';
+/**
+ * Audio that is produced as it is played instead of decoded up front: a tracker, a chip
+ * player, a synthesiser. The consumer pulls frames in order; it can also ask for a different
+ * position, which a stateful source answers by skipping or rewinding as it can.
+ */
+export interface BlockSource {
+    readonly sampleRate: number;
+    /** total frames, or undefined for a source with no end (a chip tune that never finishes) */
+    readonly length?: number;
+    /** writes up to `count` frames at `start` of both buffers and returns how many it wrote; fewer than asked means the source ended */
+    read(left: Float32Array, right: Float32Array, start: number, count: number): number;
+    /** makes the next `read` return frames from this position */
+    seek(frame: number): void;
+}
+export interface StreamChannelOptions {
+    /** seconds of audio per scheduled chunk; 0.5 when omitted */
+    chunkSeconds?: number;
+    /** how far ahead of the clock chunks are queued; 2 seconds when omitted, enough to ride out a throttled background timer */
+    lookaheadSeconds?: number;
+    /** milliseconds between self-driven pumps; 100 when omitted, 0 to turn the timer off and call `update()` yourself */
+    pumpMs?: number;
+    /** replaces `setTimeout` for the pump, so a test drives time by hand */
+    schedule?: (callback: () => void, ms: number) => unknown;
+    /** cancels what `schedule` returned; `clearTimeout` when omitted */
+    unschedule?: (handle: unknown) => void;
+}
+export interface StreamPlayOptions {
+    /** level, 0 to 1 */
+    volume?: number;
+    /** playback ratio, 1 unchanged: speed and pitch together, resampled linearly */
+    pitch?: number;
+    /** stereo position, -1 (left) to 1 (right) */
+    pan?: number;
+    /** start offset in seconds */
+    pos?: number;
+    /** true repeats through `loop`, or the whole source when it has a length; false plays once */
+    repeat?: boolean;
+    /** seconds the repeat jumps back to and wraps from; the whole source when omitted */
+    loop?: LoopRegion | null;
+    /** stop after this many seconds played, for a source with no end; unlimited when omitted */
+    endAfterSeconds?: number;
+    /** seconds of fade ahead of `endAfterSeconds`'s end; 2 when omitted */
+    endFadeSeconds?: number;
+}
+/**
+ * The streaming twin of `Channel`: it queues short buffers on the audio clock ahead of the
+ * playhead from a `BlockSource` instead of owning one decoded buffer, so a long or endless
+ * track costs a couple of seconds of memory rather than the whole render. It loops on a
+ * region, seeks, retunes volume, pitch and pan, fades an endless source out after a limit, and
+ * reports `onUnderrun` when the clock got ahead of what was queued.
+ *
+ * Chunks are queued by a timer it runs itself (`pumpMs`), so a game that never calls `update()`
+ * still hears sound; a timer throttled in a background tab is the reason the lookahead is two
+ * seconds. A pitch change applies from the next chunk, up to the lookahead later.
+ *
+ * @example
+ * ```ts
+ * import { StreamChannel, type BlockSource } from '@datamoc/mw_games/audio';
+ *
+ * declare const context: AudioContext;
+ * declare const tune: BlockSource;
+ *
+ * const channel = new StreamChannel(context);
+ * channel.onEnded.add(() => console.log('done'));
+ * channel.play(tune, { repeat: false, volume: 0.8 });
+ * console.log(channel.position());
+ * channel.stop(1);
+ * ```
+ */
+export declare class StreamChannel {
+    /** fires once when a source that does not repeat has played out, or an endless one reached its limit */
+    readonly onEnded: Signal<void>;
+    /** fires when the clock passed the end of the queue before the next chunk was ready, with how late it was in seconds */
+    readonly onUnderrun: Signal<number>;
+    /** fires when the source threw while being read: the voice stops instead of letting the error escape from a timer */
+    readonly onError: Signal<Error>;
+    private readonly context;
+    private readonly destination;
+    private readonly chunkSeconds;
+    private readonly lookahead;
+    private readonly pumpMs;
+    private readonly schedule;
+    private readonly unschedule;
+    private timer;
+    private source;
+    private gainNode;
+    private pannerNode;
+    private params;
+    private repeat;
+    private loopStart;
+    private loopEnd;
+    private endAfterFrames;
+    private endFadeFrames;
+    private chunks;
+    private nextWhen;
+    private active;
+    private drained;
+    private lastTimeline;
+    private outputFrames;
+    private underruns;
+    private pendingLeft;
+    private pendingRight;
+    private pendingLength;
+    private cursor;
+    private readFrame;
+    private timeline;
+    private sourceEnded;
+    constructor(context: AudioContext, destination?: AudioNode, options?: StreamChannelOptions);
+    get isPlaying(): boolean;
+    /** how many times the queue ran dry since the channel was made */
+    get underrunCount(): number;
+    /** seconds of the source, or Infinity when it has no end */
+    get duration(): number;
+    /** starts the source with these parameters, stopping whatever played before */
+    play(source: BlockSource, options?: StreamPlayOptions): void;
+    /** retunes the playing voice in place: no restart, no seek */
+    update(params?: {
+        volume?: number;
+        pitch?: number;
+        pan?: number;
+    }): void;
+    /** stops the voice, fading out over `fadeSeconds` first when positive; the playhead is remembered for a later `play` with the same `pos` */
+    stop(fadeSeconds?: number): void;
+    /** seconds into the source, wrapping inside the loop region while it repeats */
+    position(): number;
+    /** the playhead as a source frame, the exact unit a save stores and a restore skips to */
+    positionFrames(): number;
+    /** moves the playhead, restarting the queue from there */
+    seek(seconds: number): void;
+    /** queues whatever chunks the lookahead allows; called by the timer and safe to call each frame */
+    pump(): void;
+    private wire;
+    private cancelTimer;
+    private begin;
+    /** a position inside the loop region while repeating, else as given */
+    private timelineAt;
+    private queueChunk;
+    /** marks the stream as fully queued; the ending fires when the last chunk has sounded */
+    private finish;
+    /** resamples source frames into the two output arrays; returns how many it wrote */
+    private fill;
+    /** appends the next block of source frames, wrapping to the loop start at its end */
+    private readMore;
+    private ensureCapacity;
+    /** drops consumed frames so the buffer does not grow with the length of the track */
+    private compact;
+}
+//# sourceMappingURL=StreamChannel.d.ts.map

package/dist/audio/StreamChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamChannel.d.ts","sourceRoot":"","sources":["../../src/audio/StreamChannel.ts"],"names":[],"mappings":"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"}