@denaudio/den 0.0.0-stage → 0.2.0

package/dist/oscillator.d.ts

@@ -0,0 +1,10 @@
+import { type Node } from '@unworklet/core';
+export interface OscillatorConfig {
+    sampleRate: number;
+    waveform: 'sine' | 'saw';
+}
+/** Phase accumulator with sine or four-sample polynomial BLEP saw. */
+export declare const oscillator: import("@unworklet/core").SubgraphDecl<[config: OscillatorConfig], {
+    /** Emit current phase, then advance. Reset emits phase zero on that sample. */
+    tick(frequency: Node<"f32">, reset: Node<"bool">): Node<"f32">;
+}>;

package/dist/oscillator.js

@@ -0,0 +1,35 @@
+import { defineSubgraph, f32, f64, select, state } from '@unworklet/core';
+/** Phase accumulator with sine or four-sample polynomial BLEP saw. */
+export const oscillator = defineSubgraph((config) => {
+    if (!Number.isFinite(config.sampleRate) || config.sampleRate < 8000 || config.sampleRate > 192000) {
+        throw new RangeError('oscillator sampleRate must be finite and in [8000, 192000] Hz');
+    }
+    if (config.waveform !== 'sine' && config.waveform !== 'saw')
+        throw new RangeError('unknown oscillator waveform');
+    const phase = state.f64(0).named('phase');
+    return {
+        /** Emit current phase, then advance. Reset emits phase zero on that sample. */
+        tick(frequency, reset) {
+            const dt = f64(frequency).clamp(0, 0.45 * config.sampleRate).div(config.sampleRate);
+            const p = select(reset, f64(0), phase.read());
+            phase.write(p.add(dt).frac());
+            if (config.waveform === 'sine') {
+                // Fold to [-pi/2, pi/2]; degree 13 has <7e-10 remainder here.
+                const cycles = select(p.lt(0.25), p, select(p.lt(0.75), f64(0.5).sub(p), p.sub(1)));
+                const angle = cycles.mul(2 * Math.PI), z = angle.mul(angle);
+                const polynomial = f64(1 / 6227020800).mul(z).sub(1 / 39916800).mul(z).add(1 / 362880).mul(z).sub(1 / 5040).mul(z).add(1 / 120).mul(z).sub(1 / 6).mul(z).add(1);
+                return f32(angle.mul(polynomial));
+            }
+            // A zero frequency holds phase; avoid 0/0 even in eagerly evaluated selects.
+            const width = select(dt.gt(0), dt, f64(1));
+            // Integrate a cubic B-spline kernel (four boxes convolved). Its step
+            // complement for x >= 0 has support two sample intervals.
+            const complement = (x) => {
+                const x2 = x.mul(x), outer = f64(2).sub(x).max(0);
+                return select(x.lt(1), f64(0.5).sub(x.mul(2 / 3)).add(x2.mul(x).div(3)).sub(x2.mul(x2).div(8)), outer.mul(outer).mul(outer).mul(outer).div(24));
+            };
+            const correction = complement(p.div(width)).sub(complement(f64(1).sub(p).div(width))).mul(2);
+            return f32(p.mul(2).sub(1).add(select(dt.gt(0), correction, f64(0))));
+        },
+    };
+});

package/dist/oversampled-drive.d.ts

@@ -0,0 +1,19 @@
+import { type Node } from '@unworklet/core';
+import type { DriveCurve } from './drive.js';
+/** Matched linear-phase bulk delay. FIR precursors exist before sample 32. */
+export declare const OVERSAMPLED_DRIVE_LATENCY_SAMPLES = 32;
+export interface OversampledDriveConfig {
+    /** Host rate. The fixed arithmetic shaper has no nested sample-rate runtime. */
+    sampleRate: number;
+    factor: 2 | 4;
+    curve: DriveCurve;
+}
+/** Fixed polyphase interpolation -> memoryless shape -> FIR/phase-zero
+ * decimation. Both factors have 32-sample matched bulk delay and deliberate
+ * high-frequency rolloff. Dry follows the exact linear resampling cascade.
+ */
+export declare const oversampledDrive: import("@unworklet/core").SubgraphDecl<[config: OversampledDriveConfig], {
+    /** Once per host sample. Input [-8,8], linear gain [0,32], mix [0,1].
+     * Reset invalidates old history before consuming the current sample. */
+    tick(input: Node<"f32">, gain: Node<"f32">, mix: Node<"f32">, reset: Node<"bool">): Node<"f32">;
+}>;

package/dist/oversampled-drive.js

@@ -0,0 +1,99 @@
+import { defineSubgraph, f32, f64, floor, i32, select, state } from '@unworklet/core';
+/** Matched linear-phase bulk delay. FIR precursors exist before sample 32. */
+export const OVERSAMPLED_DRIVE_LATENCY_SAMPLES = 32;
+const SCALE = 2 ** 128;
+function bounded(value, low, high) {
+    const wide = f64(value);
+    return select(wide.eq(wide), wide, f64(0)).clamp(low, high);
+}
+function soft(value) {
+    const x = value.clamp(-1, 1);
+    return x.mul(f64(1.5).sub(x.mul(x).mul(.5)));
+}
+function shape(x, curve) {
+    if (curve === 'hard')
+        return x.clamp(-1, 1);
+    if (curve === 'soft')
+        return soft(x);
+    if (curve === 'asymmetric')
+        return select(x.lt(0), soft(x.mul(2)).mul(.5), soft(x));
+    const phase = x.add(1).sub(floor(x.add(1).div(4)).mul(4));
+    return select(x.abs().lte(1), x, f64(1).sub(phase.sub(2).abs()));
+}
+function kernel(factor) {
+    const half = 16 * factor, cutoff = .45 / factor;
+    const values = Array.from({ length: 2 * half + 1 }, (_, k) => {
+        const distance = Math.abs(k - half);
+        if (distance === half)
+            return 0;
+        const ideal = distance === 0 ? 2 * cutoff : Math.sin(2 * Math.PI * cutoff * distance) / (Math.PI * distance);
+        return ideal * (.42 + .5 * Math.cos(Math.PI * distance / half) + .08 * Math.cos(2 * Math.PI * distance / half));
+    });
+    const sum = values.reduce((a, b) => a + b, 0);
+    return values.map(value => value / sum);
+}
+/** Fixed polyphase interpolation -> memoryless shape -> FIR/phase-zero
+ * decimation. Both factors have 32-sample matched bulk delay and deliberate
+ * high-frequency rolloff. Dry follows the exact linear resampling cascade.
+ */
+export const oversampledDrive = defineSubgraph((config) => {
+    const { sampleRate, factor, curve } = config;
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('oversampledDrive sampleRate must be in [8000,192000] Hz');
+    if (factor !== 2 && factor !== 4)
+        throw new RangeError('oversampledDrive factor must be 2 or 4');
+    if (!['hard', 'soft', 'asymmetric', 'fold'].includes(curve))
+        throw new RangeError('unknown oversampledDrive curve');
+    const h = kernel(factor), size = h.length;
+    const dryKernel = Array.from({ length: 65 }, (_, j) => factor * h.reduce((sum, value, k) => sum + value * (h[factor * j - k] ?? 0), 0));
+    const driven = state.buffer.f64({ size: 33 }).expose({ name: 'driven-scaled', snapshot: 'persistent' });
+    const raw = state.buffer.f64({ size: 65 }).expose({ name: 'dry-scaled', snapshot: 'persistent' });
+    const shaped = state.buffer.f64({ size }).expose({ name: 'shaped-scaled', snapshot: 'persistent' });
+    const drivenCursor = state.i32(0).named('driven-cursor'), dryCursor = state.i32(0).named('dry-cursor');
+    const highCursor = state.i32(0).named('high-cursor');
+    const baseValid = state.i32(0).named('base-valid'), highValid = state.i32(0).named('high-valid');
+    const up = state.f64(0).expose({ name: 'interpolated-scaled', snapshot: 'transient' });
+    const wet = state.f64(0).expose({ name: 'wet-sum-scaled', snapshot: 'transient' });
+    const dry = state.f64(0).expose({ name: 'dry-sum-scaled', snapshot: 'transient' });
+    return {
+        /** Once per host sample. Input [-8,8], linear gain [0,32], mix [0,1].
+         * Reset invalidates old history before consuming the current sample. */
+        tick(input, gain, mix, reset) {
+            const audio = bounded(input, -8, 8), amount = bounded(mix, 0, 1);
+            baseValid.write(select(reset, i32(1), baseValid.read().add(1).min(65)));
+            highValid.write(select(reset, i32(0), highValid.read()));
+            raw.write(dryCursor.read(), audio.mul(SCALE));
+            driven.write(drivenCursor.read(), audio.mul(bounded(gain, 0, 32)).mul(SCALE));
+            const baseAt = (lag) => select(baseValid.read().gt(lag), driven.read(drivenCursor.read().add(33 - lag).mod(33)), f64(0));
+            const highAt = (lag) => select(highValid.read().gt(lag), shaped.read(highCursor.read().add(size - lag).mod(size)), f64(0));
+            // These are fixed construction-time phases, not a second graph scheduler.
+            // Filtering suppresses images before and after the nonlinearity.
+            for (let phase = 0; phase < factor; phase++) {
+                up.write(0);
+                for (let tap = phase; tap < size; tap += factor) {
+                    if (h[tap] !== 0)
+                        up.write(up.read().add(baseAt((tap - phase) / factor).mul(factor * h[tap])));
+                }
+                shaped.write(highCursor.read(), shape(up.read().div(SCALE), curve).mul(SCALE));
+                highValid.write(highValid.read().add(1).min(size));
+                if (phase === 0) {
+                    wet.write(0);
+                    for (let tap = 0; tap < size; tap++)
+                        if (h[tap] !== 0)
+                            wet.write(wet.read().add(highAt(tap).mul(h[tap])));
+                }
+                highCursor.write(highCursor.read().add(1).mod(size));
+            }
+            dry.write(0);
+            for (let tap = 0; tap < dryKernel.length; tap++) {
+                if (dryKernel[tap] !== 0) {
+                    const previous = select(baseValid.read().gt(tap), raw.read(dryCursor.read().add(65 - tap).mod(65)), f64(0));
+                    dry.write(dry.read().add(previous.mul(dryKernel[tap])));
+                }
+            }
+            drivenCursor.write(drivenCursor.read().add(1).mod(33));
+            dryCursor.write(dryCursor.read().add(1).mod(65));
+            return f32(dry.read().mul(f64(1).sub(amount)).add(wet.read().mul(amount)).div(SCALE));
+        },
+    };
+});

package/dist/performance.d.ts

@@ -0,0 +1,61 @@
+import { type MidiInputHandle, type Node } from '@unworklet/core';
+import { type VoicePolicyConfig } from './voice-policy.js';
+export interface PitchGlideConfig {
+    sampleRate: number;
+}
+export interface PitchGlideControls {
+    /** MIDI-note semitones, clamped [-128,255]. */
+    target: Node<'f32'>;
+    /** [0,30] seconds; rounded to nearest sample and latched on target change. */
+    seconds: Node<'f32'>;
+    /** Level-sensitive: follow target immediately, consuming its current value. */
+    reset: Node<'bool'>;
+    /** Level-sensitive immediate target following, e.g. a nonlegato retrigger. */
+    snap: Node<'bool'>;
+}
+/** Constant-time linear glide in musical pitch. Call once per sample. */
+export declare const pitchGlide: import("@unworklet/core").SubgraphDecl<[config: PitchGlideConfig], {
+    tick(c: PitchGlideControls): Node<"f32">;
+}>;
+export interface TuningControls {
+    note: Node<'f32'>;
+    transpose: Node<'f32'>;
+    cents: Node<'f32'>;
+    a4: Node<'f32'>;
+}
+/** Finite controls, bounded 12-TET conversion, one final frequency ceiling. */
+export declare function tunedFrequency(c: TuningControls, maxFrequency: number): Node<"f32">;
+export interface PerformancePolicyConfig extends VoicePolicyConfig {
+    /** Poly default/max 4; mono must be 1. */
+    capacity?: number;
+    /** Default/max 8; counts physically-held AND pedal-held identities. */
+    heldCapacity?: number;
+}
+/** Native MIDI expression + bounded sustain ledger over the unchanged allocator.
+ * MIDI remains quantum-boundary FIFO. All performance state is transient.
+ * See docs/performance.md for duplicate, overflow, CC and DSP-clear semantics.
+ */
+export declare const performancePolicy: import("@unworklet/core").SubgraphDecl<[config: PerformancePolicyConfig], {
+    capacity: number;
+    heldCapacity: number;
+    reset: (when?: Node<"bool">) => void;
+    overflowed: () => Node<"bool">;
+    bindMidi(input: MidiInputHandle): void;
+    voices: {
+        read(): {
+            channelPressure: Node<"f32">;
+            polyPressure: Node<"f32">;
+            bend: Node<"f32">;
+            timbre: Node<"f32">;
+            sustain: Node<"bool">;
+            active: Node<"bool">;
+            gate: Node<"bool">;
+            note: Node<"i32">;
+            channel: Node<"i32">;
+            velocity: Node<"f32">;
+        };
+        takeRetrigger(): Node<"bool">;
+        takeReset(): Node<"bool">;
+        releaseFinished(done: Node<"bool">): void;
+    }[];
+}>;

package/dist/performance.js

@@ -0,0 +1,241 @@
+import { bool, defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+import { voicePolicy } from './voice-policy.js';
+// Native scalar writes flush tiny values. Scale musical pitch state so every
+// finite f32 target survives; this is storage encoding, not a new noise floor.
+const PITCH_SCALE = 2 ** 128;
+/** Constant-time linear glide in musical pitch. Call once per sample. */
+export const pitchGlide = defineSubgraph((config) => {
+    if (!Number.isInteger(config.sampleRate) || config.sampleRate < 8000 || config.sampleRate > 192000) {
+        throw new RangeError('pitchGlide sampleRate must be an integer in [8000,192000]');
+    }
+    const live = state.bool(false).named('live');
+    const value = state.f64(0).named('valueScaled');
+    const target = state.f64(0).named('targetScaled');
+    const remaining = state.i32(0).named('remaining');
+    return { tick(c) {
+            const destination = f64(c.target.clamp(-128, 255)).mul(PITCH_SCALE);
+            const changed = destination.eq(target.read()).not();
+            const immediate = c.reset.or(c.snap).or(live.read().not());
+            const frames = i32(f64(c.seconds.clamp(0, 30)).mul(config.sampleRate).add(0.5).floor());
+            remaining.write(select(immediate, i32(0), select(changed, frames, remaining.read())));
+            const count = remaining.read();
+            const output = select(immediate.or(count.lte(1)), destination, value.read().add(destination.sub(value.read()).div(f64(count.max(1)))));
+            value.write(output);
+            target.write(destination);
+            remaining.write(count.sub(1).max(0));
+            live.write(true);
+            return f32(output.div(PITCH_SCALE));
+        } };
+});
+/** Finite controls, bounded 12-TET conversion, one final frequency ceiling. */
+export function tunedFrequency(c, maxFrequency) {
+    if (!Number.isFinite(maxFrequency) || maxFrequency <= 0 || maxFrequency > 3.4028234663852886e38) {
+        throw new RangeError('maxFrequency must be positive and representable as finite f32');
+    }
+    const semitones = f64(c.note.clamp(-128, 255)).sub(69)
+        .add(f64(c.transpose.clamp(-48, 48))).add(f64(c.cents.clamp(-1200, 1200)).div(100));
+    // Both pow and exp use an approximate f32 bridge in core 0.4.1.
+    // |semitones| <= 257: exp(x/32), |x/32| < .465, degree 12,
+    // then five squarings. The bounded remainder stays below f32 rounding.
+    const x = semitones.mul(Math.LN2 / (12 * 32));
+    let factorial = 1;
+    const inverse = [1];
+    for (let n = 1; n <= 12; n++) {
+        factorial *= n;
+        inverse.push(1 / factorial);
+    }
+    let ratio = f64(inverse[12]);
+    for (let n = 11; n >= 0; n--)
+        ratio = ratio.mul(x).add(inverse[n]);
+    for (let n = 0; n < 5; n++)
+        ratio = ratio.mul(ratio);
+    return f32(f64(c.a4.clamp(220, 880)).mul(ratio).min(maxFrequency));
+}
+/** Native MIDI expression + bounded sustain ledger over the unchanged allocator.
+ * MIDI remains quantum-boundary FIFO. All performance state is transient.
+ * See docs/performance.md for duplicate, overflow, CC and DSP-clear semantics.
+ */
+export const performancePolicy = defineSubgraph((config) => {
+    const size = config.capacity ?? (config.mode === 'mono' ? 1 : 4);
+    const heldSize = config.heldCapacity ?? 8;
+    if (!Number.isInteger(size) || size < 1 || size > 4)
+        throw new RangeError('performance capacity must be an integer in [1,4]');
+    if (!Number.isInteger(heldSize) || heldSize < size || heldSize > 8)
+        throw new RangeError('performance heldCapacity must be between capacity and 8');
+    const policy = instantiate(voicePolicy, { ...config, capacity: size, heldCapacity: heldSize }, { name: 'allocator' });
+    const ints = (name, length) => state.buffer.i32({ size: length }).expose({ name, snapshot: 'transient' });
+    const floats = (name, length) => state.buffer.f32({ size: length }).expose({ name, snapshot: 'transient' });
+    // Dense ages (1..heldSize), not an ever-increasing event counter.
+    const age = ints('heldAge', heldSize), key = ints('heldKey', heldSize), channel = ints('heldChannel', heldSize), down = ints('heldDown', heldSize);
+    const pedal = ints('pedal', 16), bend = floats('bend', 16), pressure = floats('channelPressure', 16), timbre = floats('timbre', 16);
+    const polyPressure = floats('polyPressure', size), trigger = ints('trigger', size), clear = ints('clear', size);
+    const oldKey = ints('oldKey', size), oldChannel = ints('oldChannel', size), scratch = ints('scratch', 3);
+    const previousIdentity = state.i32(-1).expose({ name: 'previousIdentity', snapshot: 'transient' });
+    const overflow = state.bool(false).expose({ name: 'overflow', snapshot: 'transient' });
+    const validChannel = (ch) => ch.gte(0).and(ch.lte(15));
+    const validKey = (note, ch) => validChannel(ch).and(note.gte(0)).and(note.lte(127));
+    const safeChannel = (ch) => ch.clamp(0, 15);
+    function newestIdentity() {
+        scratch.write(0, -1);
+        scratch.write(1, 0);
+        for (let n = 0; n < heldSize; n++) {
+            const newer = age.read(n).gt(scratch.read(1));
+            scratch.write(0, select(newer, i32(n), scratch.read(0)));
+            scratch.write(1, select(newer, age.read(n), scratch.read(1)));
+        }
+    }
+    function beforeChange() {
+        if (config.mode === 'mono') {
+            newestIdentity();
+            previousIdentity.write(scratch.read(0));
+        }
+        policy.voices.forEach((voice, n) => { const v = voice.read(); oldKey.write(n, v.note); oldChannel.write(n, v.channel); });
+    }
+    function afterChange() {
+        if (config.mode === 'mono')
+            newestIdentity();
+        const identityChanged = config.mode === 'mono' ? scratch.read(0).gte(0).and(scratch.read(0).eq(previousIdentity.read()).not()) : bool(false);
+        policy.voices.forEach((voice, n) => {
+            const v = voice.read(), retrigger = voice.takeRetrigger();
+            trigger.write(n, select(retrigger, i32(1), trigger.read(n)));
+            polyPressure.write(n, select(retrigger.or(identityChanged).or(v.active.not()).or(v.note.eq(oldKey.read(n)).not()).or(v.channel.eq(oldChannel.read(n)).not()), f32(0), polyPressure.read(n)));
+        });
+    }
+    function remove(index, when) {
+        const old = age.read(index);
+        for (let n = 0; n < heldSize; n++)
+            age.write(n, select(when.and(age.read(n).gt(old)), age.read(n).sub(1), age.read(n)));
+        age.write(index, select(when, i32(0), age.read(index)));
+        key.write(index, select(when, i32(0), key.read(index)));
+        channel.write(index, select(when, i32(0), channel.read(index)));
+        down.write(index, select(when, i32(0), down.read(index)));
+    }
+    function oldest(ch, note, physicallyDown, matchKey) {
+        scratch.write(0, 0);
+        scratch.write(1, heldSize + 1);
+        for (let n = 0; n < heldSize; n++) {
+            const candidate = age.read(n).gt(0).and(age.read(n).lt(scratch.read(1))).and(channel.read(n).eq(ch))
+                .and(physicallyDown ? down.read(n).gt(0) : down.read(n).eq(0)).and(matchKey ? key.read(n).eq(note) : bool(true));
+            scratch.write(0, select(candidate, i32(n), scratch.read(0)));
+            scratch.write(1, select(candidate, age.read(n), scratch.read(1)));
+        }
+    }
+    function noteOff(note, ch, when = bool(true)) {
+        oldest(ch, note, true, true);
+        const index = scratch.read(0), found = when.and(validKey(note, ch)).and(scratch.read(1).lte(heldSize));
+        const release = found.and(pedal.read(safeChannel(ch)).eq(0));
+        down.write(index, select(found, i32(0), down.read(index)));
+        policy.noteOff(select(release, note, i32(-1)), ch);
+        remove(index, release);
+    }
+    function flush(ch) {
+        for (let n = 0; n < heldSize; n++) {
+            oldest(ch, i32(0), false, false);
+            const index = scratch.read(0), found = validChannel(ch).and(scratch.read(1).lte(heldSize));
+            policy.noteOff(select(found, key.read(index), i32(-1)), ch);
+            remove(index, found);
+        }
+    }
+    function noteOn(note, ch, velocity) {
+        noteOff(note, ch, velocity.eq(0));
+        scratch.write(0, 0);
+        scratch.write(1, 0);
+        scratch.write(2, 0);
+        for (let n = heldSize - 1; n >= 0; n--) {
+            const free = age.read(n).eq(0);
+            scratch.write(0, select(free, i32(n), scratch.read(0)));
+            scratch.write(1, select(free, i32(1), scratch.read(1)));
+            scratch.write(2, scratch.read(2).add(select(free, i32(0), i32(1))));
+        }
+        const index = scratch.read(0), enabled = validKey(note, ch).and(velocity.gt(0)).and(velocity.lte(127));
+        const accept = enabled.and(scratch.read(1).gt(0));
+        overflow.write(overflow.read().or(enabled.and(accept.not())));
+        age.write(index, select(accept, scratch.read(2).add(1), age.read(index)));
+        key.write(index, select(accept, note, key.read(index)));
+        channel.write(index, select(accept, ch, channel.read(index)));
+        down.write(index, select(accept, i32(1), down.read(index)));
+        policy.noteOn(select(accept, note, i32(-1)), ch, velocity);
+    }
+    function allSoundOff(ch) {
+        policy.voices.forEach((voice, n) => {
+            const affected = voice.read().active.and(voice.read().channel.eq(ch));
+            clear.write(n, select(affected, i32(1), clear.read(n)));
+            trigger.write(n, select(affected, i32(0), trigger.read(n)));
+        });
+        policy.allSoundOff(ch);
+        for (let n = 0; n < heldSize; n++)
+            remove(i32(n), age.read(n).gt(0).and(channel.read(n).eq(ch)));
+        const safe = safeChannel(ch);
+        pedal.write(safe, select(validChannel(ch), i32(0), pedal.read(safe)));
+    }
+    function control(ch, controller, value) {
+        const safe = safeChannel(ch), valid = validChannel(ch).and(value.gte(0)).and(value.lte(127));
+        const sustain = valid.and(controller.eq(64)), resetControllers = valid.and(controller.eq(121));
+        const notesOff = valid.and(controller.eq(123)), soundOff = valid.and(controller.eq(120));
+        pedal.write(safe, select(resetControllers, i32(0), select(sustain, select(value.gte(64), i32(1), i32(0)), pedal.read(safe))));
+        bend.write(safe, select(resetControllers, f32(0), bend.read(safe)));
+        pressure.write(safe, select(resetControllers, f32(0), pressure.read(safe)));
+        timbre.write(safe, select(resetControllers, f32(0), select(valid.and(controller.eq(74)), f32(value).div(127), timbre.read(safe))));
+        policy.voices.forEach((voice, n) => polyPressure.write(n, select(resetControllers.and(voice.read().channel.eq(ch)), f32(0), polyPressure.read(n))));
+        for (let n = 0; n < heldSize; n++)
+            down.write(n, select(notesOff.and(channel.read(n).eq(ch)), i32(0), down.read(n)));
+        const release = resetControllers.or(sustain.and(value.lt(64))).or(notesOff.and(pedal.read(safe).eq(0)));
+        flush(select(release, ch, i32(-1)));
+        allSoundOff(select(soundOff, ch, i32(-1)));
+    }
+    function reset(when = bool(true)) {
+        policy.reset(when);
+        for (let n = 0; n < heldSize; n++) {
+            age.write(n, select(when, i32(0), age.read(n)));
+            key.write(n, select(when, i32(0), key.read(n)));
+            channel.write(n, select(when, i32(0), channel.read(n)));
+            down.write(n, select(when, i32(0), down.read(n)));
+        }
+        for (let ch = 0; ch < 16; ch++) {
+            pedal.write(ch, select(when, i32(0), pedal.read(ch)));
+            bend.write(ch, select(when, f32(0), bend.read(ch)));
+            pressure.write(ch, select(when, f32(0), pressure.read(ch)));
+            timbre.write(ch, select(when, f32(0), timbre.read(ch)));
+        }
+        for (let n = 0; n < size; n++) {
+            polyPressure.write(n, select(when, f32(0), polyPressure.read(n)));
+            trigger.write(n, select(when, i32(0), trigger.read(n)));
+            clear.write(n, select(when, i32(1), clear.read(n)));
+        }
+        overflow.write(select(when, false, overflow.read()));
+    }
+    return {
+        capacity: size, heldCapacity: heldSize, reset,
+        overflowed: () => overflow.read().or(policy.overflowed()),
+        bindMidi(input) {
+            input.onEvent('noteOn', e => { beforeChange(); noteOn(e.note, e.channel, e.velocity); afterChange(); });
+            input.onEvent('noteOff', e => { beforeChange(); noteOff(e.note, e.channel); afterChange(); });
+            input.onEvent('cc', e => { beforeChange(); control(e.channel, e.controller, e.value); afterChange(); });
+            input.onEvent('pitchBend', e => {
+                const ch = safeChannel(e.channel), value = f32(e.value).sub(8192);
+                bend.write(ch, select(validChannel(e.channel).and(e.value.gte(0)).and(e.value.lte(16383)), value.div(select(e.value.lt(8192), f32(8192), f32(8191))), bend.read(ch)));
+            });
+            input.onEvent('channelPressure', e => {
+                const ch = safeChannel(e.channel);
+                pressure.write(ch, select(validChannel(e.channel).and(e.pressure.gte(0)).and(e.pressure.lte(127)), f32(e.pressure).div(127), pressure.read(ch)));
+            });
+            input.onEvent('aftertouch', e => {
+                policy.voices.forEach((voice, n) => {
+                    const v = voice.read(), match = v.active.and(v.channel.eq(e.channel)).and(v.note.eq(e.note)).and(e.pressure.gte(0)).and(e.pressure.lte(127));
+                    polyPressure.write(n, select(match, f32(e.pressure).div(127), polyPressure.read(n)));
+                });
+            });
+        },
+        voices: policy.voices.map((voice, n) => ({
+            read() {
+                const v = voice.read(), ch = safeChannel(v.channel);
+                return { ...v, channelPressure: select(v.active, pressure.read(ch), f32(0)),
+                    polyPressure: select(v.active, polyPressure.read(n), f32(0)), bend: select(v.active, bend.read(ch), f32(0)),
+                    timbre: select(v.active, timbre.read(ch), f32(0)), sustain: v.active.and(pedal.read(ch).gt(0)) };
+            },
+            takeRetrigger() { const value = trigger.read(n).gt(0); trigger.write(n, 0); return value; },
+            takeReset() { const value = clear.read(n).gt(0); clear.write(n, 0); return value; },
+            releaseFinished(done) { voice.releaseFinished(done); },
+        })),
+    };
+});

package/dist/pitch-quantizer.d.ts

@@ -0,0 +1,26 @@
+import { type Node } from '@unworklet/core';
+export interface PitchQuantizerConfig {
+    /** 1..128 finite offsets in [0,12), in semitones. Copied, f32-rounded, sorted. */
+    pitchClasses: readonly number[];
+    /** Fixed Schmitt margin in semitones, f32-rounded in [0,12]. Default 0. */
+    hysteresis?: number;
+}
+export interface PitchQuantizerOutput {
+    /** Selected octave*12 + pitch class, rounded to f32. */
+    pitch: Node<'f32'>;
+    /** Index into the sorted, f32-rounded pitchClasses. */
+    degree: Node<'i32'>;
+    /** Octave multiplier; pitch=12*octave+pitchClasses[degree]. Not an octave label. */
+    octave: Node<'i32'>;
+}
+/**
+ * Audio-rate, octave-periodic nearest pitch, not audio pitch detection or MIDI
+ * output. Call once per sample. NaN becomes 0; other inputs clamp to +/-16384.
+ * f64 computational distance ties choose the lower pitch. A positive margin
+ * retains the previous degree inside its expanded adjacent-midpoint interval,
+ * including both endpoints. Reset (level-sensitive) and first call snap to
+ * nearest immediately. Zero margin always uses nearest, including tie policy.
+ */
+export declare const pitchQuantizer: import("@unworklet/core").SubgraphDecl<[config: PitchQuantizerConfig], {
+    tick(input: Node<"f32">, reset: Node<"bool">): PitchQuantizerOutput;
+}>;

package/dist/pitch-quantizer.js

@@ -0,0 +1,88 @@
+import { bool, defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+// Native 0.4.1 scalar state flushes tiny values. f32 controls/offsets scaled
+// by this exact power of two remain well above that floor, including 2^-149.
+const SCALE = 2 ** 128;
+/**
+ * Audio-rate, octave-periodic nearest pitch, not audio pitch detection or MIDI
+ * output. Call once per sample. NaN becomes 0; other inputs clamp to +/-16384.
+ * f64 computational distance ties choose the lower pitch. A positive margin
+ * retains the previous degree inside its expanded adjacent-midpoint interval,
+ * including both endpoints. Reset (level-sensitive) and first call snap to
+ * nearest immediately. Zero margin always uses nearest, including tie policy.
+ */
+export const pitchQuantizer = defineSubgraph((config) => {
+    if (!Array.isArray(config.pitchClasses) || config.pitchClasses.length < 1 || config.pitchClasses.length > 128) {
+        throw new RangeError('pitchClasses requires 1..128 offsets');
+    }
+    // Array.from visits sparse holes too; every supplied slot must be valid.
+    const degrees = Array.from(config.pitchClasses, value => {
+        if (!Number.isFinite(value) || value < 0 || value >= 12 || Math.fround(value) >= 12) {
+            throw new RangeError('pitch class must be finite in [0,12), including after f32 rounding');
+        }
+        return Math.fround(value) || 0;
+    }).sort((a, b) => a - b);
+    if (degrees.some((value, n) => n > 0 && value === degrees[n - 1])) {
+        throw new RangeError('pitch classes must be distinct after f32 rounding');
+    }
+    const requestedMargin = config.hysteresis ?? 0;
+    if (!Number.isFinite(requestedMargin) || requestedMargin < 0 || requestedMargin > 12) {
+        throw new RangeError('hysteresis must be finite in [0,12] semitones');
+    }
+    const margin = Math.fround(requestedMargin);
+    const degree = state.i32(0).named('degree');
+    const octave = state.i32(0).named('octave');
+    const initialized = state.bool(false).named('initialized');
+    const nearestDegree = state.i32(0).named('nearestDegree');
+    const nearestOctave = state.i32(0).named('nearestOctave');
+    const nearestPitch = state.f64(0).named('nearestPitchScaled');
+    const nearestDistance = state.f64(0).named('nearestDistanceScaled');
+    const candidateOctave = state.i32(0).named('candidateOctave');
+    const candidatePitch = state.f64(0).named('candidatePitchScaled');
+    const candidateDistance = state.f64(0).named('candidateDistanceScaled');
+    const takeCandidate = state.bool(false).named('takeCandidate');
+    const update = state.bool(false).named('update');
+    return { tick(input, reset) {
+            // Unlike min/max alone, the explicit NaN branch gives a portable policy.
+            const x = f64(select(input.eq(input), input, f32(0)).clamp(-16384, 16384));
+            nearestDistance.write(f64(32768 * SCALE));
+            nearestPitch.write(f64(32768 * SCALE));
+            for (let n = 0; n < degrees.length; n++) {
+                // Compare both bracketing octaves by their actual f64 distances.
+                // A midpoint shortcut is not equivalent near zero: e.g. +/-6 have
+                // equal rounded distances from an f32 subnormal, so lower must win.
+                candidateOctave.write(i32(x.sub(degrees[n]).div(12).floor()));
+                for (let adjacent = 0; adjacent < 2; adjacent++) {
+                    if (adjacent > 0)
+                        candidateOctave.write(candidateOctave.read().add(1));
+                    candidatePitch.write(f64(candidateOctave.read()).mul(12).add(degrees[n]).mul(SCALE));
+                    candidateDistance.write(x.mul(SCALE).sub(candidatePitch.read()).abs());
+                    takeCandidate.write(candidateDistance.read().lt(nearestDistance.read()).or(candidateDistance.read().eq(nearestDistance.read()).and(candidatePitch.read().lt(nearestPitch.read()))));
+                    nearestDegree.write(select(takeCandidate.read(), i32(n), nearestDegree.read()));
+                    nearestOctave.write(select(takeCandidate.read(), candidateOctave.read(), nearestOctave.read()));
+                    nearestPitch.write(select(takeCandidate.read(), candidatePitch.read(), nearestPitch.read()));
+                    nearestDistance.write(select(takeCandidate.read(), candidateDistance.read(), nearestDistance.read()));
+                }
+            }
+            if (margin === 0) {
+                update.write(bool(true));
+            }
+            else {
+                let lower = f64(0), upper = f64(0);
+                for (let n = 0; n < degrees.length; n++) {
+                    const previous = n === 0 ? degrees[degrees.length - 1] - 12 : degrees[n - 1];
+                    const next = n === degrees.length - 1 ? degrees[0] + 12 : degrees[n + 1];
+                    lower = select(degree.read().eq(n), f64((previous + degrees[n]) / 2 - margin), lower);
+                    upper = select(degree.read().eq(n), f64((degrees[n] + next) / 2 + margin), upper);
+                }
+                const base = f64(octave.read()).mul(12);
+                update.write(reset.or(initialized.read().not()).or(x.lt(base.add(lower))).or(x.gt(base.add(upper))));
+            }
+            degree.write(select(update.read(), nearestDegree.read(), degree.read()));
+            octave.write(select(update.read(), nearestOctave.read(), octave.read()));
+            initialized.write(bool(true));
+            let selected = f64(degrees[0]);
+            for (let n = 1; n < degrees.length; n++)
+                selected = select(degree.read().eq(n), f64(degrees[n]), selected);
+            return { pitch: f32(f64(octave.read()).mul(12).add(selected)), degree: degree.read(), octave: octave.read() };
+        } };
+});

package/dist/prepared-convolution.d.ts

@@ -0,0 +1,26 @@
+import { type EveryNSamples, type MessageGraphPayload, type Node } from '@unworklet/core';
+import { type PreparedConvolutionConfig, type PreparedConvolutionPacket } from './convolution-spectrum.js';
+export { prepareConvolutionSpectrum, type PreparedConvolutionConfig, type PreparedConvolutionPacket } from './convolution-spectrum.js';
+export interface PreparedConvolutionRuntimeConfig extends PreparedConvolutionConfig {
+    /** Pass ctx.renderQuantumSize; aligns native dispatch with snapshot boundaries. */
+    renderQuantumSize: number;
+}
+/** Fixed B128/P64 prepared-spectrum mono convolution candidate.
+ * Correctness/gain bounds require an unchanged packet from host preparation.
+ * Caller owns native CAPACITY_16 ingress with payloadCapacity 131072 bytes.
+ * Copy/scan runs in native dispatch, so preload with audible playback gated off.
+ */
+export declare const preparedConvolution: import("@unworklet/core").SubgraphDecl<[config: PreparedConvolutionRuntimeConfig], {
+    /** Module-specific native event payload; this is not a host loader/ack. */
+    load(packet: MessageGraphPayload<PreparedConvolutionPacket>): void;
+    /** Once per sample, inside stride-1 forSample with its native scheduler.
+     * Finite normalized input[-1,1]. Reset discards its sample and keeps the IR.
+     * Reload clears prior tail but accepts the next sample after its handler.
+     */
+    tick(input: Node<"f32">, reset: Node<"bool">, everyNSamples: EveryNSamples): {
+        output: Node<"f32">;
+        loaded: Node<"bool">;
+        rejected: Node<"bool">;
+        revision: Node<"i32">;
+    };
+}>;