@denaudio/den 0.0.0-stage → 0.1.0

package/dist/freeze-reverb.js

@@ -0,0 +1,61 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+// Exact binary representation scaling, not audio normalization. Keeps the
+// smallest f32 excitations above the native tiny-state scrub threshold.
+const SCALE = 2 ** 256;
+const ROWS = [[1, 1, 1, 1], [1, -1, 1, -1], [1, 1, -1, -1], [1, -1, -1, 1]];
+/** Wet-only four-line integer-delay FDN. Call tick exactly once per sample.
+ * The fully frozen, unforced real-arithmetic network preserves stored energy.
+ * Actual f64 state has rounding and very-small-state limits, not perpetual
+ * exact energy. Finite normalized inputs and adequate output headroom required.
+ * No interpolation, damping filter, shimmer, limiter, dry path or normalization.
+ */
+export const freezeReverb = defineSubgraph((config) => {
+    const { sampleRate, roomScale = 1, decaySeconds = 1.5, transitionSamples = 256 } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000 ||
+        !Number.isFinite(roomScale) || roomScale < 0.5 || roomScale > 2 ||
+        !Number.isFinite(decaySeconds) || decaySeconds < 0.1 || decaySeconds > 10 ||
+        !Number.isInteger(transitionSamples) || transitionSamples < 0 || transitionSamples > 192000) {
+        throw new RangeError('freezeReverb requires integer sampleRate [8000,192000], roomScale [0.5,2], decaySeconds [0.1,10], integer transitionSamples [0,192000]');
+    }
+    const steps = Math.max(1, transitionSamples);
+    const progress = state.i32(0).named('freezeProgress');
+    const lines = [0.0297, 0.0371, 0.0411, 0.0437].map((seconds, index) => {
+        const size = Math.round(seconds * roomScale * sampleRate);
+        return {
+            size,
+            gain: 10 ** (-3 * size / (sampleRate * decaySeconds)),
+            history: state.buffer.f64({ size }).expose({ name: `line${index}/historyScaled`, snapshot: 'persistent' }),
+            cursor: state.i32(0).named(`line${index}/cursor`),
+            valid: state.i32(0).named(`line${index}/valid`),
+            wet: state.f64(0).expose({ name: `line${index}/wetScaled`, snapshot: 'transient' }),
+        };
+    });
+    return {
+        tick(inputLeft, inputRight, c) {
+            const next = transitionSamples === 0
+                ? select(c.freeze, i32(1), i32(0))
+                : select(c.freeze, select(progress.read().lt(steps), progress.read().add(1), i32(steps)), select(progress.read().gt(0), progress.read().sub(1), i32(0)));
+            progress.write(select(c.reset, i32(0), next));
+            const amount = f64(progress.read()).div(steps);
+            const excitation = f64(1).sub(amount);
+            // Materialize every outgoing sample before any buffer write. Integer
+            // cursors avoid the fractional seconds/interpolation of delayReadhead.
+            for (const line of lines) {
+                line.wet.write(select(c.reset.or(line.valid.read().lt(line.size)), f64(0), line.history.read(line.cursor.read())));
+            }
+            const returns = lines.map(line => line.wet.read().mul(amount.add(excitation.mul(line.gain))));
+            const left = select(c.reset, f64(0), f64(inputLeft).mul(SCALE).mul(excitation));
+            const right = select(c.reset, f64(0), f64(inputRight).mul(SCALE).mul(excitation));
+            for (let row = 0; row < lines.length; row++) {
+                const line = lines[row];
+                const feedback = returns.reduce((sum, value, column) => sum.add(value.mul(ROWS[row][column] * 0.5)), f64(0));
+                const injection = left.add(right.mul(ROWS[1][row])).mul(0.5);
+                line.history.write(select(c.reset, i32(0), line.cursor.read()), injection.add(feedback));
+                line.cursor.write(select(c.reset, i32(0), select(line.cursor.read().eq(line.size - 1), i32(0), line.cursor.read().add(1))));
+                line.valid.write(select(c.reset, i32(0), select(line.valid.read().lt(line.size), line.valid.read().add(1), i32(line.size))));
+            }
+            const output = (row) => f32(lines.reduce((sum, line, column) => sum.add(line.wet.read().mul(ROWS[row][column] * 0.5)), f64(0)).div(SCALE));
+            return { left: output(2), right: output(3), freezeAmount: f32(amount), frozen: progress.read().eq(steps) };
+        },
+    };
+});

package/dist/frequency-shifter.d.ts

@@ -0,0 +1,24 @@
+import { type Node } from '@unworklet/core';
+/** Matched real/Hilbert group delay; the FIR transient spans 63 samples. */
+export declare const FREQUENCY_SHIFTER_LATENCY_SAMPLES = 31;
+export interface FrequencyShifterConfig {
+    sampleRate: number;
+}
+export interface FrequencyShifterControls {
+    /** Signed Hz, clamped to [-sampleRate/4, sampleRate/4]. Zero holds phase. */
+    shiftHz: Node<'f32'>;
+    /** Linear, latency-aligned dry/wet blend, clamped to [0,1]. */
+    mix: Node<'f32'>;
+    /** Select delayed dry; history and oscillator continue running. */
+    bypass: Node<'bool'>;
+    /** Level reset: silence/discard this sample, clear history and phase. */
+    reset: Node<'bool'>;
+}
+/** Fixed 63-tap Blackman Hilbert frequency shifter. Call once per sample.
+ * Finite controls and normalized finite input [-1,1] required. Output may exceed
+ * unity. Approximate single-sideband behavior only in the documented useful
+ * band; there is no input bandpass, antialiasing, pitch-ratio or time stretching.
+ */
+export declare const frequencyShifter: import("@unworklet/core").SubgraphDecl<[config: FrequencyShifterConfig], {
+    tick(input: Node<"f32">, c: FrequencyShifterControls): Node<"f32">;
+}>;

package/dist/frequency-shifter.js

@@ -0,0 +1,57 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+/** Matched real/Hilbert group delay; the FIR transient spans 63 samples. */
+export const FREQUENCY_SHIFTER_LATENCY_SAMPLES = 31;
+// Full-cycle degree-15 sine with f64 arithmetic and a <7e-12 remainder.
+function sine(cycles) {
+    const p = cycles.sub(cycles.add(0.5).floor());
+    const folded = select(p.gt(0.25), f64(0.5).sub(p), select(p.lt(-0.25), f64(-0.5).sub(p), p));
+    const angle = folded.mul(2 * Math.PI), square = angle.mul(angle);
+    return angle.mul(f64(-1 / 1307674368000).mul(square).add(1 / 6227020800).mul(square).sub(1 / 39916800)
+        .mul(square).add(1 / 362880).mul(square).sub(1 / 5040)
+        .mul(square).add(1 / 120).mul(square).sub(1 / 6).mul(square).add(1));
+}
+/** Fixed 63-tap Blackman Hilbert frequency shifter. Call once per sample.
+ * Finite controls and normalized finite input [-1,1] required. Output may exceed
+ * unity. Approximate single-sideband behavior only in the documented useful
+ * band; there is no input bandpass, antialiasing, pitch-ratio or time stretching.
+ */
+export const frequencyShifter = defineSubgraph((config) => {
+    const { sampleRate } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000) {
+        throw new RangeError('frequencyShifter requires an integer sampleRate in [8000,192000]');
+    }
+    const delay = FREQUENCY_SHIFTER_LATENCY_SAMPLES, size = 63;
+    // Public 0.4.1 scrubs buffer writes below 1e-30. Exact power-of-two scaling
+    // preserves the full finite normalized f32 input range, including subnormals.
+    const scale = 2 ** 128;
+    const history = state.buffer.f64({ size }).expose({ name: 'historyScaled', snapshot: 'persistent' });
+    const cursor = state.i32(0).named('cursor');
+    const valid = state.i32(0).named('valid');
+    // Centered scaled phase also preserves tiny signed increments near zero.
+    // As with any f64 accumulator, increments below its current ULP can stall.
+    const phase = state.f64(0).named('phaseScaled');
+    const quadrature = state.f64(0).expose({ name: 'quadratureScaled', snapshot: 'transient' });
+    return {
+        tick(input, c) {
+            valid.write(select(c.reset, i32(0), valid.read().add(1).min(size)));
+            history.write(cursor.read(), f64(select(c.reset, f32(0), input)).mul(scale));
+            const at = (lag) => select(valid.read().gt(lag), history.read(cursor.read().add(size - lag).mod(size)), f64(0));
+            quadrature.write(0);
+            // Odd antisymmetric taps. The Blackman endpoints are exactly zero;
+            // pair differences reduce the 63-tap FIR to 15 bounded multiply-adds.
+            for (let offset = 1; offset < delay; offset += 2) {
+                const window = 0.42 + 0.5 * Math.cos(Math.PI * offset / delay) + 0.08 * Math.cos(2 * Math.PI * offset / delay);
+                quadrature.write(quadrature.read().add(at(delay + offset).sub(at(delay - offset)).mul(2 * window / (Math.PI * offset))));
+            }
+            const dry = at(delay), p = select(c.reset, f64(0), phase.read().div(scale));
+            const wet = dry.mul(sine(p.add(0.25))).sub(quadrature.read().mul(sine(p)));
+            const mix = f64(c.mix).clamp(0, 1);
+            const output = select(c.bypass, dry, dry.mul(f64(1).sub(mix)).add(wet.mul(mix)));
+            const next = p.add(f64(c.shiftHz).clamp(-sampleRate / 4, sampleRate / 4).div(sampleRate));
+            // A held reset holds phase zero; the first subsequent sample uses zero.
+            phase.write(select(c.reset, f64(0), next.sub(next.add(0.5).floor()).mul(scale)));
+            cursor.write(cursor.read().add(1).mod(size));
+            return select(c.reset, f32(0), f32(output.div(scale)));
+        },
+    };
+});

package/dist/gate.d.ts

@@ -0,0 +1,2 @@
+/** One-sample memory with gain: only an entry-path verification fixture. */
+export declare const gate: import("@unworklet/core").CompiledProcessor<unknown>;

package/dist/gate.js

@@ -0,0 +1,12 @@
+import { audioInput, audioOutput, defineProcessor, forSample, instantiate, param } from '@unworklet/core';
+import { gateCell } from './index.js';
+/** One-sample memory with gain: only an entry-path verification fixture. */
+export const gate = defineProcessor(() => {
+    const input = audioInput({ channels: 1, name: 'main' });
+    const output = audioOutput({ channels: 1, name: 'main' });
+    const gain = param.f32({ default: 0.5, min: 0, max: 1, automationRate: 'a-rate' }).named('gain');
+    const cell = instantiate(gateCell, { scale: 1 }, { name: 'cell' });
+    return { process() {
+            forSample(i => output.ch(0).at(i).write(cell.tick(input.ch(0).at(i), gain.at(i))));
+        } };
+}, { id: 'den.entry.gate.v1' });

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { type Node } from '@unworklet/core';
+/** Minimal composition fixture, not a production DSP module. Required config avoids upstream #104. */
+export declare const gateCell: import("@unworklet/core").SubgraphDecl<[config: {
+    scale: number;
+}], {
+    tick(input: Node<"f32">, gain: Node<"f32">): Node<"f32">;
+}>;

package/dist/index.js

@@ -0,0 +1,12 @@
+import { defineSubgraph, state } from '@unworklet/core';
+/** Minimal composition fixture, not a production DSP module. Required config avoids upstream #104. */
+export const gateCell = defineSubgraph((config) => {
+    const previous = state.f32(0).named('previous');
+    return {
+        tick(input, gain) {
+            const output = previous.read().mul(gain).mul(config.scale);
+            previous.write(input);
+            return output;
+        },
+    };
+});

package/dist/instrument-example.d.ts

@@ -0,0 +1,12 @@
+import { type Node } from '@unworklet/core';
+import type { OscillatorConfig } from './oscillator.js';
+import type { FilterConfig } from './filter.js';
+/** Replacement demonstration: half-level sine using unworklet's math primitive. */
+export declare const exampleOscillator: import("@unworklet/core").SubgraphDecl<[config: OscillatorConfig], {
+    tick(frequency: Node<"f32">, reset: Node<"bool">): Node<"f32">;
+}>;
+/** Replacement demonstration: one-pole low-pass, intentionally ignores Q. */
+export declare const exampleFilter: import("@unworklet/core").SubgraphDecl<[config: FilterConfig], {
+    tick(input: Node<"f32">, cutoff: Node<"f32">, _q: Node<"f32">, reset: Node<"bool">): Node<"f32">;
+}>;
+export declare const replacementInstrument: import("@unworklet/core").CompiledProcessor<unknown>;

package/dist/instrument-example.js

@@ -0,0 +1,29 @@
+import { defineSubgraph, f32, f64, select, state } from '@unworklet/core';
+import { createInstrument } from './instrument.js';
+/** Replacement demonstration: half-level sine using unworklet's math primitive. */
+export const exampleOscillator = defineSubgraph((config) => {
+    if (config.waveform !== 'sine')
+        throw new RangeError('exampleOscillator supports sine only');
+    const phase = state.f64(0).named('phase');
+    return { tick(frequency, reset) {
+            const p = select(reset, f64(0), phase.read());
+            phase.write(p.add(f64(frequency.clamp(0, 0.45 * config.sampleRate)).div(config.sampleRate)).frac());
+            return f32(p.mul(2 * Math.PI).sin()).mul(0.5);
+        } };
+});
+/** Replacement demonstration: one-pole low-pass, intentionally ignores Q. */
+export const exampleFilter = defineSubgraph((config) => {
+    const previous = state.f64(0).named('previous');
+    return { tick(input, cutoff, _q, reset) {
+            // Backward Euler one-pole: alpha = w/(1+w), w=2*pi*fc/fs.
+            const w = f64(cutoff.clamp(20, Math.min(20000, 0.45 * config.sampleRate))).mul(2 * Math.PI / config.sampleRate);
+            const old = select(reset, f64(0), previous.read());
+            const output = old.add(w.div(w.add(1)).mul(f64(input).sub(old)));
+            previous.write(output);
+            return f32(output);
+        } };
+});
+export const replacementInstrument = createInstrument({
+    mode: 'poly', capacity: 4, heldCapacity: 32, waveform: 'sine',
+    oscillator: exampleOscillator, filter: exampleFilter,
+});

package/dist/instrument-settings.d.ts

@@ -0,0 +1,95 @@
+/** CANDIDATE: low saw body, brief filter transient, last-held mono legato. */
+export declare const bassConfig: {
+    readonly mode: "mono";
+    readonly capacity: 1;
+    readonly heldCapacity: 32;
+    readonly legato: true;
+    readonly waveform: "saw";
+};
+export declare const bassParameters: {
+    readonly gain: 0.12;
+    readonly ampAttack: 0.005;
+    readonly ampDecay: 0.12;
+    readonly ampSustain: 0.7;
+    readonly ampRelease: 0.12;
+    readonly pitchAttack: 0;
+    readonly pitchDecay: 0;
+    readonly pitchSustain: 0;
+    readonly pitchRelease: 0;
+    readonly filterAttack: 0.003;
+    readonly filterDecay: 0.18;
+    readonly filterSustain: 0.2;
+    readonly filterRelease: 0.12;
+    readonly cutoff: 300;
+    readonly resonance: 0.707;
+    readonly pitchEnvelopeDepth: 0;
+    readonly filterEnvelopeDepth: 3;
+    readonly lfoRate: 0;
+    readonly lfoAmpDepth: 0;
+    readonly lfoPitchDepth: 0;
+    readonly lfoFilterDepth: 0;
+    readonly bypass: 0;
+};
+/** CANDIDATE: tonal kick/tom body, two-octave pitch drop, retriggered hits. */
+export declare const percussionConfig: {
+    readonly mode: "mono";
+    readonly capacity: 1;
+    readonly heldCapacity: 32;
+    readonly legato: false;
+    readonly waveform: "sine";
+};
+export declare const percussionParameters: {
+    readonly gain: 0.16;
+    readonly ampAttack: 0.001;
+    readonly ampDecay: 0.22;
+    readonly ampSustain: 0;
+    readonly ampRelease: 0.04;
+    readonly pitchAttack: 0;
+    readonly pitchDecay: 0.06;
+    readonly pitchSustain: 0;
+    readonly pitchRelease: 0.04;
+    readonly filterAttack: 0;
+    readonly filterDecay: 0.08;
+    readonly filterSustain: 0;
+    readonly filterRelease: 0.04;
+    readonly cutoff: 800;
+    readonly resonance: 0.5;
+    readonly pitchEnvelopeDepth: 24;
+    readonly filterEnvelopeDepth: 2;
+    readonly lfoRate: 0;
+    readonly lfoAmpDepth: 0;
+    readonly lfoPitchDepth: 0;
+    readonly lfoFilterDepth: 0;
+    readonly bypass: 0;
+};
+/** CANDIDATE: four saw voices, slow rise/release and shared slow modulation. */
+export declare const padConfig: {
+    readonly mode: "poly";
+    readonly capacity: 4;
+    readonly heldCapacity: 32;
+    readonly waveform: "saw";
+};
+export declare const padParameters: {
+    readonly gain: 0.045;
+    readonly ampAttack: 0.8;
+    readonly ampDecay: 1.2;
+    readonly ampSustain: 0.7;
+    readonly ampRelease: 2.4;
+    readonly pitchAttack: 0;
+    readonly pitchDecay: 0;
+    readonly pitchSustain: 0;
+    readonly pitchRelease: 0;
+    readonly filterAttack: 1.4;
+    readonly filterDecay: 1.6;
+    readonly filterSustain: 0.5;
+    readonly filterRelease: 2.4;
+    readonly cutoff: 1400;
+    readonly resonance: 0.5;
+    readonly pitchEnvelopeDepth: 0;
+    readonly filterEnvelopeDepth: 0.75;
+    readonly lfoRate: 0.12;
+    readonly lfoAmpDepth: 0.08;
+    readonly lfoPitchDepth: 0.03;
+    readonly lfoFilterDepth: 0.2;
+    readonly bypass: 0;
+};

package/dist/instrument-settings.js

@@ -0,0 +1,36 @@
+/** CANDIDATE: low saw body, brief filter transient, last-held mono legato. */
+export const bassConfig = {
+    mode: 'mono', capacity: 1, heldCapacity: 32, legato: true, waveform: 'saw',
+};
+export const bassParameters = {
+    gain: 0.12,
+    ampAttack: 0.005, ampDecay: 0.12, ampSustain: 0.7, ampRelease: 0.12,
+    pitchAttack: 0, pitchDecay: 0, pitchSustain: 0, pitchRelease: 0,
+    filterAttack: 0.003, filterDecay: 0.18, filterSustain: 0.2, filterRelease: 0.12,
+    cutoff: 300, resonance: 0.707, pitchEnvelopeDepth: 0, filterEnvelopeDepth: 3,
+    lfoRate: 0, lfoAmpDepth: 0, lfoPitchDepth: 0, lfoFilterDepth: 0, bypass: 0,
+};
+/** CANDIDATE: tonal kick/tom body, two-octave pitch drop, retriggered hits. */
+export const percussionConfig = {
+    mode: 'mono', capacity: 1, heldCapacity: 32, legato: false, waveform: 'sine',
+};
+export const percussionParameters = {
+    gain: 0.16,
+    ampAttack: 0.001, ampDecay: 0.22, ampSustain: 0, ampRelease: 0.04,
+    pitchAttack: 0, pitchDecay: 0.06, pitchSustain: 0, pitchRelease: 0.04,
+    filterAttack: 0, filterDecay: 0.08, filterSustain: 0, filterRelease: 0.04,
+    cutoff: 800, resonance: 0.5, pitchEnvelopeDepth: 24, filterEnvelopeDepth: 2,
+    lfoRate: 0, lfoAmpDepth: 0, lfoPitchDepth: 0, lfoFilterDepth: 0, bypass: 0,
+};
+/** CANDIDATE: four saw voices, slow rise/release and shared slow modulation. */
+export const padConfig = {
+    mode: 'poly', capacity: 4, heldCapacity: 32, waveform: 'saw',
+};
+export const padParameters = {
+    gain: 0.045,
+    ampAttack: 0.8, ampDecay: 1.2, ampSustain: 0.7, ampRelease: 2.4,
+    pitchAttack: 0, pitchDecay: 0, pitchSustain: 0, pitchRelease: 0,
+    filterAttack: 1.4, filterDecay: 1.6, filterSustain: 0.5, filterRelease: 2.4,
+    cutoff: 1400, resonance: 0.5, pitchEnvelopeDepth: 0, filterEnvelopeDepth: 0.75,
+    lfoRate: 0.12, lfoAmpDepth: 0.08, lfoPitchDepth: 0.03, lfoFilterDepth: 0.2, bypass: 0,
+};

package/dist/instrument.d.ts

@@ -0,0 +1,42 @@
+import { oscillator } from './oscillator.js';
+import { filter } from './filter.js';
+import { type VoicePolicyConfig } from './voice-policy.js';
+export { bassConfig, bassParameters, percussionConfig, percussionParameters, padConfig, padParameters } from './instrument-settings.js';
+export interface InstrumentConfig extends VoicePolicyConfig {
+    waveform?: 'sine' | 'saw';
+    /** Compatible unworklet subgraphs, instantiated independently for each voice. */
+    oscillator?: typeof oscillator;
+    filter?: typeof filter;
+}
+/** Diagnostic initial AudioParam values, not an approved preset or a preset format. */
+export declare const diagnosticInstrumentParameters: {
+    readonly gain: 0.15;
+    readonly ampAttack: 0.005;
+    readonly ampDecay: 0.08;
+    readonly ampSustain: 0.7;
+    readonly ampRelease: 0.15;
+    readonly pitchAttack: 0;
+    readonly pitchDecay: 0.1;
+    readonly pitchSustain: 0;
+    readonly pitchRelease: 0.1;
+    readonly filterAttack: 0.01;
+    readonly filterDecay: 0.15;
+    readonly filterSustain: 0.2;
+    readonly filterRelease: 0.15;
+    readonly cutoff: 2500;
+    readonly resonance: 0.707;
+    readonly pitchEnvelopeDepth: 0;
+    readonly filterEnvelopeDepth: 1;
+    readonly lfoRate: 2;
+    readonly lfoAmpDepth: 0;
+    readonly lfoPitchDepth: 0;
+    readonly lfoFilterDepth: 0;
+    readonly bypass: 0;
+};
+/** MIDI input `midi`, stereo dual-mono output `main`, panic message `reset`.
+ * Capacities/mode/waveform/parts are construction choices; all musical controls
+ * use native AudioParams. See docs/instrument.md for timing and reset semantics.
+ */
+export declare function createInstrument(config: InstrumentConfig): import("@unworklet/core").CompiledProcessor<unknown>;
+/** Diagnostic default: four voices, configurable at construction. */
+export declare const instrument: import("@unworklet/core").CompiledProcessor<unknown>;

package/dist/instrument.js

@@ -0,0 +1,166 @@
+import { audioOutput, i32, defineProcessor, event, f32, forSample, instantiate, param, select, state } from '@unworklet/core';
+import { envelope } from './envelope.js';
+import { lfo, modulatePitch, modulateCutoff } from './lfo.js';
+import { oscillator } from './oscillator.js';
+import { filter } from './filter.js';
+import { voicePolicy } from './voice-policy.js';
+export { bassConfig, bassParameters, percussionConfig, percussionParameters, padConfig, padParameters } from './instrument-settings.js';
+/** Diagnostic initial AudioParam values, not an approved preset or a preset format. */
+export const diagnosticInstrumentParameters = {
+    gain: 0.15,
+    ampAttack: 0.005,
+    ampDecay: 0.08,
+    ampSustain: 0.7,
+    ampRelease: 0.15,
+    pitchAttack: 0,
+    pitchDecay: 0.1,
+    pitchSustain: 0,
+    pitchRelease: 0.1,
+    filterAttack: 0.01,
+    filterDecay: 0.15,
+    filterSustain: 0.2,
+    filterRelease: 0.15,
+    cutoff: 2500,
+    resonance: 0.707,
+    pitchEnvelopeDepth: 0,
+    filterEnvelopeDepth: 1,
+    lfoRate: 2,
+    lfoAmpDepth: 0,
+    lfoPitchDepth: 0,
+    lfoFilterDepth: 0,
+    bypass: 0,
+};
+/** MIDI input `midi`, stereo dual-mono output `main`, panic message `reset`.
+ * Capacities/mode/waveform/parts are construction choices; all musical controls
+ * use native AudioParams. See docs/instrument.md for timing and reset semantics.
+ */
+export function createInstrument(config) {
+    // Keep the tested compilation ceiling after the initial 32-voice graph
+    // exceeded the WASM function-size limit. This is not a real-time guarantee.
+    if ((config.capacity ?? (config.mode === 'mono' ? 1 : 4)) > 16) {
+        throw new RangeError('instrument capacity must be <= 16 (compiled graph limit)');
+    }
+    return defineProcessor(({ sampleRate }) => {
+        const policy = instantiate(voicePolicy, { ...config, capacity: config.capacity ?? (config.mode === 'mono' ? 1 : 4) }, { name: 'voices' });
+        const output = audioOutput({ channels: 2, name: 'main' });
+        const midi = event.midi({ from: 'main', name: 'midi' });
+        // A persisted marker paired with a transient marker distinguishes restore
+        // from a pristine instance even when MIDI already reactivated a voice.
+        const rendered = state.bool(false).named('rendered');
+        const live = state.bool(false).expose({ name: 'live', snapshot: 'transient' });
+        const panic = state.bool(false).expose({ name: 'panic', snapshot: 'transient' });
+        const voiceControls = state.buffer.bool({ size: 3 * policy.capacity }).expose({ name: 'voiceControls', snapshot: 'transient' });
+        const deferredRetrigger = state.buffer.bool({ size: policy.capacity }).expose({ name: 'deferredRetrigger', snapshot: 'transient' });
+        const completed = state.buffer.bool({ size: policy.capacity }).expose({ name: 'completed', snapshot: 'transient' });
+        const cleared = state.buffer.bool({ size: policy.capacity }).expose({ name: 'cleared', snapshot: 'transient' });
+        const tuning = state.buffer.f32({ size: 128 }).expose({ name: 'tuning', snapshot: 'transient' });
+        const modulation = instantiate(lfo, { sampleRate }, { name: 'lfo' });
+        // Materialize intermediate signals: 0.4.1 analysis recursively expands DAGs.
+        // Only cache musical exponents: below the state flush threshold (1e-30),
+        // their octave ratio already rounds to exactly 1. Do not cache final audio,
+        // where a finite sub-threshold result must survive downstream gain.
+        const depths = state.buffer.f32({ size: 2 * policy.capacity }).expose({ name: 'depths', snapshot: 'transient' });
+        const signals = state.buffer.f32({ size: 4 * policy.capacity + 1 }).expose({ name: 'signals', snapshot: 'transient' });
+        const gain = param.f32({ default: diagnosticInstrumentParameters.gain, min: 0, max: 1, automationRate: 'a-rate' }).named('gain');
+        const ampAttack = param.f32({ default: diagnosticInstrumentParameters.ampAttack, min: 0, max: 30, automationRate: 'a-rate' }).named('ampAttack');
+        const ampDecay = param.f32({ default: diagnosticInstrumentParameters.ampDecay, min: 0, max: 30, automationRate: 'a-rate' }).named('ampDecay');
+        const ampSustain = param.f32({ default: diagnosticInstrumentParameters.ampSustain, min: 0, max: 1, automationRate: 'a-rate' }).named('ampSustain');
+        const ampRelease = param.f32({ default: diagnosticInstrumentParameters.ampRelease, min: 0, max: 30, automationRate: 'a-rate' }).named('ampRelease');
+        const pitchAttack = param.f32({ default: diagnosticInstrumentParameters.pitchAttack, min: 0, max: 30, automationRate: 'a-rate' }).named('pitchAttack');
+        const pitchDecay = param.f32({ default: diagnosticInstrumentParameters.pitchDecay, min: 0, max: 30, automationRate: 'a-rate' }).named('pitchDecay');
+        const pitchSustain = param.f32({ default: diagnosticInstrumentParameters.pitchSustain, min: 0, max: 1, automationRate: 'a-rate' }).named('pitchSustain');
+        const pitchRelease = param.f32({ default: diagnosticInstrumentParameters.pitchRelease, min: 0, max: 30, automationRate: 'a-rate' }).named('pitchRelease');
+        const filterAttack = param.f32({ default: diagnosticInstrumentParameters.filterAttack, min: 0, max: 30, automationRate: 'a-rate' }).named('filterAttack');
+        const filterDecay = param.f32({ default: diagnosticInstrumentParameters.filterDecay, min: 0, max: 30, automationRate: 'a-rate' }).named('filterDecay');
+        const filterSustain = param.f32({ default: diagnosticInstrumentParameters.filterSustain, min: 0, max: 1, automationRate: 'a-rate' }).named('filterSustain');
+        const filterRelease = param.f32({ default: diagnosticInstrumentParameters.filterRelease, min: 0, max: 30, automationRate: 'a-rate' }).named('filterRelease');
+        const cutoff = param.f32({ default: diagnosticInstrumentParameters.cutoff, min: 20, max: 20000, automationRate: 'a-rate' }).named('cutoff');
+        const resonance = param.f32({ default: diagnosticInstrumentParameters.resonance, min: 0.5, max: 10, automationRate: 'a-rate' }).named('resonance');
+        const pitchEnvelopeDepth = param.f32({ default: diagnosticInstrumentParameters.pitchEnvelopeDepth, min: -24, max: 24, automationRate: 'a-rate' }).named('pitchEnvelopeDepth');
+        const filterEnvelopeDepth = param.f32({ default: diagnosticInstrumentParameters.filterEnvelopeDepth, min: -8, max: 8, automationRate: 'a-rate' }).named('filterEnvelopeDepth');
+        const lfoRate = param.f32({ default: diagnosticInstrumentParameters.lfoRate, min: 0, max: 20, automationRate: 'a-rate' }).named('lfoRate');
+        const lfoAmpDepth = param.f32({ default: diagnosticInstrumentParameters.lfoAmpDepth, min: 0, max: 1, automationRate: 'a-rate' }).named('lfoAmpDepth');
+        const lfoPitchDepth = param.f32({ default: diagnosticInstrumentParameters.lfoPitchDepth, min: -24, max: 24, automationRate: 'a-rate' }).named('lfoPitchDepth');
+        const lfoFilterDepth = param.f32({ default: diagnosticInstrumentParameters.lfoFilterDepth, min: -8, max: 8, automationRate: 'a-rate' }).named('lfoFilterDepth');
+        const bypass = param.f32({ default: diagnosticInstrumentParameters.bypass, min: 0, max: 1, automationRate: 'a-rate' }).named('bypass');
+        const parts = policy.voices.map((_, index) => ({
+            amp: instantiate(envelope, { sampleRate }, { name: `amp${index}` }),
+            pitch: instantiate(envelope, { sampleRate }, { name: `pitch${index}` }),
+            tone: instantiate(envelope, { sampleRate }, { name: `tone${index}` }),
+            oscillator: instantiate(config.oscillator ?? oscillator, { sampleRate, waveform: config.waveform ?? 'sine' }, { name: `oscillator${index}` }),
+            filter: instantiate(config.filter ?? filter, { sampleRate }, { name: `filter${index}` }),
+        }));
+        midi.onEvent('noteOn', e => policy.noteOn(e.note, e.channel, e.velocity));
+        midi.onEvent('noteOff', e => policy.noteOff(e.note, e.channel));
+        midi.onEvent('cc', e => {
+            // Capture ownership before CC120 frees/reassigns voices. A subsequent note
+            // in this quantum starts cold, even when it reuses the same physical slot.
+            policy.voices.forEach((voice, n) => cleared.write(n, cleared.read(n).or(e.controller.eq(120).and(voice.read().channel.eq(e.channel)))));
+            // These policy methods have no conditional argument. CC routing uses the
+            // policy's validated channel guard for unsupported controller messages.
+            policy.allNotesOff(select(e.controller.eq(123), e.channel, i32(-1)));
+            policy.allSoundOff(select(e.controller.eq(120), e.channel, i32(-1)));
+        });
+        event({ from: 'main', name: 'reset' }).onReceive(() => panic.write(true));
+        return { process() {
+                // Reset wins over MIDI delivered in the same block. Its DSP pulse is only
+                // the first sample; subsequent blocks may accept fresh notes normally.
+                policy.reset(panic.read());
+                for (let note = 0; note < 128; note++)
+                    tuning.write(note, 440 * 2 ** ((note - 69) / 12));
+                forSample(i => {
+                    const reset = panic.read();
+                    signals.write(4 * policy.capacity, modulation.tick(lfoRate.at(i), reset, f32(0)));
+                    let sum = f32(0);
+                    policy.voices.forEach((voice, n) => {
+                        const v = voice.read();
+                        voiceControls.write(n * 3, reset.or(rendered.read().and(live.read().not())).or(v.active.not()).or(cleared.read(n)));
+                        voiceControls.write(n * 3 + 1, v.gate.and(voiceControls.read(n * 3).not()));
+                        voiceControls.write(n * 3 + 2, voice.takeRetrigger().or(deferredRetrigger.read(n)));
+                        const clear = voiceControls.read(n * 3), gate = voiceControls.read(n * 3 + 1), trigger = voiceControls.read(n * 3 + 2);
+                        // CC120 can suppress the note's first sample. Keep its reset pulse
+                        // until the first audible sample, so oscillator phase starts at zero.
+                        deferredRetrigger.write(n, clear.and(trigger).and(v.active).and(v.gate));
+                        const p = parts[n];
+                        const common = { gate, retrigger: trigger, reset: clear };
+                        const amp = p.amp.tick({ ...common, attack: ampAttack.at(i), decay: ampDecay.at(i), sustain: ampSustain.at(i), release: ampRelease.at(i) });
+                        const pitch = p.pitch.tick({ ...common, attack: pitchAttack.at(i), decay: pitchDecay.at(i), sustain: pitchSustain.at(i), release: pitchRelease.at(i) });
+                        const tone = p.tone.tick({ ...common, attack: filterAttack.at(i), decay: filterDecay.at(i), sustain: filterSustain.at(i), release: filterRelease.at(i) });
+                        signals.write(n * 4, pitch.level);
+                        signals.write(n * 4 + 1, tone.level);
+                        const wave = signals.read(4 * policy.capacity);
+                        // Combine depths in musical units before the single destination clamp.
+                        const semitones = signals.read(n * 4).mul(pitchEnvelopeDepth.at(i)).add(wave.mul(lfoPitchDepth.at(i)));
+                        const octaves = signals.read(n * 4 + 1).mul(filterEnvelopeDepth.at(i)).add(wave.mul(lfoFilterDepth.at(i)));
+                        depths.write(n * 2, semitones);
+                        depths.write(n * 2 + 1, octaves);
+                        signals.write(n * 4 + 2, modulatePitch(tuning.read(v.note.max(0)), f32(1), depths.read(n * 2), 0.45 * sampleRate));
+                        signals.write(n * 4 + 3, modulateCutoff(cutoff.at(i), f32(1), depths.read(n * 2 + 1), Math.min(20000, 0.45 * sampleRate)));
+                        // Preserve recoverable finite values across custom parts and amp gain.
+                        // Native state writes flush tiny values, so these paths stay expressions.
+                        const oscillation = p.oscillator.tick(signals.read(n * 4 + 2), clear.or(trigger));
+                        const filtered = p.filter.tick(select(clear, f32(0), oscillation), signals.read(n * 4 + 3), resonance.at(i), clear.or(trigger));
+                        // Unipolar tremolo: depth 0 is unity; depth 1 spans 0..1.
+                        const tremolo = f32(1).sub(lfoAmpDepth.at(i).mul(f32(1).sub(wave)).mul(0.5));
+                        const sample = select(v.active.and(clear.not()), filtered.mul(amp.level).mul(v.velocity).mul(tremolo), f32(0));
+                        sum = sum.add(sample);
+                        completed.write(n, amp.done);
+                        cleared.write(n, 0);
+                    });
+                    const result = select(bypass.at(i).gte(0.5).or(reset), f32(0), sum.mul(gain.at(i)));
+                    output.ch(0).at(i).write(result);
+                    output.ch(1).at(i).write(result);
+                    panic.write(false);
+                    rendered.write(true);
+                    live.write(true);
+                });
+                // MIDI is drained only before process(). Once the amp reaches zero it
+                // stays done for the rest of this block. Free completed allocations here,
+                // before the next MIDI dispatch, instead of doing O(voices²) rank updates
+                // on every sample. Audio termination remains on the exact envelope sample.
+                policy.voices.forEach((voice, n) => voice.releaseFinished(completed.read(n)));
+            } };
+    });
+}
+/** Diagnostic default: four voices, configurable at construction. */
+export const instrument = createInstrument({ mode: 'poly' });

package/dist/lfo.d.ts

@@ -0,0 +1,19 @@
+import { type Node } from '@unworklet/core';
+export interface LfoConfig {
+    sampleRate: number;
+}
+/**
+ * Free-running sine source; tick once per sample. Rate is clamped to [0,20] Hz.
+ * Output uses the current phase, then advances by rate/sampleRate. Rate zero
+ * holds phase; changing rate never resets phase. Reset emits the supplied phase
+ * on that sample and advances from it. Reset phase is in cycles, wrapped to [0,1).
+ * f64 phase prevents a small rate from stalling against a large f32 phase.
+ * Finite inputs required. No implicit note reset, depth, smoothing or routing.
+ */
+export declare const lfo: import("@unworklet/core").SubgraphDecl<[config: LfoConfig], {
+    tick(rate: Node<"f32">, reset: Node<"bool">, resetPhase: Node<"f32">): Node<"f32">;
+}>;
+/** Destination-unit depth, with final bounds enforced by the destination. */
+export declare function modulatePitch(baseHz: Node<'f32'>, signal: Node<'f32'>, semitones: Node<'f32'>, maxHz: number): Node<"f32">;
+export declare function modulateCutoff(baseHz: Node<'f32'>, signal: Node<'f32'>, octaves: Node<'f32'>, maxHz: number): Node<"f32">;
+export declare function modulateDelay(baseSeconds: Node<'f32'>, signal: Node<'f32'>, depthSeconds: Node<'f32'>, minSeconds: number, maxSeconds: number): Node<"f32">;