@datamoc/mw_games 0.41.0 → 0.43.0

package/dist/audio/MusicPlayer.js

@@ -0,0 +1,147 @@
+import { Signal } from '../core/Signal.js';
+import { Channel } from './Channels.js';
+import { toAudioBuffer } from './MidiRender.js';
+/**
+ * One music track at a time with the controls a game's jukebox needs: load a decoded track or a
+ * rendered MIDI file, play, pause, resume, read the position, seek, and be told when the track
+ * ends so the game can pick the next one. It wraps a `Channel`, so the buffer, the loop region
+ * and the playhead behave as they do there; what it adds is the paused state and the end of the
+ * track. Like `Music`, nothing advances on its own: call `update()` each frame.
+ *
+ * @example
+ * ```ts
+ * import { MusicPlayer, renderMidiToBufferAsync } from '@datamoc/mw_games/audio';
+ *
+ * declare const context: AudioContext;
+ * declare const midiBytes: ArrayBuffer;
+ * declare function nextTrack(): Promise<ArrayBuffer>;
+ *
+ * const player = new MusicPlayer(context, { volume: 0.8 });
+ * player.load(await renderMidiToBufferAsync(midiBytes));
+ * player.play();
+ * async function playNext(): Promise<void> {
+ * 	player.load(await renderMidiToBufferAsync(await nextTrack()));
+ * 	player.play();
+ * }
+ * player.onEnded.add(() => { void playNext(); });
+ *
+ * // in the scene's update:
+ * player.update();
+ * ```
+ */
+export class MusicPlayer {
+    constructor(context, options = {}) {
+        /** fires once when a track that was not repeating plays through to its end */
+        this.onEnded = new Signal();
+        this.buffer = null;
+        this.loop = null;
+        this.repeat = false;
+        this.playing = false;
+        this.paused = false;
+        this.resumeAt = 0;
+        this.context = context;
+        this.channel = new Channel(context, options.destination);
+        this.volume_ = Math.min(1, Math.max(0, options.volume ?? 1));
+    }
+    /** stops what plays and makes this track the one to play; a rendered MIDI file is copied into a buffer first */
+    load(track) {
+        this.stop();
+        if ('left' in track) {
+            this.buffer = toAudioBuffer(this.context, track);
+            this.loop = { start: track.loopStart, end: track.loopEnd };
+        }
+        else {
+            this.buffer = track;
+            this.loop = null;
+        }
+    }
+    /** plays the loaded track from the start, or from `pos` */
+    play(options = {}) {
+        if (!this.buffer)
+            return;
+        this.repeat = options.repeat ?? false;
+        this.paused = false;
+        this.playing = true;
+        this.resumeAt = options.pos ?? 0;
+        this.start();
+    }
+    pause() {
+        if (!this.playing || this.paused)
+            return;
+        this.resumeAt = this.channel.position();
+        this.paused = true;
+        this.channel.stop();
+    }
+    resume() {
+        if (!this.paused || !this.buffer)
+            return;
+        this.paused = false;
+        this.start();
+    }
+    /** pauses a playing track and resumes a paused one */
+    togglePause() {
+        if (this.paused)
+            this.resume();
+        else
+            this.pause();
+    }
+    /** stops and forgets the position; `play()` starts over */
+    stop() {
+        this.channel.stop();
+        this.playing = false;
+        this.paused = false;
+        this.resumeAt = 0;
+    }
+    get isPlaying() {
+        return this.playing && !this.paused;
+    }
+    get isPaused() {
+        return this.paused;
+    }
+    /** seconds of the loaded track */
+    get duration() {
+        return this.buffer?.duration ?? 0;
+    }
+    /** seconds into the track, held while paused */
+    position() {
+        if (!this.playing)
+            return 0;
+        return this.paused ? this.resumeAt : this.channel.position();
+    }
+    /** moves the playhead, keeping a paused track paused */
+    seek(pos) {
+        if (!this.buffer)
+            return;
+        const target = Math.min(Math.max(0, pos), this.buffer.duration);
+        if (this.paused)
+            this.resumeAt = target;
+        else if (this.playing)
+            this.play({ pos: target, repeat: this.repeat });
+    }
+    get volume() {
+        return this.volume_;
+    }
+    set volume(level) {
+        this.volume_ = Math.min(1, Math.max(0, level));
+        this.channel.update({ volume: this.volume_ });
+    }
+    /** call each frame: fires `onEnded` once when a non-repeating track has finished */
+    update() {
+        if (!this.playing || this.paused || this.channel.isPlaying)
+            return;
+        this.playing = false;
+        this.resumeAt = 0;
+        this.onEnded.dispatch();
+    }
+    start() {
+        if (!this.buffer)
+            return;
+        this.channel.play(this.buffer, {
+            volume: this.volume_,
+            pos: this.resumeAt,
+            loop: this.loop,
+            repeat: this.repeat,
+        });
+    }
+}
+//# sourceMappingURL=MusicPlayer.js.map

package/dist/audio/MusicPlayer.js.map

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

package/dist/audio/SampleDecoder.d.ts

@@ -21,11 +21,25 @@ export interface SampleDecodingContext {
 export declare const MIN_SAMPLE_RATE = 400;
 export declare const MAX_SAMPLE_RATE = 200000;
 export declare const MAX_SAMPLE_FRAMES: number;
+/**
+ * How much a SoundFont 3 may decode to, in frames. The defaults (`MAX_SAMPLE_FRAMES` for one sample, 128
+ * million, 256 MB of 16-bit audio, for the whole font) suit a game font; raise them for a very large one
+ * you trust, since each frame is two bytes of memory and a damaged font can ask for any number.
+ */
+export interface SoundFontLimits {
+    /** frames one decoded sample may have */
+    sampleFrames?: number;
+    /** frames all the decoded samples of one font may have */
+    totalFrames?: number;
+}
+/** the whole-font default of {@link SoundFontLimits} */
+export declare const MAX_TOTAL_FRAMES: number;
 /**
  * A decoder over WebAudio's `decodeAudioData`, for a browser: each sample decodes in a context
  * created at the sample's own rate, so the browser does not resample it and the loop points keep
  * meaning what the font wrote. A rate outside what a context accepts (8 to 96 kHz) decodes at
- * the nearest accepted rate and is resampled back. `create` replaces the context factory.
+ * the nearest accepted rate and is resampled back. `create` replaces the context factory and `limits`
+ * the longest sample it will return.
  *
  * @example
  * ```ts
@@ -37,5 +51,5 @@ export declare const MAX_SAMPLE_FRAMES: number;
  * console.log(font.presetCount);
  * ```
  */
-export declare function webAudioSampleDecoder(create?: (rate: number) => SampleDecodingContext): SoundFontSampleDecoder;
+export declare function webAudioSampleDecoder(create?: (rate: number) => SampleDecodingContext, limits?: SoundFontLimits): SoundFontSampleDecoder;
 //# sourceMappingURL=SampleDecoder.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"SampleDecoder.d.ts","sourceRoot":"","sources":["../../src/audio/SampleDecoder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzG,yFAAyF;AACzF,MAAM,WAAW,qBAAqB;IACrC,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;QAC3C,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAAC;KAC9C,CAAC,CAAC;CACH;AAMD;;;;GAIG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,eAAe,SAAS,CAAC;AACtC,eAAO,MAAM,iBAAiB,QAAU,CAAC;AA+BzC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,qBAAsC,GAC9D,sBAAsB,CAcxB"}
+{"version":3,"file":"SampleDecoder.d.ts","sourceRoot":"","sources":["../../src/audio/SampleDecoder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzG,yFAAyF;AACzF,MAAM,WAAW,qBAAqB;IACrC,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;QAC3C,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAAC;KAC9C,CAAC,CAAC;CACH;AAMD;;;;GAIG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,eAAe,SAAS,CAAC;AACtC,eAAO,MAAM,iBAAiB,QAAU,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,QAAU,CAAC;AA+BxC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,qBAAsC,EAChE,MAAM,GAAE,eAAoB,GAC1B,sBAAsB,CAcxB"}

package/dist/audio/SampleDecoder.js

@@ -9,6 +9,8 @@ const MAX_RATE = 96000;
 export const MIN_SAMPLE_RATE = 400;
 export const MAX_SAMPLE_RATE = 200000;
 export const MAX_SAMPLE_FRAMES = 1 << 24;
+/** the whole-font default of {@link SoundFontLimits} */
+export const MAX_TOTAL_FRAMES = 1 << 27;
 function toInt16(frames) {
     const out = new Int16Array(frames.length);
     for (let index = 0; index < frames.length; index++) {
@@ -17,9 +19,9 @@ function toInt16(frames) {
     return out;
 }
 /** linear resampling, only for the rare sample whose rate a context cannot be created at */
-function resample(frames, from, to) {
+function resample(frames, from, to, maxFrames) {
     const length = Math.max(1, Math.round((frames.length * to) / from));
-    if (length > MAX_SAMPLE_FRAMES)
+    if (length > maxFrames)
         throw new Error('a decoded sample is longer than a SoundFont sample may be');
     const out = new Float32Array(length);
     for (let index = 0; index < out.length; index++) {
@@ -40,7 +42,8 @@ function offlineContext(rate) {
  * A decoder over WebAudio's `decodeAudioData`, for a browser: each sample decodes in a context
  * created at the sample's own rate, so the browser does not resample it and the loop points keep
  * meaning what the font wrote. A rate outside what a context accepts (8 to 96 kHz) decodes at
- * the nearest accepted rate and is resampled back. `create` replaces the context factory.
+ * the nearest accepted rate and is resampled back. `create` replaces the context factory and `limits`
+ * the longest sample it will return.
  *
  * @example
  * ```ts
@@ -52,7 +55,8 @@ function offlineContext(rate) {
  * console.log(font.presetCount);
  * ```
  */
-export function webAudioSampleDecoder(create = offlineContext) {
+export function webAudioSampleDecoder(create = offlineContext, limits = {}) {
+    const maxFrames = limits.sampleFrames ?? MAX_SAMPLE_FRAMES;
     return async (ogg, rate) => {
         if (!(rate >= MIN_SAMPLE_RATE && rate <= MAX_SAMPLE_RATE)) {
             throw new Error(`a sample rate of ${rate} Hz is not one a SoundFont can state`);
@@ -61,10 +65,10 @@ export function webAudioSampleDecoder(create = offlineContext) {
         //decodeAudioData detaches what it is given, and `ogg` is a view into the caller's font
         const copy = ogg.slice().buffer;
         const decoded = await create(contextRate).decodeAudioData(copy);
-        if (decoded.length > MAX_SAMPLE_FRAMES)
+        if (decoded.length > maxFrames)
             throw new Error('a decoded sample is longer than a SoundFont sample may be');
         const channel = decoded.getChannelData(0);
-        return toInt16(decoded.sampleRate === rate ? channel : resample(channel, decoded.sampleRate, rate));
+        return toInt16(decoded.sampleRate === rate ? channel : resample(channel, decoded.sampleRate, rate, maxFrames));
     };
 }
 //# sourceMappingURL=SampleDecoder.js.map

package/dist/audio/SampleDecoder.js.map

@@ -1 +1 @@
-{"version":3,"file":"SampleDecoder.js","sourceRoot":"","sources":["../../src/audio/SampleDecoder.ts"],"names":[],"mappings":"AAiBA,4EAA4E;AAC5E,MAAM,QAAQ,GAAG,IAAI,CAAC;AACtB,MAAM,QAAQ,GAAG,KAAK,CAAC;AAEvB;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AACnC,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AACtC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,CAAC;AAEzC,SAAS,OAAO,CAAC,MAAoB;IACpC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACpD,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,4FAA4F;AAC5F,SAAS,QAAQ,CAAC,MAAoB,EAAE,IAAY,EAAE,EAAU;IAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACpE,IAAI,MAAM,GAAG,iBAAiB;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC7G,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IACrC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,EAAE,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACnD,GAAG,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IACnC,IAAI,OAAO,mBAAmB,KAAK,WAAW,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,IAAI,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CACpC,MAAM,GAA4C,cAAc;IAEhE,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC1B,IAAI,CAAC,CAAC,IAAI,IAAI,eAAe,IAAI,IAAI,IAAI,eAAe,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,sCAAsC,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QACjE,uFAAuF;QACvF,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,MAAqB,CAAC;QAC/C,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAChE,IAAI,OAAO,CAAC,MAAM,GAAG,iBAAiB;YACrC,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC9E,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;QAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;IACrG,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"SampleDecoder.js","sourceRoot":"","sources":["../../src/audio/SampleDecoder.ts"],"names":[],"mappings":"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"}

package/dist/audio/Sound.d.ts

@@ -28,6 +28,8 @@ export declare class Sound {
     private caption?;
     private suspended_;
     volume: number;
+    /** how many times `play` actually started a clip (not counting calls made while suspended), for a test to assert on without a microphone */
+    plays: number;
     constructor(path: string, options?: SoundOptions);
     /**
      * Plays one instance from the pool.

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

@@ -1 +1 @@
-{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEpC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAMnD;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,SAAI,EAAE,KAAK,SAAI,GAAG,IAAI,CAc9B;IAED,OAAO,IAAI,IAAI,CAKd;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI,CAGd;IAED,wCAAwC;IACxC,MAAM,IAAI,IAAI,CAEb;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;CACD"}
+{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEpC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,4IAA4I;IAC5I,KAAK,SAAK;IAEV,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAMnD;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,SAAI,EAAE,KAAK,SAAI,GAAG,IAAI,CAe9B;IAED,OAAO,IAAI,IAAI,CAKd;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI,CAGd;IAED,wCAAwC;IACxC,MAAM,IAAI,IAAI,CAEb;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;CACD"}

package/dist/audio/Sound.js

@@ -18,6 +18,8 @@ export class Sound {
     constructor(path, options = {}) {
         this.next = 0;
         this.suspended_ = false;
+        /** how many times `play` actually started a clip (not counting calls made while suspended), for a test to assert on without a microphone */
+        this.plays = 0;
         const size = Math.max(1, options.poolSize ?? 4);
         const create = options.create ?? createAudio;
         this.volume = options.volume ?? 1;
@@ -39,6 +41,7 @@ export class Sound {
     play(gain = 1, pitch = 1) {
         if (this.suspended_)
             return;
+        this.plays++;
         const audio = this.pool[this.next];
         this.next = (this.next + 1) % this.pool.length;
         audio.volume = this.volume * gain;

package/dist/audio/Sound.js.map

@@ -1 +1 @@
-{"version":3,"file":"Sound.js","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAc1C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,KAAK;IAOjB,YAAY,IAAY,EAAE,OAAO,GAAiB,EAAE;QAL5C,SAAI,GAAG,CAAC,CAAC;QAET,eAAU,GAAG,KAAK,CAAC;QAI1B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,WAAW,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC;QACvB,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAE/C,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QAClC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC;QAC3B,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACtB,mFAAmF;QACnF,qFAAqF;QACrF,wFAAwF;QACxF,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEnD,IAAI,IAAI,CAAC,OAAO;YAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACN,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,OAAO;QACN,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;IAED,wCAAwC;IACxC,MAAM;QACL,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IACzB,CAAC;IAED,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;CACD"}
+{"version":3,"file":"Sound.js","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAc1C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,KAAK;IASjB,YAAY,IAAY,EAAE,OAAO,GAAiB,EAAE;QAP5C,SAAI,GAAG,CAAC,CAAC;QAET,eAAU,GAAG,KAAK,CAAC;QAE3B,4IAA4I;QAC5I,UAAK,GAAG,CAAC,CAAC;QAGT,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,WAAW,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC;QACvB,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAE/C,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QAClC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC;QAC3B,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACtB,mFAAmF;QACnF,qFAAqF;QACrF,wFAAwF;QACxF,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEnD,IAAI,IAAI,CAAC,OAAO;YAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACN,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,OAAO;QACN,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;IAED,wCAAwC;IACxC,MAAM;QACL,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IACzB,CAAC;IAED,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;CACD"}

package/dist/audio/SoundFont.d.ts

@@ -1,5 +1,5 @@
 import { type MidiFile } from './Midi.ts';
-import type { SoundFontSampleDecoder } from './SampleDecoder.ts';
+import type { SoundFontLimits, SoundFontSampleDecoder } from './SampleDecoder.ts';
 /** one mono sample: raw frames plus its loop region in frames and native rate */
 export interface SoundFontSample {
     data: Float32Array;
@@ -40,6 +40,18 @@ export interface SoundFontProgram {
     bank: number;
     program: number;
 }
+/**
+ * What plays for a (bank, program) the font does not carry. A bank missing the program falls back to
+ * bank 0 and a missing drum kit to the standard kit (never to a melodic preset) whatever the policy; past that, `'piano'` (the
+ * default, how most players behave) voices the font's own preset 0:0, and `'synth'` voices nothing, so
+ * the renderer's built-in synthesizer plays the instrument instead. A game with a trimmed bank picks
+ * `'synth'` to hear the synthesizer's timbre for an instrument it did not ship rather than a piano line.
+ */
+export type MissingProgram = 'piano' | 'synth';
+export interface SoundFontOptions {
+    /** what plays for a program the font lacks; `'piano'` when omitted */
+    missingProgram?: MissingProgram;
+}
 /**
  * Reads SoundFont 2 bytes into layered preset voices.
  *
@@ -55,7 +67,7 @@ export interface SoundFontProgram {
  * console.log(font.presetCount, rendered.duration);
  * ```
  */
-export declare function parseSoundFont(data: ArrayBuffer | ArrayBufferView): SoundFont;
+export declare function parseSoundFont(data: ArrayBuffer | ArrayBufferView, options?: SoundFontOptions): SoundFont;
 /**
  * Every sampled voice the given MIDI files can request, as (bank, program) pairs:
  * the channel voice in effect at each scheduled note, with drums mapped to bank 128
@@ -73,6 +85,27 @@ export declare function parseSoundFont(data: ArrayBuffer | ArrayBufferView): Sou
  * ```
  */
 export declare function collectSoundFontUsage(files: readonly MidiFile[]): SoundFontProgram[];
+/**
+ * The programs of `usage` the font does not carry, so a game can tell at build time which of the
+ * instruments its MIDI files ask for would be missing. A bank without the program counts as carried
+ * when bank 0 has it (the fallback every player makes), a drum kit only when the font has that exact
+ * kit. What plays for a missing one is the `missingProgram` policy of `parseSoundFont`. Works on a
+ * SoundFont 2 or 3.
+ *
+ * @example
+ * ```ts
+ * import { missingSoundFontPrograms, parseMidi, collectSoundFontUsage } from '@datamoc/mw_games/audio';
+ *
+ * declare const soundfontBytes: ArrayBuffer;
+ * declare const midiBytes: ArrayBuffer;
+ *
+ * const usage = collectSoundFontUsage([parseMidi(midiBytes)]);
+ * for (const { bank, program } of missingSoundFontPrograms(soundfontBytes, usage)) {
+ * 	console.log(`bank ${bank} program ${program} is not in the font`);
+ * }
+ * ```
+ */
+export declare function missingSoundFontPrograms(data: ArrayBuffer | ArrayBufferView, usage: readonly SoundFontProgram[]): SoundFontProgram[];
 /**
  * Joins several SoundFont 2 files into one, presets in the order given. When two files
  * carry the same (bank, program) the first wins and the other's preset, instruments
@@ -98,7 +131,8 @@ export declare function mergeSoundFonts(fonts: readonly (ArrayBuffer | ArrayBuff
  * the sample chunk, and the loop points a SoundFont 3 states relative to its sample become the
  * absolute ones SoundFont 2 uses. A SoundFont 2 comes back unchanged and `decode` is never called.
  * The result feeds everything that takes SoundFont 2 bytes, `renderMidiToBufferAsync` included.
- * A loop that ends past the decoded frames is cut to them.
+ * A loop that ends past the decoded frames is cut to them. `limits` raises or lowers what a sample and
+ * the whole font may decode to (see `SoundFontLimits`).
  *
  * @example
  * ```ts
@@ -110,7 +144,7 @@ export declare function mergeSoundFonts(fonts: readonly (ArrayBuffer | ArrayBuff
  * console.log(sf2.byteLength);
  * ```
  */
-export declare function decodeSoundFont(data: ArrayBuffer | ArrayBufferView, decode: SoundFontSampleDecoder): Promise<ArrayBuffer>;
+export declare function decodeSoundFont(data: ArrayBuffer | ArrayBufferView, decode: SoundFontSampleDecoder, limits?: SoundFontLimits): Promise<ArrayBuffer>;
 /**
  * Reads a SoundFont 2 or 3 into layered preset voices: `parseSoundFont` for a plain font, and a
  * SoundFont 3 decoded first through `decode`, `webAudioSampleDecoder()` (the browser) unless one
@@ -128,8 +162,9 @@ export declare function decodeSoundFont(data: ArrayBuffer | ArrayBufferView, dec
  * console.log(rendered.duration);
  * ```
  */
-export declare function loadSoundFont(data: ArrayBuffer | ArrayBufferView, options?: {
+export declare function loadSoundFont(data: ArrayBuffer | ArrayBufferView, options?: SoundFontOptions & {
     decode?: SoundFontSampleDecoder;
+    limits?: SoundFontLimits;
 }): Promise<SoundFont>;
 /**
  * Writes a smaller, valid SoundFont 2 file carrying only the used programs: their

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

@@ -1 +1 @@
-{"version":3,"file":"SoundFont.d.ts","sourceRoot":"","sources":["../../src/audio/SoundFont.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAwCjE,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;IACvF,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAuND;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,SAAS,CAuG7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,gBAAgB,EAAE,CAcpF;AA6CD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,CAAC,WAAW,GAAG,eAAe,CAAC,EAAE,GAAG,WAAW,CA+F9F;AAkBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CACpC,IAAI,EAAE,WAAW,GAAG,eAAe,EACnC,MAAM,EAAE,sBAAsB,GAC5B,OAAO,CAAC,WAAW,CAAC,CAyDtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAClC,IAAI,EAAE,WAAW,GAAG,eAAe,EACnC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,sBAAsB,CAAA;CAAO,GAC/C,OAAO,CAAC,SAAS,CAAC,CAEpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,EAAE,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,WAAW,CAmBpH"}
+{"version":3,"file":"SoundFont.d.ts","sourceRoot":"","sources":["../../src/audio/SoundFont.ts"],"names":[],"mappings":"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"}

package/dist/audio/SoundFont.js

@@ -1,5 +1,5 @@
 import { scheduleMidi } from './Midi.js';
-import { MAX_SAMPLE_FRAMES, MAX_SAMPLE_RATE, MIN_SAMPLE_RATE, webAudioSampleDecoder } from './SampleDecoder.js';
+import { MAX_SAMPLE_FRAMES, MAX_SAMPLE_RATE, MAX_TOTAL_FRAMES, MIN_SAMPLE_RATE, webAudioSampleDecoder, } from './SampleDecoder.js';
 /**
  * A SoundFont 2 reader: presets to instruments to sample zones, enough to play
  * General MIDI music with real samples. Supported: key and velocity ranges, root key
@@ -174,11 +174,10 @@ function zonesOf(headers, bagList, gens, index, terminal) {
 function generatorOf(zone, oper) {
     return zone.gens.get(oper) ?? zone.global?.get(oper) ?? null;
 }
-function presetIndexOf(presets, bank, program) {
+function presetIndexOf(presets, bank, program, missing = 'piano') {
     return (presets.get(`${bank}:${program}`) ??
-        presets.get(`0:${program}`) ??
-        (bank === 128 ? presets.get('128:0') : undefined) ??
-        presets.get('0:0'));
+        (bank === 128 ? presets.get('128:0') : presets.get(`0:${program}`)) ??
+        (missing === 'piano' ? presets.get('0:0') : undefined));
 }
 /**
  * Reads SoundFont 2 bytes into layered preset voices.
@@ -195,7 +194,7 @@ function presetIndexOf(presets, bank, program) {
  * console.log(font.presetCount, rendered.duration);
  * ```
  */
-export function parseSoundFont(data) {
+export function parseSoundFont(data, options = {}) {
     const tables = readTables(toBytes(data));
     if (tables.compressed) {
         throw new Error('SoundFont 3 (Ogg Vorbis samples) needs decoding first: use loadSoundFont() or decodeSoundFont(), or convert it with "mwg-soundfonts convert <in.sf3> <out.sf2>"');
@@ -233,7 +232,7 @@ export function parseSoundFont(data) {
     }
     //Zones that sound for (bank, program, key, velocity), each with the resolved playback recipe.
     function voices(bank, program, key, velocity) {
-        const presetIndex = presetIndexOf(presets, bank, program);
+        const presetIndex = presetIndexOf(presets, bank, program, options.missingProgram);
         if (presetIndex === undefined)
             return [];
         const out = [];
@@ -314,6 +313,43 @@ export function collectSoundFontUsage(files) {
     }
     return out;
 }
+/**
+ * The programs of `usage` the font does not carry, so a game can tell at build time which of the
+ * instruments its MIDI files ask for would be missing. A bank without the program counts as carried
+ * when bank 0 has it (the fallback every player makes), a drum kit only when the font has that exact
+ * kit. What plays for a missing one is the `missingProgram` policy of `parseSoundFont`. Works on a
+ * SoundFont 2 or 3.
+ *
+ * @example
+ * ```ts
+ * import { missingSoundFontPrograms, parseMidi, collectSoundFontUsage } from '@datamoc/mw_games/audio';
+ *
+ * declare const soundfontBytes: ArrayBuffer;
+ * declare const midiBytes: ArrayBuffer;
+ *
+ * const usage = collectSoundFontUsage([parseMidi(midiBytes)]);
+ * for (const { bank, program } of missingSoundFontPrograms(soundfontBytes, usage)) {
+ * 	console.log(`bank ${bank} program ${program} is not in the font`);
+ * }
+ * ```
+ */
+export function missingSoundFontPrograms(data, usage) {
+    const carried = new Set(readTables(toBytes(data))
+        .presets.slice(0, -1)
+        .map((preset) => `${preset.bank}:${preset.preset}`));
+    const seen = new Set();
+    const missing = [];
+    for (const { bank, program } of usage) {
+        const key = `${bank}:${program}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (carried.has(key) || (bank !== 128 && carried.has(`0:${program}`)))
+            continue;
+        missing.push({ bank, program });
+    }
+    return missing;
+}
 function u16le(value) {
     return [value & 0xff, (value >> 8) & 0xff];
 }
@@ -466,15 +502,14 @@ function distinctPresets(tables) {
     }
     return out;
 }
-/** decoded frames one font may hold in all: 256 MB of 16-bit audio */
-const MAX_DECODED_FRAMES = 1 << 27;
 /**
  * Decodes a SoundFont 3 into a plain SoundFont 2: every Ogg Vorbis sample a preset reaches goes
  * through `decode` (one call per sample, mono 16-bit frames at the rate the header states) into
  * the sample chunk, and the loop points a SoundFont 3 states relative to its sample become the
  * absolute ones SoundFont 2 uses. A SoundFont 2 comes back unchanged and `decode` is never called.
  * The result feeds everything that takes SoundFont 2 bytes, `renderMidiToBufferAsync` included.
- * A loop that ends past the decoded frames is cut to them.
+ * A loop that ends past the decoded frames is cut to them. `limits` raises or lowers what a sample and
+ * the whole font may decode to (see `SoundFontLimits`).
  *
  * @example
  * ```ts
@@ -486,7 +521,9 @@ const MAX_DECODED_FRAMES = 1 << 27;
  * console.log(sf2.byteLength);
  * ```
  */
-export async function decodeSoundFont(data, decode) {
+export async function decodeSoundFont(data, decode, limits = {}) {
+    const maxSample = limits.sampleFrames ?? MAX_SAMPLE_FRAMES;
+    const maxTotal = limits.totalFrames ?? MAX_TOTAL_FRAMES;
     const bytes = toBytes(data);
     const tables = readTables(bytes);
     if (!tables.compressed)
@@ -510,8 +547,8 @@ export async function decodeSoundFont(data, decode) {
             }
             const pcm = await decode(reachable.smplBytes.subarray(sample.start, sample.end), sample.rate);
             //what a decoder returns is bounded too: a few bytes of Ogg can name a very long sound
-            if (pcm.length > MAX_SAMPLE_FRAMES || total + pcm.length > MAX_DECODED_FRAMES) {
-                throw new Error('the decoded sample data is larger than a SoundFont may hold: subset the font before shipping it');
+            if (pcm.length > maxSample || total + pcm.length > maxTotal) {
+                throw new Error('the decoded sample data is larger than the limits allow: subset the font, or raise `limits`');
             }
             at = { start: total, length: pcm.length };
             placed.set(key, at);
@@ -560,7 +597,8 @@ export async function decodeSoundFont(data, decode) {
  * ```
  */
 export async function loadSoundFont(data, options = {}) {
-    return parseSoundFont(await decodeSoundFont(data, options.decode ?? webAudioSampleDecoder()));
+    const decode = options.decode ?? webAudioSampleDecoder(undefined, options.limits);
+    return parseSoundFont(await decodeSoundFont(data, decode, options.limits), options);
 }
 /**
  * Writes a smaller, valid SoundFont 2 file carrying only the used programs: their