@denaudio/den 0.0.0-stage → 0.1.0

package/dist/virtual-analog.js

@@ -0,0 +1,66 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+function bounded(value, low, high, fallback) {
+    return select(value.eq(value), f64(value), f64(fallback)).clamp(low, high);
+}
+/** Alias-reduced pulse and triangle. Polynomial smoothing is not a brickwall filter. */
+export const virtualAnalogSource = defineSubgraph((config) => {
+    const { sampleRate, waveform, phaseCycles = 0 } = config;
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('VA sampleRate must be in [8000,192000] Hz');
+    if (waveform !== 'pulse' && waveform !== 'triangle')
+        throw new RangeError('unknown VA waveform');
+    if (!Number.isFinite(phaseCycles) || phaseCycles < 0 || phaseCycles >= 1)
+        throw new RangeError('phaseCycles must be in [0,1)');
+    // Exact power-of-two scaling avoids the native |state|<1e-30 flush,
+    // including f64 phaseCycles=Number.MIN_VALUE and smallest f32 Hz.
+    // Phase is wrapped below1 before scaling, with >16x finite headroom.
+    const scale = 2 ** 1020;
+    const phase = state.f64(phaseCycles * scale).named('scaledPhase');
+    return { tick(c) {
+            const step = bounded(c.frequencyHz, 0, .45 * sampleRate, 0).div(sampleRate);
+            const p = select(c.reset, f64(phaseCycles), phase.read().div(scale));
+            // Both select branches evaluate: the zero-Hz denominator must remain safe.
+            const width = select(step.gt(0), step, f64(1));
+            let output;
+            if (waveform === 'pulse') {
+                const duty = bounded(c.duty, 0, 1, .5);
+                // Rising-step residual for the unit-area triangular kernel [-1,1].
+                const blep = (q) => {
+                    const after = f64(1).sub(q.div(width)).max(0);
+                    const before = f64(1).sub(f64(1).sub(q).div(width)).max(0);
+                    return before.mul(before).sub(after.mul(after));
+                };
+                const relative = p.sub(duty), falling = relative.sub(relative.floor());
+                const raw = select(p.lt(duty), f64(1), f64(-1));
+                output = raw.add(select(step.gt(0), blep(p).sub(blep(falling)), f64(0)));
+            }
+            else {
+                const rampResidual = (distance) => {
+                    const t = f64(1).sub(distance.div(width)).max(0);
+                    return t.mul(t).mul(t).div(6);
+                };
+                const raw = f64(1).sub(p.sub(.5).abs().mul(4));
+                // Slope jumps +8 at phase0 and -8 at phase.5. Support <.5 cycle,
+                // so only phase0 needs the periodic image at phase1.
+                const correction = rampResidual(p).add(rampResidual(f64(1).sub(p)))
+                    .sub(rampResidual(p.sub(.5).abs())).mul(step).mul(8);
+                output = raw.add(select(step.gt(0), correction, f64(0)));
+            }
+            phase.write(p.add(step).frac().mul(scale));
+            return f32(output);
+        } };
+});
+/** Park–Miller 48271 white-noise candidate; deterministic, not cryptographic. */
+export const seededNoise = defineSubgraph((config = {}) => {
+    const { seed = 1 } = config;
+    if (!Number.isInteger(seed) || seed < 1 || seed > 2147483646)
+        throw new RangeError('noise seed must be an integer in [1,2147483646]');
+    const random = state.i32(seed).named('random');
+    return { tick(reset) {
+            const current = select(reset, i32(seed), random.read());
+            // Exact integer product in f64; i32 multiplication would overflow.
+            const next = i32(f64(current).mul(48271).mod(2147483647));
+            random.write(next);
+            return f32(f64(next).mul(2 / 2147483647).sub(1));
+        } };
+});

package/dist/voice-policy.d.ts

@@ -0,0 +1,37 @@
+import { type MidiInputHandle, type Node } from '@unworklet/core';
+/** Fixed construction capacities, not product-wide polyphony limits. */
+export interface VoicePolicyConfig {
+    mode: 'mono' | 'poly';
+    /** Poly default 16; mono must use one slot. Maximum 32 limits graph expansion. */
+    capacity?: number;
+    /** Held note-on identities (including stolen notes). Default 128, maximum 256. */
+    heldCapacity?: number;
+    /** Mono only: preserve gate without a retrigger when another held note takes priority. */
+    legato?: boolean;
+}
+/** Voice allocation only. MIDI transport, graph storage, and node control remain unworklet's. */
+export declare const voicePolicy: import("@unworklet/core").SubgraphDecl<[config: VoicePolicyConfig], {
+    capacity: number;
+    heldCapacity: number;
+    noteOn: (key: Node<"i32">, ch: Node<"i32">, vel: Node<"i32">) => void;
+    noteOff: (key: Node<"i32">, ch: Node<"i32">, when?: Node<"bool">) => void;
+    reset: (when?: Node<"bool">) => void;
+    allNotesOff: (ch: Node<"i32">) => void;
+    allSoundOff: (ch: Node<"i32">) => void;
+    overflowed: () => Node<"bool">;
+    /** Call once in declaration scope with an existing unworklet MIDI input. */
+    bindMidi(input: MidiInputHandle): void;
+    voices: {
+        read(): {
+            active: Node<"bool">;
+            gate: Node<"bool">;
+            note: Node<"i32">;
+            channel: Node<"i32">;
+            velocity: Node<"f32">;
+        };
+        /** One latched start/retrigger; read once per sample before invoking the envelope. */
+        takeRetrigger(): Node<"bool">;
+        /** Envelope completion may free only a released voice, never a newly held one. */
+        releaseFinished(done: Node<"bool">): void;
+    }[];
+}>;

package/dist/voice-policy.js

@@ -0,0 +1,245 @@
+import { bool, defineSubgraph, f32, i32, select, state } from '@unworklet/core';
+function capacity(value, maximum, name) {
+    if (!Number.isInteger(value) || value < 1 || value > maximum) {
+        throw new RangeError(`${name} must be an integer in [1, ${maximum}]`);
+    }
+    return value;
+}
+/** Voice allocation only. MIDI transport, graph storage, and node control remain unworklet's. */
+export const voicePolicy = defineSubgraph((config) => {
+    if (config.mode !== 'mono' && config.mode !== 'poly')
+        throw new TypeError('mode must be mono or poly');
+    const size = capacity(config.capacity ?? (config.mode === 'mono' ? 1 : 16), 32, 'capacity');
+    const heldSize = capacity(config.heldCapacity ?? Math.max(128, size), 256, 'heldCapacity');
+    if (config.mode === 'mono' && size !== 1)
+        throw new RangeError('mono capacity must be 1');
+    if (heldSize < size)
+        throw new RangeError('heldCapacity must be at least capacity');
+    if (config.legato !== undefined && typeof config.legato !== 'boolean')
+        throw new TypeError('legato must be boolean');
+    const legato = config.legato ?? true;
+    const ints = (name, length) => state.buffer.i32({ size: length }).expose({ name, snapshot: 'transient' });
+    const note = ints('note', size);
+    const channel = ints('channel', size);
+    const velocity = state.buffer.f32({ size }).expose({ name: 'velocity', snapshot: 'transient' });
+    const age = ints('age', size); // zero means free, otherwise dense allocation order 1..size
+    const releaseAge = ints('releaseAge', size); // zero means held, otherwise release order
+    const owner = ints('owner', size); // held token 1..heldSize; zero means no key owns the release tail
+    const retrigger = ints('retrigger', size);
+    const heldNote = ints('heldNote', heldSize + 1);
+    const heldChannel = ints('heldChannel', heldSize + 1);
+    const heldVelocity = ints('heldVelocity', heldSize + 1);
+    // Intrusive held-key order: token 0 is a sentinel; valid tokens are 1..heldSize.
+    const occupied = ints('occupied', heldSize + 1);
+    const previous = ints('previous', heldSize + 1);
+    const next = ints('next', heldSize + 1);
+    const head = state.i32(0).expose({ name: 'head', snapshot: 'transient' });
+    const tail = state.i32(0).expose({ name: 'tail', snapshot: 'transient' });
+    // Materialize loop accumulators: unworklet 0.4.1 analysis recursively expands
+    // expression DAGs, so nested selects otherwise grow exponentially.
+    const scratch = ints('scratch', 4);
+    const overflow = state.bool(false).expose({ name: 'overflow', snapshot: 'transient' });
+    const validKey = (key, ch) => key.gte(0).and(key.lte(127)).and(ch.gte(0)).and(ch.lte(15));
+    const releaseCount = () => {
+        let count = i32(0);
+        for (let n = 0; n < size; n++)
+            count = count.add(select(releaseAge.read(n).gt(0), i32(1), i32(0)));
+        return count;
+    };
+    function releaseVoice(index, when) {
+        const shouldRelease = when.and(age.read(index).gt(0)).and(owner.read(index).gt(0));
+        const nextOrder = releaseCount().add(1);
+        owner.write(index, select(shouldRelease, i32(0), owner.read(index)));
+        releaseAge.write(index, select(shouldRelease, nextOrder, releaseAge.read(index)));
+    }
+    function freeVoice(index, when) {
+        const oldAge = age.read(index);
+        const oldRelease = releaseAge.read(index);
+        const enabled = when.and(oldAge.gt(0));
+        for (let n = 0; n < size; n++) {
+            const a = age.read(n);
+            const r = releaseAge.read(n);
+            age.write(n, select(enabled.and(a.gt(oldAge)), a.sub(1), a));
+            releaseAge.write(n, select(enabled.and(oldRelease.gt(0)).and(r.gt(oldRelease)), r.sub(1), r));
+        }
+        age.write(index, select(enabled, i32(0), age.read(index)));
+        releaseAge.write(index, select(enabled, i32(0), releaseAge.read(index)));
+        owner.write(index, select(enabled, i32(0), owner.read(index)));
+        note.write(index, select(enabled, i32(0), note.read(index)));
+        channel.write(index, select(enabled, i32(0), channel.read(index)));
+        velocity.write(index, select(enabled, f32(0), velocity.read(index)));
+        retrigger.write(index, select(enabled, i32(0), retrigger.read(index)));
+    }
+    function activate(index, token, when, trigger) {
+        const oldAge = age.read(index);
+        const oldRelease = releaseAge.read(index);
+        let count = i32(0);
+        for (let n = 0; n < size; n++)
+            count = count.add(select(age.read(n).gt(0), i32(1), i32(0)));
+        for (let n = 0; n < size; n++) {
+            const a = age.read(n);
+            const r = releaseAge.read(n);
+            age.write(n, select(when.and(oldAge.gt(0)).and(a.gt(oldAge)), a.sub(1), a));
+            releaseAge.write(n, select(when.and(oldRelease.gt(0)).and(r.gt(oldRelease)), r.sub(1), r));
+        }
+        age.write(index, select(when, select(oldAge.gt(0), count, count.add(1)), age.read(index)));
+        releaseAge.write(index, select(when, i32(0), releaseAge.read(index)));
+        owner.write(index, select(when, token, owner.read(index)));
+        note.write(index, select(when, heldNote.read(token), note.read(index)));
+        channel.write(index, select(when, heldChannel.read(token), channel.read(index)));
+        velocity.write(index, select(when, f32(heldVelocity.read(token)).div(127), velocity.read(index)));
+        retrigger.write(index, select(when.and(trigger), i32(1), retrigger.read(index)));
+    }
+    function monoPriority(when) {
+        const selected = tail.read();
+        const newest = selected;
+        const changed = owner.read(0).eq(selected).not();
+        const trigger = bool(!legato).or(owner.read(0).eq(0));
+        activate(i32(0), selected, when.and(newest.gt(0)).and(changed), trigger);
+        releaseVoice(0, when.and(newest.eq(0)));
+    }
+    function removeHeld(token, when) {
+        const before = previous.read(token);
+        const after = next.read(token);
+        next.write(before, select(when.and(before.gt(0)), after, next.read(before)));
+        previous.write(after, select(when.and(after.gt(0)), before, previous.read(after)));
+        head.write(select(when.and(head.read().eq(token)), after, head.read()));
+        tail.write(select(when.and(tail.read().eq(token)), before, tail.read()));
+        occupied.write(token, select(when, i32(0), occupied.read(token)));
+        previous.write(token, select(when, i32(0), previous.read(token)));
+        next.write(token, select(when, i32(0), next.read(token)));
+        heldNote.write(token, select(when, i32(0), heldNote.read(token)));
+        heldChannel.write(token, select(when, i32(0), heldChannel.read(token)));
+        heldVelocity.write(token, select(when, i32(0), heldVelocity.read(token)));
+    }
+    function noteOff(key, ch, when = bool(true)) {
+        scratch.write(0, 0);
+        scratch.write(1, head.read());
+        for (let n = 0; n < heldSize; n++) {
+            const token = scratch.read(0);
+            const cursor = scratch.read(1);
+            const match = token.eq(0).and(cursor.gt(0)).and(heldNote.read(cursor).eq(key)).and(heldChannel.read(cursor).eq(ch));
+            scratch.write(0, select(match, cursor, token));
+            scratch.write(1, next.read(cursor));
+        }
+        const token = scratch.read(0);
+        const found = when.and(validKey(key, ch)).and(token.gt(0));
+        removeHeld(token, found);
+        if (config.mode === 'mono')
+            monoPriority(found);
+        else
+            for (let n = 0; n < size; n++)
+                releaseVoice(n, found.and(owner.read(n).eq(token)));
+    }
+    function noteOn(key, ch, vel) {
+        noteOff(key, ch, vel.eq(0));
+        const enabled = validKey(key, ch).and(vel.gt(0)).and(vel.lte(127));
+        let token = i32(0);
+        let found = bool(false);
+        for (let n = heldSize; n >= 1; n--) {
+            const free = occupied.read(n).eq(0);
+            token = select(free, i32(n), token);
+            found = found.or(free);
+        }
+        const accept = enabled.and(found);
+        overflow.write(overflow.read().or(enabled.and(found.not())));
+        const last = tail.read();
+        next.write(last, select(accept.and(last.gt(0)), token, next.read(last)));
+        previous.write(token, select(accept, last, previous.read(token)));
+        next.write(token, select(accept, i32(0), next.read(token)));
+        head.write(select(accept.and(last.eq(0)), token, head.read()));
+        tail.write(select(accept, token, tail.read()));
+        occupied.write(token, select(accept, i32(1), occupied.read(token)));
+        heldNote.write(token, select(accept, key, heldNote.read(token)));
+        heldChannel.write(token, select(accept, ch, heldChannel.read(token)));
+        heldVelocity.write(token, select(accept, vel, heldVelocity.read(token)));
+        if (config.mode === 'mono')
+            monoPriority(accept);
+        else {
+            scratch.write(2, 2 * size + 1);
+            scratch.write(3, 0);
+            for (let n = 0; n < size; n++) {
+                const a = age.read(n);
+                const r = releaseAge.read(n);
+                const score = select(a.eq(0), i32(0), select(r.gt(0), r, a.add(size)));
+                const best = scratch.read(2);
+                const chosen = scratch.read(3);
+                const better = score.lt(best); // ascending slots break ties deterministically
+                scratch.write(3, select(better, i32(n), chosen));
+                scratch.write(2, select(better, score, best));
+            }
+            activate(scratch.read(3), token, accept, bool(true));
+        }
+    }
+    function channelOff(ch, immediate, when = bool(true)) {
+        const enabled = when.and(ch.gte(0)).and(ch.lte(15));
+        // Remove matching identities through bounded, constant-time list unlinking.
+        for (let n = 1; n <= heldSize; n++) {
+            removeHeld(i32(n), enabled.and(occupied.read(n).gt(0)).and(heldChannel.read(n).eq(ch)));
+        }
+        if (immediate)
+            for (let n = 0; n < size; n++)
+                freeVoice(n, enabled.and(channel.read(n).eq(ch)));
+        if (config.mode === 'mono')
+            monoPriority(enabled);
+        else if (!immediate)
+            for (let n = 0; n < size; n++)
+                releaseVoice(n, enabled.and(channel.read(n).eq(ch)));
+    }
+    function reset(when = bool(true)) {
+        for (let n = 0; n < size; n++)
+            freeVoice(n, when);
+        for (let n = 0; n <= heldSize; n++) {
+            occupied.write(n, select(when, i32(0), occupied.read(n)));
+            previous.write(n, select(when, i32(0), previous.read(n)));
+            next.write(n, select(when, i32(0), next.read(n)));
+            heldNote.write(n, select(when, i32(0), heldNote.read(n)));
+            heldChannel.write(n, select(when, i32(0), heldChannel.read(n)));
+            heldVelocity.write(n, select(when, i32(0), heldVelocity.read(n)));
+        }
+        head.write(select(when, i32(0), head.read()));
+        tail.write(select(when, i32(0), tail.read()));
+        overflow.write(select(when, false, overflow.read()));
+    }
+    return {
+        capacity: size,
+        heldCapacity: heldSize,
+        noteOn,
+        noteOff,
+        reset,
+        allNotesOff: (ch) => channelOff(ch, false),
+        allSoundOff: (ch) => channelOff(ch, true),
+        overflowed: () => overflow.read(),
+        /** Call once in declaration scope with an existing unworklet MIDI input. */
+        bindMidi(input) {
+            input.onEvent('noteOn', e => noteOn(e.note, e.channel, e.velocity));
+            input.onEvent('noteOff', e => noteOff(e.note, e.channel));
+            input.onEvent('cc', e => {
+                channelOff(e.channel, false, e.controller.eq(123));
+                channelOff(e.channel, true, e.controller.eq(120));
+            });
+        },
+        voices: Array.from({ length: size }, (_, index) => ({
+            read() {
+                const active = age.read(index).gt(0);
+                return {
+                    active,
+                    gate: owner.read(index).gt(0),
+                    note: select(active, note.read(index), i32(-1)),
+                    channel: select(active, channel.read(index), i32(-1)),
+                    velocity: velocity.read(index),
+                };
+            },
+            /** One latched start/retrigger; read once per sample before invoking the envelope. */
+            takeRetrigger() {
+                const value = retrigger.read(index).gt(0);
+                retrigger.write(index, 0);
+                return value;
+            },
+            /** Envelope completion may free only a released voice, never a newly held one. */
+            releaseFinished(done) {
+                freeVoice(index, done.and(owner.read(index).eq(0)));
+            },
+        })),
+    };
+});

package/dist/wavetable-bands.d.ts

@@ -0,0 +1,37 @@
+import type { WavetableConfig, WavetableControls } from './wavetable.js';
+export interface PreparedWavetableBands {
+    /** Band-major, then frame-major complete cycles, without duplicated endpoints. */
+    data: Float32Array;
+    frameLength: number;
+    frameCount: number;
+    /** Descending retained positive harmonics; DC is preserved in every band. */
+    harmonicLimits: readonly number[];
+}
+export interface WavetableBandsOptions {
+    /** Original finite mono cycles. Equal power-of-two lengths 16..4096; 1..16 frames.
+     * All derived bands together must fit 65536 samples. Input is never changed. */
+    frames: readonly Float32Array[];
+}
+/** Layout is the fixed schedule produced by prepareWavetableBands. */
+export interface BandedWavetableConfig extends WavetableConfig {
+    /** Power of two, 16..4096 samples per cycle. */
+    frameLength: number;
+    /** 1..16 morph frames; frameLength * frameCount * derived band count must
+     * fit both the shared resident capacity and the 65536-sample native limit. */
+    frameCount: number;
+}
+/** Prepare harmonic-truncated pitch bands outside the audio callback. No per-band
+ * normalization, resampling, loader, or provenance/license assumption is added.
+ * Reject nonfinite input or reconstruction that overflows float32. DC, phase and
+ * retained harmonic gain are preserved within FFT/float32 roundoff. */
+export declare function prepareWavetableBands({ frames }: WavetableBandsOptions): PreparedWavetableBands;
+/** Four periodic cycle interpolations: frame morph in neighboring pitch bands.
+ * Fetches eight integer resident reads so tiny local fractions survive offsets.
+ * Static harmonic truncation is not a brickwall reconstruction filter and does
+ * not remove interpolation images or bandwidth from modulation/reset/asset edits. */
+export declare const bandedWavetableSource: import("@unworklet/core").SubgraphDecl<[config: BandedWavetableConfig], {
+    tick(c: WavetableControls): {
+        output: import("@unworklet/core").Node<"f32">;
+        missing: import("@unworklet/core").Node<"bool">;
+    };
+}>;

package/dist/wavetable-bands.js

@@ -0,0 +1,145 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+import { readWavetableCycle } from './wavetable-read.js';
+function layout(length, count) {
+    if (!Number.isInteger(length) || length < 16 || length > 4096 || !Number.isInteger(Math.log2(length)) ||
+        !Number.isInteger(count) || count < 1 || count > 16)
+        throw new RangeError('banded wavetable requires power-of-two frameLength 16..4096 and frameCount 1..16');
+    const harmonics = [];
+    for (let h = length / 2 - 1; h >= 1; h = Math.floor(h / 2))
+        harmonics.push(h);
+    const required = length * count * harmonics.length;
+    if (required > 65536)
+        throw new RangeError('all wavetable bands must fit 65536 samples');
+    return { harmonics, required };
+}
+// Host-only radix-2 FFT. This runs before native ingress, never in audio processing.
+function transform(real, imag, inverse) {
+    const size = real.length;
+    for (let n = 1, j = 0; n < size; n++) {
+        let bit = size >> 1;
+        for (; j & bit; bit >>= 1)
+            j ^= bit;
+        j ^= bit;
+        if (n < j) {
+            const r = real[n], im = imag[n];
+            real[n] = real[j];
+            imag[n] = imag[j];
+            real[j] = r;
+            imag[j] = im;
+        }
+    }
+    for (let width = 2; width <= size; width *= 2) {
+        for (let base = 0; base < size; base += width)
+            for (let k = 0; k < width / 2; k++) {
+                const angle = (inverse ? 2 : -2) * Math.PI * k / width, c = Math.cos(angle), s = Math.sin(angle);
+                const a = base + k, b = a + width / 2;
+                const tr = c * real[b] - s * imag[b], ti = s * real[b] + c * imag[b];
+                real[b] = real[a] - tr;
+                imag[b] = imag[a] - ti;
+                real[a] += tr;
+                imag[a] += ti;
+            }
+    }
+    if (inverse)
+        for (let n = 0; n < size; n++) {
+            real[n] /= size;
+            imag[n] /= size;
+        }
+}
+/** Prepare harmonic-truncated pitch bands outside the audio callback. No per-band
+ * normalization, resampling, loader, or provenance/license assumption is added.
+ * Reject nonfinite input or reconstruction that overflows float32. DC, phase and
+ * retained harmonic gain are preserved within FFT/float32 roundoff. */
+export function prepareWavetableBands({ frames }) {
+    const frameCount = frames.length, frameLength = frames[0]?.length ?? 0;
+    const { harmonics, required } = layout(frameLength, frameCount);
+    for (const frame of frames) {
+        if (!(frame instanceof Float32Array) || frame.length !== frameLength || frame.some(x => !Number.isFinite(x))) {
+            throw new RangeError('wavetable frames must be equal-length finite Float32Arrays');
+        }
+    }
+    const data = new Float32Array(required);
+    const real = new Float64Array(frameLength), imag = new Float64Array(frameLength);
+    const r = new Float64Array(frameLength), im = new Float64Array(frameLength);
+    for (let frame = 0; frame < frameCount; frame++) {
+        real.set(frames[frame]);
+        imag.fill(0);
+        transform(real, imag, false);
+        for (let band = 0; band < harmonics.length; band++) {
+            r.fill(0);
+            im.fill(0);
+            const limit = harmonics[band];
+            r[0] = real[0];
+            // Explicit conjugate pairs guarantee a real table despite FFT roundoff.
+            for (let h = 1; h <= limit; h++) {
+                r[h] = (real[h] + real[frameLength - h]) / 2;
+                im[h] = (imag[h] - imag[frameLength - h]) / 2;
+                r[frameLength - h] = r[h];
+                im[frameLength - h] = -im[h];
+            }
+            transform(r, im, true);
+            const offset = (band * frameCount + frame) * frameLength;
+            for (let n = 0; n < frameLength; n++) {
+                const value = Math.fround(r[n]);
+                if (!Number.isFinite(value))
+                    throw new RangeError('prepared wavetable exceeds finite float32 PCM range');
+                data[offset + n] = value;
+            }
+        }
+    }
+    return { data, frameLength, frameCount, harmonicLimits: Object.freeze(harmonics) };
+}
+function bounded(value, high) {
+    return select(value.eq(value), f64(value), f64(0)).clamp(0, high);
+}
+/** Four periodic cycle interpolations: frame morph in neighboring pitch bands.
+ * Fetches eight integer resident reads so tiny local fractions survive offsets.
+ * Static harmonic truncation is not a brickwall reconstruction filter and does
+ * not remove interpolation images or bandwidth from modulation/reset/asset edits. */
+export const bandedWavetableSource = defineSubgraph((config) => {
+    const { sampleRate, sample, frameLength, frameCount, phaseCycles = 0 } = config;
+    const { harmonics, required } = layout(frameLength, frameCount);
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('banded wavetable sampleRate must be in [8000,192000] Hz');
+    if (!Number.isInteger(sample.capacity) || sample.capacity < required || sample.capacity > 65536)
+        throw new RangeError('all wavetable bands must fit resident capacity');
+    if (!Number.isFinite(phaseCycles) || phaseCycles < 0 || phaseCycles >= 1)
+        throw new RangeError('phaseCycles must be in [0,1)');
+    const phaseScale = 2 ** 1020, controlScale = 2 ** 128;
+    const phase = state.f64(phaseCycles * phaseScale).named('scaledPhase'), revision = state.i32(-1).named('revision');
+    const current = state.f64(phaseCycles * phaseScale).named('scaledCurrentPhase');
+    const scan = state.f64(0).named('scaledFrame'), pitch = state.f64(0).named('scaledFrequency'), band = state.f64(0).named('scaledBand');
+    const frameLo = state.i32(0).named('frameLo'), frameHi = state.i32(0).named('frameHi');
+    const bandLo = state.i32(0).named('bandLo'), bandHi = state.i32(0).named('bandHi');
+    const starts = Array.from({ length: 4 }, (_, i) => state.i32(0).named(`start${i}`));
+    return { tick(c) {
+            current.write(select(c.reset.or(sample.revision().eq(revision.read()).not()), f64(phaseCycles * phaseScale), phase.read()));
+            scan.write(bounded(c.frame, frameCount - 1).mul(controlScale));
+            pitch.write(bounded(c.frequencyHz, .45 * sampleRate).mul(controlScale));
+            const frequency = pitch.read().div(controlScale), frame = scan.read().div(controlScale), p = current.read().div(phaseScale);
+            // Nonoverlapping transitions: the bright H band has zero weight by .45*sr/H.
+            let position = f64(0);
+            for (const h of harmonics.slice(0, -1)) {
+                const start = .225 * sampleRate / h;
+                position = position.add(frequency.sub(start).div(start).clamp(0, 1));
+            }
+            band.write(position.mul(controlScale));
+            const b = band.read().div(controlScale), frameMix = frame.sub(frame.floor()), bandMix = b.sub(b.floor());
+            frameLo.write(i32(frame.floor()));
+            frameHi.write(frameLo.read().add(1).min(frameCount - 1));
+            bandLo.write(i32(b.floor()));
+            bandHi.write(bandLo.read().add(1).min(harmonics.length - 1));
+            starts[0].write(bandLo.read().mul(frameCount).add(frameLo.read()).mul(frameLength));
+            starts[1].write(bandLo.read().mul(frameCount).add(frameHi.read()).mul(frameLength));
+            starts[2].write(bandHi.read().mul(frameCount).add(frameLo.read()).mul(frameLength));
+            starts[3].write(bandHi.read().mul(frameCount).add(frameHi.read()).mul(frameLength));
+            const values = starts.map(start => readWavetableCycle(sample, p, start.read(), frameLength));
+            const a = f64(values[0]).mul(f64(1).sub(frameMix)).add(f64(values[1]).mul(frameMix));
+            const z = f64(values[2]).mul(f64(1).sub(frameMix)).add(f64(values[3]).mul(frameMix));
+            const missing = sample.length().lt(required);
+            const output = select(missing, f32(0), f32(a.mul(f64(1).sub(bandMix)).add(z.mul(bandMix))));
+            phase.write(p.add(frequency.div(sampleRate)).frac().mul(phaseScale));
+            revision.write(sample.revision());
+            return { output, missing };
+        } };
+});

package/dist/wavetable-read.d.ts

@@ -0,0 +1,6 @@
+import { type Node } from '@unworklet/core';
+import type { ResidentSample } from './sample.js';
+/** Construction helper, not a resident/runtime API. Keep the cycle-local fraction
+ * separate from the absolute integer offset so tiny phase contributions survive
+ * at nonzero frames/bands even against the full finite float32 PCM range. */
+export declare function readWavetableCycle(sample: ResidentSample, phase: Node<'f64'>, start: Node<'i32'>, length: number): Node<'f32'>;

package/dist/wavetable-read.js

@@ -0,0 +1,11 @@
+import { f32, f64, i32 } from '@unworklet/core';
+/** Construction helper, not a resident/runtime API. Keep the cycle-local fraction
+ * separate from the absolute integer offset so tiny phase contributions survive
+ * at nonzero frames/bands even against the full finite float32 PCM range. */
+export function readWavetableCycle(sample, phase, start, length) {
+    const position = phase.mul(length), whole = i32(position.floor()), fraction = position.sub(f64(whole));
+    const a = sample.read(f64(start.add(whole)), start, start.add(length), false);
+    const b = sample.read(f64(start.add(whole.add(1).mod(length))), start, start.add(length), false);
+    // Convex weighting avoids cancellation in a+(b-a)*fraction near the endpoint.
+    return f32(f64(a).mul(f64(1).sub(fraction)).add(f64(b).mul(fraction)));
+}

package/dist/wavetable.d.ts

@@ -0,0 +1,29 @@
+import { type Node } from '@unworklet/core';
+import type { ResidentSample } from './sample.js';
+export interface WavetableConfig {
+    sampleRate: number;
+    /** Shared mono PCM. Concatenate complete cycles, without duplicate end samples. */
+    sample: ResidentSample;
+    /** Samples per cycle, integer4..4096. */
+    frameLength: number;
+    /** Fixed number of morph frames, integer1..16; total must fit resident capacity. */
+    frameCount: number;
+    /** Initial/reset phase in cycles, [0,1). */
+    phaseCycles?: number;
+}
+export interface WavetableControls {
+    /** Hz clipped to [0,.45*sampleRate], NaN becomes0. */
+    frequencyHz: Node<'f32'>;
+    /** Fractional frame index, clipped to [0,frameCount−1], NaN becomes0. */
+    frame: Node<'f32'>;
+    /** Level-sensitive phase reset. A resident revision also restarts phase. */
+    reset: Node<'bool'>;
+}
+/** Two periodic linear cycle interpolations and frame morph. No automatic bandlimit. */
+export declare const wavetableSource: import("@unworklet/core").SubgraphDecl<[config: WavetableConfig], {
+    tick(c: WavetableControls): {
+        output: Node<"f32">;
+        missing: Node<"bool">;
+    };
+}>;
+export { bandedWavetableSource, prepareWavetableBands, type BandedWavetableConfig, type PreparedWavetableBands, type WavetableBandsOptions } from './wavetable-bands.js';

package/dist/wavetable.js

@@ -0,0 +1,49 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+import { readWavetableCycle } from './wavetable-read.js';
+function integer(value, low, high, name) {
+    if (!Number.isInteger(value) || value < low || value > high)
+        throw new RangeError(`${name} must be an integer in [${low},${high}]`);
+}
+function bounded(value, high) {
+    return select(value.eq(value), f64(value), f64(0)).clamp(0, high);
+}
+/** Two periodic linear cycle interpolations and frame morph. No automatic bandlimit. */
+export const wavetableSource = defineSubgraph((config) => {
+    const { sampleRate, sample, frameLength, frameCount, phaseCycles = 0 } = config;
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('wavetable sampleRate must be in [8000,192000] Hz');
+    integer(sample.capacity, 4, 65536, 'resident capacity');
+    integer(frameLength, 4, 4096, 'frameLength');
+    integer(frameCount, 1, 16, 'frameCount');
+    const required = frameLength * frameCount;
+    if (required > sample.capacity)
+        throw new RangeError('wavetable frames must fit resident capacity');
+    if (!Number.isFinite(phaseCycles) || phaseCycles < 0 || phaseCycles >= 1)
+        throw new RangeError('phaseCycles must be in [0,1)');
+    // Phase accepts f64 configuration, including Number.MIN_VALUE: scaling
+    // by 2^1020 keeps even that value above the native 1e-30 flush. Phase
+    // is always <1 before scaling, leaving >16x finite headroom. Morph is
+    // f32 input and only needs 2^128; neither scaled value touches PCM.
+    const scale = 2 ** 1020, frameScale = 2 ** 128;
+    const phase = state.f64(phaseCycles * scale).named('scaledPhase'), revision = state.i32(-1).named('revision');
+    // Native materialization bounds capture size even when resident.read expands
+    // its four wrap/validation paths. These are ordinary same-schema snapshot slots.
+    const current = state.f64(phaseCycles * scale).named('scaledCurrentPhase'), scan = state.f64(0).named('scaledFrame');
+    const lower = state.i32(0).named('lowerStart'), upper = state.i32(0).named('upperStart');
+    return { tick(c) {
+            const changed = sample.revision().eq(revision.read()).not();
+            current.write(select(c.reset.or(changed), f64(phaseCycles * scale), phase.read()));
+            scan.write(bounded(c.frame, frameCount - 1).mul(frameScale));
+            const frame = scan.read().div(frameScale), p = current.read().div(scale);
+            lower.write(i32(frame.floor()).mul(frameLength));
+            upper.write(i32(frame.floor()).add(1).min(frameCount - 1).mul(frameLength));
+            const a = readWavetableCycle(sample, p, lower.read(), frameLength);
+            const b = readWavetableCycle(sample, p, upper.read(), frameLength);
+            const missing = sample.length().lt(required), mix = frame.sub(frame.floor());
+            const output = select(missing, f32(0), f32(f64(a).mul(f64(1).sub(mix)).add(f64(b).mul(mix))));
+            phase.write(p.add(bounded(c.frequencyHz, .45 * sampleRate).div(sampleRate)).frac().mul(scale));
+            revision.write(sample.revision());
+            return { output, missing };
+        } };
+});
+export { bandedWavetableSource, prepareWavetableBands } from './wavetable-bands.js';