@weasel-js/audio 1.9.3 → 1.10.0

package/README.md

@@ -17,6 +17,10 @@ dedicated Worker instead (`createTickTimer`). The worker is built from an inline
 global, or a Content-Security-Policy without `worker-src blob:` — it falls back
 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`.
+
 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.
 
@@ -30,6 +34,11 @@ Browsers start an `AudioContext` suspended until a user gesture. The engine
 resumes on the first gesture automatically; `play()` before that drops the voice
 with a dev warning rather than queueing it.
 
+`onDone` is called when a voice's source ends: it played out, or was stopped,
+faded or stolen. A voice that never played calls `onDrop(reason)` instead, with
+`'locked'`, `'disposed'`, `'stopped'`, `'unready'`, `'failed'` or `'stale'`, so
+code chaining one sound after another hears about both.
+
 ## Notes and patterns
 
 `playNote` plays a synthesized voice — an `OscillatorNode` under an ADSR
@@ -85,6 +94,45 @@ player.start();
 player.setTempo(140);
 ```
 
+A `step` can be fractional: `{ step: 2.25 }` sounds a quarter of a step after
+step 2, which is how a pattern swings or a hit drags. The player's `detune` is
+cents added to every event, as a number or a function of the event's step, for
+a loop that drifts in pitch. `patternVoicePeaks(events, opts)` returns the most
+voices the pattern holds at once on each bus, to check against `voiceLimit`
+before it plays.
+
+## Generative scoring
+
+`createScore` writes music from a mood instead of choosing a clip. A mood is
+three numbers — `valence` (-1 dark to 1 bright), `tension` and `urgency` (0 to
+1) — and each one moves its own musical parameters: valence picks the mode, the
+register and how open the chords are; tension picks the harmony and how many
+layers build up; urgency picks the tempo, the pulse, the articulation and how
+often the chord changes.
+
+```ts
+const score = createScore(engine, {
+  mood: { valence: -1, tension: 1, urgency: 0 },
+  bus: 'music',
+  onBar: (state) => {
+    label.textContent = `${state.cue.name}: ${state.params.mode}, ${state.params.tempo} bpm`;
+  },
+});
+score.start();
+score.setMood({ valence: 0, tension: 0.7, urgency: 1 }); // from the next bar line
+```
+
+The corners of that space are the stock devices of documentary and news
+scoring, listed in `scoreCues` with a sentence each on what they do: `dread`,
+`investigation`, `wonder` and `urgency`. They work on a listener without asking
+them, so the score says what it is doing: `state()` and `onBar` give the cue in
+force, each cue's share of the mood (`cue.weights`), and every parameter the bar
+was written from. Show it.
+
+The layers underneath are usable on their own: `scoreParams(mood)` resolves a
+mood, `scoreChord` and `scoreBar` write a chord and a bar of pattern events
+from the parameters, and `readScoreCue(mood)` names the cue.
+
 ## Insert effects
 
 Each bus has an ordered insert chain, `engine.bus(name).inserts`, between where
@@ -124,7 +172,7 @@ bed.stop(800);
 ```
 
 It is a voice like the others: a `VoiceHandle`, the bus's inserts and voice
-pool, `cancelKey`, `onDone`, position and pan. What does not carry over:
+pool, `cancelKey`, `onDone`, `onDrop`, position and pan. What does not carry over:
 
 - **No `when`.** The element starts once it has buffered enough; the start is
   not sample-accurate and cannot be booked ahead on the audio clock.

package/dist/index.d.ts

@@ -59,6 +59,7 @@ interface InsertSlot {
     /** Position in the chain, or -1 once removed. */
     index(): number;
 }
+/** Where `InsertChain.add` puts an effect, and whether it starts bypassed. */
 interface InsertAddOptions {
     /** Default: the end of the chain. Clamped. */
     index?: number;
@@ -76,6 +77,7 @@ interface InsertChain {
     clear(): void;
     settled(): Promise<void>;
 }
+/** Options for an insert chain: its crossfade length, and the timers it schedules with. */
 interface InsertChainOptions extends Partial<Timers> {
     /** Crossfade length for every edit, in ms. Default 15. */
     fadeMs?: number;
@@ -186,12 +188,15 @@ interface Envelope {
     /** Default 30. */
     release?: number;
 }
+/** An envelope with every default filled in and every value in range. */
 type ResolvedEnvelope = Required<Envelope>;
+/** One breakpoint of an envelope's curve: a level at a time. */
 interface EnvelopePoint {
     /** ms from the note's start. */
     at: number;
     value: number;
 }
+/** Fill an envelope's defaults, clamping times to zero or more and `sustain` to 0..1. */
 declare function resolveEnvelope(env?: Envelope): ResolvedEnvelope;
 /** The level `t` ms after the start. With `gate`, the release begins that many
  *  ms in, from whatever level the envelope had reached. */
@@ -214,6 +219,7 @@ declare function midiToFrequency(midi: number): number;
 /** MIDI number of a scientific pitch name: C4 is 60. Accepts any run of `#`
  *  or `b` after the letter. */
 declare function noteToMidi(name: string): number;
+/** A pitch in hertz. Throws on a note name it cannot read, and on a frequency that is not positive and finite. */
 declare function toFrequency(pitch: Pitch): number;
 
 /** Which voice a full pool evicts: the earliest started, or the lowest gain. */
@@ -279,8 +285,24 @@ interface PlayOptions {
     when?: number;
     /** `stopKey(key)` stops every voice sharing this key. */
     cancelKey?: string;
+    /** The voice's source ended: it played out, or was stopped, faded, released
+     *  or stolen after it started. */
     onDone?: () => void;
+    /** The voice never got a source, so `onDone` will not be called. Called
+     *  after `play()` has returned, never from inside it. */
+    onDrop?: (reason: VoiceDropReason) => void;
 }
+/**
+ * Why a voice never played:
+ *
+ * - `locked` — the context was not running when it was played.
+ * - `disposed` — the engine was disposed, before the play or while it waited.
+ * - `stopped` — stopped, released or `stopKey`ed before it came due.
+ * - `unready` — its sound was not loaded in this engine when it came due.
+ * - `failed` — its node threw as it started.
+ * - `stale` — it came due while the context was suspended.
+ */
+type VoiceDropReason = 'locked' | 'disposed' | 'stopped' | 'unready' | 'failed' | 'stale';
 /** Controls for one voice from `play()`. Safe to keep past the voice's end:
  *  every setter is then a no-op and `isPlaying()` is false. */
 interface VoiceHandle {
@@ -424,6 +446,10 @@ interface AudioEngineOptions {
      *  replaces the default, and the missing half falls back to `setTimeout`'s. */
     setTimer?: (cb: () => void, ms: number) => unknown;
     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. */
+    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`. */
@@ -493,6 +519,7 @@ interface AudioEngine {
  */
 declare function createAudioEngine(opts?: AudioEngineOptions): AudioEngine;
 
+/** Options for `createFilterEffect`. Unset ones keep the node's defaults. */
 interface FilterEffectOptions {
     /** Default 'lowpass'. */
     type?: BiquadFilterType;
@@ -502,6 +529,7 @@ interface FilterEffectOptions {
     /** dB, for the shelf and peaking types. */
     gain?: number;
 }
+/** A filter insert, with its `BiquadFilterNode` exposed. */
 interface FilterEffect extends InsertEffect {
     readonly filter: BiquadFilterNode;
 }
@@ -514,6 +542,7 @@ interface WetDryMix {
     mix(): number;
     setMix(mix: number, rampMs?: number): void;
 }
+/** Options for `createReverbEffect`. */
 interface ReverbEffectOptions {
     /** The room: an impulse response, loaded or synthesized like any buffer. */
     impulse: AudioBuffer;
@@ -522,11 +551,13 @@ interface ReverbEffectOptions {
     /** Scale the impulse to a consistent level. Default true, the node's own. */
     normalize?: boolean;
 }
+/** A reverb insert, with its `ConvolverNode` exposed. */
 interface ReverbEffect extends InsertEffect, WetDryMix {
     readonly convolver: ConvolverNode;
 }
 /** Convolution reverb from an impulse buffer, with a wet/dry mix. */
 declare function createReverbEffect(ctx: BaseAudioContext, opts: ReverbEffectOptions): ReverbEffect;
+/** Options for `createDelayEffect`. */
 interface DelayEffectOptions {
     /** ms. Default 250. */
     time?: number;
@@ -538,6 +569,7 @@ interface DelayEffectOptions {
      *  of 1000 and `time`. */
     maxTime?: number;
 }
+/** A feedback delay insert, with its `DelayNode` exposed. Ramps are ms. */
 interface DelayEffect extends InsertEffect, WetDryMix {
     readonly delay: DelayNode;
     setTime(ms: number, rampMs?: number): void;
@@ -549,6 +581,7 @@ interface DelayEffect extends InsertEffect, WetDryMix {
 /** A feedback delay with a wet/dry mix. Ramping `setTime` bends the pitch of
  *  the repeats while it moves, as a tape delay does. */
 declare function createDelayEffect(ctx: BaseAudioContext, opts?: DelayEffectOptions): DelayEffect;
+/** Options for `createCompressorEffect`. Unset ones keep the node's defaults. */
 interface CompressorEffectOptions {
     /** dB. */
     threshold?: number;
@@ -562,6 +595,7 @@ interface CompressorEffectOptions {
     /** Linear gain after the compressor, to win back the level it takes. Default 1. */
     makeup?: number;
 }
+/** A compressor insert, with its `DynamicsCompressorNode` and makeup `GainNode` exposed. */
 interface CompressorEffect extends InsertEffect {
     readonly compressor: DynamicsCompressorNode;
     readonly makeup: GainNode;
@@ -582,6 +616,11 @@ interface SchedulerOptions {
     lookahead?: number;
     /** Time between passes, in ms. Default 25. */
     interval?: number;
+    /** An event fired `lateMs` after its time `when`: the passes that should
+     *  have reached it inside the lookahead stalled, and whatever it starts will
+     *  sound late by that much. Never called for an event booked inside the
+     *  lookahead or for a time already past, which no pass was meant to catch. */
+    onLate?: (lateMs: number, when: number) => void;
 }
 /** A queue of callbacks keyed to engine time. See `createScheduler`. */
 interface Scheduler {
@@ -634,7 +673,11 @@ interface TickTimer {
  */
 declare function createTickTimer(): TickTimer;
 
-/** A synth note on a step. `length` is its gate in steps, default 1. */
+/** A synth note on a step. `length` is its gate in steps, default 1.
+ *
+ *  Any event's `step` may be fractional: it is booked with the step it sits in
+ *  and sounds that fraction of a step later, so `2.5` is halfway from step 2 to
+ *  step 3. That is swing, a flam, or a hit that drags. */
 interface PatternNote extends Omit<NoteOptions, 'when' | 'duration'> {
     step: number;
     length?: number;
@@ -650,6 +693,7 @@ interface PatternHit extends Omit<PlayOptions, 'when'> {
     step: number;
     sound: SoundHandle;
 }
+/** Anything a pattern plays on a step. */
 type PatternEvent = PatternNote | PatternNoise | PatternHit;
 /** Options for `createPatternPlayer`. */
 interface PatternPlayerOptions {
@@ -663,10 +707,16 @@ interface PatternPlayerOptions {
     length?: number;
     /** Default true. */
     loop?: boolean;
+    /** Cents added to every event's own `detune`: a number, or a function of
+     *  the event's `step`, for a pattern that drifts in pitch as it plays. A
+     *  function is asked as each event is booked. Default 0. */
+    detune?: PatternDetune;
     /** Called as each step is booked — up to a lookahead ahead of it sounding —
      *  with its index in the pattern and its engine time in ms. */
     onStep?: (step: number, when: number) => void;
 }
+/** See `PatternPlayerOptions.detune`. */
+type PatternDetune = number | ((step: number) => number);
 /** A running sequence of steps. See `createPatternPlayer`. */
 interface PatternPlayer {
     /** Start from step 0 at engine time `when`, default now. No-op while playing. */
@@ -675,11 +725,17 @@ interface PatternPlayer {
     stop(): void;
     playing(): boolean;
     tempo(): number;
-    /** Takes effect from the next step not yet booked. */
+    /** Takes effect from the next step not yet booked. Called from `onStep`,
+     *  that is the step after the one reported, which keeps its own length. */
     setTempo(bpm: number): void;
     /** Takes effect from the next step not yet booked. */
+    setDetune(detune: PatternDetune): void;
+    /** Takes effect from the next step not yet booked. */
     setEvents(events: readonly PatternEvent[], length?: number): void;
 }
+/** Steps in one pass of `events` when no length is given: through the last
+ *  event, rounded up to a whole beat. */
+declare function patternLength(events: readonly PatternEvent[], stepsPerBeat?: number): number;
 /**
  * A step sequencer over `engine`. Each step is one `engine.schedule` booking;
  * when it fires, it books that step's events at the step's exact time and then
@@ -693,6 +749,167 @@ interface PatternPlayer {
  */
 declare function createPatternPlayer(engine: AudioEngine, opts: PatternPlayerOptions): PatternPlayer;
 
+/** Options for `patternVoicePeaks`. The first four mean what they mean to
+ *  `createPatternPlayer`, and should be the values the player is given. */
+interface PatternLoadOptions {
+    tempo: number;
+    stepsPerBeat?: number;
+    length?: number;
+    loop?: boolean;
+    /** The bus of an event that names none: the engine's first. Default 'sfx'. */
+    bus?: string;
+    /** The engine's `lookahead` in ms. Default 100. */
+    lookahead?: number;
+    /** How long a buffer hit sounds, in ms. Default: one step. */
+    hitMs?: (hit: PatternHit) => number;
+}
+/**
+ * The most voices a pattern holds at once on each bus, to set against the
+ * engine's `voiceLimit` before the pattern plays: past the limit, each new
+ * event steals a voice that is still ringing.
+ *
+ * A note or a noise holds its voice through its gate and its envelope's
+ * release. With `loop`, what rings past the end of a pass is counted against
+ * the start of the next.
+ */
+declare function patternVoicePeaks(events: readonly PatternEvent[], opts: PatternLoadOptions): Record<string, number>;
+
+/** Where a score sits on the three axes it is steered by. Values outside a
+ *  range are read as its nearest end. */
+interface ScoreMood {
+    /** -1 dark to 1 bright. */
+    valence: number;
+    /** 0 consonant and settled to 1 dissonant. */
+    tension: number;
+    /** 0 still to 1 driving. */
+    urgency: number;
+}
+/** The scoring devices of factual screen content that a mood can land on. */
+type ScoreCueName = 'dread' | 'investigation' | 'wonder' | 'urgency';
+/** One named device: the mood that produces it, and what it does to a listener
+ *  in words, for a consumer to show beside the score. */
+interface ScoreCue {
+    name: ScoreCueName;
+    mood: ScoreMood;
+    device: string;
+}
+/** The built-in cues: each names a mood and the musical device that carries it. */
+declare const scoreCues: readonly ScoreCue[];
+/** Which cue a mood is applying: the nearest, and how much of each. */
+interface ScoreCueReading {
+    name: ScoreCueName;
+    /** Each cue's share, summing to 1. A mood at a cue's own `mood` is all that cue. */
+    weights: Record<ScoreCueName, number>;
+}
+/** Name the cue a mood is applying, and weigh the others against it by
+ *  inverse squared distance. */
+declare function readScoreCue(mood: ScoreMood): ScoreCueReading;
+/** The modes a score draws on, brightest first. */
+type ScoreMode = 'lydian' | 'ionian' | 'dorian' | 'aeolian' | 'phrygian';
+/** Each mode's seven tones, in semitones above its tonic. */
+declare const scoreModes: Record<ScoreMode, readonly number[]>;
+/** The musical parameters a mood resolves to. Each follows one axis only. */
+interface ScoreParams {
+    /** From valence. */
+    mode: ScoreMode;
+    /** MIDI note of the tonic the chords are built up from. From valence. */
+    register: number;
+    /** Octaves a chord is opened across, 1 to 3. From valence. */
+    spread: number;
+    /** How the tones above a root are chosen: thirds from the mode, stacked
+     *  fourths and fifths, or a minor second and a tritone. From tension. */
+    harmony: 'triadic' | 'quartal' | 'cluster';
+    /** The most layers a pulsed score builds up to. From tension. */
+    layers: number;
+    /** Beats per minute. From urgency. */
+    tempo: number;
+    /** Notes to a beat; 0 is no pulse at all. From urgency. */
+    density: 0 | 1 | 2 | 4;
+    /** From urgency. */
+    articulation: 'sustained' | 'plucked';
+    /** Bars a chord lasts. From urgency. */
+    harmonicRhythm: number;
+    /** Envelope attack in ms. From urgency. */
+    attack: number;
+}
+/** Resolve a mood to the parameters `scoreBar` writes music from. */
+declare function scoreParams(mood: ScoreMood): ScoreParams;
+
+/** Steps in a bar of score: sixteenths in 4/4. */
+declare const SCORE_BAR_STEPS = 16;
+/** How `scoreBar` places and routes its notes. */
+interface ScoreBarOptions {
+    /** Semitones above C for the tonic. Default 0. */
+    tonic?: number;
+    /** Default: the engine's first bus. */
+    bus?: string;
+    /** The level the notes sounding on one step add up to at most. Default 0.5. */
+    gain?: number;
+    /** Chooses the order an ostinato takes a chord's tones in. Default: rising. */
+    seed?: number;
+}
+/**
+ * The chord a score plays, as MIDI notes, root first. `chord` counts chords
+ * since the score began; a cluster stays on the tonic, and the other harmonies
+ * walk a four-chord progression inside the mode.
+ */
+declare function scoreChord(params: ScoreParams, chord: number, tonic?: number): number[];
+/**
+ * One bar of score as pattern events, for a player `SCORE_BAR_STEPS` long.
+ * `bar` counts bars since the score began: it picks the chord, by the harmonic
+ * rhythm, and how many layers a pulsed score has built up to, one more every
+ * two bars. The same arguments always write the same bar.
+ *
+ * With no pulse, the bar is its chord held throughout. With one, the layers
+ * are an ostinato over the chord's tones, a bass on the root, the ostinato
+ * doubled an octave up on the off pulses, and the chord held as a pad.
+ */
+declare function scoreBar(params: ScoreParams, bar: number, opts?: ScoreBarOptions): PatternNote[];
+
+/** What a score is playing in one bar, and why: the mood it was given, the cue
+ *  that mood applies, and the parameters the bar was written from. */
+interface ScoreState {
+    /** Bars since `start`. */
+    bar: number;
+    /** Bars since the cue last changed, which is what a pulsed score's layers
+     *  build up from. */
+    cueBar: number;
+    mood: ScoreMood;
+    cue: ScoreCueReading;
+    params: ScoreParams;
+}
+/** Options for `createScore`. */
+interface ScoreOptions extends ScoreBarOptions {
+    mood: ScoreMood;
+    /** Called as each bar's first step is booked — up to a lookahead before it
+     *  sounds — with what the bar plays and its engine time in ms. */
+    onBar?: (state: ScoreState, when: number) => void;
+}
+/** A running generative score. See `createScore`. */
+interface Score {
+    /** Start from bar 0 at engine time `when`, default now. No-op while playing. */
+    start(when?: number): void;
+    /** Book nothing further, and release every voice the score started. */
+    stop(): void;
+    playing(): boolean;
+    /** The mood last set, which the next bar will take. */
+    mood(): ScoreMood;
+    /** Takes effect at the next bar line. */
+    setMood(mood: ScoreMood): void;
+    /** The bar most recently booked. */
+    state(): ScoreState;
+}
+/**
+ * Music written continuously from a mood rather than chosen from clips. Each
+ * bar is `scoreBar` of the mood's `scoreParams`, booked through a pattern
+ * player, and a new mood lands on the next bar line with its tempo.
+ *
+ * These devices work on a listener without asking them, which is what they are
+ * for. `state()` and `onBar` name the cue in force and every parameter behind
+ * it, so a consumer can show what is being applied as well as play it.
+ */
+declare function createScore(engine: AudioEngine, opts: ScoreOptions): Score;
+
 /** Samples of `color` noise, seeded so every context gets the same loop. The
  *  end is pulled onto the start, so the loop point does not click. */
 declare function noiseSamples(color: NoiseColor, length: number): Float32Array;
@@ -727,4 +944,4 @@ declare const partialPresets: {
     };
 };
 
-export { type Acquisition, type AnalyserTap, type AnalyserTapOptions, type AudioEngine, type AudioEngineOptions, 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 NoiseColor, type NoiseOptions, type NoisePatch, type NoteOptions, type PatternEvent, type PatternHit, type PatternNoise, type PatternNote, type PatternPlayer, type PatternPlayerOptions, type Pitch, type PlayOptions, type ResolvedEnvelope, type ReverbEffect, type ReverbEffectOptions, type Scheduler, type SchedulerOptions, type SoundCache, type SoundHandle, type SpatialOptions, type StealPolicy, type StreamOptions, type SynthPartial, type SynthPatch, type TickTimer, type Vec2, type VoiceFilter, type VoiceHandle, type VoicePool, type VoicePoolOptions, type VoiceRecord, type Waveform, type WetDryMix, createAnalyserTap, createAudioEngine, createBusGraph, createCompressorEffect, createDelayEffect, createFilterEffect, createPatternPlayer, createReverbEffect, createScheduler, createSoundCache, createTickTimer, createVoicePool, envelopeLevel, envelopePoints, midiToFrequency, noiseSamples, noteToMidi, partialPresets, resolveEnvelope, spatialize, toFrequency };
+export { type Acquisition, type AnalyserTap, type AnalyserTapOptions, type AudioEngine, type AudioEngineOptions, 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 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 VoicePool, type VoicePoolOptions, type VoiceRecord, type Waveform, type WetDryMix, createAnalyserTap, createAudioEngine, createBusGraph, createCompressorEffect, createDelayEffect, createFilterEffect, createPatternPlayer, createReverbEffect, createScheduler, createScore, createSoundCache, createTickTimer, createVoicePool, envelopeLevel, envelopePoints, midiToFrequency, noiseSamples, noteToMidi, partialPresets, patternLength, patternVoicePeaks, readScoreCue, resolveEnvelope, scoreBar, scoreChord, scoreCues, scoreModes, scoreParams, spatialize, toFrequency };