@datamoc/mw_games 0.40.0 → 0.42.0

package/dist/audio/SampleDecoder.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Turns the Ogg Vorbis bytes of one SoundFont 3 sample into mono 16-bit frames at the
+ * sample's own rate, which is the rate its header states and the frame count its loop
+ * points were written against. Synchronous or asynchronous: a browser decodes through
+ * WebAudio (`webAudioSampleDecoder`), a Node tool through whatever it has installed.
+ */
+export type SoundFontSampleDecoder = (ogg: Uint8Array, rate: number) => Int16Array | Promise<Int16Array>;
+/** the slice of `OfflineAudioContext` the decoder uses, so a test can stand in for it */
+export interface SampleDecodingContext {
+    decodeAudioData(data: ArrayBuffer): Promise<{
+        sampleRate: number;
+        length: number;
+        getChannelData(channel: number): Float32Array;
+    }>;
+}
+/**
+ * What a sample header may claim. The rate and the Ogg bytes come from a font file that may have been
+ * downloaded, so what they ask the decoder to allocate is bounded: the SoundFont 2 format itself
+ * stops at 50 kHz, and sixteen million frames is six minutes at 44.1 kHz for a single instrument sample.
+ */
+export declare const MIN_SAMPLE_RATE = 400;
+export declare const MAX_SAMPLE_RATE = 200000;
+export declare const MAX_SAMPLE_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.
+ *
+ * @example
+ * ```ts
+ * import { loadSoundFont, webAudioSampleDecoder } from '@datamoc/mw_games/audio';
+ *
+ * declare const sf3Bytes: ArrayBuffer;
+ *
+ * const font = await loadSoundFont(sf3Bytes, { decode: webAudioSampleDecoder() });
+ * console.log(font.presetCount);
+ * ```
+ */
+export declare function webAudioSampleDecoder(create?: (rate: number) => SampleDecodingContext): SoundFontSampleDecoder;
+//# sourceMappingURL=SampleDecoder.d.ts.map

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

@@ -0,0 +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"}

package/dist/audio/SampleDecoder.js

@@ -0,0 +1,70 @@
+/** the narrowest rate range every engine's `OfflineAudioContext` accepts */
+const MIN_RATE = 8000;
+const MAX_RATE = 96000;
+/**
+ * What a sample header may claim. The rate and the Ogg bytes come from a font file that may have been
+ * downloaded, so what they ask the decoder to allocate is bounded: the SoundFont 2 format itself
+ * stops at 50 kHz, and sixteen million frames is six minutes at 44.1 kHz for a single instrument sample.
+ */
+export const MIN_SAMPLE_RATE = 400;
+export const MAX_SAMPLE_RATE = 200000;
+export const MAX_SAMPLE_FRAMES = 1 << 24;
+function toInt16(frames) {
+    const out = new Int16Array(frames.length);
+    for (let index = 0; index < frames.length; index++) {
+        out[index] = Math.round(Math.max(-1, Math.min(1, frames[index])) * 32767);
+    }
+    return out;
+}
+/** linear resampling, only for the rare sample whose rate a context cannot be created at */
+function resample(frames, from, to) {
+    const length = Math.max(1, Math.round((frames.length * to) / from));
+    if (length > MAX_SAMPLE_FRAMES)
+        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++) {
+        const at = (index * from) / to;
+        const base = Math.floor(at);
+        const next = Math.min(base + 1, frames.length - 1);
+        out[index] = frames[base] + (frames[next] - frames[base]) * (at - base);
+    }
+    return out;
+}
+function offlineContext(rate) {
+    if (typeof OfflineAudioContext === 'undefined') {
+        throw new Error('no OfflineAudioContext here: pass a decoder of your own to decode a SoundFont 3');
+    }
+    return new OfflineAudioContext(1, 1, 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.
+ *
+ * @example
+ * ```ts
+ * import { loadSoundFont, webAudioSampleDecoder } from '@datamoc/mw_games/audio';
+ *
+ * declare const sf3Bytes: ArrayBuffer;
+ *
+ * const font = await loadSoundFont(sf3Bytes, { decode: webAudioSampleDecoder() });
+ * console.log(font.presetCount);
+ * ```
+ */
+export function webAudioSampleDecoder(create = offlineContext) {
+    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`);
+        }
+        const contextRate = Math.max(MIN_RATE, Math.min(MAX_RATE, rate));
+        //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)
+            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));
+    };
+}
+//# sourceMappingURL=SampleDecoder.js.map

package/dist/audio/SampleDecoder.js.map

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

package/dist/audio/SoundFont.d.ts

@@ -1,4 +1,5 @@
 import { type MidiFile } from './Midi.ts';
+import type { SoundFontSampleDecoder } from './SampleDecoder.ts';
 /** one mono sample: raw frames plus its loop region in frames and native rate */
 export interface SoundFontSample {
     data: Float32Array;
@@ -39,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.
  *
@@ -54,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
@@ -72,6 +85,85 @@ 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
+ * and samples are dropped, so the result never holds a voice nothing can reach. This is
+ * how single-instrument files (a per-program font collection) become the one file a game
+ * ships; `subsetSoundFont` then trims it like any other.
+ *
+ * @example
+ * ```ts
+ * import { mergeSoundFonts, parseSoundFont } from '@datamoc/mw_games/audio';
+ *
+ * declare const pianoBytes: ArrayBuffer;
+ * declare const drumsBytes: ArrayBuffer;
+ *
+ * const merged = mergeSoundFonts([pianoBytes, drumsBytes]);
+ * console.log(parseSoundFont(merged).presetCount);
+ * ```
+ */
+export declare function mergeSoundFonts(fonts: readonly (ArrayBuffer | ArrayBufferView)[]): ArrayBuffer;
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { decodeSoundFont, webAudioSampleDecoder } from '@datamoc/mw_games/audio';
+ *
+ * declare const sf3Bytes: ArrayBuffer;
+ *
+ * const sf2 = await decodeSoundFont(sf3Bytes, webAudioSampleDecoder());
+ * console.log(sf2.byteLength);
+ * ```
+ */
+export declare function decodeSoundFont(data: ArrayBuffer | ArrayBufferView, decode: SoundFontSampleDecoder): 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
+ * is given. This is what a game calls on the bytes it ships, whichever kind they are.
+ *
+ * @example
+ * ```ts
+ * import { loadSoundFont, parseMidi, renderMidiToBuffer } from '@datamoc/mw_games/audio';
+ *
+ * declare const fontBytes: ArrayBuffer;
+ * declare const midiBytes: ArrayBuffer;
+ *
+ * const font = await loadSoundFont(fontBytes);
+ * const rendered = renderMidiToBuffer(parseMidi(midiBytes), { soundfont: font });
+ * console.log(rendered.duration);
+ * ```
+ */
+export declare function loadSoundFont(data: ArrayBuffer | ArrayBufferView, options?: SoundFontOptions & {
+    decode?: SoundFontSampleDecoder;
+}): Promise<SoundFont>;
 /**
  * Writes a smaller, valid SoundFont 2 file carrying only the used programs: their
  * presets (names kept), instruments and samples, with zones, ranges, tuning,

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;AAwCxD,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;AAyMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,SAAS,CAkG7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,gBAAgB,EAAE,CAcpF;AA6CD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,EAAE,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,WAAW,CAiOpH"}
+{"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;AA8MD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,CAAC;AAE/C,MAAM,WAAW,gBAAgB;IAChC,sEAAsE;IACtE,cAAc,CAAC,EAAE,cAAc,CAAC;CAChC;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAuG7G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,gBAAgB,EAAE,CAcpF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACvC,IAAI,EAAE,WAAW,GAAG,eAAe,EACnC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAChC,gBAAgB,EAAE,CAgBpB;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,gBAAgB,GAAG;IAAE,MAAM,CAAC,EAAE,sBAAsB,CAAA;CAAO,GAClE,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"}

package/dist/audio/SoundFont.js

@@ -1,4 +1,5 @@
 import { scheduleMidi } from './Midi.js';
+import { MAX_SAMPLE_FRAMES, MAX_SAMPLE_RATE, 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
@@ -117,7 +118,19 @@ function readTables(bytes) {
         type: view.getUint16(at + 44, true),
     }));
     const smplChunk = chunks.get('smpl');
-    const smpl = new Int16Array(bytes.buffer.slice(bytes.byteOffset + smplChunk.at, bytes.byteOffset + smplChunk.at + smplChunk.size - (smplChunk.size & 1)));
+    const smplBytes = bytes.slice(smplChunk.at, smplChunk.at + smplChunk.size);
+    //ROM and empty samples have no data here; the rest must agree on what their offsets count
+    const sampled = samples.filter((sample) => sample.end > sample.start && !(sample.type & 0x8000));
+    const compressed = sampled.some((sample) => sample.type & 0x10);
+    if (compressed && !sampled.every((sample) => sample.type & 0x10)) {
+        throw new Error('SoundFont mixes compressed and plain samples, which it cannot address consistently');
+    }
+    //the offsets come from the file, so a lying header must not reach beyond the sample data
+    const limit = compressed ? smplBytes.length : smplBytes.length >> 1;
+    if (sampled.some((sample) => sample.end > limit)) {
+        throw new Error('a sample points outside the sample data: the SoundFont is damaged');
+    }
+    const smpl = compressed ? new Int16Array(0) : new Int16Array(smplBytes.buffer, 0, smplBytes.length >> 1);
     const info = lists.get('INFO') ?? null;
     return {
         bytes,
@@ -128,7 +141,9 @@ function readTables(bytes) {
         instBags: bags('ibag'),
         instGens: generators('igen'),
         samples,
+        smplBytes,
         smpl,
+        compressed,
         info: info ? bytes.slice(info.at, info.at + 8 + info.size + (info.size & 1)) : null,
     };
 }
@@ -159,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.
@@ -180,8 +194,11 @@ 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>"');
+    }
     const sampleCache = new Map();
     const tuning = new Map();
     const sampleOf = (id) => {
@@ -215,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 = [];
@@ -296,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];
 }
@@ -333,6 +387,217 @@ function listBytes(type, subs) {
     const body = concat([new Uint8Array(asciiBytes(type)), ...subs]);
     return concat([new Uint8Array(asciiBytes('LIST')), new Uint8Array(u32le(body.length)), body]);
 }
+/**
+ * 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
+ * and samples are dropped, so the result never holds a voice nothing can reach. This is
+ * how single-instrument files (a per-program font collection) become the one file a game
+ * ships; `subsetSoundFont` then trims it like any other.
+ *
+ * @example
+ * ```ts
+ * import { mergeSoundFonts, parseSoundFont } from '@datamoc/mw_games/audio';
+ *
+ * declare const pianoBytes: ArrayBuffer;
+ * declare const drumsBytes: ArrayBuffer;
+ *
+ * const merged = mergeSoundFonts([pianoBytes, drumsBytes]);
+ * console.log(parseSoundFont(merged).presetCount);
+ * ```
+ */
+export function mergeSoundFonts(fonts) {
+    if (fonts.length === 0)
+        throw new Error('mergeSoundFonts needs at least one SoundFont');
+    const sources = fonts.map((font) => readTables(toBytes(font)));
+    const compressed = sources[0].compressed;
+    if (sources.some((source) => source.compressed !== compressed)) {
+        throw new Error('cannot merge a SoundFont 3 with a SoundFont 2: decode it first with decodeSoundFont()');
+    }
+    const merged = {
+        bytes: new Uint8Array(0),
+        presets: [],
+        presetBags: [],
+        presetGens: [],
+        instruments: [],
+        instBags: [],
+        instGens: [],
+        samples: [],
+        smplBytes: new Uint8Array(0),
+        smpl: new Int16Array(0),
+        compressed,
+        info: sources[0].info,
+    };
+    const parts = [];
+    let smplLength = 0; //bytes so far
+    for (const source of sources) {
+        const instrumentBase = merged.instruments.length;
+        const sampleBase = merged.samples.length;
+        const presetBagBase = merged.presetBags.length;
+        const presetGenBase = merged.presetGens.length;
+        const instBagBase = merged.instBags.length;
+        const instGenBase = merged.instGens.length;
+        //a plain font's sample offsets count frames, a SoundFont 3's count bytes (and its loops stay relative)
+        const offsetBase = compressed ? smplLength : smplLength >> 1;
+        //each table ends in a terminal record that only the joined result keeps
+        merged.presets.push(...source.presets.slice(0, -1).map((preset) => ({ ...preset, bag: preset.bag + presetBagBase })));
+        merged.presetBags.push(...source.presetBags.slice(0, -1).map((gen) => gen + presetGenBase));
+        merged.presetGens.push(...source.presetGens
+            .slice(0, source.presetBags[source.presetBags.length - 1])
+            .map((generator) => generator.oper === GENERATORS.instrument
+            ? { ...generator, amount: generator.amount + instrumentBase }
+            : generator));
+        merged.instruments.push(...source.instruments
+            .slice(0, -1)
+            .map((instrument) => ({ ...instrument, bag: instrument.bag + instBagBase })));
+        merged.instBags.push(...source.instBags.slice(0, -1).map((gen) => gen + instGenBase));
+        merged.instGens.push(...source.instGens
+            .slice(0, source.instBags[source.instBags.length - 1])
+            .map((generator) => generator.oper === GENERATORS.sampleId
+            ? { ...generator, amount: generator.amount + sampleBase }
+            : generator));
+        merged.samples.push(...source.samples.slice(0, -1).map((sample) => ({
+            ...sample,
+            start: sample.start + offsetBase,
+            end: sample.end + offsetBase,
+            loopStart: compressed ? sample.loopStart : sample.loopStart + offsetBase,
+            loopEnd: compressed ? sample.loopEnd : sample.loopEnd + offsetBase,
+            link: sample.link + sampleBase,
+        })));
+        //a plain font's chunk can end on an odd byte, which would shift every frame after it
+        const part = compressed ? source.smplBytes : source.smplBytes.subarray(0, source.smplBytes.length & ~1);
+        parts.push(part);
+        smplLength += part.length;
+    }
+    merged.presetBags.push(merged.presetGens.length);
+    merged.instBags.push(merged.instGens.length);
+    merged.presets.push({ name: 'EOS', preset: 0, bank: 0, bag: merged.presetBags.length - 1 });
+    merged.instruments.push({ name: 'EOS', bag: merged.instBags.length - 1 });
+    merged.samples.push({
+        name: 'EOS',
+        start: 0,
+        end: 0,
+        loopStart: 0,
+        loopEnd: 0,
+        rate: 0,
+        rootKey: 0,
+        correction: 0,
+        link: 0,
+        type: 0,
+    });
+    merged.smplBytes = concat(parts);
+    if (!compressed)
+        merged.smpl = new Int16Array(merged.smplBytes.slice().buffer);
+    return writeSoundFont(merged, distinctPresets(merged));
+}
+/** the presets of `tables` (indices) with each (bank, program) once, the first occurrence winning */
+function distinctPresets(tables) {
+    const seen = new Set();
+    const out = [];
+    for (let index = 0; index < tables.presets.length - 1; index++) {
+        const key = `${tables.presets[index].bank}:${tables.presets[index].preset}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(index);
+    }
+    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.
+ *
+ * @example
+ * ```ts
+ * import { decodeSoundFont, webAudioSampleDecoder } from '@datamoc/mw_games/audio';
+ *
+ * declare const sf3Bytes: ArrayBuffer;
+ *
+ * const sf2 = await decodeSoundFont(sf3Bytes, webAudioSampleDecoder());
+ * console.log(sf2.byteLength);
+ * ```
+ */
+export async function decodeSoundFont(data, decode) {
+    const bytes = toBytes(data);
+    const tables = readTables(bytes);
+    if (!tables.compressed)
+        return bytes.slice().buffer;
+    //prune first, so a sample no preset reaches is never decoded
+    const reachable = readTables(new Uint8Array(writeSoundFont(tables, distinctPresets(tables))));
+    const frames = [];
+    const placed = new Map();
+    let total = 0;
+    const samples = [];
+    for (const sample of reachable.samples) {
+        if (!(sample.end > sample.start) || sample.type & 0x8000) {
+            samples.push(sample);
+            continue;
+        }
+        const key = `${sample.start}:${sample.end}`;
+        let at = placed.get(key);
+        if (!at) {
+            if (!(sample.rate >= MIN_SAMPLE_RATE && sample.rate <= MAX_SAMPLE_RATE)) {
+                throw new Error(`a sample states ${sample.rate} Hz, which no SoundFont does: the font is damaged`);
+            }
+            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');
+            }
+            at = { start: total, length: pcm.length };
+            placed.set(key, at);
+            frames.push(pcm);
+            total += pcm.length;
+        }
+        samples.push({
+            ...sample,
+            start: at.start,
+            end: at.start + at.length,
+            loopStart: at.start + Math.min(sample.loopStart, at.length),
+            loopEnd: at.start + Math.min(sample.loopEnd, at.length),
+            type: sample.type & ~0x10,
+        });
+    }
+    const smpl = new Int16Array(total);
+    let offset = 0;
+    for (const pcm of frames) {
+        smpl.set(pcm, offset);
+        offset += pcm.length;
+    }
+    const plain = {
+        ...reachable,
+        samples,
+        smpl,
+        smplBytes: new Uint8Array(smpl.buffer),
+        compressed: false,
+    };
+    return writeSoundFont(plain, distinctPresets(plain));
+}
+/**
+ * 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
+ * is given. This is what a game calls on the bytes it ships, whichever kind they are.
+ *
+ * @example
+ * ```ts
+ * import { loadSoundFont, parseMidi, renderMidiToBuffer } from '@datamoc/mw_games/audio';
+ *
+ * declare const fontBytes: ArrayBuffer;
+ * declare const midiBytes: ArrayBuffer;
+ *
+ * const font = await loadSoundFont(fontBytes);
+ * const rendered = renderMidiToBuffer(parseMidi(midiBytes), { soundfont: font });
+ * console.log(rendered.duration);
+ * ```
+ */
+export async function loadSoundFont(data, options = {}) {
+    return parseSoundFont(await decodeSoundFont(data, options.decode ?? webAudioSampleDecoder()), options);
+}
 /**
  * Writes a smaller, valid SoundFont 2 file carrying only the used programs: their
  * presets (names kept), instruments and samples, with zones, ranges, tuning,
@@ -372,6 +637,10 @@ export function subsetSoundFont(data, usage) {
         }
     }
     usedPresets.sort((a, b) => a - b);
+    return writeSoundFont(tables, usedPresets);
+}
+/** writes the presets of `tables` listed in `usedPresets` (indices) with everything they reach, remapped */
+function writeSoundFont(tables, usedPresets) {
     const usableSample = (id) => {
         const header = tables.samples[id];
         return !!header && header.end > header.start && !(header.type & 0x8000);
@@ -496,12 +765,25 @@ export function subsetSoundFont(data, usage) {
     const sampleData = [];
     for (const old of sampleOrder) {
         const header = tables.samples[old];
+        const self = sampleNew.get(old);
+        if (tables.compressed) {
+            //Ogg bytes copied as they are: offsets count bytes and the loop points stay relative to the sample
+            const start = sampleData.length;
+            for (let index = header.start; index < header.end; index++)
+                sampleData.push(tables.smplBytes[index]);
+            newSamples.push({
+                ...header,
+                start,
+                end: start + (header.end - header.start),
+                link: sampleNew.get(header.link) ?? self,
+            });
+            continue;
+        }
         const start = sampleData.length / 2;
         for (let index = header.start; index < header.end; index++) {
             const word = tables.smpl[index];
             sampleData.push(word & 0xff, (word >> 8) & 0xff);
         }
-        const self = sampleNew.get(old);
         newSamples.push({
             ...header,
             start,