@algo-wasm/algo-wasm 1.0.0 → 1.2.0

package/dist/profile-spec.d.ts

@@ -0,0 +1,178 @@
+/** The allowed range of one numeric profile field. */
+export interface FieldSpec {
+    min: number;
+    max: number;
+    /** True when the value must be a whole number. */
+    integer?: boolean;
+    /** True when the field may be left out. */
+    optional?: boolean;
+}
+/**
+ * Every numeric field in a profile section, with its allowed range.
+ *
+ * This table is the single description of the profile's numeric limits. The
+ * runtime validator reads it, and the published JSON schema is generated from
+ * it, so the two cannot disagree. The engine repeats the same limits as a
+ * second line of defence.
+ */
+export declare const SECTION_FIELDS: {
+    readonly tempo: {
+        readonly minBpm: FieldSpec;
+        readonly maxBpm: FieldSpec;
+        readonly defaultBpm: FieldSpec;
+    };
+    readonly chordRules: {
+        readonly cadenceWeight: {
+            readonly min: 0;
+            readonly max: 4;
+        };
+        readonly movementWeight: {
+            readonly min: 0;
+            readonly max: 4;
+        };
+        readonly suspendedChance: FieldSpec;
+        readonly brightBorrowChance: FieldSpec;
+    };
+    readonly rhythmRules: {
+        readonly kickDensity: FieldSpec;
+        readonly hatDensity: FieldSpec;
+        readonly percussionDensity: FieldSpec;
+        readonly fillChance: FieldSpec;
+        readonly halfTimeChance: FieldSpec;
+    };
+    readonly bassRules: {
+        readonly density: FieldSpec;
+        readonly slideChance: FieldSpec;
+        readonly accentChance: FieldSpec;
+        readonly octaveJumpChance: FieldSpec;
+        readonly sustainChance: FieldSpec;
+    };
+    readonly melodyRules: {
+        readonly density: FieldSpec;
+        readonly mutationChance: FieldSpec;
+        readonly callResponseChance: FieldSpec;
+        readonly maxRangeSemitones: {
+            readonly min: 1;
+            readonly max: 48;
+            readonly integer: true;
+        };
+    };
+    readonly arrangementRules: {
+        readonly minSectionBars: FieldSpec;
+        readonly maxSectionBars: FieldSpec;
+        readonly futureBars: FieldSpec;
+        readonly resetChance: FieldSpec;
+    };
+    readonly automationRules: {
+        readonly filterMotion: FieldSpec;
+        readonly sendMotion: FieldSpec;
+        readonly panMotion: FieldSpec;
+    };
+    readonly limits: {
+        readonly minSampleRate: {
+            readonly min: 22050;
+            readonly max: 96000;
+            readonly integer: true;
+        };
+        readonly maxSampleRate: {
+            readonly min: 22050;
+            readonly max: 96000;
+            readonly integer: true;
+        };
+        readonly minBpm: {
+            readonly min: 1;
+            readonly max: 1000;
+        };
+        readonly maxBpm: {
+            readonly min: 1;
+            readonly max: 1000;
+        };
+        readonly maxTracks: {
+            readonly min: 11;
+            readonly max: 11;
+            readonly integer: true;
+        };
+        readonly maxVoices: {
+            readonly min: 1;
+            readonly max: 64;
+            readonly integer: true;
+        };
+        readonly maxBarsQueued: {
+            readonly min: 1;
+            readonly max: 64;
+            readonly integer: true;
+        };
+        readonly maxEventsPerBlock: {
+            readonly min: 1;
+            readonly max: 512;
+            readonly integer: true;
+        };
+    };
+};
+/** Numeric fields of the mixer, apart from its per-track entries. */
+export declare const MIXER_FIELDS: {
+    readonly masterGain: FieldSpec;
+    readonly limiterDrive: FieldSpec;
+    readonly delayFeedback: FieldSpec;
+    readonly reverbMix: FieldSpec;
+};
+/** Numeric fields of one patch. */
+export declare const PATCH_FIELDS: {
+    readonly gain: FieldSpec;
+    readonly pan: FieldSpec;
+    readonly attackMs: FieldSpec;
+    readonly decayMs: FieldSpec;
+    readonly sustain: FieldSpec;
+    readonly releaseMs: FieldSpec;
+    readonly filterCutoff: {
+        readonly min: 20;
+        readonly max: 20000;
+    };
+    readonly resonance: FieldSpec;
+    readonly delaySend: FieldSpec;
+    readonly reverbSend: FieldSpec;
+    readonly detuneCents: {
+        readonly min: 0;
+        readonly max: 50;
+        readonly optional: true;
+    };
+    readonly filterEnvOctaves: {
+        readonly min: 0;
+        readonly max: 6;
+        readonly optional: true;
+    };
+    readonly filterEnvDecayMs: {
+        readonly min: 1;
+        readonly max: 10000;
+        readonly optional: true;
+    };
+    readonly lfoRate: {
+        readonly min: 0;
+        readonly max: 8;
+        readonly optional: true;
+    };
+    readonly lfoDepth: {
+        readonly min: 0;
+        readonly max: 4;
+        readonly optional: true;
+    };
+    readonly width: FieldSpec;
+    readonly duck: FieldSpec;
+};
+/** Numeric fields of one mixer track entry. */
+export declare const MIXER_TRACK_FIELDS: {
+    readonly gain: FieldSpec;
+    readonly pan: FieldSpec;
+};
+/** Largest allowed scale weight. */
+export declare const MAX_SCALE_WEIGHT = 1000000;
+type JsonSchema = Record<string, unknown>;
+/**
+ * Builds the JSON schema for a profile from the field tables.
+ *
+ * The build writes the result to `dist/profile-schema.json`. A schema cannot
+ * express every rule, such as the tempo range being ordered, so
+ * `validateProfile` remains the authority.
+ */
+export declare function buildProfileSchema(): JsonSchema;
+export {};

package/dist/profile-wire.d.ts

@@ -0,0 +1,50 @@
+import type { AlgoWasmProfile } from './types.js';
+/**
+ * Version of the flat profile layout. The engine checks it, so a package and
+ * a WASM binary from different releases fail loudly instead of misreading
+ * values.
+ */
+export declare const PROFILE_WIRE_VERSION = 1;
+/** Largest number of weighted scales a profile may list. */
+export declare const MAX_SCALES = 8;
+/** Track ids in the order the engine stores patches and mixer entries. */
+export declare const WIRE_TRACK_IDS: readonly ['kick', 'snare', 'closed_hat', 'open_hat', 'percussion', 'bass', 'chords', 'pad', 'lead', 'arp', 'fx'];
+/** Wave shapes in the order of their numeric ids. */
+export declare const WIRE_WAVE_SHAPES: readonly ['sine', 'triangle', 'saw', 'square', 'pulse', 'noise'];
+/** Scale names in the order of their numeric ids. */
+export declare const WIRE_SCALE_NAMES: readonly ['natural_minor', 'dorian', 'aeolian', 'phrygian_dominant', 'minor_pentatonic'];
+/** Mood ids in the order of their numeric ids. */
+export declare const WIRE_MOODS: readonly ['dark', 'bright', 'tense', 'calm'];
+/** Section names in the order of their numeric ids. */
+export declare const WIRE_SECTIONS: readonly ['intro', 'groove_a', 'groove_b', 'build', 'drop', 'variation', 'breakdown', 'fill', 'transition', 'reset'];
+/**
+ * Values used for the optional profile fields added in 1.2.0. Each default
+ * reproduces the behaviour of earlier releases, so older profiles keep
+ * composing the same songs.
+ */
+export declare const PROFILE_DEFAULTS: {
+    readonly halfTimeChance: 0.3;
+    readonly sustainChance: 0;
+    readonly detuneCents: 0;
+    readonly filterEnvOctaves: 0;
+    readonly filterEnvDecayMs: 120;
+    readonly lfoRate: 0;
+    readonly lfoDepth: 0;
+    readonly width: 0;
+    readonly duck: 0;
+};
+/** Total number of values in the flat profile layout. */
+export declare const PROFILE_WIRE_LENGTH: number;
+/**
+ * Encodes a validated profile as the flat `Float32Array` the engine reads.
+ *
+ * The layout is `[version, tempo x3, chords x4, rhythm x5, bass x5, melody x4,
+ * arrangement x4, automation x3, mixer x4, limits x8, scale count,
+ * (scale id, weight) x8, patches x11, mixer tracks x11]`. Patches and mixer
+ * tracks are written in built-in track order whatever order the profile lists
+ * them in. The engine's `Profile::from_wire` reads the same layout.
+ *
+ * Call `validateProfile` first: this function assumes every field is present
+ * and of the right type.
+ */
+export declare function encodeProfile(profile: AlgoWasmProfile): Float32Array;

package/dist/profile.d.ts

@@ -1,15 +1,39 @@
 import type { AlgoWasmProfile } from './types.js';
+/** The built-in track ids, in the engine's fixed order. */
 export declare const trackIds: readonly ["kick", "snare", "closed_hat", "open_hat", "percussion", "bass", "chords", "pad", "lead", "arp", "fx"];
+/**
+ * Factories for the built-in profiles. Each call returns a fresh copy, so a
+ * profile can be edited without affecting later calls.
+ */
 export declare const builtInProfiles: {
+    /** Mid-1990s Amiga-inspired house with a four-on-the-floor kick. */
     amigaHouse95ish(): AlgoWasmProfile;
+    /** Slower broken-beat profile. */
     downtempoBreakbeat(): AlgoWasmProfile;
+    /** Deep, dub-flavoured house. */
     dubDeepHouse(): AlgoWasmProfile;
+    /** Half-time, sub-led dubstep with a wobbling mid bass. */
+    dubstep(): AlgoWasmProfile;
 };
+/** Returns a deep copy of a profile. */
 export declare function cloneProfile(profile: AlgoWasmProfile): AlgoWasmProfile;
+/**
+ * Checks an untrusted value against every profile rule and returns a deep
+ * copy typed as a profile.
+ *
+ * @throws {AlgoWasmError} With code `profile_invalid` and a message naming
+ * the field and its allowed range.
+ */
 export declare function validateProfile(profile: unknown): AlgoWasmProfile;
+/**
+ * Converts a seed to an unsigned 64-bit integer. Larger values wrap.
+ *
+ * @throws {AlgoWasmError} With code `profile_invalid` when the seed is a
+ * negative or fractional number, or a string that is not decimal digits.
+ */
 export declare function normaliseSeed(seed: bigint | number | string | undefined): bigint;
+/** Splits a 64-bit seed into the two 32-bit halves the engine takes. */
 export declare function splitSeed(seed: bigint): {
     high: number;
     low: number;
 };
-//# sourceMappingURL=profile.d.ts.map

package/dist/types.d.ts

@@ -23,12 +23,23 @@ export interface AlgoWasmRhythmRules {
     hatDensity: number;
     percussionDensity: number;
     fillChance: number;
+    /**
+     * Chance, from 0 to 1, that a broken-beat song puts its snare on beat
+     * three only, for a half-time feel. Ignored when `kickDensity` is 1.
+     * Defaults to 0.3.
+     */
+    halfTimeChance?: number;
 }
 export interface AlgoWasmBassRules {
     density: number;
     slideChance: number;
     accentChance: number;
     octaveJumpChance: number;
+    /**
+     * Chance, from 0 to 1, that a song holds each bass note until the next one
+     * starts instead of using a short gate. Defaults to 0.
+     */
+    sustainChance?: number;
 }
 export interface AlgoWasmMelodyRules {
     density: number;
@@ -60,6 +71,20 @@ export interface AlgoWasmPatch {
     resonance: number;
     delaySend: number;
     reverbSend: number;
+    /** Detune of a second oscillator, in cents from 0 to 50. Defaults to 0 (off). */
+    detuneCents?: number;
+    /** How far the filter opens at note start, in octaves from 0 to 6. Defaults to 0. */
+    filterEnvOctaves?: number;
+    /** Time the filter envelope takes to close, from 1 to 10000 ms. Defaults to 120. */
+    filterEnvDecayMs?: number;
+    /** Tempo-synced filter LFO rate, in cycles per beat from 0 to 8. Defaults to 0 (off). */
+    lfoRate?: number;
+    /** Filter LFO depth, in octaves from 0 to 4. Defaults to 0. */
+    lfoDepth?: number;
+    /** Stereo spread of the track's notes, from 0 (centred) to 1. Defaults to 0. */
+    width?: number;
+    /** How much each kick ducks this track, from 0 (none) to 1. Defaults to 0. */
+    duck?: number;
 }
 export interface AlgoWasmMixerTrackProfile {
     track: AlgoWasmTrackId;
@@ -186,4 +211,3 @@ export interface AlgoWasmOfflineRenderOptions {
 export interface AlgoWasmMidiExportOptions {
     downloadName?: string;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/wire-decode.d.ts

@@ -0,0 +1,18 @@
+import type { AlgoWasmGeneratedEvent, AlgoWasmSnapshot } from './types.js';
+/** Number of values each event occupies in the engine's event buffer. */
+export declare const EVENT_WIRE_SIZE = 5;
+/** Number of values in the engine's binary snapshot. */
+export declare const SNAPSHOT_WIRE_LENGTH: number;
+/**
+ * Decodes the engine's binary snapshot.
+ *
+ * The layout is `[seed high, seed low, sample rate, bpm, bar, beat, section,
+ * energy, intensity, playing]`, then `[muted, solo, level]` for each track.
+ */
+export declare function decodeSnapshot(wire: Float64Array): AlgoWasmSnapshot;
+/**
+ * Decodes the engine's binary event buffer, five values per event:
+ * `[kind, sample, a, b, c]`. Kind 0 is note-on, 3 section-change, 4 bar, and
+ * 5 beat. Unknown kinds are skipped.
+ */
+export declare function decodeEvents(wire: Float64Array): AlgoWasmGeneratedEvent[];

package/dist/worklet/algo-worklet.d.ts

@@ -1,83 +1 @@
-declare const sampleRate: number;
-declare class AudioWorkletProcessor {
-    readonly port: MessagePort;
-    process(inputs: Float32Array[][], outputs: Float32Array[][], parameters: Record<string, Float32Array>): boolean;
-}
-declare function registerProcessor(name: string, processorCtor: typeof AudioWorkletProcessor): void;
-type WasmFn = (...args: number[]) => number;
-type WorkletCommand = {
-    type: string;
-    id?: number;
-    wasmUrl?: string;
-    wasmBytes?: ArrayBuffer;
-    profile?: unknown;
-    seed?: string;
-    sampleRate?: number;
-    volume?: number;
-    value?: number;
-    trackId?: string;
-    muted?: boolean;
-    solo?: boolean;
-    mood?: string;
-    minBpm?: number;
-    maxBpm?: number;
-};
-type WorkletExports = Record<string, WebAssembly.ExportValue>;
-declare class WorkletWasmBinding {
-    private readonly exports;
-    private enginePtr;
-    private renderPtr;
-    private renderLength;
-    private renderView?;
-    constructor(instance: WebAssembly.Instance);
-    create(profile: unknown, seed: string, requestedSampleRate: number, volume: number): void;
-    start(): void;
-    pause(): void;
-    resume(): void;
-    stop(): void;
-    setSeed(seed: string): void;
-    setProfile(profile: unknown): void;
-    setVolume(value: number): void;
-    setEnergy(value: number): void;
-    setIntensity(value: number): void;
-    setMood(mood: string): void;
-    setTempoRange(minBpm: number, maxBpm: number): void;
-    setMuted(trackId: string, muted: boolean): void;
-    setSolo(trackId: string, solo: boolean): void;
-    renderTo(output: Float32Array): void;
-    snapshot(): unknown;
-    events(): unknown[];
-    exportMidi(): Uint8Array;
-    destroy(): void;
-    private get memory();
-    private ensureRenderBuffer;
-    private writeString;
-    private readJson;
-    private callCode;
-    private assertCode;
-    private call;
-    private lastError;
-}
-declare class AlgoWasmProcessor extends AudioWorkletProcessor {
-    private binding?;
-    private playing;
-    private scratch;
-    private eventCountdown;
-    private commandQueue;
-    constructor();
-    process(_inputs: Float32Array[][], outputs: Float32Array[][], _parameters: Record<string, Float32Array>): boolean;
-    private handleCommand;
-    private configure;
-    private applyCommand;
-    private requireBinding;
-    private reply;
-}
-declare function instantiateWorkletWasm(url: string | undefined, wasmBytes: ArrayBuffer | undefined): Promise<WebAssembly.Instance>;
-declare function splitSeed(seed: string): {
-    high: number;
-    low: number;
-};
-declare function clampUnit(value: number): number;
-declare function encodeUtf8(value: string): Uint8Array;
-declare function decodeUtf8(bytes: Uint8Array): string;
-//# sourceMappingURL=algo-worklet.d.ts.map
+export {};