@denaudio/den 0.0.0-stage → 0.2.0

package/dist/convolution-spectrum.js

@@ -0,0 +1,82 @@
+export const PREPARED_BLOCK = 128;
+export const PREPARED_FFT_SIZE = 256;
+export const PREPARED_PARTITIONS = 64;
+export const PREPARED_VALUES = 32768;
+export const PREPARATION_ERROR_LIMIT = 4e-6;
+const CERTIFICATE_GUARD = 1e-8;
+export function validatePreparedConvolutionConfig(config) {
+    if (!config || config.blockSize !== PREPARED_BLOCK || config.partitions !== PREPARED_PARTITIONS) {
+        throw new RangeError('preparedConvolution requires fixed blockSize 128 and partitions 64');
+    }
+}
+/** Host-only preparation. Do not call from an audio callback.
+ * Returns a complete native f32 packet; send it unchanged through the caller's
+ * explicitly sized native event. The original IR is not normalized or clipped.
+ * Quantization is approximate, with a guarded inverse-DFT error certificate.
+ */
+export function prepareConvolutionSpectrum(impulse, config) {
+    validatePreparedConvolutionConfig(config);
+    if (!(Array.isArray(impulse) || impulse instanceof Float32Array || impulse instanceof Float64Array) || impulse.length < 1 || impulse.length > 8192) {
+        throw new RangeError('prepared convolution IR requires 1..8192 real taps');
+    }
+    const taps = Array.from(impulse);
+    let absoluteSum = 0, compensation = 0;
+    for (const tap of taps) {
+        if (!Number.isFinite(tap) || Math.abs(tap) > 1)
+            throw new RangeError('prepared convolution IR taps must be finite in [-1,1]');
+        const increment = Math.abs(tap) - compensation, next = absoluteSum + increment;
+        compensation = (next - absoluteSum) - increment;
+        absoluteSum = next;
+    }
+    if (absoluteSum > 4)
+        throw new RangeError('prepared convolution IR absolute sum must be <=4');
+    const B = PREPARED_BLOCK, N = PREPARED_FFT_SIZE;
+    const spectrum = new Float32Array(PREPARED_VALUES);
+    const cosine = Float64Array.from({ length: N }, (_, n) => Math.cos(2 * Math.PI * n / N));
+    const sine = Float64Array.from({ length: N }, (_, n) => Math.sin(2 * Math.PI * n / N));
+    // Independent inverse basis, with modulo-reduced arguments. It checks every
+    // reconstructed tap, including the half that is ideally zero padding.
+    const inverseCos = Float64Array.from({ length: N * N }, (_, index) => {
+        const n = Math.floor(index / N), k = index % N;
+        return Math.cos(2 * Math.PI * ((n * k) % N) / N);
+    });
+    const inverseSin = Float64Array.from({ length: N * N }, (_, index) => {
+        const n = Math.floor(index / N), k = index % N;
+        return Math.sin(2 * Math.PI * ((n * k) % N) / N);
+    });
+    let error = CERTIFICATE_GUARD;
+    for (let p = 0; p < Math.ceil(taps.length / B); p++) {
+        const values = Array.from({ length: B }, (_, n) => taps[p * B + n] ?? 0);
+        if (values.every(value => value === 0))
+            continue;
+        for (let k = 0; k <= N / 2; k++) {
+            let real = 0, imag = 0;
+            for (let n = 0; n < B; n++) {
+                real += values[n] * cosine[(k * n) % N];
+                imag -= values[n] * sine[(k * n) % N];
+            }
+            const re = Math.fround(real), im = k === 0 || k === N / 2 ? 0 : Math.fround(imag);
+            if (!Number.isFinite(re) || !Number.isFinite(im) || Math.abs(re) > 4 || Math.abs(im) > 4)
+                throw new RangeError('prepared convolution spectrum exceeds finite component bounds');
+            spectrum[2 * (p * N + k)] = re;
+            spectrum[2 * (p * N + k) + 1] = im;
+            if (k > 0 && k < N / 2) {
+                spectrum[2 * (p * N + N - k)] = re;
+                spectrum[2 * (p * N + N - k) + 1] = -im;
+            }
+        }
+        for (let n = 0; n < N; n++) {
+            let real = 0, imag = 0;
+            for (let k = 0; k < N; k++) {
+                const re = spectrum[2 * (p * N + k)], im = spectrum[2 * (p * N + k) + 1];
+                const c = inverseCos[n * N + k], s = inverseSin[n * N + k];
+                real += re * c - im * s;
+                imag += re * s + im * c;
+            }
+            error += Math.abs(real / N - (values[n] ?? 0)) + Math.abs(imag / N);
+        }
+    }
+    if (!Number.isFinite(error) || error > PREPARATION_ERROR_LIMIT)
+        throw new RangeError('prepared convolution IR exceeds the guarded 4e-6 quantization certificate');
+    return { formatVersion: 1, blockSize: B, partitions: PREPARED_PARTITIONS, impulseFrames: taps.length, declaredValues: PREPARED_VALUES, spectrum };
+}

package/dist/convolution.d.ts

@@ -0,0 +1,17 @@
+import { type EveryNSamples, type Node } from '@unworklet/core';
+export interface PartitionedConvolutionConfig {
+    /** Pass ctx.renderQuantumSize; aligns native dispatch with snapshot boundaries. */
+    renderQuantumSize: number;
+    /** Construction-fixed power of two in [4,32]. FFT size is twice this value. */
+    blockSize: number;
+    /** Fixed IR, length 1..4*blockSize. Every tap in [-1,1], total absolute gain <=4. */
+    impulse: readonly number[];
+}
+/** Bounded uniform-partition convolution candidate, exactly blockSize latency.
+ * Call once per sample in stride-1 forSample with its native everyNSamples.
+ * Input must be finite normalized audio [-1,1]. No IR loader/swap or dry path.
+ * Level reset silences immediately and discards its input without rephasing hops.
+ */
+export declare const partitionedConvolution: import("@unworklet/core").SubgraphDecl<[config: PartitionedConvolutionConfig], {
+    tick(input: Node<"f32">, reset: Node<"bool">, everyNSamples: EveryNSamples): Node<"f32">;
+}>;

package/dist/convolution.js

@@ -0,0 +1,87 @@
+import { defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+import { spectralDispatchPeriod, spectralFft } from './spectral-fft.js';
+/** Bounded uniform-partition convolution candidate, exactly blockSize latency.
+ * Call once per sample in stride-1 forSample with its native everyNSamples.
+ * Input must be finite normalized audio [-1,1]. No IR loader/swap or dry path.
+ * Level reset silences immediately and discards its input without rephasing hops.
+ */
+export const partitionedConvolution = defineSubgraph((config) => {
+    const { blockSize: block } = config;
+    if (!Number.isInteger(block) || block < 4 || block > 32 || !Number.isInteger(Math.log2(block)) ||
+        !Array.isArray(config.impulse) || config.impulse.length < 1 || config.impulse.length > 4 * block ||
+        Array.from(config.impulse).some(tap => !Number.isFinite(tap) || Math.abs(tap) > 1) ||
+        config.impulse.reduce((sum, tap) => sum + Math.abs(tap), 0) > 4) {
+        throw new RangeError('partitionedConvolution requires power-of-two blockSize [4,32], 1..4*blockSize finite IR taps in [-1,1], and IR absolute sum <=4');
+    }
+    const dispatchPeriod = spectralDispatchPeriod(block, config.renderQuantumSize);
+    const impulse = [...config.impulse], size = 2 * block, partitions = Math.ceil(impulse.length / block);
+    // Construction-only O(P*N*B) coefficient preparation. No host FFT runtime,
+    // asset read, callback allocation or coefficient update on the audio thread.
+    const spectra = Array.from({ length: partitions }, (_, p) => Array.from({ length: size }, (_, k) => {
+        let real = 0, imag = 0;
+        for (let n = 0; n < block; n++) {
+            const tap = impulse[p * block + n] ?? 0, angle = -2 * Math.PI * k * n / size;
+            real += tap * Math.cos(angle);
+            imag += tap * Math.sin(angle);
+        }
+        return { real, imag };
+    }));
+    const fft = instantiate(spectralFft, { size }, { name: 'fft' });
+    const scale = 2 ** 128;
+    const history = state.buffer.f64({ size: block }).expose({ name: 'historyScaled', snapshot: 'persistent' });
+    const previousReal = state.buffer.f64({ size: partitions * size }).expose({ name: 'previousReal', snapshot: 'persistent' });
+    const previousImag = state.buffer.f64({ size: partitions * size }).expose({ name: 'previousImag', snapshot: 'persistent' });
+    const mixedReal = state.buffer.f64({ size }).expose({ name: 'mixedReal', snapshot: 'transient' });
+    const mixedImag = state.buffer.f64({ size }).expose({ name: 'mixedImag', snapshot: 'transient' });
+    const overlap = state.buffer.f64({ size }).expose({ name: 'overlap', snapshot: 'persistent' });
+    const cursor = state.i32(0).named('cursor');
+    const spectrumCursor = state.i32(0).named('spectrumCursor');
+    const validSamples = state.i32(0).named('validSamples');
+    const validBlocks = state.i32(0).named('validBlocks');
+    const pendingReset = state.bool(true).named('pendingReset');
+    return {
+        tick(input, reset, everyNSamples) {
+            validSamples.write(select(reset, i32(0), validSamples.read()));
+            validBlocks.write(select(reset, i32(0), validBlocks.read()));
+            pendingReset.write(pendingReset.read().or(reset));
+            // A quantum need not divide blockSize. Persistent cursor phase keeps
+            // frame commits exact when native scheduler counters restart on restore.
+            everyNSamples(dispatchPeriod, () => {
+                const frameDue = cursor.read().mod(block).eq(0);
+                const transformed = fft.transform(n => select(n.lt(block).and(validSamples.read().gte(i32(block).sub(n))), history.read(cursor.read().add(n).mod(block)), f64(0)), () => f64(0), false);
+                for (let k = 0; k < size; k++) {
+                    const index = spectrumCursor.read().mul(size).add(k);
+                    previousReal.write(index, select(frameDue, transformed.real(k), previousReal.read(index)));
+                    previousImag.write(index, select(frameDue, transformed.imag(k), previousImag.read(index)));
+                }
+                for (let k = 0; k < size; k++) {
+                    let real = f64(0), imag = f64(0);
+                    for (let p = 0; p < partitions; p++) {
+                        const index = spectrumCursor.read().add(partitions - p).mod(partitions).mul(size).add(k);
+                        const xr = select(validBlocks.read().gte(p), previousReal.read(index), f64(0));
+                        const xi = select(validBlocks.read().gte(p), previousImag.read(index), f64(0));
+                        real = real.add(xr.mul(spectra[p][k].real).sub(xi.mul(spectra[p][k].imag)));
+                        imag = imag.add(xr.mul(spectra[p][k].imag).add(xi.mul(spectra[p][k].real)));
+                    }
+                    mixedReal.write(k, real);
+                    mixedImag.write(k, imag);
+                }
+                const frame = fft.transform(n => mixedReal.read(n), n => mixedImag.read(n), true);
+                for (let n = 0; n < size; n++) {
+                    const index = cursor.read().add(n).mod(size);
+                    const prior = overlap.read(index);
+                    overlap.write(index, select(frameDue, select(pendingReset.read(), f64(0), prior).add(frame.real(n)), prior));
+                }
+                spectrumCursor.write(select(frameDue, spectrumCursor.read().add(1).mod(partitions), spectrumCursor.read()));
+                validBlocks.write(select(frameDue, validBlocks.read().add(1).min(partitions - 1), validBlocks.read()));
+                pendingReset.write(pendingReset.read().and(frameDue.not()));
+            });
+            const output = select(reset.or(pendingReset.read()), f32(0), f32(overlap.read(cursor.read()).div(scale)));
+            overlap.write(cursor.read(), f64(0));
+            history.write(cursor.read().mod(block), f64(select(reset, f32(0), input)).mul(scale));
+            cursor.write(cursor.read().add(1).mod(size));
+            validSamples.write(select(reset, i32(0), validSamples.read().add(1).min(block)));
+            return output;
+        },
+    };
+});

package/dist/crossover.d.ts

@@ -0,0 +1,11 @@
+import { type Node } from '@unworklet/core';
+export interface CrossoverConfig {
+    sampleRate: number;
+}
+/** Fourth-order Linkwitz–Riley: cascaded Butterworth LP/HP; positive-polarity sum is allpass. */
+export declare const crossover: import("@unworklet/core").SubgraphDecl<[config: CrossoverConfig], {
+    tick(input: Node<"f32">, cutoffHz: Node<"f32">, reset: Node<"bool">): {
+        low: Node<"f32">;
+        high: Node<"f32">;
+    };
+}>;

package/dist/crossover.js

@@ -0,0 +1,17 @@
+import { defineSubgraph, f32, instantiate } from '@unworklet/core';
+import { stateVariableFilter } from './state-variable-filter.js';
+import { checkedSampleRate } from './catalog-filter-math.js';
+/** Fourth-order Linkwitz–Riley: cascaded Butterworth LP/HP; positive-polarity sum is allpass. */
+export const crossover = defineSubgraph((config) => {
+    checkedSampleRate(config.sampleRate);
+    const first = instantiate(stateVariableFilter, config, { name: 'first' });
+    const low = instantiate(stateVariableFilter, config, { name: 'low' });
+    const high = instantiate(stateVariableFilter, config, { name: 'high' });
+    return {
+        tick(input, cutoffHz, reset) {
+            const firstOutput = first.tick(input, cutoffHz, f32(Math.SQRT1_2), reset);
+            return { low: low.tick(firstOutput.lowpass, cutoffHz, f32(Math.SQRT1_2), reset).lowpass,
+                high: high.tick(firstOutput.highpass, cutoffHz, f32(Math.SQRT1_2), reset).highpass };
+        },
+    };
+});

package/dist/curve-shaper.d.ts

@@ -0,0 +1,26 @@
+import { type Node } from '@unworklet/core';
+export type CurveShaperQuality = 'direct' | 'adaa';
+export interface CurveShaperConfig {
+    sampleRate: number;
+    /** Fixed count of equally spaced input knots on [-1,1], integer 2..17. */
+    pointCount: number;
+    /** Immutable quality. First-order interval averaging is not oversampling. */
+    quality?: CurveShaperQuality;
+}
+export interface CurveShaperControls {
+    /** Exactly pointCount audio-rate y values. Each clamps to [-1,1], NaN -> 0. */
+    ordinates: readonly Node<'f32'>[];
+    /** Linear multiplier [0,32]. Changes affect the current driven input. */
+    gain: Node<'f32'>;
+    /** Immediate blend [0,1]. ADAA dry uses a two-sample average. */
+    mix: Node<'f32'>;
+    /** Clear histories before processing this sample, including its curve edits. */
+    reset: Node<'bool'>;
+}
+/** Bounded editable piecewise-linear LUT, optionally first-order antialiased for
+ * fixed curves. Curve edits use current ordinates over the whole input interval;
+ * their modulation is not smoothed or guaranteed alias-free. Call once/sample.
+ */
+export declare const curveShaper: import("@unworklet/core").SubgraphDecl<[config: CurveShaperConfig], {
+    tick(input: Node<"f32">, controls: CurveShaperControls): Node<"f32">;
+}>;

package/dist/curve-shaper.js

@@ -0,0 +1,73 @@
+import { defineSubgraph, f32, f64, select, state } from '@unworklet/core';
+const HISTORY_SCALE = 2 ** 128;
+function bounded(value, low, high) {
+    const wide = f64(value);
+    return select(wide.eq(wide), wide, f64(0)).clamp(low, high);
+}
+/** Bounded editable piecewise-linear LUT, optionally first-order antialiased for
+ * fixed curves. Curve edits use current ordinates over the whole input interval;
+ * their modulation is not smoothed or guaranteed alias-free. Call once/sample.
+ */
+export const curveShaper = defineSubgraph((config) => {
+    const { sampleRate, pointCount, quality = 'adaa' } = config;
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('curveShaper sampleRate must be in [8000,192000] Hz');
+    if (!Number.isInteger(pointCount) || pointCount < 2 || pointCount > 17)
+        throw new RangeError('curveShaper pointCount must be an integer in [2,17]');
+    if (quality !== 'direct' && quality !== 'adaa')
+        throw new RangeError('unknown curveShaper quality');
+    const previous = quality === 'adaa' ? state.f64(0).named('previous-driven-scaled') : undefined;
+    const previousDry = quality === 'adaa' ? state.f64(0).named('previous-dry-scaled') : undefined;
+    const extent = pointCount - 1;
+    return { tick(input, controls) {
+            if (controls.ordinates.length !== pointCount)
+                throw new RangeError('curveShaper ordinates must contain exactly pointCount nodes');
+            const y = controls.ordinates.map(value => bounded(value, -1, 1));
+            const dry = bounded(input, -8, 8), x = dry.mul(bounded(controls.gain, 0, 32));
+            const mix = bounded(controls.mix, 0, 1);
+            // Integer knot coordinates avoid asymmetry from rounded fractional knots.
+            const coordinate = x.mul(extent);
+            const segment = (value, i) => {
+                const left = -extent + 2 * i, right = left + 2;
+                const difference = y[i + 1].sub(y[i]), slope = difference.mul(.5);
+                const nonzero = slope.eq(0).not();
+                // Anchor a sign-crossing segment at its zero, preserving tiny input for
+                // e.g. the two-point identity LUT. All select branches execute: protect
+                // zero slope even when its root is not selected.
+                const root = select(y[i].eq(0), f64(left), select(y[i + 1].eq(0), f64(right), y[i + 1].mul(left).sub(y[i].mul(right)).div(select(nonzero, difference, f64(1)))));
+                const crossing = y[i].mul(y[i + 1]).lte(0).and(nonzero);
+                return select(crossing, value.sub(root).mul(slope), y[i].add(value.sub(left).mul(slope)));
+            };
+            const shape = (value) => {
+                let output = y[pointCount - 1];
+                for (let i = pointCount - 2; i >= 0; i--) {
+                    output = select(value.lt(-extent + 2 * (i + 1)), segment(value, i), output);
+                }
+                return select(value.lte(-extent), y[0], output);
+            };
+            let wet, alignedDry = dry;
+            if (previous && previousDry) {
+                const last = select(controls.reset, f64(0), previous.read().div(HISTORY_SCALE));
+                const lastDry = select(controls.reset, f64(0), previousDry.read().div(HISTORY_SCALE));
+                const lastCoordinate = last.mul(extent);
+                const low = coordinate.min(lastCoordinate), high = coordinate.max(lastCoordinate), distance = high.sub(low);
+                // In integer-knot coordinates |dy/dt| <= 1. Mean-vs-midpoint
+                // error <= distance/4 <=2.5e-7, including knot crossings.
+                const close = distance.lte(1e-6);
+                let area = high.min(-extent).sub(low).max(0).mul(y[0])
+                    .add(high.sub(low.max(extent)).max(0).mul(y[pointCount - 1]));
+                for (let i = 0; i < pointCount - 1; i++) {
+                    const left = -extent + 2 * i, right = left + 2;
+                    const a = low.clamp(left, right), b = high.clamp(left, right);
+                    area = area.add(b.sub(a).mul(segment(a.add(b).mul(.5), i)));
+                }
+                wet = select(close, shape(coordinate.add(lastCoordinate).mul(.5)), area.div(select(close, f64(1), distance)));
+                alignedDry = dry.add(lastDry).mul(.5);
+                previous.write(x.mul(HISTORY_SCALE));
+                previousDry.write(dry.mul(HISTORY_SCALE));
+            }
+            else
+                wet = shape(coordinate);
+            return f32(alignedDry.mul(f64(1).sub(mix)).add(wet.mul(mix)));
+        } };
+});

package/dist/delay-fx.d.ts

@@ -0,0 +1,37 @@
+import { type Node } from '@unworklet/core';
+export interface DelayFxConfig {
+    sampleRate: number;
+    /** Fixed allocation per channel; eight seconds is a configurable starting default. */
+    maxDelaySeconds?: number;
+    /** Immutable feedback tone mode. Flat is useful when uncolored repeats are wanted. */
+    tone?: 'lowpass' | 'flat';
+    /** Right LFO phase relative to left, in cycles. Default 0.5 (opposite motion). */
+    stereoPhaseCycles?: number;
+}
+export interface DelayFxControls {
+    timeLeftSeconds: Node<'f32'>;
+    timeRightSeconds: Node<'f32'>;
+    /** When true, use 60 * beats / bpm. One beat is a quarter note. */
+    sync: Node<'bool'>;
+    bpm: Node<'f32'>;
+    beatsLeft: Node<'f32'>;
+    beatsRight: Node<'f32'>;
+    feedback: Node<'f32'>;
+    cutoffHz: Node<'f32'>;
+    mix: Node<'f32'>;
+    rateHz: Node<'f32'>;
+    depthSeconds: Node<'f32'>;
+    bypass: Node<'bool'>;
+    reset: Node<'bool'>;
+}
+/** One stereo delay FX engine. Tick once per sample; duplicate mono input explicitly.
+ * Finite audio/controls required. See docs/delay-fx.md for bounds and acoustic policies.
+ */
+export declare const delayFx: import("@unworklet/core").SubgraphDecl<[config: DelayFxConfig], {
+    tick(inputLeft: Node<"f32">, inputRight: Node<"f32">, c: DelayFxControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+        timingRejected: Node<"bool">;
+        modulationClipped: Node<"bool">;
+    };
+}>;

package/dist/delay-fx.js

@@ -0,0 +1,84 @@
+import { defineSubgraph, instantiate, f32, f64, select, state } from '@unworklet/core';
+import { delayReadhead } from './delay-readhead.js';
+import { filter } from './filter.js';
+import { lfo, modulateDelay } from './lfo.js';
+/** One stereo delay FX engine. Tick once per sample; duplicate mono input explicitly.
+ * Finite audio/controls required. See docs/delay-fx.md for bounds and acoustic policies.
+ */
+export const delayFx = defineSubgraph((config) => {
+    const { sampleRate, maxDelaySeconds = 8, tone = 'lowpass', stereoPhaseCycles = 0.5 } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000 ||
+        !['lowpass', 'flat'].includes(tone) || !Number.isFinite(stereoPhaseCycles)) {
+        throw new RangeError('delayFx requires an integer rate in [8000,192000], lowpass/flat tone and finite stereo phase');
+    }
+    const left = instantiate(delayReadhead, { sampleRate, maxDelaySeconds }, { name: 'left' });
+    const right = instantiate(delayReadhead, { sampleRate, maxDelaySeconds }, { name: 'right' });
+    const toneLeft = instantiate(filter, { sampleRate }, { name: 'toneLeft' });
+    const toneRight = instantiate(filter, { sampleRate }, { name: 'toneRight' });
+    const lfoLeft = instantiate(lfo, { sampleRate }, { name: 'lfoLeft' });
+    const lfoRight = instantiate(lfo, { sampleRate }, { name: 'lfoRight' });
+    // Materialize per-sample values in existing unworklet scalar slots. Without
+    // these boundaries 0.4.1 recursively expands the composed expression DAG.
+    // They are overwritten before use each sample and are not snapshot history.
+    const signalLeft = state.f32(0).expose({ name: 'signalLeft', snapshot: 'transient' });
+    const signalRight = state.f32(0).expose({ name: 'signalRight', snapshot: 'transient' });
+    const timeLeft = state.f32(0).expose({ name: 'timeLeft', snapshot: 'transient' });
+    const timeRight = state.f32(0).expose({ name: 'timeRight', snapshot: 'transient' });
+    const wetLeft = state.f32(0).expose({ name: 'wetLeft', snapshot: 'transient' });
+    const wetRight = state.f32(0).expose({ name: 'wetRight', snapshot: 'transient' });
+    const timingValid = state.bool(false).expose({ name: 'timingValid', snapshot: 'transient' });
+    const toneCutoff = state.f32(0).expose({ name: 'toneCutoff', snapshot: 'transient' });
+    const first = state.bool(true).named('first');
+    const minimum = Math.fround(1 / sampleRate), maximum = Math.fround(maxDelaySeconds);
+    const acceptedLeft = state.f32(minimum).named('acceptedLeft');
+    const acceptedRight = state.f32(minimum).named('acceptedRight');
+    return {
+        tick(inputLeft, inputRight, c) {
+            const seconds = (beats) => f32(f64(beats).mul(60).div(f64(c.bpm).clamp(30, 300)));
+            const requestedLeft = select(c.sync, seconds(c.beatsLeft), c.timeLeftSeconds);
+            const requestedRight = select(c.sync, seconds(c.beatsRight), c.timeRightSeconds);
+            const within = (time) => time.gte(minimum).and(time.lte(maximum));
+            const tempoValid = c.bpm.gte(30).and(c.bpm.lte(300));
+            timingValid.write(within(requestedLeft).and(within(requestedRight)).and(c.sync.not().or(tempoValid)));
+            const valid = timingValid.read();
+            // Reject the entire stereo request: keep the previous rhythm internally,
+            // stop new input and emit dry. Never present clamped time as an exact rhythm.
+            acceptedLeft.write(select(valid, requestedLeft, select(c.reset, f32(minimum), acceptedLeft.read())));
+            acceptedRight.write(select(valid, requestedRight, select(c.reset, f32(minimum), acceptedRight.read())));
+            // Reuse this sample's accepted state instead of expanding its selection again.
+            const baseLeft = acceptedLeft.read(), baseRight = acceptedRight.read();
+            const phaseReset = c.reset.or(first.read());
+            signalLeft.write(lfoLeft.tick(c.rateHz, phaseReset, f32(0)));
+            signalRight.write(lfoRight.tick(c.rateHz, phaseReset, f32(stereoPhaseCycles - Math.floor(stereoPhaseCycles))));
+            const modulationLeft = signalLeft.read(), modulationRight = signalRight.read();
+            first.write(false);
+            const rawLeft = baseLeft.add(modulationLeft.mul(c.depthSeconds.clamp(0, 0.05)));
+            const rawRight = baseRight.add(modulationRight.mul(c.depthSeconds.clamp(0, 0.05)));
+            const modulationClipped = within(rawLeft).and(within(rawRight)).not();
+            const delayLeft = modulateDelay(baseLeft, modulationLeft, c.depthSeconds, minimum, maximum);
+            const delayRight = modulateDelay(baseRight, modulationRight, c.depthSeconds, minimum, maximum);
+            timeLeft.write(delayLeft);
+            timeRight.write(delayRight);
+            const tapLeft = left.read(timeLeft.read(), c.reset), tapRight = right.read(timeRight.read(), c.reset);
+            wetLeft.write(tapLeft.output);
+            wetRight.write(tapRight.output);
+            // Q=0.5 and g=tan(pi*fc/fs)<1 admit a positive two-stage realization.
+            // The 0.24*fs ceiling keeps a margin below g=1, even with coefficient error.
+            toneCutoff.write(c.cutoffHz.clamp(20, Math.min(20000, 0.24 * sampleRate)));
+            const cutoff = toneCutoff.read();
+            const filteredLeft = toneLeft.tick(wetLeft.read(), cutoff, f32(0.5), c.reset);
+            const filteredRight = toneRight.tick(wetRight.read(), cutoff, f32(0.5), c.reset);
+            const gain = c.feedback.clamp(0, 0.95);
+            const dryOnly = c.bypass.or(valid.not());
+            tapLeft.write(select(dryOnly, f32(0), inputLeft).add((tone === 'flat' ? wetLeft.read() : filteredLeft).mul(gain)));
+            tapRight.write(select(dryOnly, f32(0), inputRight).add((tone === 'flat' ? wetRight.read() : filteredRight).mul(gain)));
+            const mix = c.mix.clamp(0, 1);
+            return {
+                left: select(dryOnly, inputLeft, inputLeft.mul(f32(1).sub(mix)).add(wetLeft.read().mul(mix))),
+                right: select(dryOnly, inputRight, inputRight.mul(f32(1).sub(mix)).add(wetRight.read().mul(mix))),
+                timingRejected: valid.not(),
+                modulationClipped,
+            };
+        },
+    };
+});

package/dist/delay-readhead.d.ts

@@ -0,0 +1,19 @@
+import { type Node } from '@unworklet/core';
+export interface DelayReadheadConfig {
+    /** Use the enclosing processor's ctx.sampleRate. */
+    sampleRate: number;
+    /** Fixed allocation; defaults to two seconds, not a product limit. */
+    maxDelaySeconds?: number;
+}
+/** Mono moving readhead. Per sample, use tick or one read followed by its write. */
+export declare const delayReadhead: import("@unworklet/core").SubgraphDecl<[config: DelayReadheadConfig], {
+    read: (delaySeconds: Node<"f32">, reset: Node<"bool">) => {
+        output: Node<"f32">;
+        outOfRange: Node<"bool">;
+        write(input: Node<"f32">): void;
+    };
+    tick(input: Node<"f32">, delaySeconds: Node<"f32">, reset: Node<"bool">): {
+        output: Node<"f32">;
+        outOfRange: Node<"bool">;
+    };
+}>;

package/dist/delay-readhead.js

@@ -0,0 +1,54 @@
+import { and, clamp, defineSubgraph, f32, f64, floor, i32, select, state } from '@unworklet/core';
+/** Mono moving readhead. Per sample, use tick or one read followed by its write. */
+export const delayReadhead = defineSubgraph((config) => {
+    const { sampleRate, maxDelaySeconds = 2 } = config;
+    // Compare the reciprocal boundary directly: sr * (1 / sr) may round just
+    // below one. Only an already-valid one-sample capacity receives this floor.
+    const maximum = Math.max(1, sampleRate * maxDelaySeconds);
+    const size = Math.ceil(maximum) + 2;
+    if (!Number.isFinite(sampleRate) || sampleRate <= 0 ||
+        !Number.isFinite(maxDelaySeconds) || maxDelaySeconds < 1 / sampleRate ||
+        !Number.isFinite(maximum) || size > 0x7fffffff ||
+        Math.fround(1 / sampleRate) <= 0 || !Number.isFinite(Math.fround(maxDelaySeconds))) {
+        throw new RangeError('delayReadhead requires a positive finite sampleRate and capacity of at least one sample fitting i32 indexing');
+    }
+    const history = state.buffer.f32({ size }).expose({ name: 'history', snapshot: 'persistent' });
+    const cursor = state.i32(0).named('cursor');
+    const valid = state.i32(0).named('valid');
+    function read(delaySeconds, reset) {
+        // Reset invalidates history before either tap is read, without an O(size) clear.
+        const write = select(reset, i32(0), cursor.read());
+        const available = select(reset, i32(0), valid.read());
+        const requested = f64(delaySeconds).mul(sampleRate);
+        const inRange = and(delaySeconds.gte(Math.fround(1 / sampleRate)), delaySeconds.lte(Math.fround(maxDelaySeconds)));
+        // NaN selects minimum; infinities saturate. Report all out-of-range controls.
+        const delay = clamp(select(requested.eq(requested), requested, f64(1)), 1, maximum);
+        const whole = i32(floor(delay));
+        const fraction = f32(delay.sub(f64(whole)));
+        const relative = write.sub(whole);
+        const recentIndex = select(relative.lt(0), relative.add(size), relative);
+        const olderIndex = select(recentIndex.eq(0), i32(size - 1), recentIndex.sub(1));
+        const recent = select(available.gte(whole), history.read(recentIndex), f32(0));
+        const older = select(available.gt(whole), history.read(olderIndex), f32(0));
+        const output = recent.mul(f32(1).sub(fraction)).add(older.mul(fraction));
+        return {
+            output,
+            outOfRange: inRange.not(),
+            // This closure runs at graph construction, never on the audio thread.
+            // Consume exactly once, after using output to construct the current input.
+            write(input) {
+                history.write(write, input);
+                cursor.write(write.add(1).mod(size));
+                valid.write(select(available.lt(size), available.add(1), i32(size)));
+            },
+        };
+    }
+    return {
+        read,
+        tick(input, delaySeconds, reset) {
+            const tap = read(delaySeconds, reset);
+            tap.write(input);
+            return { output: tap.output, outOfRange: tap.outOfRange };
+        },
+    };
+});

package/dist/delay-settings.d.ts

@@ -0,0 +1,55 @@
+import type { DelayFxConfig, DelayFxControls } from './delay-fx.js';
+/** Values for existing delayFx inputs, not a serialization or parameter registry. */
+export type DelaySettingsValues = {
+    readonly [K in keyof DelayFxControls]: K extends 'sync' | 'bypass' | 'reset' ? boolean : number;
+};
+export interface DelaySettings {
+    readonly config: Readonly<Omit<DelayFxConfig, 'sampleRate'>>;
+    readonly parameters: DelaySettingsValues;
+}
+/** CANDIDATE: short, opposite-phase motion blended with the original signal. */
+export declare const chorusSettings: {
+    readonly config: {
+        readonly maxDelaySeconds: 2;
+        readonly tone: "flat";
+        readonly stereoPhaseCycles: 0.5;
+    };
+    readonly parameters: {
+        readonly timeLeftSeconds: 0.018;
+        readonly timeRightSeconds: 0.018;
+        readonly sync: false;
+        readonly bpm: 120;
+        readonly beatsLeft: 1;
+        readonly beatsRight: 1;
+        readonly feedback: 0;
+        readonly cutoffHz: 3200;
+        readonly mix: 0.45;
+        readonly rateHz: 0.65;
+        readonly depthSeconds: 0.003;
+        readonly bypass: false;
+        readonly reset: false;
+    };
+};
+/** CANDIDATE: dotted eighth left, quarter right; tone acts only on feedback. */
+export declare const rhythmicDelaySettings: {
+    readonly config: {
+        readonly maxDelaySeconds: 2;
+        readonly tone: "lowpass";
+        readonly stereoPhaseCycles: 0.5;
+    };
+    readonly parameters: {
+        readonly timeLeftSeconds: 0.375;
+        readonly timeRightSeconds: 0.5;
+        readonly sync: true;
+        readonly bpm: 120;
+        readonly beatsLeft: 0.75;
+        readonly beatsRight: 1;
+        readonly feedback: 0.48;
+        readonly cutoffHz: 3200;
+        readonly mix: 0.35;
+        readonly rateHz: 0;
+        readonly depthSeconds: 0;
+        readonly bypass: false;
+        readonly reset: false;
+    };
+};

package/dist/delay-settings.js

@@ -0,0 +1,20 @@
+/** CANDIDATE: short, opposite-phase motion blended with the original signal. */
+export const chorusSettings = {
+    config: { maxDelaySeconds: 2, tone: 'flat', stereoPhaseCycles: 0.5 },
+    parameters: {
+        timeLeftSeconds: 0.018, timeRightSeconds: 0.018,
+        sync: false, bpm: 120, beatsLeft: 1, beatsRight: 1,
+        feedback: 0, cutoffHz: 3200, mix: 0.45,
+        rateHz: 0.65, depthSeconds: 0.003, bypass: false, reset: false,
+    },
+};
+/** CANDIDATE: dotted eighth left, quarter right; tone acts only on feedback. */
+export const rhythmicDelaySettings = {
+    config: { maxDelaySeconds: 2, tone: 'lowpass', stereoPhaseCycles: 0.5 },
+    parameters: {
+        timeLeftSeconds: 0.375, timeRightSeconds: 0.5,
+        sync: true, bpm: 120, beatsLeft: 0.75, beatsRight: 1,
+        feedback: 0.48, cutoffHz: 3200, mix: 0.35,
+        rateHz: 0, depthSeconds: 0, bypass: false, reset: false,
+    },
+};

package/dist/drive.d.ts

@@ -0,0 +1,24 @@
+import { type Node } from '@unworklet/core';
+export type DriveCurve = 'hard' | 'soft' | 'asymmetric' | 'fold';
+export type DriveQuality = 'direct' | 'adaa';
+export interface DriveConfig {
+    sampleRate: number;
+    curve: DriveCurve;
+    /** Immutable quality. ADAA is first-order, not oversampling or a bandlimit. */
+    quality?: DriveQuality;
+    /** Explicit wet-path DC blocker; zero (default) disables it. Range [0, 200] Hz. */
+    dcBlockHz?: number;
+}
+export interface ReductionConfig {
+    sampleRate: number;
+}
+/** Fixed analytic memoryless waveshaper, optional first-order ADAA and DC block. */
+export declare const drive: import("@unworklet/core").SubgraphDecl<[config: DriveConfig], {
+    /** Once per sample. Input [-8,8], linear drive [0,32], wet mix [0,1]. */
+    tick(input: Node<"f32">, gain: Node<"f32">, mix: Node<"f32">, reset: Node<"bool">): Node<"f32">;
+}>;
+/** Signed-PCM quantizer plus sample hold. Aliasing is intentional; no AA claim. */
+export declare const reduction: import("@unworklet/core").SubgraphDecl<[config: ReductionConfig], {
+    /** Bits [2,24], hold period [1,4096] samples, both floored at capture. */
+    tick(input: Node<"f32">, bits: Node<"f32">, holdSamples: Node<"f32">, mix: Node<"f32">, reset: Node<"bool">): Node<"f32">;
+}>;