@algo-wasm/algo-wasm 1.1.0 → 1.2.0

package/dist/load-wasm.d.ts

@@ -0,0 +1,92 @@
+import { EngineCore } from './engine-core.js';
+import type { AlgoWasmGeneratedEvent, AlgoWasmMood, AlgoWasmProfile, AlgoWasmSnapshot, AlgoWasmTrackId } from './types.js';
+/** A compiled and instantiated AlgoWASM binary. */
+export interface AlgoWasmInstantiation {
+    instance: WebAssembly.Instance;
+    module: WebAssembly.Module;
+}
+/**
+ * Fetches and instantiates the AlgoWASM binary.
+ *
+ * Streaming compilation is used when the server sends `application/wasm`. If
+ * the MIME type is wrong, as on some local servers, the file is fetched again
+ * and compiled from bytes instead.
+ *
+ * @throws {AlgoWasmError} With code `wasm_load_failed` when the file cannot
+ * be fetched or compiled.
+ */
+export declare function instantiateAlgoWasm(wasmUrl: string | URL): Promise<AlgoWasmInstantiation>;
+/**
+ * Converts a mood id to its engine index.
+ *
+ * @throws {TypeError} When the mood is not recognised.
+ */
+export declare function moodIndex(mood: AlgoWasmMood): number;
+/**
+ * Converts a track id to its engine index.
+ *
+ * @throws {TypeError} When the track id is not recognised.
+ */
+export declare function trackIndex(trackId: AlgoWasmTrackId): number;
+/**
+ * Typed binding to one engine inside a WASM instance, for use outside an
+ * `AlgoWasmPlayer`, for example to render audio offline.
+ *
+ * Memory ownership: the binding owns the WASM buffers it allocates. Call
+ * `destroy` when finished to free them.
+ *
+ * ```ts
+ * const { instance } = await instantiateAlgoWasm(wasmUrl);
+ * const binding = new AlgoWasmEngineBinding(instance);
+ *
+ * try {
+ *   binding.create(48000, 42n, builtInProfiles.dubstep());
+ *   binding.start();
+ *   binding.renderTo(output);
+ * } finally {
+ *   binding.destroy();
+ * }
+ * ```
+ */
+export declare class AlgoWasmEngineBinding extends EngineCore {
+    /**
+     * Validates the profile and creates the engine.
+     *
+     * @throws {AlgoWasmError} With code `profile_invalid` or `engine_failed`.
+     */
+    create(sampleRate: number, seed: bigint, profile: AlgoWasmProfile): void;
+    /** Re-seeds the engine and restarts the song. */
+    setSeed(seed: bigint): void;
+    /**
+     * Validates and applies a new profile, then restarts the song.
+     *
+     * @throws {AlgoWasmError} With code `profile_invalid` or `engine_failed`.
+     */
+    setProfile(profile: AlgoWasmProfile): void;
+    /**
+     * Sets the mood.
+     *
+     * @throws {TypeError} When the mood is not recognised.
+     */
+    setMood(value: AlgoWasmMood): void;
+    /**
+     * Mutes or unmutes a track.
+     *
+     * @throws {TypeError} When the track id is not recognised.
+     */
+    setMuted(trackId: AlgoWasmTrackId, muted: boolean): void;
+    /**
+     * Solos or unsolos a track.
+     *
+     * @throws {TypeError} When the track id is not recognised.
+     */
+    setSolo(trackId: AlgoWasmTrackId, solo: boolean): void;
+    /** Returns the engine's current state. */
+    snapshot(): AlgoWasmSnapshot;
+    /**
+     * Returns the events generated since the last call, and removes them from
+     * the engine's buffer. The buffer holds up to 512 events, so call this
+     * often enough that it does not fill.
+     */
+    events(): AlgoWasmGeneratedEvent[];
+}