@datamoc/mw_games 0.44.2 → 0.46.0

package/dist/audio/SoundFont.d.ts

@@ -1,192 +0,0 @@
-import { type MidiFile } from './Midi.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;
-    rate: number;
-    loopStart: number;
-    loopEnd: number;
-}
-/** how one layered voice plays its sample for a note */
-export interface SoundFontVoice {
-    sample: SoundFontSample;
-    rootKey: number;
-    /** tuning offset in cents, applied on top of the root key */
-    cents: number;
-    loop: boolean;
-    /** linear level multiplier from attenuation layering */
-    gain: number;
-    /** stereo position, -1 (left) to 1 (right) */
-    pan: number;
-    /** envelope stages in seconds, except sustain which is a level multiplier */
-    attack: number;
-    hold: number;
-    decay: number;
-    sustain: number;
-    release: number;
-}
-/**
- * The samples behind a SoundFont file: one call per note returns the layered voices
- * for its bank, program, key and velocity. A game ships its own file (parsed here)
- * and hands the result wherever samples are needed; nothing here fetches or picks one.
- */
-export interface SoundFont {
-    voices(bank: number, program: number, key: number, velocity: number): SoundFontVoice[];
-    hasPreset(bank: number, program: number): boolean;
-    readonly presetCount: number;
-}
-/** one used program: the voice a game's MIDI files actually request */
-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.
- *
- * @example
- * ```ts
- * import { parseSoundFont, parseMidi, renderMidiToBuffer } from '@datamoc/mw_games/audio';
- *
- * declare const soundfontBytes: ArrayBuffer;
- * declare const midiBytes: ArrayBuffer;
- *
- * const font = parseSoundFont(soundfontBytes);
- * const rendered = renderMidiToBuffer(parseMidi(midiBytes), { soundfont: font });
- * console.log(font.presetCount, rendered.duration);
- * ```
- */
-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
- * the same way the renderer maps them. A game's compile step feeds this straight
- * into `subsetSoundFont` so the shipped font carries only these programs.
- *
- * @example
- * ```ts
- * import { parseMidi, collectSoundFontUsage } from '@datamoc/mw_games/audio';
- *
- * declare const midiBytes: ArrayBuffer;
- *
- * const usage = collectSoundFontUsage([parseMidi(midiBytes)]);
- * console.log(usage.length);
- * ```
- */
-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. `limits` raises or lowers what a sample and
- * the whole font may decode to (see `SoundFontLimits`).
- *
- * @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, 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
- * 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;
-    limits?: SoundFontLimits;
-}): 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,
- * envelopes and sample loops copied verbatim and every index remapped. Zones that
- * reference samples missing from the file (ROM samples) are dropped, matching what
- * the reader voices for the full font; the library, genre and morphology metadata
- * is zeroed and the INFO list, when present, rides along untouched. Modulator lists
- * are emptied and 24-bit upper bits are dropped: the reader voices neither, so what
- * it plays is unchanged, while a third-party player would miss those.
- *
- * @example
- * ```ts
- * import { parseMidi, collectSoundFontUsage, subsetSoundFont } from '@datamoc/mw_games/audio';
- *
- * declare const midiBytes: ArrayBuffer;
- * declare const soundfontBytes: ArrayBuffer;
- *
- * const usage = collectSoundFontUsage([parseMidi(midiBytes)]);
- * const pruned = subsetSoundFont(soundfontBytes, usage);
- * console.log(usage.length, pruned.byteLength);
- * ```
- */
-export declare function subsetSoundFont(data: ArrayBuffer | ArrayBufferView, usage: readonly SoundFontProgram[]): ArrayBuffer;
-//# sourceMappingURL=SoundFont.d.ts.map

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

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