@weasel-js/audio 1.11.0 → 1.12.0

package/README.md

@@ -180,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,88 @@ 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`.
+     *  A source that stops on its own, as a non-looping file reaching its end does, calls `ended` so the graph can start it again. */
+    start?(when: number, ended?: () => void): 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;
@@ -522,6 +604,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;
 }
@@ -1008,4 +1092,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 };