@weasel-js/audio 1.9.4 → 1.10.1

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.
 
@@ -72,6 +76,21 @@ engine.playNoise({
 });
 ```
 
+`renderNote` and `renderNoise` compute the same voices as samples, with no
+`AudioContext`: a `Float32Array` of the whole note through its release, to put
+in an `AudioBuffer` and `register`. `createNoteKernel` and `createNoiseKernel`
+are the block-at-a-time form, with `release()` and `retune()`, for rendering
+inside an `AudioWorkletProcessor`. A square or a sawtooth is band-limited and a
+harmonic past Nyquist is left out, so they do not alias; pan, position, and
+routing are not a kernel's.
+
+```ts
+const samples = renderNote({ pitch: 'C5', wave: partialPresets.bell, duration: 1500 }, ctx.sampleRate);
+const buffer = ctx.createBuffer(1, samples.length, ctx.sampleRate);
+buffer.getChannelData(0).set(samples);
+const bell = engine.register(buffer);
+```
+
 `createPatternPlayer` is a step sequencer on top. Events sit on steps — a note
 or a noise with a `length` in steps, or a buffer `sound` — and each step is
 booked through `engine.schedule` only when the lookahead window reaches it, so `setTempo` and
@@ -90,6 +109,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

package/dist/index.d.ts

@@ -446,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`. */
@@ -612,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 {
@@ -664,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;
@@ -694,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. */
@@ -706,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
@@ -724,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;
@@ -758,4 +944,50 @@ 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 VoiceDropReason, 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 };
+/** What of a `playNote` call shapes its samples. Routing, position, and timing
+ *  belong to whatever plays them. */
+type KernelNote = Pick<NoteOptions, 'pitch' | 'wave' | 'envelope' | 'glide' | 'filter' | 'duration' | 'gain' | 'detune'>;
+/** What of a `playNoise` call shapes its samples. */
+type KernelNoise = Pick<NoiseOptions, 'noise' | 'envelope' | 'filter' | 'duration' | 'gain' | 'rate' | 'detune'>;
+/** One voice, rendered a block at a time. */
+interface VoiceKernel {
+    /** Add the voice's next samples into `out[from..to)`, the whole of `out` by
+     *  default. False once the voice has ended; it adds nothing from then on. */
+    render(out: Float32Array, from?: number, to?: number): boolean;
+    /** Note-off at the next sample: the envelopes release from wherever they
+     *  have got to. Does nothing once the gate has closed. */
+    release(): void;
+    /** What `setRate` and `setDetune` do to a sounding voice. `detune` is cents. */
+    retune(rate: number, detune: number): void;
+}
+/** A `playNote` voice. Throws on a bad pitch or partial, as `playNote` does. */
+declare function createNoteKernel(note: KernelNote, sampleRate: number): VoiceKernel;
+/** A `playNoise` voice. `random` picks where in the loop it starts. */
+declare function createNoiseKernel(noise: KernelNoise, sampleRate: number, random?: () => number): VoiceKernel;
+/** A whole note as samples, through its release: `duration + release` ms at
+ *  `sampleRate`. Put them in an `AudioBuffer` and `engine.register` it to play
+ *  the note as a sound. */
+declare function renderNote(note: KernelNote, sampleRate: number): Float32Array;
+/** A whole noise voice as samples, through its release. */
+declare function renderNoise(noise: KernelNoise, sampleRate: number, random?: () => number): Float32Array;
+
+/** A biquad's coefficients, already divided by `a0`. */
+interface BiquadCoefficients {
+    b0: number;
+    b1: number;
+    b2: number;
+    a1: number;
+    a2: number;
+}
+/**
+ * The coefficients a `BiquadFilterNode` of `type` runs at `frequency`, by the
+ * formulas in the Web Audio specification. `Q` is in dB for a lowpass or a
+ * highpass and a plain quality factor for the rest, as it is on the node, and
+ * `gain` is dB, read by the shelves and the peaking filter only. Pass `into`
+ * to have them written to an object you keep, which allocates nothing.
+ */
+declare function biquadCoefficients(type: BiquadFilterType, frequency: number, sampleRate: number, Q?: number, gain?: number, into?: BiquadCoefficients): BiquadCoefficients;
+/** 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 };