@weasel-js/audio 1.10.0 → 1.10.1

package/README.md

@@ -76,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

package/dist/index.d.ts

@@ -944,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 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 };
+/** 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 };

package/dist/index.js

@@ -1889,6 +1889,241 @@ function createScore(engine, opts) {
   };
 }
 
-export { SCORE_BAR_STEPS, 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 };
+// src/biquad.ts
+function biquadCoefficients(type, frequency, sampleRate, Q = 1, gain = 0, into = { b0: 0, b1: 0, b2: 0, a1: 0, a2: 0 }) {
+  const f = Math.min(Math.max(frequency, 1e-3), sampleRate * 0.4999);
+  const w0 = 2 * Math.PI * f / sampleRate;
+  const cos = Math.cos(w0);
+  const sin = Math.sin(w0);
+  const A = 10 ** (gain / 40);
+  const alphaQ = sin / (2 * Math.max(Q, 1e-4));
+  const alphaDb = sin / (2 * 10 ** (Q / 20));
+  const shelf = sin * Math.SQRT2 * Math.sqrt(A);
+  let b0 = (1 - cos) / 2;
+  let b1 = 1 - cos;
+  let b2 = b0;
+  let a0 = 1 + alphaDb;
+  let a1 = -2 * cos;
+  let a2 = 1 - alphaDb;
+  if (type === "highpass") {
+    b0 = b2 = (1 + cos) / 2;
+    b1 = -(1 + cos);
+  } else if (type === "peaking") {
+    b0 = 1 + alphaQ * A;
+    b1 = -2 * cos;
+    b2 = 1 - alphaQ * A;
+    a0 = 1 + alphaQ / A;
+    a2 = 1 - alphaQ / A;
+  } else if (type === "lowshelf") {
+    b0 = A * (A + 1 - (A - 1) * cos + shelf);
+    b1 = 2 * A * (A - 1 - (A + 1) * cos);
+    b2 = A * (A + 1 - (A - 1) * cos - shelf);
+    a0 = A + 1 + (A - 1) * cos + shelf;
+    a1 = -2 * (A - 1 + (A + 1) * cos);
+    a2 = A + 1 + (A - 1) * cos - shelf;
+  } else if (type === "highshelf") {
+    b0 = A * (A + 1 + (A - 1) * cos + shelf);
+    b1 = -2 * A * (A - 1 + (A + 1) * cos);
+    b2 = A * (A + 1 + (A - 1) * cos - shelf);
+    a0 = A + 1 - (A - 1) * cos + shelf;
+    a1 = 2 * (A - 1 - (A + 1) * cos);
+    a2 = A + 1 - (A - 1) * cos - shelf;
+  } else if (type !== "lowpass") {
+    a0 = 1 + alphaQ;
+    a2 = 1 - alphaQ;
+    b0 = type === "bandpass" ? alphaQ : type === "notch" ? 1 : 1 - alphaQ;
+    b1 = type === "bandpass" ? 0 : -2 * cos;
+    b2 = type === "bandpass" ? -alphaQ : type === "notch" ? 1 : 1 + alphaQ;
+  }
+  into.b0 = b0 / a0;
+  into.b1 = b1 / a0;
+  into.b2 = b2 / a0;
+  into.a1 = a1 / a0;
+  into.a2 = a2 / a0;
+  return into;
+}
+function biquadResponseDb(c, hz, sampleRate) {
+  const w = 2 * Math.PI * hz / sampleRate;
+  const c1 = Math.cos(w);
+  const s1 = Math.sin(w);
+  const c2 = Math.cos(2 * w);
+  const s2 = Math.sin(2 * w);
+  const num = (c.b0 + c.b1 * c1 + c.b2 * c2) ** 2 + (c.b1 * s1 + c.b2 * s2) ** 2;
+  const den = (1 + c.a1 * c1 + c.a2 * c2) ** 2 + (c.a1 * s1 + c.a2 * s2) ** 2;
+  return 10 * Math.log10(num / den);
+}
+
+// src/oscillator.ts
+var TAU = 2 * Math.PI;
+var PEAK_POINTS = 4096;
+var TRIANGLE_SUMMED_FROM = 1 / 128;
+function polyBlep(t, dt) {
+  const d = Math.min(dt, 0.5);
+  if (t < d) {
+    const x = t / d;
+    return x + x - x * x - 1;
+  }
+  if (t > 1 - d) {
+    const x = (t - 1) / d;
+    return x * x + x + x + 1;
+  }
+  return 0;
+}
+var sineShape = (phase) => Math.sin(TAU * phase);
+var STEPPED_LEVEL = 1 / 1.17898;
+var BUILT_IN = {
+  sine: sineShape,
+  square: (phase, dt) => STEPPED_LEVEL * ((phase < 0.5 ? 1 : -1) + polyBlep(phase, dt) - polyBlep((phase + 0.5) % 1, dt)),
+  sawtooth: (phase, dt) => {
+    const t = (phase + 0.5) % 1;
+    return STEPPED_LEVEL * (2 * t - 1 - polyBlep(t, dt));
+  },
+  triangle: (phase, dt) => {
+    if (dt < TRIANGLE_SUMMED_FROM) return phase < 0.25 ? 4 * phase : phase < 0.75 ? 2 - 4 * phase : 4 * phase - 4;
+    let v = 0;
+    let sign = 1;
+    for (let k = 1; k * dt < 0.5; k += 2) {
+      v += sign * Math.sin(TAU * k * phase) / (k * k);
+      sign = -sign;
+    }
+    return v * 8 / (Math.PI * Math.PI);
+  }
+};
+function harmonicShape(levels) {
+  const sum = (phase, count) => {
+    let v = 0;
+    for (let k = 1; k <= count; k += 1) v += levels[k - 1] * Math.sin(TAU * k * phase);
+    return v;
+  };
+  let peak = 0;
+  for (let i = 0; i < PEAK_POINTS; i += 1) peak = Math.max(peak, Math.abs(sum(i / PEAK_POINTS, levels.length)));
+  const scale = peak > 0 ? 1 / peak : 0;
+  return (phase, dt) => scale * sum(phase, Math.min(levels.length, Math.ceil(0.5 / dt) - 1));
+}
+function waveShape(wave) {
+  return typeof wave === "string" ? BUILT_IN[wave] : harmonicShape(wave);
+}
+
+// src/voiceKernel.ts
+var tuning = (rate, detune) => rate * 2 ** (detune / 1200);
+function filterStage(spec, sampleRate) {
+  const type = spec.type ?? "lowpass";
+  const amount = spec.amount ?? 0;
+  const env = spec.envelope && amount !== 0 ? resolveEnvelope(spec.envelope) : null;
+  const coefficients = biquadCoefficients(type, spec.frequency, sampleRate, spec.Q, spec.gain);
+  let cutoff = spec.frequency;
+  let z1 = 0;
+  let z2 = 0;
+  return (x, t, gate) => {
+    if (env) {
+      const hz = spec.frequency + amount * envelopeLevel(env, t, gate);
+      if (hz !== cutoff) {
+        cutoff = hz;
+        biquadCoefficients(type, hz, sampleRate, spec.Q, spec.gain, coefficients);
+      }
+    }
+    const y = coefficients.b0 * x + z1;
+    z1 = coefficients.b1 * x - coefficients.a1 * y + z2;
+    z2 = coefficients.b2 * x - coefficients.a2 * y;
+    return y;
+  };
+}
+function createKernel(patch, sampleRate, source) {
+  const env = resolveEnvelope(patch.envelope);
+  const gain = patch.gain ?? 1;
+  const filter = patch.filter ? filterStage(patch.filter, sampleRate) : null;
+  const msPerSample = 1e3 / sampleRate;
+  let gate = patch.duration;
+  let tune = tuning(patch.rate ?? 1, patch.detune ?? 0);
+  let n = 0;
+  let ended = false;
+  return {
+    render(out, from = 0, to = out.length) {
+      if (ended) return false;
+      for (let i = from; i < to; i += 1) {
+        const t = n * msPerSample;
+        if (gate !== void 0 && t >= gate + env.release) {
+          ended = true;
+          return false;
+        }
+        const raw = source(t, tune);
+        out[i] += gain * envelopeLevel(env, t, gate) * (filter ? filter(raw, t, gate) : raw);
+        n += 1;
+      }
+      return true;
+    },
+    release() {
+      const t = n * msPerSample;
+      if (gate === void 0 || t < gate) gate = t;
+    },
+    retune(rate, detune) {
+      tune = tuning(rate, detune);
+    }
+  };
+}
+function createNoteKernel(note, sampleRate) {
+  const from = toFrequency(note.pitch);
+  const glideTo = note.glide ? toFrequency(note.glide.to) : void 0;
+  const glideMs = note.glide?.ms ?? note.duration ?? 100;
+  const linear = note.glide?.curve === "linear";
+  const wave = note.wave ?? "sine";
+  const shape = isInharmonic(wave) ? sineShape : waveShape(wave);
+  const tones = isInharmonic(wave) ? resolvePartials(wave).map((p) => ({ ratio: p.ratio, gain: p.gain, decay: p.decay, phase: 0 })) : [{ ratio: 1, gain: 1, phase: 0 }];
+  return createKernel(note, sampleRate, (t, tune) => {
+    let hz = from;
+    if (glideTo !== void 0) {
+      const k = glideMs > 0 ? Math.min(1, t / glideMs) : 1;
+      hz = linear ? from + (glideTo - from) * k : from * (glideTo / from) ** k;
+    }
+    const cycles = hz * tune / sampleRate;
+    let sum = 0;
+    for (const tone of tones) {
+      const dt = cycles * tone.ratio;
+      if (dt >= 0.5) continue;
+      const level = tone.decay === void 0 ? tone.gain : tone.gain * Math.exp(-t / tone.decay);
+      sum += level * shape(tone.phase, dt);
+      tone.phase = (tone.phase + dt) % 1;
+    }
+    return sum;
+  });
+}
+var loops = /* @__PURE__ */ new Map();
+function noiseLoop(color, sampleRate) {
+  const key = `${color}:${sampleRate}`;
+  let loop = loops.get(key);
+  if (!loop) {
+    loop = noiseSamples(color, Math.round(sampleRate * NOISE_SECONDS));
+    loops.set(key, loop);
+  }
+  return loop;
+}
+function createNoiseKernel(noise, sampleRate, random = Math.random) {
+  const loop = noiseLoop(noise.noise, sampleRate);
+  let at = Math.floor(random() * loop.length);
+  return createKernel(noise, sampleRate, (_t, tune) => {
+    const i = Math.floor(at);
+    const a = loop[i];
+    const sample = a + (loop[(i + 1) % loop.length] - a) * (at - i);
+    at = (at + tune) % loop.length;
+    return sample;
+  });
+}
+function renderWhole(kernel, patch, sampleRate, what) {
+  if (patch.duration === void 0) {
+    throw new RangeError(`@weasel-js/audio: ${what} needs a duration to know where the voice ends`);
+  }
+  const total = patch.duration + resolveEnvelope(patch.envelope).release;
+  const out = new Float32Array(Math.round(total * sampleRate / 1e3));
+  kernel.render(out);
+  return out;
+}
+function renderNote(note, sampleRate) {
+  return renderWhole(createNoteKernel(note, sampleRate), note, sampleRate, "renderNote");
+}
+function renderNoise(noise, sampleRate, random = Math.random) {
+  return renderWhole(createNoiseKernel(noise, sampleRate, random), noise, sampleRate, "renderNoise");
+}
+
+export { SCORE_BAR_STEPS, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map