@datamoc/mw_games 0.43.0 → 0.44.2

package/dist/audio/Playable.d.ts

@@ -3,6 +3,13 @@
  * already provides, named here so a test (or a game with its own audio backend) can supply
  * a fake without a real `Audio` element existing, which nothing outside a browser can
  * create.
+ *
+ * A backend that synthesises its sound instead of decoding a file (see `StreamPlayable`) has to
+ * answer the questions `HTMLAudioElement` answers implicitly: `currentTime` reads and seeks the
+ * playhead and holds the duration once a track that does not loop has ended; `playbackRate` is
+ * honoured (by resampling) or ignored but never throws; `onended` fires once at the end of a
+ * track that does not loop and never for one that does; and `play()` may return a promise that
+ * settles when the audio is allowed to start.
  */
 export interface Playable {
     play(): void | Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"Playable.d.ts","sourceRoot":"","sources":["../../src/audio/Playable.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;+EAC2E;IAC3E,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAUlD"}
+{"version":3,"file":"Playable.d.ts","sourceRoot":"","sources":["../../src/audio/Playable.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACxB,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;+EAC2E;IAC3E,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAUlD"}

package/dist/audio/Playable.js.map

@@ -1 +1 @@
-{"version":3,"file":"Playable.js","sourceRoot":"","sources":["../../src/audio/Playable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC;AAqBhD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACvC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACJ,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,0FAA0F;QAC1F,OAAO,CAAC,IAAI,CAAC,GAAI,KAAe,CAAC,OAAO,OAAO,IAAI,kBAAkB,CAAC,CAAC;QACvE,OAAO,cAAc,EAAE,CAAC;IACzB,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,4FAA4F;AAC5F,SAAS,cAAc;IACtB,OAAO,EAAE,IAAI,KAAI,CAAC,EAAE,KAAK,KAAI,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1E,CAAC"}
+{"version":3,"file":"Playable.js","sourceRoot":"","sources":["../../src/audio/Playable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC;AA4BhD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACvC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACJ,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,0FAA0F;QAC1F,OAAO,CAAC,IAAI,CAAC,GAAI,KAAe,CAAC,OAAO,OAAO,IAAI,kBAAkB,CAAC,CAAC;QACvE,OAAO,cAAc,EAAE,CAAC;IACzB,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,4FAA4F;AAC5F,SAAS,cAAc;IACtB,OAAO,EAAE,IAAI,KAAI,CAAC,EAAE,KAAK,KAAI,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1E,CAAC"}

package/dist/audio/Positional.d.ts

@@ -1,4 +1,7 @@
-import type { Sound } from './Sound.ts';
+/** anything a `SoundSource` can play at a mix: a `Sound`, or an `SfxSound` that also takes a pan */
+export interface PositionalSound {
+    play(gain?: number, pitch?: number, pan?: number): unknown;
+}
 /** A point in the same 2D space the game's camera works in, in world units. */
 export interface AudioPoint {
     x: number;
@@ -113,13 +116,18 @@ export declare class SoundSource implements AudioPoint {
     y: number;
     private readonly sound;
     private readonly falloff;
-    constructor(sound: Sound, options?: SoundSourceOptions);
+    constructor(sound: PositionalSound, options?: SoundSourceOptions);
     moveTo(x: number, y: number): void;
     gainTo(listener: AudioPoint): number;
     panTo(listener: AudioPoint & {
         facing: number;
     }): number;
-    /** Plays the source at the gain the listener hears it; returns the gain actually used. */
-    playFor(listener: AudioPoint): number;
+    /**
+     * Plays the source at the gain the listener hears it; returns the gain actually used. A listener
+     * with a `facing` also pans the sound, for a sound that takes a pan (a `Sound` ignores it).
+     */
+    playFor(listener: AudioPoint | (AudioPoint & {
+        facing: number;
+    })): number;
 }
 //# sourceMappingURL=Positional.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Positional.d.ts","sourceRoot":"","sources":["../../src/audio/Positional.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC5B,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAU9E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAW9F;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,UAAU;IAC/C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,OAAO,GAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,EAIpE;IAED,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjC;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1B;CACD;AAED,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACvD,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,YAAY,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,kBAAuB,EASzD;IAED,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjC;IAED,MAAM,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAEnC;IAED,KAAK,CAAC,QAAQ,EAAE,UAAU,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAEvD;IAED,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAKpC;CACD"}
+{"version":3,"file":"Positional.d.ts","sourceRoot":"","sources":["../../src/audio/Positional.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3D;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC5B,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAU9E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAW9F;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,UAAU;IAC/C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,OAAO,GAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,EAIpE;IAED,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjC;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1B;CACD;AAED,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACvD,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,YAAY,KAAK,EAAE,eAAe,EAAE,OAAO,GAAE,kBAAuB,EASnE;IAED,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjC;IAED,MAAM,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAEnC;IAED,KAAK,CAAC,QAAQ,EAAE,UAAU,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAEvD;IAED;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,GAAG,CAAC,UAAU,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,MAAM,CAKxE;CACD"}

package/dist/audio/Positional.js

@@ -123,12 +123,15 @@ export class SoundSource {
     panTo(listener) {
         return audioPan(listener, this);
     }
-    /** Plays the source at the gain the listener hears it; returns the gain actually used. */
+    /**
+     * Plays the source at the gain the listener hears it; returns the gain actually used. A listener
+     * with a `facing` also pans the sound, for a sound that takes a pan (a `Sound` ignores it).
+     */
     playFor(listener) {
         const gain = this.gainTo(listener);
         if (gain <= 0)
             return 0;
-        this.sound.play(gain);
+        this.sound.play(gain, 1, 'facing' in listener ? this.panTo(listener) : 0);
         return gain;
     }
 }

package/dist/audio/Positional.js.map

@@ -1 +1 @@
-{"version":3,"file":"Positional.js","sourceRoot":"","sources":["../../src/audio/Positional.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Positional.js","sourceRoot":"","sources":["../../src/audio/Positional.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,OAAO,GAAiB,EAAE;IACrE,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,QAAQ,CAAC;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;IAErC,IAAI,CAAC,CAAC,QAAQ,GAAG,WAAW,CAAC;QAAE,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC,QAAQ,GAAG,WAAW,CAAC;QAAE,OAAO,CAAC,CAAC;IAExC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,QAAQ,EAAE,OAAO,CAAC,CAAC;IACvD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAyC,EAAE,MAAkB;IACrF,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IACjC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACpC,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAE7B,gFAAgF;IAChF,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,MAAM,GAAG,EAAE,GAAG,MAAM,CAAC,GAAG,QAAQ,CAAC;IACnD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,aAAa;IAOzB,YAAY,OAAO,GAAgD,EAAE;QACpE,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,CAAS,EAAE,CAAS;QAC1B,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACX,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC;IAED,IAAI,CAAC,OAAe;QACnB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;IACvB,CAAC;CACD;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,WAAW;IAOvB,YAAY,KAAsB,EAAE,OAAO,GAAuB,EAAE;QACnE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG;YACd,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,OAAO,EAAE,OAAO,CAAC,OAAO;SACxB,CAAC;IACH,CAAC;IAED,MAAM,CAAC,CAAS,EAAE,CAAS;QAC1B,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACX,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC;IAED,MAAM,CAAC,QAAoB;QAC1B,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACtF,CAAC;IAED,KAAK,CAAC,QAAyC;QAC9C,OAAO,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,QAAwD;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,IAAI,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC;IACb,CAAC;CACD"}

package/dist/audio/Resample.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Plain-array helpers for fitting rendered audio to a budget: cut to a length with a fade,
+ * fold to mono, halve the rate, convert between rates. They work on the `Float32Array`
+ * pairs a render produces, so nothing here needs an `AudioContext`.
+ */
+/** stereo frames at a sample rate: the shape every renderer in this module hands back */
+export interface StereoFrames {
+    sampleRate: number;
+    left: Float32Array;
+    right: Float32Array;
+}
+/**
+ * Converts stereo frames to another sample rate by linear interpolation. Linear is audibly
+ * soft above the new Nyquist, which is the right trade for ambience and background music where
+ * this is used to save memory; a game that needs a clean conversion renders at the target
+ * rate instead.
+ *
+ * @example
+ * ```ts
+ * import { resampleStereo } from '@datamoc/mw_games/audio';
+ *
+ * declare const frames: { sampleRate: number; left: Float32Array; right: Float32Array };
+ *
+ * const half = resampleStereo(frames, frames.sampleRate / 2);
+ * console.log(half.left.length);
+ * ```
+ */
+export declare function resampleStereo<T extends StereoFrames>(frames: T, sampleRate: number): T;
+/** what a track may cost: every field optional, an omitted one leaves that dimension alone */
+export interface RenderBudget {
+    /** cut the track to this many seconds, fading the cut so it does not click */
+    maxSeconds?: number;
+    /** seconds of fade at a cut; 0.5 when omitted */
+    fadeSeconds?: number;
+    /** fold both channels into one, stored twice-referenced so a stereo consumer still works */
+    mono?: boolean;
+    /** halve the sample rate, for ambience that carries no high frequencies */
+    halfRate?: boolean;
+}
+/**
+ * Fits a rendered track to a budget: cuts it to `maxSeconds` with a fade, folds it to mono
+ * and halves its rate, in that order. A mono track shares one array between both channels, so
+ * it costs half the memory in the renderer's hands even though a stereo `AudioBuffer` made
+ * from it later still has two. Loop points past the cut are pulled back to the new end.
+ *
+ * @example
+ * ```ts
+ * import { fitToBudget, renderMidiToBuffer, parseMidi } from '@datamoc/mw_games/audio';
+ *
+ * declare const midiBytes: ArrayBuffer;
+ *
+ * const ambience = fitToBudget(renderMidiToBuffer(parseMidi(midiBytes)), { maxSeconds: 60, mono: true, halfRate: true });
+ * console.log(ambience.duration);
+ * ```
+ */
+export declare function fitToBudget<T extends StereoFrames & {
+    loopStart?: number;
+    loopEnd?: number;
+    duration?: number;
+}>(track: T, budget: RenderBudget): T;
+//# sourceMappingURL=Resample.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Resample.d.ts","sourceRoot":"","sources":["../../src/audio/Resample.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,YAAY,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC,CAiBvF;AAED,8FAA8F;AAC9F,MAAM,WAAW,YAAY;IAC5B,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,YAAY,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EAC/G,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,YAAY,GAClB,CAAC,CAyBH"}

package/dist/audio/Resample.js

@@ -0,0 +1,97 @@
+/**
+ * Plain-array helpers for fitting rendered audio to a budget: cut to a length with a fade,
+ * fold to mono, halve the rate, convert between rates. They work on the `Float32Array`
+ * pairs a render produces, so nothing here needs an `AudioContext`.
+ */
+/**
+ * Converts stereo frames to another sample rate by linear interpolation. Linear is audibly
+ * soft above the new Nyquist, which is the right trade for ambience and background music where
+ * this is used to save memory; a game that needs a clean conversion renders at the target
+ * rate instead.
+ *
+ * @example
+ * ```ts
+ * import { resampleStereo } from '@datamoc/mw_games/audio';
+ *
+ * declare const frames: { sampleRate: number; left: Float32Array; right: Float32Array };
+ *
+ * const half = resampleStereo(frames, frames.sampleRate / 2);
+ * console.log(half.left.length);
+ * ```
+ */
+export function resampleStereo(frames, sampleRate) {
+    if (!(sampleRate > 0))
+        throw new Error('target sample rate must be positive');
+    if (sampleRate === frames.sampleRate)
+        return frames;
+    const length = Math.max(1, Math.round((frames.left.length * sampleRate) / frames.sampleRate));
+    const step = frames.sampleRate / sampleRate;
+    const left = new Float32Array(length);
+    const right = new Float32Array(length);
+    const last = frames.left.length - 1;
+    for (let i = 0; i < length; i++) {
+        const position = i * step;
+        const floor = Math.min(last, Math.floor(position));
+        const next = Math.min(last, floor + 1);
+        const fraction = position - floor;
+        left[i] = frames.left[floor] + (frames.left[next] - frames.left[floor]) * fraction;
+        right[i] = frames.right[floor] + (frames.right[next] - frames.right[floor]) * fraction;
+    }
+    return { ...frames, sampleRate, left, right };
+}
+/**
+ * Fits a rendered track to a budget: cuts it to `maxSeconds` with a fade, folds it to mono
+ * and halves its rate, in that order. A mono track shares one array between both channels, so
+ * it costs half the memory in the renderer's hands even though a stereo `AudioBuffer` made
+ * from it later still has two. Loop points past the cut are pulled back to the new end.
+ *
+ * @example
+ * ```ts
+ * import { fitToBudget, renderMidiToBuffer, parseMidi } from '@datamoc/mw_games/audio';
+ *
+ * declare const midiBytes: ArrayBuffer;
+ *
+ * const ambience = fitToBudget(renderMidiToBuffer(parseMidi(midiBytes)), { maxSeconds: 60, mono: true, halfRate: true });
+ * console.log(ambience.duration);
+ * ```
+ */
+export function fitToBudget(track, budget) {
+    let result = track;
+    if (budget.maxSeconds !== undefined) {
+        if (!(budget.maxSeconds > 0))
+            throw new Error('budget maxSeconds must be positive');
+        const limit = Math.max(1, Math.floor(budget.maxSeconds * result.sampleRate));
+        if (result.left.length > limit) {
+            const left = result.left.slice(0, limit);
+            const right = result.right.slice(0, limit);
+            const fade = Math.min(limit, Math.floor((budget.fadeSeconds ?? 0.5) * result.sampleRate));
+            for (let i = 0; i < fade; i++) {
+                const gain = i / fade;
+                left[limit - 1 - i] *= gain;
+                right[limit - 1 - i] *= gain;
+            }
+            const seconds = limit / result.sampleRate;
+            result = withEnd({ ...result, left, right }, seconds);
+        }
+    }
+    if (budget.mono) {
+        const mixed = new Float32Array(result.left.length);
+        for (let i = 0; i < mixed.length; i++)
+            mixed[i] = (result.left[i] + result.right[i]) / 2;
+        result = { ...result, left: mixed, right: mixed };
+    }
+    if (budget.halfRate)
+        result = resampleStereo(result, result.sampleRate / 2);
+    return result;
+}
+function withEnd(track, seconds) {
+    const next = { ...track };
+    if (next.duration !== undefined)
+        next.duration = seconds;
+    if (next.loopEnd !== undefined)
+        next.loopEnd = Math.min(next.loopEnd, seconds);
+    if (next.loopStart !== undefined)
+        next.loopStart = Math.min(next.loopStart, Math.max(0, seconds - 0.1));
+    return next;
+}
+//# sourceMappingURL=Resample.js.map

package/dist/audio/Resample.js.map

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

package/dist/audio/Settings.d.ts

@@ -0,0 +1,99 @@
+import type { AudioBus, BusKind } from './Channels.ts';
+/** the television standard a retro machine ran at: it sets the clock its music was timed by */
+export type AudioRegion = 'pal' | 'ntsc';
+/**
+ * How a machine profile's output stage is treated: `faithful` keeps what the hardware did
+ * (DC offset, aliasing and all), `clean` removes the DC and softens the top end.
+ */
+export type OutputStage = 'faithful' | 'clean';
+/** player-facing audio settings as plain data, the shape a save or a settings file holds */
+export interface AudioSettingsData {
+    /** volume per bus kind, 0 to 100 like every other volume in the bus API */
+    busVolumes: Record<BusKind, number>;
+    /** the MIDI engine name content is voiced by first, or null for the internal path */
+    preferredEngine: string | null;
+    region: AudioRegion;
+    outputStage: OutputStage;
+    /** whether caption text is shown for captioned sounds */
+    captions: boolean;
+    /** dynamics control, 0 (untouched) to 1 (a soft limiter at full), for loudness comfort */
+    dynamics: number;
+    /** softening of bright or broadband sounds, 0 (untouched) to 1 (most softened) */
+    soften: number;
+}
+/**
+ * The playback rate a tune authored for one region runs at on the other: a PAL machine's
+ * 50 Hz clock against NTSC's 60 Hz makes the same file slower and lower, which is the
+ * difference a player who grew up with the other standard hears first.
+ *
+ * @example
+ * ```ts
+ * import { regionPlaybackRate } from '@datamoc/mw_games/audio';
+ *
+ * console.log(regionPlaybackRate('pal', 'ntsc')); // 0.8333..., slower on PAL
+ * console.log(regionPlaybackRate('ntsc', 'ntsc')); // 1, its own region
+ * ```
+ */
+export declare function regionPlaybackRate(region: AudioRegion, authored?: AudioRegion): number;
+/**
+ * The low-pass cutoff, in hertz, that a `soften` amount asks an output stage for: nothing
+ * at 0, down to a muffled 3.5 kHz at 1, never above what the sample rate can represent.
+ *
+ * @example
+ * ```ts
+ * import { softenCutoff } from '@datamoc/mw_games/audio';
+ *
+ * console.log(softenCutoff(0, 44100)); // 18000, effectively open
+ * console.log(softenCutoff(1, 44100) < softenCutoff(0.5, 44100)); // true, more soften, lower cutoff
+ * ```
+ */
+export declare function softenCutoff(soften: number, sampleRate: number): number;
+/**
+ * One sample through the dynamics control: at 0 the sample is untouched, and as the amount
+ * rises a soft knee pulls peaks toward full scale without ever passing it, so a loud game
+ * gets quieter peaks rather than clipped ones.
+ *
+ * @example
+ * ```ts
+ * import { dynamicsLimit } from '@datamoc/mw_games/audio';
+ *
+ * console.log(dynamicsLimit(0.5, 0)); // 0.5, untouched
+ * console.log(dynamicsLimit(4, 1) < 1); // true, a hot sample is pulled under full scale
+ * ```
+ */
+export declare function dynamicsLimit(sample: number, dynamics: number): number;
+/**
+ * The player's audio settings in one place, over the pieces that already exist: bus
+ * volumes apply to an `AudioBus` (`applyToBus`), the preferred engine names what
+ * `resolveMidiSynth` is asked for first, the region and output stage describe the machine
+ * profile a retro package renders for, and captions, dynamics and soften are the
+ * accessibility dials. Everything clamps on the way in, and `snapshot`/`restore` round-trip
+ * the plain-data shape a settings screen persists.
+ *
+ * @example
+ * ```ts
+ * import { AudioSettings } from '@datamoc/mw_games/audio';
+ *
+ * const settings = new AudioSettings({ preferredEngine: 'retro:mt32', soften: 0.4 });
+ * settings.setBusVolume('se', 130);
+ * console.log(settings.snapshot().busVolumes.se); // 100, clamped
+ * ```
+ */
+export declare class AudioSettings {
+    private data;
+    constructor(initial?: Partial<AudioSettingsData>);
+    /** a copy of the current settings, safe to store */
+    snapshot(): AudioSettingsData;
+    /** takes settings in, clamping every dial; a partial update keeps the rest */
+    restore(data: Partial<AudioSettingsData>): void;
+    setBusVolume(kind: BusKind, volume: number): void;
+    /** pushes the per-bus volumes onto a bus's mixer, the settings' one live connection */
+    applyToBus(bus: AudioBus): void;
+    /** the rate content authored for `authored` should play at under this region */
+    playbackRate(authored?: AudioRegion): number;
+    /** the cutoff the current soften amount (and a clean stage's extra softening) asks for */
+    cutoff(sampleRate: number): number;
+    /** one sample through the current dynamics amount */
+    limit(sample: number): number;
+}
+//# sourceMappingURL=Settings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../../src/audio/Settings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAEvD,+FAA+F;AAC/F,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;AAE/C,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACpC,qFAAqF;IACrF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAC;IAClB,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAE,WAAoB,GAAG,MAAM,CAG9F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAIvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,IAAI,CAAoB;IAEhC,YAAY,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,EAWnD;IAED,oDAAoD;IACpD,QAAQ,IAAI,iBAAiB,CAE5B;IAED,8EAA8E;IAC9E,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAY9C;IAED,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAEhD;IAED,uFAAuF;IACvF,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAI9B;IAED,gFAAgF;IAChF,YAAY,CAAC,QAAQ,GAAE,WAAoB,GAAG,MAAM,CAEnD;IAED,0FAA0F;IAC1F,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGjC;IAED,qDAAqD;IACrD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5B;CACD"}

package/dist/audio/Settings.js

@@ -0,0 +1,134 @@
+import { clamp } from '../core/Math.js';
+/**
+ * The playback rate a tune authored for one region runs at on the other: a PAL machine's
+ * 50 Hz clock against NTSC's 60 Hz makes the same file slower and lower, which is the
+ * difference a player who grew up with the other standard hears first.
+ *
+ * @example
+ * ```ts
+ * import { regionPlaybackRate } from '@datamoc/mw_games/audio';
+ *
+ * console.log(regionPlaybackRate('pal', 'ntsc')); // 0.8333..., slower on PAL
+ * console.log(regionPlaybackRate('ntsc', 'ntsc')); // 1, its own region
+ * ```
+ */
+export function regionPlaybackRate(region, authored = 'ntsc') {
+    if (region === authored)
+        return 1;
+    return region === 'pal' ? 50 / 60 : 60 / 50;
+}
+/**
+ * The low-pass cutoff, in hertz, that a `soften` amount asks an output stage for: nothing
+ * at 0, down to a muffled 3.5 kHz at 1, never above what the sample rate can represent.
+ *
+ * @example
+ * ```ts
+ * import { softenCutoff } from '@datamoc/mw_games/audio';
+ *
+ * console.log(softenCutoff(0, 44100)); // 18000, effectively open
+ * console.log(softenCutoff(1, 44100) < softenCutoff(0.5, 44100)); // true, more soften, lower cutoff
+ * ```
+ */
+export function softenCutoff(soften, sampleRate) {
+    const amount = clamp(soften, 0, 1);
+    const cutoff = 18000 * (3500 / 18000) ** amount;
+    return Math.min(cutoff, sampleRate / 2);
+}
+/**
+ * One sample through the dynamics control: at 0 the sample is untouched, and as the amount
+ * rises a soft knee pulls peaks toward full scale without ever passing it, so a loud game
+ * gets quieter peaks rather than clipped ones.
+ *
+ * @example
+ * ```ts
+ * import { dynamicsLimit } from '@datamoc/mw_games/audio';
+ *
+ * console.log(dynamicsLimit(0.5, 0)); // 0.5, untouched
+ * console.log(dynamicsLimit(4, 1) < 1); // true, a hot sample is pulled under full scale
+ * ```
+ */
+export function dynamicsLimit(sample, dynamics) {
+    const amount = clamp(dynamics, 0, 1);
+    if (amount === 0)
+        return sample;
+    const limited = Math.tanh(sample);
+    return sample * (1 - amount) + limited * amount;
+}
+/**
+ * The player's audio settings in one place, over the pieces that already exist: bus
+ * volumes apply to an `AudioBus` (`applyToBus`), the preferred engine names what
+ * `resolveMidiSynth` is asked for first, the region and output stage describe the machine
+ * profile a retro package renders for, and captions, dynamics and soften are the
+ * accessibility dials. Everything clamps on the way in, and `snapshot`/`restore` round-trip
+ * the plain-data shape a settings screen persists.
+ *
+ * @example
+ * ```ts
+ * import { AudioSettings } from '@datamoc/mw_games/audio';
+ *
+ * const settings = new AudioSettings({ preferredEngine: 'retro:mt32', soften: 0.4 });
+ * settings.setBusVolume('se', 130);
+ * console.log(settings.snapshot().busVolumes.se); // 100, clamped
+ * ```
+ */
+export class AudioSettings {
+    constructor(initial = {}) {
+        this.data = {
+            busVolumes: { bgm: 90, bgs: 90, me: 90, se: 90 },
+            preferredEngine: null,
+            region: 'ntsc',
+            outputStage: 'faithful',
+            captions: false,
+            dynamics: 0,
+            soften: 0,
+        };
+        this.restore(initial);
+    }
+    /** a copy of the current settings, safe to store */
+    snapshot() {
+        return { ...this.data, busVolumes: { ...this.data.busVolumes } };
+    }
+    /** takes settings in, clamping every dial; a partial update keeps the rest */
+    restore(data) {
+        if (data.busVolumes) {
+            for (const kind of Object.keys(data.busVolumes)) {
+                this.data.busVolumes[kind] = clamp(data.busVolumes[kind], 0, 100);
+            }
+        }
+        if (data.preferredEngine !== undefined)
+            this.data.preferredEngine = data.preferredEngine;
+        if (data.region !== undefined)
+            this.data.region = data.region;
+        if (data.outputStage !== undefined)
+            this.data.outputStage = data.outputStage;
+        if (data.captions !== undefined)
+            this.data.captions = data.captions;
+        if (data.dynamics !== undefined)
+            this.data.dynamics = clamp(data.dynamics, 0, 1);
+        if (data.soften !== undefined)
+            this.data.soften = clamp(data.soften, 0, 1);
+    }
+    setBusVolume(kind, volume) {
+        this.data.busVolumes[kind] = clamp(volume, 0, 100);
+    }
+    /** pushes the per-bus volumes onto a bus's mixer, the settings' one live connection */
+    applyToBus(bus) {
+        for (const kind of Object.keys(this.data.busVolumes)) {
+            bus.setMixer(kind, { volume: this.data.busVolumes[kind] / 100 });
+        }
+    }
+    /** the rate content authored for `authored` should play at under this region */
+    playbackRate(authored = 'ntsc') {
+        return regionPlaybackRate(this.data.region, authored);
+    }
+    /** the cutoff the current soften amount (and a clean stage's extra softening) asks for */
+    cutoff(sampleRate) {
+        const extra = this.data.outputStage === 'clean' ? 0.25 : 0;
+        return softenCutoff(clamp(this.data.soften + extra, 0, 1), sampleRate);
+    }
+    /** one sample through the current dynamics amount */
+    limit(sample) {
+        return dynamicsLimit(sample, this.data.dynamics);
+    }
+}
+//# sourceMappingURL=Settings.js.map

package/dist/audio/Settings.js.map

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