@weasel-js/audio 1.10.1 → 1.11.1

package/README.md

@@ -20,6 +20,11 @@ to `setTimeout`, and a hidden tab books late again.
 The worker times the pass, but the pass itself runs on the main thread, so a
 stall there longer than the lookahead starts whatever came due late. The
 `onLate(lateMs, when)` option reports each one; if it fires, raise `lookahead`.
+Or pass `synthVoices: 'worklet'`: `playNote` and `playNoise` voices are then
+rendered in an `AudioWorkletProcessor` from events posted when they are played,
+so one played ahead of a stall starts on time. The processor loads from a
+`blob:` URL (CSP: `script-src blob:`); until it has, and where it cannot,
+synth voices play on nodes.
 
 A suspended `AudioContext` is a separate matter: its clock stops, and on resume
 the engine drops what came due meanwhile rather than firing it all at once.
@@ -175,6 +180,27 @@ fade is `insertFadeMs`, default 15. A move is a splice out and a splice back in,
 so the moved effect drops out for one fade. A removed effect's `dispose` runs
 once it has left the graph.
 
+## Patchable graph
+
+`engine.graph(bus)` returns a graph of nodes feeding that bus's input (the
+first bus by default), which can be edited while it plays. Every structural
+edit crossfades — `add`, `remove`, `replace`, `connect`, `disconnect` — and
+`set` ramps a param. Sources are `createFileSourceNode` (a looping buffer),
+`createOscillatorNode` and `createNoiseNode`; `createGainNode`,
+`createPanNode`, `createMixNode`, `filterNode`, `delayNode`, `reverbNode` and
+`compressorNode` process, and `insertNode` wraps any insert effect. `tap(id)`
+puts an analyser on a node. The graph is disposed with the engine.
+
+```ts
+const g = engine.graph('music');
+g.add('osc', createOscillatorNode(engine.context, { frequency: 220 }));
+g.add('echo', delayNode(engine.context, { time: 300, feedback: 0.4 }));
+g.connect('osc', { node: 'echo', port: 'in' });
+g.connect('echo', { output: true });
+g.start();
+g.replace('osc', createOscillatorNode(engine.context, { wave: 'square', frequency: 220 }));
+```
+
 ## Streaming
 
 `load` and `decode` hold a whole sound in memory, which is wrong for a long

package/dist/index.d.ts

@@ -24,7 +24,7 @@ interface AnalyserTap {
 }
 /** Attach a new `AnalyserNode` to `source`. The tap only listens, adding no
  *  path to the destination; `dispose()` detaches it. */
-declare function createAnalyserTap(ctx: AudioContext, source: AudioNode, opts?: AnalyserTapOptions): AnalyserTap;
+declare function createAnalyserTap(ctx: BaseAudioContext, source: AudioNode, opts?: AnalyserTapOptions): AnalyserTap;
 
 /** A one-shot timer pair, as `AudioEngineOptions.setTimer` takes it. */
 interface Timers {
@@ -127,6 +127,87 @@ type BusGraphOptions = InsertChainOptions;
  */
 declare function createBusGraph(ctx: AudioContext, names: string[], opts?: BusGraphOptions): BusGraph;
 
+/** What a node factory returns and the graph wraps. `inputs` is empty for a source. */
+interface GraphNodeDef {
+    readonly inputs: Readonly<Record<string, AudioNode>>;
+    readonly output: AudioNode;
+    /** `rampMs` is always passed; the graph supplies its fade when the caller gives none. */
+    readonly params: Readonly<Record<string, (value: number, rampMs: number) => void>>;
+    /** Sources only. `when` is context seconds. Called when the graph starts, or on add/replace while it runs. A source must be startable again after `stop`. */
+    start?(when: number): void;
+    /** Sources only. Stop at `when` (context seconds). */
+    stop?(when: number): void;
+    /** Called once, after the node has faded out of the graph. */
+    dispose?(): void;
+}
+/** A connection's far end: a node's named input port, or the graph's output. */
+type GraphTarget = {
+    node: string;
+    port: string;
+} | {
+    output: true;
+};
+/** One edit to an `AudioGraph`, applied by its `apply` in order. */
+type GraphPatch = {
+    kind: 'add';
+    id: string;
+    def: GraphNodeDef;
+} | {
+    kind: 'remove';
+    id: string;
+} | {
+    kind: 'replace';
+    id: string;
+    def: GraphNodeDef;
+} | {
+    kind: 'connect';
+    from: string;
+    to: GraphTarget;
+} | {
+    kind: 'disconnect';
+    from: string;
+    to: GraphTarget;
+} | {
+    kind: 'set';
+    id: string;
+    param: string;
+    value: number;
+    rampMs?: number;
+};
+/** Options for `AudioGraph`: the crossfade length (`fadeMs`) and any timer overrides. */
+interface AudioGraphOptions extends Partial<Timers> {
+    /** Crossfade for every structural edit, and the default ramp for `set`, in ms. Default 15. */
+    fadeMs?: number;
+}
+/** A patchable graph of nodes that can be added, wired and set while it plays. */
+interface AudioGraph {
+    add(id: string, def: GraphNodeDef): void;
+    remove(id: string): void;
+    replace(id: string, def: GraphNodeDef): void;
+    connect(from: string, to: GraphTarget): void;
+    disconnect(from: string, to: GraphTarget): void;
+    set(id: string, param: string, value: number, rampMs?: number): void;
+    /** Applies in order; each patch calls the method of the same name.
+     *  A structural error anywhere in the list throws before anything changes.
+     *  A param write that throws is skipped; the rest apply, then its error is rethrown. */
+    apply(patches: readonly GraphPatch[]): void;
+    /** Start every source now, and every source added later, until `stop`. */
+    start(): void;
+    /** Fade the graph's output to silence over `fadeMs`, then stop every source. */
+    stop(): void;
+    playing(): boolean;
+    has(id: string): boolean;
+    ids(): string[];
+    /** Listens to a node's output; survives `replace`; disposed with the node. */
+    tap(id: string, opts?: AnalyserTapOptions): AnalyserTap;
+    /** Resolves once no fade is in flight. */
+    settled(): Promise<void>;
+    /** Cancels fades, stops sources, disposes every def and tap, disconnects from the destination.
+     *  While it may be sounding on a running context, it first fades the output out over `fadeMs`;
+     *  every mutator throws from the call on. */
+    dispose(): void;
+}
+
 /** Opaque reference to a decoded sound. Mirrors `TextureHandle` in core. */
 interface SoundHandle {
     readonly id: string;
@@ -448,12 +529,26 @@ interface AudioEngineOptions {
     clearTimer?: (handle: unknown) => void;
     /** A voice or an `engine.schedule` callback came due `lateMs` after its
      *  time `when`, both in engine ms: the main thread stalled for longer than
-     *  the lookahead covers, and the voice sounded late by that much. */
+     *  the lookahead covers, and the voice sounded late by that much. A
+     *  `synthVoices: 'worklet'` voice is never reported: it was not late. */
     onLate?: (lateMs: number, when: number) => void;
     /** Crossfade for every insert-chain edit and bypass, in ms. Default 15. */
     insertFadeMs?: number;
     /** Uniform in [0, 1), for where in its loop a noise voice starts. Default `Math.random`. */
     random?: () => number;
+    /**
+     * Where `playNote` and `playNoise` make their samples. Default `'nodes'`:
+     * oscillator and buffer nodes, built when the scheduler fires, so a main
+     * thread stalled past the lookahead starts the voice late. `'worklet'`
+     * renders them in an `AudioWorkletProcessor` from events posted at the
+     * call, so a voice played ahead of a stall still starts on time. Its handle,
+     * bus pool, stealing, pan and position behave as a node voice's do.
+     *
+     * The processor loads from a `blob:` URL, which a CSP must allow under
+     * `script-src`. Until it has loaded — `unlock()` waits for it — and on a
+     * context with no `audioWorklet`, synth voices play on nodes.
+     */
+    synthVoices?: 'nodes' | 'worklet';
 }
 
 /** A sound engine: named mix buses, a per-bus voice pool, lookahead
@@ -508,6 +603,8 @@ interface AudioEngine {
      *  for a future `when` is not counted until it starts. */
     activeVoices(bus?: string): number;
     analyser(busName?: string, opts?: AnalyserTapOptions): AnalyserTap;
+    /** A graph feeding `bus`'s input (default: the first bus). Disposed with the engine. */
+    graph(bus?: string): AudioGraph;
     setListener(p: Vec2, opts?: SpatialOptions): void;
     dispose(): void;
 }
@@ -631,8 +728,12 @@ interface Scheduler {
      *  true time to `source.start()` rather than "now". It runs on the first
      *  pass whose lookahead window reaches it — or, when the window already
      *  covers it and the scheduler is running, at the end of the current task,
-     *  in time order with everything else then due. */
-    schedule(when: number, fire: (when: number) => void, key?: string): void;
+     *  in time order with everything else then due. `reportLate: false` keeps
+     *  it from `onLate`, for a callback whose work no longer depends on when it
+     *  runs. */
+    schedule(when: number, fire: (when: number) => void, key?: string, opts?: {
+        reportLate?: boolean;
+    }): void;
     /** Drop queued events with this key. A pass takes its whole batch out of the
      *  queue before firing any of it, so a callback cannot cancel a sibling that
      *  came due alongside it. */
@@ -990,4 +1091,78 @@ declare function biquadCoefficients(type: BiquadFilterType, frequency: number, s
 /** How much a filter with coefficients `c` passes at `hz`, in dB. */
 declare function biquadResponseDb(c: BiquadCoefficients, hz: number, sampleRate: number): number;
 
-export { type Acquisition, type AnalyserTap, type AnalyserTapOptions, type AudioEngine, type AudioEngineOptions, type BiquadCoefficients, type BusGraph, type BusGraphOptions, type BusHandle, type CompressorEffect, type CompressorEffectOptions, type DelayEffect, type DelayEffectOptions, type Envelope, type EnvelopePoint, type FilterEffect, type FilterEffectOptions, type Glide, type Inharmonic, type InsertAddOptions, type InsertChain, type InsertChainOptions, type InsertEffect, type InsertSlot, type KernelNoise, type KernelNote, type NoiseColor, type NoiseOptions, type NoisePatch, type NoteOptions, type PatternDetune, type PatternEvent, type PatternHit, type PatternLoadOptions, type PatternNoise, type PatternNote, type PatternPlayer, type PatternPlayerOptions, type Pitch, type PlayOptions, type ResolvedEnvelope, type ReverbEffect, type ReverbEffectOptions, SCORE_BAR_STEPS, type Scheduler, type SchedulerOptions, type Score, type ScoreBarOptions, type ScoreCue, type ScoreCueName, type ScoreCueReading, type ScoreMode, type ScoreMood, type ScoreOptions, type ScoreParams, type ScoreState, type SoundCache, type SoundHandle, type SpatialOptions, type StealPolicy, type StreamOptions, type SynthPartial, type SynthPatch, type TickTimer, type Vec2, type VoiceDropReason, type VoiceFilter, type VoiceHandle, type VoiceKernel, type VoicePool, type VoicePoolOptions, type VoiceRecord, type Waveform, type WetDryMix, biquadCoefficients, biquadResponseDb, createAnalyserTap, createAudioEngine, createBusGraph, createCompressorEffect, createDelayEffect, createFilterEffect, createNoiseKernel, createNoteKernel, createPatternPlayer, createReverbEffect, createScheduler, createScore, createSoundCache, createTickTimer, createVoicePool, envelopeLevel, envelopePoints, midiToFrequency, noiseSamples, noteToMidi, partialPresets, patternLength, patternVoicePeaks, readScoreCue, renderNoise, renderNote, resolveEnvelope, scoreBar, scoreChord, scoreCues, scoreModes, scoreParams, spatialize, toFrequency };
+/** Options for `impulseResponse`: the tail's decay, channel count and noise seed. */
+interface ImpulseResponseOptions {
+    /** How far the tail falls by its end, dB. Default 60 (an RT60). */
+    decayDb?: number;
+    /** Default 2. */
+    channels?: number;
+    /** Seed for the noise, so the same call makes the same buffer. Default 1. */
+    seed?: number;
+}
+/** Noise under an exponential decay that falls `decayDb` over `seconds`. */
+declare function impulseResponse(ctx: BaseAudioContext, seconds: number, opts?: ImpulseResponseOptions): AudioBuffer;
+
+/**
+ * A patchable graph of node defs feeding `destination`. Every structural edit
+ * fades: a connection opens through its own gain and closes through it before
+ * the cut, and a removed node leaves once its edges have closed.
+ */
+declare function createAudioGraph(ctx: BaseAudioContext, destination: AudioNode, opts?: AudioGraphOptions): AudioGraph;
+
+/** The waves an oscillator node takes: any `Waveform` except an inharmonic one. */
+type OscillatorWave = Exclude<Waveform, Inharmonic>;
+/** Options for `createFileSourceNode`: the buffer to play and whether it loops. */
+interface FileSourceNodeOptions {
+    buffer: AudioBuffer;
+    /** Default true. */
+    loop?: boolean;
+}
+/** Plays a buffer, picking up where `stop` left it. Params: `rate`, `level`. */
+declare function createFileSourceNode(ctx: BaseAudioContext, opts: FileSourceNodeOptions): GraphNodeDef;
+/** Options for `createOscillatorNode`: the wave shape and starting frequency. */
+interface OscillatorNodeOptions {
+    /** Default 'sine'. An array is the amplitude of each whole-number partial. */
+    wave?: OscillatorWave;
+    /** Hz. Default 440. */
+    frequency?: number;
+}
+/** A tone. Params: `frequency`, `detune`, `level`. */
+declare function createOscillatorNode(ctx: BaseAudioContext, opts: OscillatorNodeOptions): GraphNodeDef;
+/** Options for `createNoiseNode`: the noise color whose shared buffer it loops. */
+interface NoiseNodeOptions {
+    color: NoiseColor;
+}
+/** A loop of the shared noise buffer for its color. Param: `level`. */
+declare function createNoiseNode(ctx: BaseAudioContext, opts: NoiseNodeOptions): GraphNodeDef;
+
+/** A graph node that multiplies its input by a gain: port `in`; param `gain`. */
+declare function createGainNode(ctx: BaseAudioContext, opts?: {
+    gain?: number;
+}): GraphNodeDef;
+/** A graph node that pans its input in stereo: port `in`; param `pan`. */
+declare function createPanNode(ctx: BaseAudioContext, opts?: {
+    pan?: number;
+}): GraphNodeDef;
+/** One port and one level param per name in `inputs`, summed into `output`. */
+declare function createMixNode(ctx: BaseAudioContext, opts: {
+    inputs: readonly string[];
+}): GraphNodeDef;
+/** Wrap an insert effect as a node with one port, `in`. */
+declare function insertNode(effect: InsertEffect, params: GraphNodeDef['params']): GraphNodeDef;
+/** A graph node over a filter insert: port `in`; params `frequency`, `Q`, `gain`. */
+declare function filterNode(ctx: BaseAudioContext, opts?: FilterEffectOptions): GraphNodeDef;
+/** A graph node over a delay insert: port `in`; params `time` (ms), `feedback`, `mix`. */
+declare function delayNode(ctx: BaseAudioContext, opts?: DelayEffectOptions): GraphNodeDef;
+/** Options for `reverbNode`: the reverb effect's options, plus an `impulse` or the `seconds` of a synthesized one. */
+type ReverbNodeOptions = Omit<ReverbEffectOptions, 'impulse'> & {
+    impulse?: AudioBuffer;
+    /** Length of the synthesized impulse when none is given. Default 2. */
+    seconds?: number;
+};
+/** A graph node over a reverb insert: port `in`; param `mix`. */
+declare function reverbNode(ctx: BaseAudioContext, opts?: ReverbNodeOptions): GraphNodeDef;
+/** A graph node over a compressor insert: port `in`; params `threshold`, `knee`, `ratio`, `attack` (ms), `release` (ms), `makeup`. */
+declare function compressorNode(ctx: BaseAudioContext, opts?: CompressorEffectOptions): GraphNodeDef;
+
+export { type Acquisition, type AnalyserTap, type AnalyserTapOptions, type AudioEngine, type AudioEngineOptions, type AudioGraph, type AudioGraphOptions, type BiquadCoefficients, type BusGraph, type BusGraphOptions, type BusHandle, type CompressorEffect, type CompressorEffectOptions, type DelayEffect, type DelayEffectOptions, type Envelope, type EnvelopePoint, type FileSourceNodeOptions, type FilterEffect, type FilterEffectOptions, type Glide, type GraphNodeDef, type GraphPatch, type GraphTarget, type ImpulseResponseOptions, type Inharmonic, type InsertAddOptions, type InsertChain, type InsertChainOptions, type InsertEffect, type InsertSlot, type KernelNoise, type KernelNote, type NoiseColor, type NoiseNodeOptions, type NoiseOptions, type NoisePatch, type NoteOptions, type OscillatorNodeOptions, type OscillatorWave, type PatternDetune, type PatternEvent, type PatternHit, type PatternLoadOptions, type PatternNoise, type PatternNote, type PatternPlayer, type PatternPlayerOptions, type Pitch, type PlayOptions, type ResolvedEnvelope, type ReverbEffect, type ReverbEffectOptions, type ReverbNodeOptions, SCORE_BAR_STEPS, type Scheduler, type SchedulerOptions, type Score, type ScoreBarOptions, type ScoreCue, type ScoreCueName, type ScoreCueReading, type ScoreMode, type ScoreMood, type ScoreOptions, type ScoreParams, type ScoreState, type SoundCache, type SoundHandle, type SpatialOptions, type StealPolicy, type StreamOptions, type SynthPartial, type SynthPatch, type TickTimer, type Vec2, type VoiceDropReason, type VoiceFilter, type VoiceHandle, type VoiceKernel, type VoicePool, type VoicePoolOptions, type VoiceRecord, type Waveform, type WetDryMix, biquadCoefficients, biquadResponseDb, compressorNode, createAnalyserTap, createAudioEngine, createAudioGraph, createBusGraph, createCompressorEffect, createDelayEffect, createFileSourceNode, createFilterEffect, createGainNode, createMixNode, createNoiseKernel, createNoiseNode, createNoteKernel, createOscillatorNode, createPanNode, createPatternPlayer, createReverbEffect, createScheduler, createScore, createSoundCache, createTickTimer, createVoicePool, delayNode, envelopeLevel, envelopePoints, filterNode, impulseResponse, insertNode, midiToFrequency, noiseSamples, noteToMidi, partialPresets, patternLength, patternVoicePeaks, readScoreCue, renderNoise, renderNote, resolveEnvelope, reverbNode, scoreBar, scoreChord, scoreCues, scoreModes, scoreParams, spatialize, toFrequency };