@driftengine/audio 4.8.2 → 4.8.4

package/README.md

@@ -4,7 +4,7 @@ Layered stems, synthesis, rhythm and kick detection, distance and stereo placeme
 sources, reverb zones a **source** can be inside as well as the listener, and first-order
 ambisonic soundfields decoded through six virtual speakers.
 
-**Cost: 6.1 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 6.3 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/audioHarness.d.ts

@@ -42,6 +42,8 @@ export declare class StubNode {
     readonly stops: number[];
     /** Instants `start` was asked for, so a test can see an offline launch has no lead. */
     readonly starts: number[];
+    /** Offsets into the buffer `start` was asked for, beside `starts`. */
+    readonly offsets: number[];
     type: string;
     buffer: unknown;
     loop: boolean;
@@ -83,7 +85,7 @@ export declare class StubNode {
      */
     connect(target: StubNode, output?: number): StubNode;
     disconnect(): void;
-    start(at?: number): void;
+    start(at?: number, offset?: number): void;
     stop(at?: number): void;
     getByteFrequencyData(): void;
     getFloatFrequencyData(): void;

package/dist/audioHarness.js

@@ -40,6 +40,8 @@ export class StubNode {
     stops = [];
     /** Instants `start` was asked for, so a test can see an offline launch has no lead. */
     starts = [];
+    /** Offsets into the buffer `start` was asked for, beside `starts`. */
+    offsets = [];
     type = '';
     buffer = null;
     loop = false;
@@ -86,8 +88,9 @@ export class StubNode {
         return target;
     }
     disconnect() { }
-    start(at = 0) {
+    start(at = 0, offset = 0) {
         this.starts.push(at);
+        this.offsets.push(offset);
     }
     stop(at = 0) {
         this.stops.push(at);

package/dist/graph.d.ts

@@ -245,7 +245,7 @@ export declare class AudioGraph {
      */
     release(): void;
     /**
-     * Stop the stems and start them again from the top.
+     * Stop the stems and start them again: from the top, or from `fromSec` into the track.
      *
      * A `BufferSource` cannot be rewound — the spec makes it one-shot — so starting
      * over means discarding the sources and creating new ones. That is cheap: a
@@ -256,12 +256,18 @@ export declare class AudioGraph {
      * in its own world. Left running instead, a loop's downbeats land somewhere
      * different on every attempt.
      *
-     * **Returns how long until beat zero is actually heard**, in seconds, because
+     * **`fromSec` is a seek**, for music held to a clock of its own: a demo's frame counter or a
+     * replay's tick has to resume the score where that clock is after every skip, and every stem
+     * starts there at one instant, wrapped by its own length because the stems loop. A caller that
+     * ran its own source into the music bus instead had a track outside every stem's lock. Anything
+     * not a positive number is the top.
+     *
+     * **Returns how long until that place is actually heard**, in seconds, because
      * `launch` schedules a little ahead of now and a caller lining a picture up
      * against the music needs that number rather than an assumption. Zero when
      * nothing started.
      */
-    restart(): number;
+    restart(fromSec?: number): number;
     /**
      * Seconds until the scheduled start of whatever is playing, or 0 if it is
      * already sounding.

package/dist/graph.js

@@ -242,7 +242,7 @@ export class AudioGraph {
         this.launch(this.positionSec);
     }
     /**
-     * Stop the stems and start them again from the top.
+     * Stop the stems and start them again: from the top, or from `fromSec` into the track.
      *
      * A `BufferSource` cannot be rewound — the spec makes it one-shot — so starting
      * over means discarding the sources and creating new ones. That is cheap: a
@@ -253,16 +253,22 @@ export class AudioGraph {
      * in its own world. Left running instead, a loop's downbeats land somewhere
      * different on every attempt.
      *
-     * **Returns how long until beat zero is actually heard**, in seconds, because
+     * **`fromSec` is a seek**, for music held to a clock of its own: a demo's frame counter or a
+     * replay's tick has to resume the score where that clock is after every skip, and every stem
+     * starts there at one instant, wrapped by its own length because the stems loop. A caller that
+     * ran its own source into the music bus instead had a track outside every stem's lock. Anything
+     * not a positive number is the top.
+     *
+     * **Returns how long until that place is actually heard**, in seconds, because
      * `launch` schedules a little ahead of now and a caller lining a picture up
      * against the music needs that number rather than an assumption. Zero when
      * nothing started.
      */
-    restart() {
+    restart(fromSec = 0) {
         this.stopSources();
-        this.started = false;
         this.paused = false;
-        this.start();
+        this.started = true;
+        this.launch(Number.isFinite(fromSec) && fromSec > 0 ? fromSec : 0);
         return this.startsInSec;
     }
     /**

package/dist/registry.d.ts

@@ -1,6 +1,6 @@
 /**
  * Named sound slots, resolved once at load: real file if present, synthesised
- * buffer if not.
+ * buffer if not — or, for a slot registered with no stand-in, a loud failure.
  *
  * Synthesis is a placeholder, never the destination. Addressing every sound by
  * slot means dropping a file into the assets folder replaces it — no code
@@ -22,8 +22,16 @@ export interface SoundSource {
      * the browser decodes all of these natively.
      */
     urls: readonly string[];
-    /** Built only when no candidate is present or usable. */
-    synth: (ctx: BaseAudioContext) => AudioBuffer;
+    /**
+     * Built only when no candidate is present or usable.
+     *
+     * **Omitted, the slot is required.** A stand-in is right for a footstep and wrong for a score
+     * that has to be the file or nothing a game would ship, which until now could not be registered
+     * at all and was decoded outside the registry. A required slot none of whose candidates loads is
+     * recorded in `unbuilt`, and `load` rejects — after every other slot has settled, so one absent
+     * file still silences nothing else — naming each such slot and what it tried.
+     */
+    synth?: (ctx: BaseAudioContext) => AudioBuffer;
 }
 /** How a slot ended up being filled. Useful in dev to see what is still synth. */
 export type SoundOrigin = 'file' | 'synth';

package/dist/registry.js

@@ -79,9 +79,16 @@ export class SoundRegistry {
     async load(ctx) {
         const entries = [...this.sources.entries()];
         await Promise.allSettled(entries.map(([slot, source]) => this.loadFile(ctx, slot, source)));
+        const missing = [];
         for (const [slot, source] of entries) {
             if (this.buffers.has(slot))
                 continue;
+            if (source.synth === undefined) {
+                const tried = source.urls.length === 0 ? 'no candidates' : source.urls.join(', ');
+                this.failed.set(slot, `required, and none of its files loaded: ${tried}`);
+                missing.push(`\`${slot}\` (${tried})`);
+                continue;
+            }
             await new Promise((resolve) => {
                 setTimeout(resolve, 0);
             });
@@ -106,6 +113,10 @@ export class SoundRegistry {
                 this.failed.set(slot, error instanceof Error ? error.message : String(error));
             }
         }
+        if (missing.length > 0) {
+            throw new Error(`SoundRegistry: ${missing.length === 1 ? 'a required slot' : `${missing.length} required slots`} ` +
+                `did not load, and a required slot has no stand-in: ${missing.join('; ')}.`);
+        }
     }
     /** The first candidate that loads and decodes wins; none of them is normal. */
     async loadFile(ctx, slot, source) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/audio",
-  "version": "4.8.2",
+  "version": "4.8.4",
   "description": "Layered stems, synthesis, rhythm analysis and positional placement",
   "license": "Apache-2.0",
   "type": "module",

package/src/audioHarness.ts

@@ -52,6 +52,8 @@ export class StubNode {
   readonly stops: number[] = [];
   /** Instants `start` was asked for, so a test can see an offline launch has no lead. */
   readonly starts: number[] = [];
+  /** Offsets into the buffer `start` was asked for, beside `starts`. */
+  readonly offsets: number[] = [];
   type = '';
   buffer: unknown = null;
   loop = false;
@@ -102,8 +104,9 @@ export class StubNode {
     return target;
   }
   disconnect(): void {}
-  start(at = 0): void {
+  start(at = 0, offset = 0): void {
     this.starts.push(at);
+    this.offsets.push(offset);
   }
   stop(at = 0): void {
     this.stops.push(at);

package/src/graph.ts

@@ -357,7 +357,7 @@ export class AudioGraph {
   }
 
   /**
-   * Stop the stems and start them again from the top.
+   * Stop the stems and start them again: from the top, or from `fromSec` into the track.
    *
    * A `BufferSource` cannot be rewound — the spec makes it one-shot — so starting
    * over means discarding the sources and creating new ones. That is cheap: a
@@ -368,16 +368,22 @@ export class AudioGraph {
    * in its own world. Left running instead, a loop's downbeats land somewhere
    * different on every attempt.
    *
-   * **Returns how long until beat zero is actually heard**, in seconds, because
+   * **`fromSec` is a seek**, for music held to a clock of its own: a demo's frame counter or a
+   * replay's tick has to resume the score where that clock is after every skip, and every stem
+   * starts there at one instant, wrapped by its own length because the stems loop. A caller that
+   * ran its own source into the music bus instead had a track outside every stem's lock. Anything
+   * not a positive number is the top.
+   *
+   * **Returns how long until that place is actually heard**, in seconds, because
    * `launch` schedules a little ahead of now and a caller lining a picture up
    * against the music needs that number rather than an assumption. Zero when
    * nothing started.
    */
-  restart(): number {
+  restart(fromSec = 0): number {
     this.stopSources();
-    this.started = false;
     this.paused = false;
-    this.start();
+    this.started = true;
+    this.launch(Number.isFinite(fromSec) && fromSec > 0 ? fromSec : 0);
     return this.startsInSec;
   }
 

package/src/registry.ts

@@ -1,6 +1,6 @@
 /**
  * Named sound slots, resolved once at load: real file if present, synthesised
- * buffer if not.
+ * buffer if not — or, for a slot registered with no stand-in, a loud failure.
  *
  * Synthesis is a placeholder, never the destination. Addressing every sound by
  * slot means dropping a file into the assets folder replaces it — no code
@@ -23,8 +23,16 @@ export interface SoundSource {
    * the browser decodes all of these natively.
    */
   urls: readonly string[];
-  /** Built only when no candidate is present or usable. */
-  synth: (ctx: BaseAudioContext) => AudioBuffer;
+  /**
+   * Built only when no candidate is present or usable.
+   *
+   * **Omitted, the slot is required.** A stand-in is right for a footstep and wrong for a score
+   * that has to be the file or nothing a game would ship, which until now could not be registered
+   * at all and was decoded outside the registry. A required slot none of whose candidates loads is
+   * recorded in `unbuilt`, and `load` rejects — after every other slot has settled, so one absent
+   * file still silences nothing else — naming each such slot and what it tried.
+   */
+  synth?: (ctx: BaseAudioContext) => AudioBuffer;
 }
 
 /** How a slot ended up being filled. Useful in dev to see what is still synth. */
@@ -117,8 +125,15 @@ export class SoundRegistry {
     const entries = [...this.sources.entries()];
     await Promise.allSettled(entries.map(([slot, source]) => this.loadFile(ctx, slot, source)));
 
+    const missing: string[] = [];
     for (const [slot, source] of entries) {
       if (this.buffers.has(slot)) continue;
+      if (source.synth === undefined) {
+        const tried = source.urls.length === 0 ? 'no candidates' : source.urls.join(', ');
+        this.failed.set(slot, `required, and none of its files loaded: ${tried}`);
+        missing.push(`\`${slot}\` (${tried})`);
+        continue;
+      }
       await new Promise<void>((resolve) => {
         setTimeout(resolve, 0);
       });
@@ -142,6 +157,12 @@ export class SoundRegistry {
         this.failed.set(slot, error instanceof Error ? error.message : String(error));
       }
     }
+    if (missing.length > 0) {
+      throw new Error(
+        `SoundRegistry: ${missing.length === 1 ? 'a required slot' : `${missing.length} required slots`} ` +
+          `did not load, and a required slot has no stand-in: ${missing.join('; ')}.`,
+      );
+    }
   }
 
   /** The first candidate that loads and decodes wins; none of them is normal. */