@denaudio/den 0.0.0-stage → 0.1.0

package/dist/lfo.js

@@ -0,0 +1,55 @@
+import { defineSubgraph, f32, f64, select, state } from '@unworklet/core';
+/**
+ * Free-running sine source; tick once per sample. Rate is clamped to [0,20] Hz.
+ * Output uses the current phase, then advances by rate/sampleRate. Rate zero
+ * holds phase; changing rate never resets phase. Reset emits the supplied phase
+ * on that sample and advances from it. Reset phase is in cycles, wrapped to [0,1).
+ * f64 phase prevents a small rate from stalling against a large f32 phase.
+ * Finite inputs required. No implicit note reset, depth, smoothing or routing.
+ */
+export const lfo = defineSubgraph((config) => {
+    if (!Number.isInteger(config.sampleRate) || config.sampleRate < 1) {
+        throw new RangeError('lfo sampleRate must be a positive integer');
+    }
+    const phase = state.f64(0).named('phase');
+    return {
+        tick(rate, reset, resetPhase) {
+            const requested = f64(resetPhase);
+            const current = select(reset, requested.sub(requested.floor()), phase.read());
+            const next = current.add(f64(rate.clamp(0, 20)).div(config.sampleRate));
+            phase.write(next.sub(next.floor()));
+            // Reflect cycles into [-1/4,1/4] before polynomial evaluation. The
+            // degree-13 sine remainder is <= (pi/2)^15 / 15! < 7e-10.
+            // unworklet 0.4.1 sin demotes f64 to its f32 degree-9 approximation;
+            // direct f64 arithmetic preserves slow phase changes and the error bound.
+            const centered = current.sub(select(current.gt(0.5), f64(1), f64(0)));
+            const folded = select(centered.gt(0.25), f64(0.5).sub(centered), select(centered.lt(-0.25), f64(-0.5).sub(centered), centered));
+            const x = folded.mul(2 * Math.PI), x2 = x.mul(x);
+            const polynomial = f64(1 / 6227020800).mul(x2).sub(1 / 39916800)
+                .mul(x2).add(1 / 362880).mul(x2).sub(1 / 5040)
+                .mul(x2).add(1 / 120).mul(x2).sub(1 / 6).mul(x2).add(1);
+            return f32(x.mul(polynomial)).clamp(-1, 1);
+        },
+    };
+});
+// The musical octave ratio has a bounded exponent [-8,8]. Evaluate exp(x/16)
+// through degree 8, then square four times: |x/16| <= ln(2)/2, giving < 5e-9
+// relative truncation error. This avoids 0.4.1's approximate f32 pow/log path.
+function octaveRatio(octaves) {
+    const x = f64(octaves).mul(Math.LN2 / 16);
+    const p = f64(1 / 40320).mul(x).add(1 / 5040).mul(x).add(1 / 720)
+        .mul(x).add(1 / 120).mul(x).add(1 / 24).mul(x).add(1 / 6)
+        .mul(x).add(0.5).mul(x).add(1).mul(x).add(1);
+    const p2 = p.mul(p), p4 = p2.mul(p2), p8 = p4.mul(p4);
+    return f32(p8.mul(p8));
+}
+/** Destination-unit depth, with final bounds enforced by the destination. */
+export function modulatePitch(baseHz, signal, semitones, maxHz) {
+    return baseHz.mul(octaveRatio(signal.clamp(-1, 1).mul(semitones.clamp(-24, 24)).div(12))).clamp(0, maxHz);
+}
+export function modulateCutoff(baseHz, signal, octaves, maxHz) {
+    return baseHz.mul(octaveRatio(signal.clamp(-1, 1).mul(octaves.clamp(-8, 8)))).clamp(20, maxHz);
+}
+export function modulateDelay(baseSeconds, signal, depthSeconds, minSeconds, maxSeconds) {
+    return baseSeconds.add(signal.clamp(-1, 1).mul(depthSeconds.clamp(0, 0.05))).clamp(minSeconds, maxSeconds);
+}

package/dist/live-buffer.d.ts

@@ -0,0 +1,39 @@
+import { type Node } from '@unworklet/core';
+export interface LiveSampleBufferConfig {
+    /** Fixed mono history capacity, 1..65,536 accepted writes. */
+    capacity: number;
+    /** Incoming processor rate, 8,000..192,000 Hz. No resampling. */
+    sampleRate: number;
+}
+export interface LiveSampleBufferControls {
+    input: Node<'f32'>;
+    /** Accept one frame per tick. False freezes history, including its ages. */
+    record: Node<'bool'>;
+    /** Level-sensitive logical clear, with priority over record. Not secure erasure. */
+    reset: Node<'bool'>;
+}
+export interface LiveSampleBufferRead {
+    output: Node<'f32'>;
+    /** True only for finite age in [0,length-1], including both interpolation taps. */
+    available: Node<'bool'>;
+}
+export interface LiveSampleBufferStatus {
+    written: Node<'bool'>;
+    full: Node<'bool'>;
+    length: Node<'i32'>;
+}
+export interface LiveSampleBuffer {
+    readonly capacity: number;
+    readonly sampleRate: number;
+    tick(controls: LiveSampleBufferControls): LiveSampleBufferStatus;
+    /** Age 0 is the latest accepted write at this statement position. Linear
+     * interpolation toward older writes; unavailable ages are silent, not wrapped. */
+    readAge(ageFrames: Node<'f64'>): LiveSampleBufferRead;
+    length(): Node<'i32'>;
+    /** Wrapping i32 mutation serial: one increment per accepted write or reset. */
+    revision(): Node<'i32'>;
+}
+/** Bounded rolling mono history with explicit accepted-write ages. Intentionally
+ * not a ResidentSample: rotating age coordinates must not silently change the
+ * meaning of existing sample-player/grain positions. No device or host ingress. */
+export declare const liveSampleBuffer: import("@unworklet/core").SubgraphDecl<[config: LiveSampleBufferConfig], LiveSampleBuffer>;

package/dist/live-buffer.js

@@ -0,0 +1,52 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+const PCM_SCALE = 2 ** 128;
+const AGE_SCALE = 2 ** 192;
+const F32_MAX = 3.4028234663852886e38;
+/** Bounded rolling mono history with explicit accepted-write ages. Intentionally
+ * not a ResidentSample: rotating age coordinates must not silently change the
+ * meaning of existing sample-player/grain positions. No device or host ingress. */
+export const liveSampleBuffer = defineSubgraph((config) => {
+    const { capacity, sampleRate } = config;
+    if (!Number.isInteger(capacity) || capacity < 1 || capacity > 65536)
+        throw new RangeError('live buffer capacity must be an integer in [1,65536]');
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('sampleRate must be in [8000,192000] Hz');
+    // Exact binary scaling preserves every finite f32, including subnormals,
+    // across core 0.4.1's 1e-30 scalar-store floor. The extra cell is private.
+    const pcm = state.buffer.f64({ size: capacity + 1 }).expose({ name: 'pcm', snapshot: 'persistent' });
+    const head = state.i32(0).named('head'), length = state.i32(0).named('length');
+    const revision = state.i32(0).named('revision');
+    const readAge = state.f64(0).expose({ name: 'readAge', snapshot: 'transient' });
+    return {
+        capacity, sampleRate,
+        tick(c) {
+            const written = c.record.and(c.reset.not());
+            const finite = c.input.eq(c.input).and(c.input.abs().lte(F32_MAX));
+            // select evaluates both branches. Paused/reset ticks touch the sentinel,
+            // not exposed history, and no clearing pass runs on reset.
+            pcm.write(select(written, head.read(), i32(capacity)), select(written.and(finite), f64(c.input).mul(PCM_SCALE), f64(0)));
+            head.write(select(c.reset, i32(0), select(written, head.read().add(1).mod(capacity), head.read())));
+            length.write(select(c.reset, i32(0), length.read().add(select(written, i32(1), i32(0))).min(capacity)));
+            revision.write(revision.read().add(select(written.or(c.reset), i32(1), i32(0))));
+            const current = length.read();
+            return { written, full: current.eq(capacity), length: current };
+        },
+        readAge(ageFrames) {
+            const count = length.read();
+            const available = ageFrames.gte(0).and(ageFrames.lte(f64(count.sub(1))));
+            // Keep invalid ages out of integer conversion and address arithmetic.
+            // Scale the cache before its native store so tiny valid fractions still
+            // contribute when adjacent samples span the full finite f32 range.
+            readAge.write(select(available, ageFrames, f64(0)).mul(AGE_SCALE));
+            const age = readAge.read().div(AGE_SCALE), whole = i32(age.floor());
+            const fraction = age.sub(f64(whole));
+            const older = whole.add(1).min(count.sub(1).max(0));
+            const newest = head.read().add(capacity - 1);
+            const a = pcm.read(newest.sub(whole).mod(capacity)).div(PCM_SCALE);
+            const b = pcm.read(newest.sub(older).mod(capacity)).div(PCM_SCALE);
+            return { output: select(available, f32(a.add(b.sub(a).mul(fraction))), f32(0)), available };
+        },
+        length() { return length.read(); },
+        revision() { return revision.read(); },
+    };
+});

package/dist/live-granular.d.ts

@@ -0,0 +1,41 @@
+import { type Node } from '@unworklet/core';
+import type { LiveSampleBuffer } from './live-buffer.js';
+export interface LiveGranularConfig {
+    /** Shared accepted-write history; its sampleRate must match the processor. */
+    history: LiveSampleBuffer;
+    /** Immutable first-free pool size, integer 1..8. */
+    maxGrains: number;
+}
+export interface LiveGranularControls {
+    /** Exactly the immediately preceding history.tick() status.written. */
+    written: Node<'bool'>;
+    /** The same reset passed to history.tick(); level-sensitive, highest priority. */
+    reset: Node<'bool'>;
+    /** One request per true sample; held true requests every sample. */
+    trigger: Node<'bool'>;
+    /** Onset age after the current write, in retained accepted-write frames. */
+    ageFrames: Node<'f32'>;
+    /** Signed frames toward newer source material per output sample, [-16,16]. */
+    rate: Node<'f32'>;
+    /** [0,2] seconds, rounded to frames with minimum 3. Zero is valid. */
+    durationSeconds: Node<'f32'>;
+}
+export interface LiveGranularResult {
+    output: Node<'f32'>;
+    /** Valid reads this sample, including both zero-weight window endpoints. */
+    activeGrains: Node<'i32'>;
+    launched: Node<'bool'>;
+    /** Valid request with a full pool; no stealing or queue. */
+    dropped: Node<'bool'>;
+    /** Invalid controls or unavailable onset. Does not interrupt existing grains. */
+    rejected: Node<'bool'>;
+    /** Existing grains whose current read became unavailable; excludes reset/EOF. */
+    expiredGrains: Node<'i32'>;
+}
+export interface LiveGranularSource {
+    tick(controls: LiveGranularControls): LiveGranularResult;
+}
+/** Fixed mono live-history grain reader. Call the writer, then this reader once
+ * per sample with the writer's written flag and shared reset. No density clock,
+ * source ownership, resampling filter, implicit safety margin or host ingress. */
+export declare const liveGranularSource: import("@unworklet/core").SubgraphDecl<[config: LiveGranularConfig], LiveGranularSource>;

package/dist/live-granular.js

@@ -0,0 +1,64 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+// Preserve small representable scalar values across core 0.4.1's 1e-30
+// state-store floor. This does not extend f64 precision at a large cursor.
+const SCALE = 2 ** 192;
+/** Fixed mono live-history grain reader. Call the writer, then this reader once
+ * per sample with the writer's written flag and shared reset. No density clock,
+ * source ownership, resampling filter, implicit safety margin or host ingress. */
+export const liveGranularSource = defineSubgraph((config) => {
+    const { history, maxGrains } = config;
+    if (!Number.isInteger(maxGrains) || maxGrains < 1 || maxGrains > 8)
+        throw new RangeError('liveGranularSource maxGrains must be an integer in [1,8]');
+    if (!Number.isInteger(history.capacity) || history.capacity < 1 || history.capacity > 65536 || !Number.isFinite(history.sampleRate) || history.sampleRate < 8000 || history.sampleRate > 192000)
+        throw new RangeError('liveGranularSource history requires capacity [1,65536] and sampleRate [8000,192000]');
+    const allocated = state.bool(false).expose({ name: 'allocated', snapshot: 'transient' });
+    const grains = Array.from({ length: maxGrains }, (_, n) => ({
+        active: state.bool(false).named(`grain${n}Active`),
+        index: state.i32(0).named(`grain${n}Index`),
+        duration: state.i32(3).named(`grain${n}Duration`),
+        age: state.f64(0).named(`grain${n}AgeScaled`),
+        rate: state.f64(0).named(`grain${n}RateScaled`),
+    }));
+    return { tick(c) {
+            const requested = c.trigger.and(c.reset.not());
+            const valid = c.ageFrames.gte(0).and(c.ageFrames.lte(history.capacity - 1))
+                .and(f64(c.ageFrames).lte(f64(history.length().sub(1))))
+                .and(c.rate.gte(-16)).and(c.rate.lte(16))
+                .and(c.durationSeconds.gte(0)).and(c.durationSeconds.lte(2));
+            const attempt = requested.and(valid);
+            // select is eager. Sanitize before conversion even on rejected requests.
+            const duration = i32(f64(select(valid, c.durationSeconds, f32(0))).mul(history.sampleRate).add(.5).floor()).clamp(3, Math.round(2 * history.sampleRate));
+            const onsetAge = f64(select(valid, c.ageFrames, f32(0))), onsetRate = f64(select(valid, c.rate, f32(0)));
+            allocated.write(false);
+            let sum = f64(0), count = i32(0), expired = i32(0);
+            for (const grain of grains) {
+                const activeBefore = grain.active.read().and(c.reset.not());
+                // Add the increment as one expression: (tinyAge + 1) - 1 would erase
+                // representable tiny onset fractions while continuously writing at rate 1.
+                const increment = select(c.written, f64(1), f64(0)).sub(grain.rate.read().div(SCALE));
+                const currentAge = grain.age.read().div(SCALE).add(increment);
+                const available = currentAge.gte(0).and(currentAge.lte(f64(history.length().sub(1))));
+                const existing = activeBefore.and(available);
+                expired = expired.add(select(activeBefore.and(available.not()), i32(1), i32(0)));
+                const alreadyAllocated = allocated.read();
+                const launch = attempt.and(alreadyAllocated.not()).and(existing.not());
+                allocated.write(alreadyAllocated.or(launch));
+                const active = existing.or(launch);
+                grain.index.write(select(c.reset.or(launch), i32(0), grain.index.read()));
+                grain.duration.write(select(c.reset, i32(3), select(launch, duration, grain.duration.read())));
+                grain.rate.write(select(c.reset, f64(0), select(launch, onsetRate.mul(SCALE), grain.rate.read())));
+                grain.age.write(select(active, select(launch, onsetAge, currentAge).mul(SCALE), f64(0)));
+                const index = grain.index.read(), length = grain.duration.read();
+                const window = f64(1).sub(f64(index).mul(2).div(f64(length.sub(1))).sub(1).abs()).max(0);
+                const read = history.readAge(grain.age.read().div(SCALE));
+                sum = sum.add(select(active, f64(read.output).mul(window), f64(0)));
+                count = count.add(select(active, i32(1), i32(0)));
+                grain.index.write(select(active, index.add(1), i32(0)));
+                // Natural completion is recorded now, before next sample's age validity.
+                grain.active.write(active.and(index.add(1).lt(length)));
+            }
+            const launched = allocated.read();
+            return { output: f32(sum.div(maxGrains)), activeGrains: count, launched,
+                dropped: attempt.and(launched.not()), rejected: requested.and(valid.not()), expiredGrains: expired };
+        } };
+});

package/dist/lookahead-limiter.d.ts

@@ -0,0 +1,31 @@
+import { type Node } from '@unworklet/core';
+export interface LookaheadLimiterConfig {
+    sampleRate: number;
+    /** Fixed integer latency/allocation, 0..2048 samples. No implicit default. */
+    lookaheadSamples: number;
+}
+export interface LookaheadLimiterControls {
+    /** Current-output sample ceiling in dBFS, clamped to [-120,0]; nonfinite -> 0. */
+    ceilingDb: Node<'f32'>;
+    /** Peak-detector release, 0..30 seconds; nonfinite -> 0. Attack is immediate. */
+    release: Node<'f32'>;
+    /** Invalidate all history before accepting this sample. */
+    reset: Node<'bool'>;
+}
+/** Bounded stereo-linked sample-peak limiter. Not a true-peak limiter. */
+export declare const lookaheadLimiter: import("@unworklet/core").SubgraphDecl<[config: LookaheadLimiterConfig], {
+    latencySamples: number;
+    latencySeconds: number;
+    /** Exactly once per sample. Dry outputs have the same fixed latency. */
+    tick(left: Node<"f32">, right: Node<"f32">, controls: LookaheadLimiterControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+        dryLeft: Node<"f32">;
+        dryRight: Node<"f32">;
+        envelope: Node<"f32">;
+        windowPeak: Node<"f32">;
+        ceiling: Node<"f32">;
+        /** Diagnostic only: this f32 conversion may underflow for extreme audio. */
+        gain: Node<"f32">;
+    };
+}>;

package/dist/lookahead-limiter.js

@@ -0,0 +1,67 @@
+import { defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+import { envelopeFollower } from './dynamics.js';
+const SCALE = 2 ** 128;
+function finite(input) {
+    return select(input.eq(input).and(input.abs().lte(3.4028234663852886e38)), input, f32(0));
+}
+/** Bounded stereo-linked sample-peak limiter. Not a true-peak limiter. */
+export const lookaheadLimiter = defineSubgraph((config) => {
+    const { sampleRate, lookaheadSamples: delay } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000) {
+        throw new RangeError('lookaheadLimiter sampleRate must be an integer in [8000,192000]');
+    }
+    if (!Number.isInteger(delay) || delay < 0 || delay > 2048) {
+        throw new RangeError('lookaheadLimiter lookaheadSamples must be an integer in [0,2048]');
+    }
+    const size = delay + 1, capacity = 2 ** Math.ceil(Math.log2(size));
+    // Native buffer writes flush magnitudes below 1e-30. Exact binary scaling
+    // preserves every finite f32 value, including subnormals, without overflow.
+    const leftHistory = state.buffer.f64({ size }).expose({ name: 'leftScaled', snapshot: 'persistent' });
+    const rightHistory = state.buffer.f64({ size }).expose({ name: 'rightScaled', snapshot: 'persistent' });
+    const peaks = state.buffer.f64({ size: capacity * 2 }).expose({ name: 'peakTreeScaled', snapshot: 'persistent' });
+    const cursor = state.i32(0).named('cursor'), valid = state.i32(0).named('valid');
+    const follower = instantiate(envelopeFollower, { sampleRate, mode: 'peak' }, { name: 'detector' });
+    return {
+        latencySamples: delay,
+        latencySeconds: delay / sampleRate,
+        /** Exactly once per sample. Dry outputs have the same fixed latency. */
+        tick(left, right, controls) {
+            const write = select(controls.reset, i32(0), cursor.read());
+            const available = select(controls.reset, i32(0), valid.read()).add(1).min(size);
+            const l = f64(finite(left)).mul(SCALE), r = f64(finite(right)).mul(SCALE);
+            leftHistory.write(write, l);
+            rightHistory.write(write, r);
+            peaks.write(write.add(capacity), l.abs().max(r.abs()));
+            // At reset the valid leaves form an initially empty prefix. Sequential
+            // refill ensures each included sibling was rebuilt since that reset.
+            // Other siblings (including permanently unused leaves) are read as zero.
+            // Once full, all real leaves stay valid across arbitrary ring wraps.
+            for (let width = 2; width <= capacity; width *= 2) {
+                const block = write.div(width), first = block.mul(width), node = block.add(capacity / width);
+                const low = select(first.lt(available), peaks.read(node.mul(2)), f64(0));
+                const high = select(first.add(width / 2).lt(available), peaks.read(node.mul(2).add(1)), f64(0));
+                peaks.write(node, low.max(high));
+            }
+            const windowPeak = f32(peaks.read(1).div(SCALE));
+            const envelope = follower.tick(windowPeak, { attack: f32(0), release: controls.release, reset: controls.reset });
+            const ceiling = finite(controls.ceilingDb).clamp(-120, 0).mul(Math.LN10 / 20).exp();
+            const gain = select(envelope.gt(0), f64(ceiling).div(select(envelope.gt(0), f64(envelope), f64(1))).min(1), f64(1));
+            const read = write.add(1).mod(size);
+            const ready = available.eq(size);
+            const dryLeft = select(ready, leftHistory.read(read).div(SCALE), f64(0));
+            const dryRight = select(ready, rightHistory.read(read).div(SCALE), f64(0));
+            cursor.write(read);
+            valid.write(available);
+            return {
+                // Keep the gain f64 through multiplication: full-range f32 input at a
+                // -120dB ceiling would otherwise quantize its tiny gain to a few ulps.
+                left: f32(dryLeft.mul(gain)).clamp(ceiling.neg(), ceiling),
+                right: f32(dryRight.mul(gain)).clamp(ceiling.neg(), ceiling),
+                dryLeft: f32(dryLeft), dryRight: f32(dryRight),
+                envelope, windowPeak, ceiling,
+                /** Diagnostic only: this f32 conversion may underflow for extreme audio. */
+                gain: f32(gain),
+            };
+        },
+    };
+});

package/dist/loop-crossfade.d.ts

@@ -0,0 +1,28 @@
+import { type Node } from '@unworklet/core';
+import type { ResidentSample, SamplePlayerControls } from './sample.js';
+export interface CrossfadedLoopConfig {
+    sampleRate: number;
+    sample: ResidentSample;
+    /** Fixed source slice [startFrame,endFrame), intersected with loaded length. */
+    startFrame?: number;
+    endFrame?: number;
+    /** Source-frame overlap, 0..floor(slice length/2). Effective period is L-F,
+     * and forward playback starts at startFrame+F. Zero disables the overlap. */
+    crossfadeFrames: number;
+    /** Linear gate-off ramp in output samples; zero/one stops on first off sample. */
+    releaseFrames?: number;
+}
+/** One mono cyclic waveform with a unity-sum linear tail/head overlap. Shortens
+ * the source period from L to L-F; reverse traverses that same waveform backward.
+ * Not a dry-attack, time-stretching, antialiasing or arbitrary-content seam promise. */
+export declare const crossfadedLoopPlayer: import("@unworklet/core").SubgraphDecl<[config: CrossfadedLoopConfig], {
+    tick(c: SamplePlayerControls): {
+        output: Node<"f32">;
+        active: Node<"bool">;
+        position: Node<"f32">;
+        phase: Node<"f32">;
+        periodFrames: Node<"i32">;
+        crossfadeFrames: Node<"i32">;
+        missing: Node<"bool">;
+    };
+}>;

package/dist/loop-crossfade.js

@@ -0,0 +1,72 @@
+import { bool, defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+const PHASE_SCALE = 2 ** 128;
+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}]`);
+}
+// Preserve the local fraction before adding an integer slice/head offset. An
+// absolute position addition would erase tiny phase * full-finite-PCM products.
+// Resident reads retain the existing ingress, bounds and per-tap sanitization.
+function localRead(sample, local, start, end, loop) {
+    const whole = i32(local.floor()), fraction = local.sub(f64(whole));
+    const first = start.add(whole).min(end.sub(1).max(start));
+    const next = select(first.add(1).gte(end), select(loop, start, first), first.add(1));
+    const a = sample.read(f64(first), start, end, false), b = sample.read(f64(next), start, end, false);
+    return f32(f64(a).mul(f64(1).sub(fraction)).add(f64(b).mul(fraction)));
+}
+/** One mono cyclic waveform with a unity-sum linear tail/head overlap. Shortens
+ * the source period from L to L-F; reverse traverses that same waveform backward.
+ * Not a dry-attack, time-stretching, antialiasing or arbitrary-content seam promise. */
+export const crossfadedLoopPlayer = defineSubgraph((config) => {
+    if (!Number.isFinite(config.sampleRate) || config.sampleRate < 8000 || config.sampleRate > 192000)
+        throw new RangeError('sampleRate must be in [8000,192000] Hz');
+    const { sample, startFrame = 0, endFrame = sample.capacity, crossfadeFrames, releaseFrames = 0 } = config;
+    integer(startFrame, 0, sample.capacity - 1, 'startFrame');
+    integer(endFrame, startFrame + 1, sample.capacity, 'endFrame');
+    integer(crossfadeFrames, 0, Math.floor((endFrame - startFrame) / 2), 'crossfadeFrames');
+    integer(releaseFrames, 0, Math.ceil(config.sampleRate * 10), 'releaseFrames');
+    const phase = state.f64(0).named('scaledPhase'), active = state.bool(false).named('active');
+    const previousGate = state.bool(false).named('previousGate'), revision = state.i32(-1).named('revision');
+    const remaining = state.i32(0).named('releaseRemaining');
+    // Transient materialization keeps repeated resident read graphs bounded. Only
+    // persistent phase/gate/release/revision state is required across snapshots.
+    const current = state.f64(0).expose({ name: 'scaledCurrentPhase', snapshot: 'transient' });
+    const speedState = state.f64(0).expose({ name: 'scaledSpeed', snapshot: 'transient' });
+    const endState = state.i32(0).expose({ name: 'end', snapshot: 'transient' });
+    const overlapState = state.i32(0).expose({ name: 'overlap', snapshot: 'transient' });
+    const periodState = state.i32(0).expose({ name: 'period', snapshot: 'transient' });
+    return { tick(c) {
+            endState.write(sample.length().min(endFrame));
+            const end = endState.read(), start = i32(startFrame), length = end.sub(start).max(0), available = length.gt(0);
+            overlapState.write(length.div(2).min(crossfadeFrames));
+            periodState.write(length.sub(overlapState.read()));
+            const overlap = overlapState.read(), period = periodState.read();
+            speedState.write(select(c.rate.eq(c.rate), f64(c.rate), f64(0)).clamp(-16, 16).mul(sample.sourceSampleRate / config.sampleRate).mul(PHASE_SCALE));
+            const speed = speedState.read().div(PHASE_SCALE), changed = sample.revision().eq(revision.read()).not();
+            // A load is NOT a gate rise: evaluate against the actual prior gate first.
+            const trigger = c.trigger.or(c.gate.and(previousGate.read().not())).and(c.gate).and(c.reset.not()).and(available);
+            const alive = select(trigger, bool(true), active.read().and(changed.not())).and(c.reset.not()).and(available);
+            const initial = select(speed.lt(0), f64(period.sub(1).max(0)), f64(0));
+            current.write(select(trigger, initial, select(c.reset.or(changed).or(available.not()), f64(0), phase.read().div(PHASE_SCALE))).mul(PHASE_SCALE));
+            const q = current.read().div(PHASE_SCALE);
+            const releaseLeft = select(trigger, i32(releaseFrames), select(c.gate, remaining.read(), remaining.read().sub(1).max(0)));
+            const gain = releaseFrames > 0 ? f64(releaseLeft).div(releaseFrames) : select(c.gate, f64(1), f64(0));
+            active.write(alive.and(gain.gt(0)));
+            const playing = active.read(), primaryStart = start.add(overlap);
+            const tail = localRead(sample, q, primaryStart, end, overlap.eq(0));
+            const headPhase = q.sub(f64(period.sub(overlap))).max(0);
+            const head = localRead(sample, headPhase, start, end, bool(false));
+            const weight = select(overlap.gt(0), headPhase.div(f64(overlap.max(1))), f64(0));
+            const mixed = f32(f64(tail).mul(f64(1).sub(weight)).add(f64(head).mul(weight)));
+            const output = select(playing, f32(f64(mixed).mul(gain)), f32(0));
+            const advanced = q.add(speed), divisor = f64(period.max(1));
+            const wrapped = advanced.sub(advanced.div(divisor).floor().mul(divisor));
+            // Negative tiny increments can round a remainder to the upper endpoint.
+            const next = select(wrapped.gte(divisor), f64(0), wrapped.max(0));
+            phase.write(select(playing, next, q).mul(PHASE_SCALE));
+            remaining.write(select(playing, releaseLeft, i32(0)));
+            previousGate.write(c.gate.and(c.reset.not()));
+            revision.write(sample.revision());
+            return { output, active: playing, position: f32(f64(primaryStart).add(q)), phase: f32(q), periodFrames: period, crossfadeFrames: overlap, missing: available.not() };
+        } };
+});

package/dist/modulation-fx.d.ts

@@ -0,0 +1,47 @@
+import { type Node } from '@unworklet/core';
+export interface FlangerConfig {
+    sampleRate: number;
+    /** Fixed capacity in seconds, [one sample, 0.02]. Default 0.02. */
+    maxDelaySeconds?: number;
+    /** Right LFO phase relative to left, in cycles. Default 0.5. */
+    stereoPhaseCycles?: number;
+}
+export interface FlangerControls {
+    delaySeconds: Node<'f32'>;
+    depthSeconds: Node<'f32'>;
+    rateHz: Node<'f32'>;
+    /** Positive feedback, clamped to [0, 0.95]. */
+    feedback: Node<'f32'>;
+    mix: Node<'f32'>;
+    bypass: Node<'bool'>;
+    reset: Node<'bool'>;
+}
+/** Stereo moving-head comb/flanger. Call once per sample; finite inputs required. */
+export declare const flanger: import("@unworklet/core").SubgraphDecl<[config: FlangerConfig], {
+    tick(left: Node<"f32">, right: Node<"f32">, c: FlangerControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+        timingRejected: Node<"bool">;
+        modulationClipped: Node<"bool">;
+    };
+}>;
+export interface PhaserConfig {
+    sampleRate: number;
+    /** Fixed number of normalized first-order allpasses. Default 4. */
+    stages?: 2 | 4 | 6 | 8;
+}
+export interface PhaserControls {
+    /** Per-stage -90 degree frequency. Clamped to [20, 0.45 * sampleRate]. */
+    frequencyHz: Node<'f32'>;
+    /** One-sample-delayed wet feedback, clamped to [-0.95, 0.95]. */
+    feedback: Node<'f32'>;
+    mix: Node<'f32'>;
+    bypass: Node<'bool'>;
+    reset: Node<'bool'>;
+}
+/** Mono allpass phaser, not a delay preset. Compose two instances for stereo.
+ * Normalized lattice scattering preserves per-sample energy under cutoff motion.
+ */
+export declare const phaser: import("@unworklet/core").SubgraphDecl<[config: PhaserConfig], {
+    tick(input: Node<"f32">, c: PhaserControls): Node<"f32">;
+}>;

package/dist/modulation-fx.js

@@ -0,0 +1,58 @@
+import { defineSubgraph, f32, f64, instantiate, select, sqrt, state } from '@unworklet/core';
+import { delayFx } from './delay-fx.js';
+/** Stereo moving-head comb/flanger. Call once per sample; finite inputs required. */
+export const flanger = defineSubgraph((config) => {
+    const maxDelaySeconds = config.maxDelaySeconds ?? 0.02;
+    if (!Number.isFinite(maxDelaySeconds) || maxDelaySeconds < 1 / config.sampleRate || maxDelaySeconds > 0.02) {
+        throw new RangeError('flanger capacity must be between one sample and 0.02 seconds');
+    }
+    const engine = instantiate(delayFx, { ...config, maxDelaySeconds, tone: 'flat' }, { name: 'delay' });
+    return {
+        tick(left, right, c) {
+            return engine.tick(left, right, {
+                timeLeftSeconds: c.delaySeconds, timeRightSeconds: c.delaySeconds,
+                sync: f32(0).gt(1), bpm: f32(120), beatsLeft: f32(1), beatsRight: f32(1),
+                feedback: c.feedback, cutoffHz: f32(1000), mix: c.mix,
+                rateHz: c.rateHz, depthSeconds: c.depthSeconds,
+                bypass: c.bypass, reset: c.reset,
+            });
+        },
+    };
+});
+/** Mono allpass phaser, not a delay preset. Compose two instances for stereo.
+ * Normalized lattice scattering preserves per-sample energy under cutoff motion.
+ */
+export const phaser = defineSubgraph((config) => {
+    const { sampleRate, stages = 4 } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000 || ![2, 4, 6, 8].includes(stages)) {
+        throw new RangeError('phaser requires an integer sample rate in [8000,192000] and 2/4/6/8 stages');
+    }
+    const history = Array.from({ length: stages }, (_, i) => state.f64(0).named(`stage${i}`));
+    const signal = state.f64(0).expose({ name: 'signal', snapshot: 'transient' });
+    const coefficient = state.f64(0).expose({ name: 'coefficient', snapshot: 'transient' });
+    const coupling = state.f64(0).expose({ name: 'coupling', snapshot: 'transient' });
+    const feedback = state.f64(0).named('feedback');
+    return {
+        tick(input, c) {
+            const angle = f64(c.frequencyHz).clamp(20, 0.45 * sampleRate).mul(Math.PI / sampleRate);
+            const z = angle.mul(angle);
+            // Degree 13/14 sine/cosine on [0, .45*pi], as in the existing SVF.
+            const sine = angle.mul(f64(-1 / 6227020800).mul(z).add(1 / 39916800).mul(z).sub(1 / 362880).mul(z).add(1 / 5040).mul(z).sub(1 / 120).mul(z).add(1 / 6).mul(z).neg().add(1));
+            const cosine = f64(-1 / 87178291200).mul(z).add(1 / 479001600).mul(z).sub(1 / 3628800).mul(z).add(1 / 40320).mul(z).sub(1 / 720).mul(z).add(1 / 24).mul(z).sub(1 / 2).mul(z).add(1);
+            coefficient.write(sine.sub(cosine).div(sine.add(cosine)).clamp(-0.999999, 0.999999));
+            const a = coefficient.read();
+            coupling.write(sqrt(f64(1).sub(a.mul(a)).clamp(0, 1)));
+            const b = coupling.read();
+            signal.write(f64(select(c.bypass, f32(0), input)).add(select(c.reset, f64(0), feedback.read()).mul(f64(c.feedback).clamp(-0.95, 0.95))));
+            for (const slot of history) {
+                const x = signal.read(), previous = select(c.reset, f64(0), slot.read());
+                signal.write(a.mul(x).add(b.mul(previous)));
+                slot.write(b.mul(x).sub(a.mul(previous)));
+            }
+            const wet = signal.read();
+            feedback.write(wet);
+            const mix = f64(c.mix).clamp(0, 1);
+            return select(c.bypass, input, f32(f64(input).mul(f64(1).sub(mix)).add(wet.mul(mix))));
+        },
+    };
+});