@denaudio/den 0.0.0-stage → 0.2.0

package/dist/sample.d.ts

@@ -0,0 +1,113 @@
+import { type Node, type TypedArrayFieldRef } from '@unworklet/core';
+export interface ResidentSampleConfig {
+    /** Fixed mono PCM capacity, 1..65,536 frames; decoding/file I/O run outside the processor. */
+    capacity: number;
+    sourceSampleRate: number;
+}
+export interface ResidentSample {
+    readonly capacity: number;
+    readonly sourceSampleRate: number;
+    /** Call in event<{data:Float32Array}>.onReceive. Copy runs at the block boundary.
+     * Prepare/decode outside the callback and load before audible use. Oversize input
+     * truncates to capacity; empty input unloads. Each load invalidates current playback. */
+    load(data: TypedArrayFieldRef<'f32'>): void;
+    length(): Node<'i32'>;
+    revision(): Node<'i32'>;
+    /** Linear interpolation; end is exclusive and clipped to loaded length.
+     * NaN position uses start; other positions saturate to the signed i32 frame range. */
+    read(position: Node<'f64'>, start: Node<'i32'>, end: Node<'i32'>, loop: boolean): Node<'f32'>;
+}
+/** A fixed-capacity mono sample, initially missing. No asset loader or streaming. */
+export declare const residentSample: import("@unworklet/core").SubgraphDecl<[config: ResidentSampleConfig], ResidentSample>;
+export interface SamplePlayerConfig {
+    sampleRate: number;
+    sample: ResidentSample;
+    /** Fixed slice [startFrame,endFrame), intersected with the current asset length. */
+    startFrame?: number;
+    endFrame?: number;
+    loop?: boolean;
+    /** Linear gate-off ramp in output samples; zero stops immediately. */
+    releaseFrames?: number;
+}
+export interface SamplePlayerControls {
+    gate: Node<'bool'>;
+    /** Level-sensitive restart; a held trigger repeats the first sample. */
+    trigger: Node<'bool'>;
+    /** Priority over gate/trigger; held reset is silent. */
+    reset: Node<'bool'>;
+    /** Signed speed, [-16,16]; source/host sample-rate conversion is automatic. */
+    rate: Node<'f32'>;
+}
+/** Mono, one voice, one-shot or loop; nearest endpoints with linear interpolation. */
+export declare const samplePlayer: import("@unworklet/core").SubgraphDecl<[config: SamplePlayerConfig], {
+    tick(c: SamplePlayerControls): {
+        output: Node<"f32">;
+        active: Node<"bool">;
+        position: Node<"f32">;
+        missing: Node<"bool">;
+    };
+}>;
+export interface SampleZone {
+    sample: ResidentSample;
+    keyLow: number;
+    keyHigh: number;
+    /** Inclusive normalized velocity endpoints. First matching zone wins overlaps. */
+    velocityLow: number;
+    velocityHigh: number;
+    rootKey: number;
+    tuneCents?: number;
+    gain?: number;
+    startFrame?: number;
+    endFrame?: number;
+    loop?: boolean;
+}
+export interface MultisampleConfig {
+    sampleRate: number;
+    zones: readonly SampleZone[];
+    releaseFrames?: number;
+}
+export interface MultisampleControls {
+    key: Node<'f32'>;
+    velocity: Node<'f32'>;
+    gate: Node<'bool'>;
+    trigger: Node<'bool'>;
+    reset: Node<'bool'>;
+    /** Additional signed ratio, multiplied after root-key transposition; final ratio clips to ±16. */
+    rate: Node<'f32'>;
+}
+/** Monophonic key/velocity selection; zone/key/velocity latch on note-on. */
+export declare const multisamplePlayer: import("@unworklet/core").SubgraphDecl<[config: MultisampleConfig], {
+    tick(c: MultisampleControls): {
+        output: Node<"f32">;
+        active: Node<"bool">;
+        zoneIndex: Node<"i32">;
+        missing: Node<"bool">;
+    };
+}>;
+export interface GranularConfig {
+    sampleRate: number;
+    sample: ResidentSample;
+    maxGrains: number;
+    seed?: number;
+    loop?: boolean;
+}
+export interface GranularControls {
+    gate: Node<'bool'>;
+    reset: Node<'bool'>;
+    positionFrames: Node<'f32'>;
+    jitterFrames: Node<'f32'>;
+    rate: Node<'f32'>;
+    durationSeconds: Node<'f32'>;
+    /** 0..2000 onsets/second. Gate-rise creates the first grain even at zero density. */
+    densityHz: Node<'f32'>;
+}
+/** Fixed grain pool, triangular endpoint-zero windows; first free slot, drop on full. */
+export declare const granularSource: import("@unworklet/core").SubgraphDecl<[config: GranularConfig], {
+    tick(c: GranularControls): {
+        output: Node<"f32">;
+        activeGrains: Node<"i32">;
+        onset: Node<"bool">;
+        dropped: Node<"bool">;
+        missing: Node<"bool">;
+    };
+}>;

package/dist/sample.js

@@ -0,0 +1,212 @@
+import { bool, defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+// Native floating scalar stores flush magnitudes below 1e-30. Exact binary
+// scaling preserves meaningful subnormal control/position contributions.
+const CONTROL_SCALE = 2 ** 128;
+const READ_POSITION_SCALE = 2 ** 192;
+function sampleRate(rate) {
+    if (!Number.isFinite(rate) || rate < 8000 || rate > 192000)
+        throw new RangeError('sample rate must be in [8000,192000] Hz');
+}
+function integer(value, minimum, maximum, name) {
+    if (!Number.isInteger(value) || value < minimum || value > maximum)
+        throw new RangeError(`${name} must be an integer in [${minimum},${maximum}]`);
+}
+function bounded(value, minimum, maximum, fallback = 0) {
+    return select(value.eq(value), f64(value), f64(fallback)).clamp(minimum, maximum);
+}
+function wrap(position, start, end) {
+    const length = f64(end.sub(start).max(1));
+    const relative = position.sub(f64(start));
+    return relative.sub(relative.div(length).floor().mul(length)).add(f64(start));
+}
+/** A fixed-capacity mono sample, initially missing. No asset loader or streaming. */
+export const residentSample = defineSubgraph((config) => {
+    integer(config.capacity, 1, 65536, 'sample capacity');
+    sampleRate(config.sourceSampleRate);
+    const pcm = state.buffer.f32({ size: config.capacity }).expose({ name: 'pcm', snapshot: 'persistent' });
+    const length = state.i32(0).named('length'), revision = state.i32(0).named('revision');
+    // A native transient scalar captures normalization once per read, including
+    // when several independent readers share this resident in the same sample.
+    const readPosition = state.f64(0).expose({ name: 'readPosition', snapshot: 'transient' });
+    return {
+        capacity: config.capacity, sourceSampleRate: config.sourceSampleRate,
+        load(data) { pcm.copyFrom(data); length.write(data.length.clamp(0, config.capacity)); revision.write(revision.read().add(1)); },
+        length() { return length.read(); }, revision() { return revision.read(); },
+        read(position, start, end, loop) {
+            const lo = start.clamp(0, config.capacity - 1), hi = end.clamp(0, config.capacity).min(length.read());
+            const valid = hi.gt(lo);
+            const safePosition = select(position.eq(position), position, f64(lo)).clamp(-2147483648, 2147483647);
+            readPosition.write((loop ? wrap(safePosition, lo, hi) : safePosition.clamp(f64(lo), f64(hi.sub(1).max(lo)))).mul(READ_POSITION_SCALE));
+            const p = readPosition.read().div(READ_POSITION_SCALE);
+            const whole = i32(p.floor()).clamp(0, config.capacity - 1), fraction = p.sub(f64(whole));
+            const next = loop ? select(whole.add(1).gte(hi), lo, whole.add(1)) : whole.add(1).min(hi.sub(1).max(lo));
+            const rawA = f64(pcm.read(whole)), rawB = f64(pcm.read(next.clamp(0, config.capacity - 1)));
+            // Invalid PCM taps are silent, without poisoning adjacent finite samples/state.
+            const a = select(rawA.eq(rawA).and(rawA.abs().lte(3.4028234663852886e38)), rawA, f64(0));
+            const b = select(rawB.eq(rawB).and(rawB.abs().lte(3.4028234663852886e38)), rawB, f64(0));
+            return select(valid, f32(a.add(b.sub(a).mul(fraction))), f32(0));
+        },
+    };
+});
+/** Mono, one voice, one-shot or loop; nearest endpoints with linear interpolation. */
+export const samplePlayer = defineSubgraph((config) => {
+    sampleRate(config.sampleRate);
+    const { sample, startFrame = 0, endFrame = sample.capacity, loop = false, releaseFrames = 0 } = config;
+    integer(startFrame, 0, sample.capacity - 1, 'startFrame');
+    integer(endFrame, startFrame + 1, sample.capacity, 'endFrame');
+    integer(releaseFrames, 0, Math.ceil(config.sampleRate * 10), 'releaseFrames');
+    const phase = state.f64(startFrame * CONTROL_SCALE).named('phase'), 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');
+    return {
+        tick(c) {
+            const end = sample.length().min(endFrame), start = i32(startFrame), available = end.gt(start);
+            const speed = bounded(c.rate, -16, 16).mul(sample.sourceSampleRate / config.sampleRate);
+            const changed = sample.revision().eq(revision.read()).not();
+            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(end.sub(1)), f64(start));
+            phase.write(select(trigger, initial, phase.read().div(CONTROL_SCALE)).mul(CONTROL_SCALE));
+            const position = phase.read().div(CONTROL_SCALE);
+            const releaseLeft = select(trigger, i32(releaseFrames), select(c.gate, remaining.read(), remaining.read().sub(1).max(0)));
+            const level = releaseFrames > 0 ? f64(releaseLeft).div(releaseFrames) : select(c.gate, f64(1), f64(0));
+            active.write(alive.and(level.gt(0)));
+            const playing = active.read();
+            const output = select(playing, f32(f64(sample.read(position, start, end, loop)).mul(level)), f32(0));
+            const advanced = position.add(speed);
+            phase.write(select(c.reset, f64(startFrame), loop ? wrap(advanced, start, end) : advanced.clamp(f64(start).sub(1), f64(end))).mul(CONTROL_SCALE));
+            active.write(playing.and(loop ? bool(true) : advanced.gte(f64(start)).and(advanced.lt(f64(end)))));
+            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(position), missing: available.not() };
+        },
+    };
+});
+// Core 0.4.1 pow uses a shared f32 approximation even for f64 operands.
+// Reduce the bounded pitch exponent to [0,1), evaluate exp(x*ln2) in f64,
+// and scale by exact powers of two. This avoids pitch drift from that bridge.
+function transposeRatio(exponent) {
+    const whole = exponent.floor(), x = exponent.sub(whole).mul(Math.LN2);
+    let factorial = 1;
+    const coefficients = [1];
+    for (let n = 1; n <= 12; n++) {
+        factorial *= n;
+        coefficients.push(1 / factorial);
+    }
+    let polynomial = f64(coefficients[12]);
+    for (let n = 11; n >= 0; n--)
+        polynomial = polynomial.mul(x).add(coefficients[n]);
+    const index = i32(whole.add(13));
+    let scale = f64(2 ** -13);
+    for (let bit = 0; bit < 5; bit++)
+        scale = scale.mul(select(index.div(2 ** bit).mod(2).eq(1), f64(2 ** (2 ** bit)), f64(1)));
+    return polynomial.mul(scale);
+}
+/** Monophonic key/velocity selection; zone/key/velocity latch on note-on. */
+export const multisamplePlayer = defineSubgraph((config) => {
+    sampleRate(config.sampleRate);
+    integer(config.zones.length, 1, 16, 'zone count');
+    const zones = config.zones.map((zone, index) => {
+        integer(zone.keyLow, 0, 127, 'keyLow');
+        integer(zone.keyHigh, zone.keyLow, 127, 'keyHigh');
+        integer(zone.rootKey, 0, 127, 'rootKey');
+        const { velocityLow: low, velocityHigh: high, tuneCents = 0, gain = 1 } = zone;
+        if (!Number.isFinite(low) || !Number.isFinite(high) || low < 0 || high > 1 || high < low || !Number.isFinite(tuneCents) || Math.abs(tuneCents) > 2400 || !Number.isFinite(gain) || Math.abs(gain) > 4)
+            throw new RangeError('invalid velocity zone, tuning or gain');
+        return { ...zone, tuneCents, gain, transposition: state.f64(1).named(`zone${index}Transposition`), player: instantiate(samplePlayer, { ...zone, sampleRate: config.sampleRate, releaseFrames: config.releaseFrames }, { name: `zone${index}` }) };
+    });
+    const selected = state.i32(-1).named('selected'), lastGate = state.bool(false).named('previousGate');
+    const keyState = state.f64(60 * CONTROL_SCALE).named('key'), velocityState = state.f64(0).named('velocity');
+    const noteOn = state.bool(false).named('noteOn');
+    return { tick(c) {
+            const key = bounded(c.key, 0, 127, 60), velocity = bounded(c.velocity, 0, 1);
+            noteOn.write(c.trigger.or(c.gate.and(lastGate.read().not())).and(c.gate).and(c.reset.not()));
+            const start = noteOn.read();
+            let match = i32(-1);
+            for (let index = zones.length - 1; index >= 0; index--) {
+                const z = zones[index];
+                match = select(key.gte(z.keyLow).and(key.lte(z.keyHigh)).and(velocity.gte(z.velocityLow)).and(velocity.lte(z.velocityHigh)), i32(index), match);
+            }
+            selected.write(select(c.reset, i32(-1), select(start, match, selected.read())));
+            const current = selected.read();
+            keyState.write(select(start, key.mul(CONTROL_SCALE), keyState.read()));
+            velocityState.write(select(start, velocity.mul(CONTROL_SCALE), velocityState.read()));
+            // Native state reads materialize latched controls before the unrolled bank.
+            const note = keyState.read().div(CONTROL_SCALE), level = velocityState.read().div(CONTROL_SCALE);
+            let sum = f64(0), active = bool(false), missing = current.lt(0);
+            zones.forEach((z, index) => {
+                const chosen = current.eq(index);
+                // Materialize the latched ratio once. Repeating the polynomial graph inside
+                // every readhead expression causes excessive capture/compiler expansion.
+                z.transposition.write(select(start, transposeRatio(note.sub(z.rootKey).div(12).add(z.tuneCents / 1200)), z.transposition.read()));
+                const ratio = z.transposition.read().mul(bounded(c.rate, -16, 16));
+                const result = z.player.tick({ gate: c.gate.and(chosen), trigger: start.and(chosen), reset: c.reset.or(start.and(chosen.not())), rate: f32(ratio) });
+                sum = sum.add(f64(result.output).mul(level).mul(z.gain));
+                active = active.or(result.active);
+                missing = missing.or(chosen.and(result.missing));
+            });
+            lastGate.write(c.gate.and(c.reset.not()));
+            return { output: f32(sum), active, zoneIndex: current, missing };
+        } };
+});
+/** Fixed grain pool, triangular endpoint-zero windows; first free slot, drop on full. */
+export const granularSource = defineSubgraph((config) => {
+    sampleRate(config.sampleRate);
+    integer(config.maxGrains, 1, 32, 'maxGrains');
+    const { sample, maxGrains, seed = 1, loop = true } = config;
+    integer(seed, 1, 2147483646, 'grain seed');
+    const random = state.i32(seed).named('random'), clock = state.f64(0).named('clock');
+    const allocatedState = state.bool(false).named('allocated'), onsetState = state.bool(false).named('onset');
+    const onsetPosition = state.f64(0).named('onsetPosition'), onsetSpeed = state.f64(0).named('onsetSpeed');
+    const onsetDuration = state.i32(3).named('onsetDuration');
+    const lastGate = state.bool(false).named('previousGate'), revision = state.i32(-1).named('revision');
+    const grains = Array.from({ length: maxGrains }, (_, index) => ({
+        position: state.f64(0).named(`grain${index}Position`), age: state.i32(0).named(`grain${index}Age`),
+        duration: state.i32(3).named(`grain${index}Duration`), speed: state.f64(0).named(`grain${index}Speed`),
+        active: state.bool(false).named(`grain${index}Active`),
+    }));
+    return { tick(c) {
+            const changed = sample.revision().eq(revision.read()).not(), clear = c.reset.or(changed);
+            const rising = c.gate.and(lastGate.read().not());
+            const phase = select(clear.or(rising), f64(0), clock.read().div(CONTROL_SCALE));
+            onsetState.write(c.gate.and(c.reset.not()).and(sample.length().gt(0)).and(rising.or(phase.gte(1))));
+            const onset = onsetState.read();
+            const rng = select(c.reset, i32(seed), random.read());
+            const nextRandom = i32(f64(rng).mul(48271).mod(2147483647));
+            random.write(select(onset, nextRandom, rng));
+            const jitter = f64(random.read()).div(2147483647).mul(2).sub(1).mul(bounded(c.jitterFrames, 0, sample.capacity - 1));
+            onsetPosition.write(bounded(c.positionFrames, 0, sample.capacity - 1).add(jitter).clamp(0, f64(sample.length().sub(1).max(0))).mul(CONTROL_SCALE));
+            onsetDuration.write(i32(bounded(c.durationSeconds, 0, 2).mul(config.sampleRate).add(0.5).floor()).clamp(3, Math.round(config.sampleRate * 2)));
+            onsetSpeed.write(bounded(c.rate, -16, 16).mul(sample.sourceSampleRate / config.sampleRate).mul(CONTROL_SCALE));
+            const center = onsetPosition.read().div(CONTROL_SCALE), duration = onsetDuration.read(), speed = onsetSpeed.read().div(CONTROL_SCALE);
+            allocatedState.write(false);
+            let sum = f64(0), count = i32(0);
+            for (const grain of grains) {
+                const existing = grain.active.read().and(grain.age.read().lt(grain.duration.read())).and(clear.not());
+                // Keep the first-free scan linear in graph size as well as runtime work.
+                const allocated = allocatedState.read();
+                const launch = onset.and(allocated.not()).and(existing.not());
+                allocatedState.write(allocated.or(launch));
+                grain.active.write(existing.or(launch));
+                grain.age.write(select(launch, i32(0), grain.age.read()));
+                grain.duration.write(select(launch, duration, grain.duration.read()));
+                grain.position.write(select(launch, center.mul(CONTROL_SCALE), grain.position.read()));
+                grain.speed.write(select(launch, speed.mul(CONTROL_SCALE), grain.speed.read()));
+                const active = grain.active.read(), age = grain.age.read(), length = grain.duration.read();
+                const position = grain.position.read().div(CONTROL_SCALE), step = grain.speed.read().div(CONTROL_SCALE);
+                const window = f64(1).sub(f64(age).div(f64(length.sub(1))).mul(2).sub(1).abs()).max(0);
+                const inBounds = position.gte(0).and(position.lt(f64(sample.length())));
+                const value = sample.read(position, i32(0), sample.length(), loop);
+                sum = sum.add(select(active.and(loop ? bool(true) : inBounds), f64(value).mul(window), f64(0)));
+                count = count.add(select(active, i32(1), i32(0)));
+                grain.position.write((loop ? wrap(position.add(step), i32(0), sample.length()) : position.add(step).clamp(-sample.capacity * 48, sample.capacity * 48)).mul(CONTROL_SCALE));
+                grain.age.write(select(active, age.add(1), i32(0)));
+                grain.active.write(active.and(age.add(1).lt(length)));
+            }
+            clock.write(select(c.gate.and(c.reset.not()), phase.sub(phase.floor()).add(bounded(c.densityHz, 0, 2000).div(config.sampleRate)), f64(0)).mul(CONTROL_SCALE));
+            lastGate.write(c.gate.and(c.reset.not()));
+            revision.write(sample.revision());
+            return { output: f32(sum.div(maxGrains)), activeGrains: count, onset, dropped: onset.and(allocatedState.read().not()), missing: sample.length().eq(0) };
+        } };
+});

package/dist/source.d.ts

@@ -0,0 +1,58 @@
+import { type Node } from '@unworklet/core';
+export interface SourceConfig {
+    sampleRate: number;
+}
+export interface PhaseModulationControls {
+    carrierHz: Node<'f32'>;
+    modulatorHz: Node<'f32'>;
+    /** Signed phase deviation, in radians, clamped to [-8π,8π]. */
+    depthRadians: Node<'f32'>;
+    /** Previous carrier output (one sample old) times this value, in radians. */
+    feedbackRadians: Node<'f32'>;
+    reset: Node<'bool'>;
+}
+export interface FrequencyModulationControls {
+    carrierHz: Node<'f32'>;
+    modulatorHz: Node<'f32'>;
+    /** Signed instantaneous frequency deviation in Hz, not a PM index. */
+    deviationHz: Node<'f32'>;
+    /** Previous carrier output (one sample old) times this value, in Hz. */
+    feedbackHz: Node<'f32'>;
+    reset: Node<'bool'>;
+}
+/** Two-operator PM with a sine modulator and one-sample carrier feedback. */
+export declare const phaseModulation: import("@unworklet/core").SubgraphDecl<[config: SourceConfig], {
+    /** Current phase is emitted before advance. Held reset emits zero every sample. */
+    tick(c: PhaseModulationControls): Node<"f32">;
+}>;
+/** Two-operator linear FM. Negative instantaneous frequency clips to zero. */
+export declare const frequencyModulation: import("@unworklet/core").SubgraphDecl<[config: SourceConfig], {
+    tick(c: FrequencyModulationControls): Node<"f32">;
+}>;
+export interface AdditivePartial {
+    ratio: number;
+    gain: number;
+}
+export interface AdditiveSourceConfig extends SourceConfig {
+    partials: readonly AdditivePartial[];
+}
+/** Fixed sine partial bank. Gains are normalized by their absolute sum. */
+export declare const additiveSource: import("@unworklet/core").SubgraphDecl<[config: AdditiveSourceConfig], {
+    /** Partials above .45*sampleRate are muted; crossing the limit is not smoothed. */
+    tick(frequencyHz: Node<"f32">, reset: Node<"bool">): Node<"f32">;
+}>;
+export interface UnisonVoice {
+    detuneCents: number;
+    pan: number;
+}
+export interface UnisonSourceConfig extends SourceConfig {
+    waveform: 'sine' | 'saw';
+    voices: readonly UnisonVoice[];
+}
+/** Fixed detune bank. Linear pan divided by voice count; L+R is the mono average. */
+export declare const unisonSource: import("@unworklet/core").SubgraphDecl<[config: UnisonSourceConfig], {
+    tick(frequencyHz: Node<"f32">, reset: Node<"bool">): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+    };
+}>;

package/dist/source.js

@@ -0,0 +1,113 @@
+import { defineSubgraph, f32, f64, instantiate, select, state } from '@unworklet/core';
+import { oscillator } from './oscillator.js';
+function maximumFrequency(sampleRate) {
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000) {
+        throw new RangeError('source sampleRate must be finite and in [8000,192000] Hz');
+    }
+    return 0.45 * sampleRate;
+}
+// Same degree-13 sine construction as oscillator, with a wrapped phase offset.
+// Pure graph arithmetic; no runtime JS, table asset, or additional state system.
+function sineCycles(cycles) {
+    const p = cycles.sub(cycles.floor());
+    const folded = select(p.lt(0.25), p, select(p.lt(0.75), f64(0.5).sub(p), p.sub(1)));
+    const angle = folded.mul(2 * Math.PI), z = angle.mul(angle);
+    const polynomial = f64(1 / 6227020800).mul(z).sub(1 / 39916800).mul(z).add(1 / 362880)
+        .mul(z).sub(1 / 5040).mul(z).add(1 / 120).mul(z).sub(1 / 6).mul(z).add(1);
+    return f32(angle.mul(polynomial));
+}
+/** Two-operator PM with a sine modulator and one-sample carrier feedback. */
+export const phaseModulation = defineSubgraph((config) => {
+    const maximum = maximumFrequency(config.sampleRate);
+    const modulator = instantiate(oscillator, { ...config, waveform: 'sine' }, { name: 'modulator' });
+    const phase = state.f64(0).named('carrierPhase');
+    const previous = state.f32(0).named('previousCarrier');
+    return {
+        /** Current phase is emitted before advance. Held reset emits zero every sample. */
+        tick(c) {
+            const p = select(c.reset, f64(0), phase.read());
+            const prior = select(c.reset, f32(0), previous.read());
+            const mod = modulator.tick(c.modulatorHz, c.reset);
+            const offset = f64(c.depthRadians).clamp(-8 * Math.PI, 8 * Math.PI).mul(f64(mod))
+                .add(f64(c.feedbackRadians).clamp(-Math.PI, Math.PI).mul(f64(prior))).div(2 * Math.PI);
+            const output = sineCycles(p.add(offset));
+            phase.write(p.add(f64(c.carrierHz).clamp(0, maximum).div(config.sampleRate)).frac());
+            previous.write(output);
+            return output;
+        },
+    };
+});
+/** Two-operator linear FM. Negative instantaneous frequency clips to zero. */
+export const frequencyModulation = defineSubgraph((config) => {
+    const maximum = maximumFrequency(config.sampleRate);
+    const modulator = instantiate(oscillator, { ...config, waveform: 'sine' }, { name: 'modulator' });
+    const phase = state.f64(0).named('carrierPhase');
+    const previous = state.f32(0).named('previousCarrier');
+    return {
+        tick(c) {
+            const p = select(c.reset, f64(0), phase.read());
+            const prior = select(c.reset, f32(0), previous.read());
+            const mod = modulator.tick(c.modulatorHz, c.reset);
+            const instantaneous = f64(c.carrierHz).clamp(0, maximum)
+                .add(f64(c.deviationHz).clamp(-maximum, maximum).mul(f64(mod)))
+                .add(f64(c.feedbackHz).clamp(-maximum, maximum).mul(f64(prior))).clamp(0, maximum);
+            const output = sineCycles(p);
+            phase.write(p.add(instantaneous.div(config.sampleRate)).frac());
+            previous.write(output);
+            return output;
+        },
+    };
+});
+/** Fixed sine partial bank. Gains are normalized by their absolute sum. */
+export const additiveSource = defineSubgraph((config) => {
+    const maximum = maximumFrequency(config.sampleRate);
+    if (config.partials.length < 1 || config.partials.length > 32)
+        throw new RangeError('additiveSource requires 1–32 partials');
+    const partials = config.partials.map((p, i) => {
+        if (!Number.isFinite(p.ratio) || p.ratio <= 0 || p.ratio > 128 || !Number.isFinite(p.gain) || Math.abs(p.gain) > 16) {
+            throw new RangeError('partial ratio must be in (0,128] and gain in [-16,16]');
+        }
+        return { ...p, source: instantiate(oscillator, { sampleRate: config.sampleRate, waveform: 'sine' }, { name: `partial${i}` }) };
+    });
+    const normalization = partials.reduce((sum, p) => sum + Math.abs(p.gain), 0) || 1;
+    return {
+        /** Partials above .45*sampleRate are muted; crossing the limit is not smoothed. */
+        tick(frequencyHz, reset) {
+            let sum = f64(0);
+            for (const p of partials) {
+                const frequency = f64(frequencyHz).clamp(0, maximum).mul(p.ratio);
+                const sample = p.source.tick(f32(frequency), reset);
+                sum = sum.add(f64(select(frequency.lte(maximum), sample, f32(0))).mul(p.gain / normalization));
+            }
+            return f32(sum);
+        },
+    };
+});
+/** Fixed detune bank. Linear pan divided by voice count; L+R is the mono average. */
+export const unisonSource = defineSubgraph((config) => {
+    const maximum = maximumFrequency(config.sampleRate);
+    if (config.voices.length < 1 || config.voices.length > 8)
+        throw new RangeError('unisonSource requires 1–8 voices');
+    if (config.waveform !== 'sine' && config.waveform !== 'saw')
+        throw new RangeError('unknown unison waveform');
+    const voices = config.voices.map((v, i) => {
+        if (!Number.isFinite(v.detuneCents) || Math.abs(v.detuneCents) > 1200 || !Number.isFinite(v.pan) || Math.abs(v.pan) > 1) {
+            throw new RangeError('unison detune must be in [-1200,1200] cents and pan in [-1,1]');
+        }
+        return { ratio: 2 ** (v.detuneCents / 1200), left: (1 - v.pan) / (2 * config.voices.length),
+            right: (1 + v.pan) / (2 * config.voices.length),
+            source: instantiate(oscillator, { sampleRate: config.sampleRate, waveform: config.waveform }, { name: `voice${i}` }) };
+    });
+    return {
+        tick(frequencyHz, reset) {
+            let left = f64(0), right = f64(0);
+            for (const voice of voices) {
+                const frequency = f64(frequencyHz).clamp(0, maximum).mul(voice.ratio).clamp(0, maximum);
+                const sample = f64(voice.source.tick(f32(frequency), reset));
+                left = left.add(sample.mul(voice.left));
+                right = right.add(sample.mul(voice.right));
+            }
+            return { left: f32(left), right: f32(right) };
+        },
+    };
+});

package/dist/spatial-chains.d.ts

@@ -0,0 +1,50 @@
+import { type EveryNSamples, type Node } from '@unworklet/core';
+export interface SpatialChainConfig {
+    /** Pass ctx.renderQuantumSize for the early convolution snapshot phase. */
+    renderQuantumSize: number;
+    /** Match the enclosing ctx.sampleRate; integer 8000..192000. */
+    sampleRate: number;
+}
+export interface SpatialChainControls {
+    /** Finite linear dry/wet, clamped to [0,1]. Zero still feeds the wet paths. */
+    mix: Node<'f32'>;
+    /** Unity dry, no new wet excitation; all existing tails keep processing. */
+    bypass: Node<'bool'>;
+    /** Highest priority: silence, discard current input and invalidate history. */
+    reset: Node<'bool'>;
+}
+export interface FeedforwardPitchedReverbConfig extends SpatialChainConfig {
+    /** Fixed pitch delay excursion: even integer 32..16384, default 2048. */
+    windowSamples?: number;
+}
+export interface FeedforwardPitchedReverbControls extends SpatialChainControls {
+    /** Reader speed [.5,2]. Invalid values retain the prior ratio, or 1 on reset. */
+    ratio: Node<'f32'>;
+    /** Finite unpitched/pitched late blend, clamped [0,1]. Readers always advance. */
+    pitchMix: Node<'f32'>;
+    /** Rephase the current pitch read while retaining history. Can click. */
+    retrigger: Node<'bool'>;
+}
+/** CANDIDATE mono-in/stereo-out short FIR + three early taps || damped FDN.
+ * Finite normalized input [-1,1]; no limiter. Dry is immediate, early has B8
+ * latency plus 7/13/23ms taps, and late begins near 29.7ms with an IIR tail.
+ * Call once per sample in stride-1 forSample with its native everyNSamples.
+ */
+export declare const hybridReverb: import("@unworklet/core").SubgraphDecl<[config: SpatialChainConfig], {
+    tick(input: Node<"f32">, c: SpatialChainControls, everyNSamples: EveryNSamples): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+    };
+}>;
+/** Same hybrid space with pitch applied only to a feedforward copy of its FDN
+ * output. No pitched signal enters the FDN or early path. This is
+ * not regenerative shimmer. Pitch adds variable 1..W+1-sample read ages, with
+ * interpolation aliasing/window coloration; parallel blending can cancel.
+ */
+export declare const feedforwardPitchedReverb: import("@unworklet/core").SubgraphDecl<[config: FeedforwardPitchedReverbConfig], {
+    tick(input: Node<"f32">, c: FeedforwardPitchedReverbControls, everyNSamples: EveryNSamples): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+        ratioRejected: Node<"bool">;
+    };
+}>;

package/dist/spatial-chains.js

@@ -0,0 +1,76 @@
+import { bool, defineSubgraph, f32, f64, instantiate, select } from '@unworklet/core';
+import { partitionedConvolution } from './convolution.js';
+import { multiTapDelay } from './stereo-delay.js';
+import { algorithmicReverb } from './reverb.js';
+import { windowedPitchShift } from './windowed-pitch-shift.js';
+// Construction-only composition. Each existing module retains its own state,
+// scheduler and native snapshot contract; no new runtime routing is introduced.
+function spatialPaths({ sampleRate, renderQuantumSize }) {
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000) {
+        throw new RangeError('spatial chains require integer sampleRate [8000,192000]');
+    }
+    const color = instantiate(partitionedConvolution, {
+        renderQuantumSize, blockSize: 8, impulse: [.625, 0, 0, .25, 0, 0, 0, -.125],
+    }, { name: 'earlyColor' });
+    const reflections = instantiate(multiTapDelay, {
+        sampleRate, maxDelaySeconds: .023,
+        taps: [
+            { delaySeconds: .007, gainLeft: .5, gainRight: .25 },
+            { delaySeconds: .013, gainLeft: .25, gainRight: -.25 },
+            { delaySeconds: .023, gainLeft: -.125, gainRight: .375 },
+        ],
+    }, { name: 'earlyTaps' });
+    const late = instantiate(algorithmicReverb, {
+        sampleRate, roomScale: 1, decaySeconds: .6, dampingHz: Math.min(3500, .4 * sampleRate),
+    }, { name: 'late' });
+    return {
+        tick(input, c, everyNSamples) {
+            const excitation = select(c.reset.or(c.bypass), f32(0), input);
+            const early = reflections.tick(color.tick(excitation, c.reset, everyNSamples), {
+                feedback: f32(0), mix: f32(1), bypass: bool(false), reset: c.reset,
+            });
+            const tail = late.tick(excitation, f32(0), { mix: f32(1), bypass: bool(false), reset: c.reset });
+            return { early, tail };
+        },
+    };
+}
+function blend(input, early, late, c) {
+    const mix = f64(c.mix).clamp(0, 1), wet = f64(early).add(late).mul(.5);
+    return select(c.reset, f32(0), select(c.bypass, input, f32(f64(input).mul(f64(1).sub(mix)).add(wet.mul(mix)))));
+}
+/** CANDIDATE mono-in/stereo-out short FIR + three early taps || damped FDN.
+ * Finite normalized input [-1,1]; no limiter. Dry is immediate, early has B8
+ * latency plus 7/13/23ms taps, and late begins near 29.7ms with an IIR tail.
+ * Call once per sample in stride-1 forSample with its native everyNSamples.
+ */
+export const hybridReverb = defineSubgraph((config) => {
+    const paths = spatialPaths(config);
+    return {
+        tick(input, c, everyNSamples) {
+            const { early, tail } = paths.tick(input, c, everyNSamples);
+            return { left: blend(input, early.left, f64(tail.left), c), right: blend(input, early.right, f64(tail.right), c) };
+        },
+    };
+});
+/** Same hybrid space with pitch applied only to a feedforward copy of its FDN
+ * output. No pitched signal enters the FDN or early path. This is
+ * not regenerative shimmer. Pitch adds variable 1..W+1-sample read ages, with
+ * interpolation aliasing/window coloration; parallel blending can cancel.
+ */
+export const feedforwardPitchedReverb = defineSubgraph((config) => {
+    const paths = spatialPaths(config);
+    const left = instantiate(windowedPitchShift, config, { name: 'pitchLeft' });
+    const right = instantiate(windowedPitchShift, config, { name: 'pitchRight' });
+    return {
+        tick(input, c, everyNSamples) {
+            const { early, tail } = paths.tick(input, c, everyNSamples);
+            const l = left.tick(tail.left, c), r = right.tick(tail.right, c);
+            const mix = f64(c.pitchMix).clamp(0, 1), dry = f64(1).sub(mix);
+            return {
+                left: blend(input, early.left, f64(tail.left).mul(dry).add(f64(l.output).mul(mix)), c),
+                right: blend(input, early.right, f64(tail.right).mul(dry).add(f64(r.output).mul(mix)), c),
+                ratioRejected: l.ratioRejected,
+            };
+        },
+    };
+});

package/dist/spectral-fft.d.ts

@@ -0,0 +1,27 @@
+import { type Node } from '@unworklet/core';
+/** Internal fixed-capacity buffer iteration, using only public native loops.
+ * No audio/parameter indexing or sample-clock advancement belongs in this body.
+ */
+export declare function spectralForEach(size: number, body: (index: Node<'i32'>) => void): void;
+/** Internal sample dispatch period. Native scheduler phase is not snapshotted.
+ * A divisor of both the hop and quantum realigns a fresh scheduler at every
+ * block-atomic restore; persistent module cursors decide when to commit frames.
+ * Keep the historical 128-sample maximum dispatch period at ordinary targets.
+ */
+export declare function spectralDispatchPeriod(hopSize: number, renderQuantumSize: number): number;
+/** Internal construction-fixed FFT. Not a separate runtime or public package API. */
+export declare const spectralFft: import("@unworklet/core").SubgraphDecl<[config: {
+    size: number;
+}], {
+    /** JS functions/loops run during graph capture. Butterfly iteration uses the
+     * public fixed-count native forIndex loop over work-buffer indices, nested
+     * inside the caller's hop body. It performs no audio I/O or audio-time update.
+     * Inputs must not alias these work buffers.
+     * Result aliases scratch and must be consumed before the next transform.
+     * Forward: sum x[n] exp(-i*2*pi*k*n/N). Inverse: positive sign and 1/N.
+     */
+    transform(real: (index: Node<"i32">) => Node<"f64">, imag: (index: Node<"i32">) => Node<"f64">, inverse: boolean): {
+        real: (index: number | Node<"i32">) => Node<"f64">;
+        imag: (index: number | Node<"i32">) => Node<"f64">;
+    };
+}>;