@denaudio/den 0.0.0-stage → 0.2.0

package/dist/spectral-fft.js

@@ -0,0 +1,84 @@
+import { defineSubgraph, f64, forIndex, i32, select, state } 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 function spectralForEach(size, body) {
+    if (size < 4 || size > 1024 || !Number.isInteger(Math.log2(size))) {
+        throw new RangeError('spectral buffer iteration requires power-of-two size [4,1024]');
+    }
+    forIndex(size, body);
+}
+/** 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 function spectralDispatchPeriod(hopSize, renderQuantumSize) {
+    if (!Number.isInteger(renderQuantumSize) || renderQuantumSize < 1) {
+        throw new RangeError('spectral renderQuantumSize must be the positive integer ctx.renderQuantumSize');
+    }
+    let divisor = Math.min(hopSize, 128), remaining = renderQuantumSize;
+    while (remaining !== 0)
+        [divisor, remaining] = [remaining, divisor % remaining];
+    return divisor;
+}
+/** Internal construction-fixed FFT. Not a separate runtime or public package API. */
+export const spectralFft = defineSubgraph((config) => {
+    const { size } = config;
+    if (!Number.isInteger(size) || size < 8 || size > 1024 || !Number.isInteger(Math.log2(size))) {
+        throw new RangeError('spectral FFT size must be a power of two in [8,1024]');
+    }
+    const stages = Math.log2(size);
+    const banks = [0, 1].map(bank => ({
+        real: state.buffer.f64({ size }).expose({ name: `real${bank}`, snapshot: 'transient' }),
+        imag: state.buffer.f64({ size }).expose({ name: `imag${bank}`, snapshot: 'transient' }),
+    }));
+    const twiddleReal = state.f64(1).expose({ name: 'twiddleReal', snapshot: 'transient' });
+    const twiddleImag = state.f64(0).expose({ name: 'twiddleImag', snapshot: 'transient' });
+    const reverse = (index) => {
+        let result = i32(0);
+        for (let bit = 0; bit < stages; bit++)
+            result = result.add(index.div(2 ** bit).mod(2).mul(2 ** (stages - 1 - bit)));
+        return result;
+    };
+    return {
+        /** 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, imag, inverse) {
+            spectralForEach(size, index => {
+                banks[0].real.write(reverse(index), real(index));
+                banks[0].imag.write(reverse(index), imag(index));
+            });
+            for (let stage = 0; stage < stages; stage++) {
+                const width = 2 ** (stage + 1), half = width / 2;
+                const source = banks[stage % 2], target = banks[(stage + 1) % 2];
+                const angle = (inverse ? 1 : -1) * 2 * Math.PI / width;
+                const cosineStep = Math.cos(angle), sineStep = Math.sin(angle);
+                spectralForEach(size / 2, index => {
+                    const j = index.mod(half);
+                    const a = index.div(half).mul(width).add(j), b = a.add(half);
+                    // Each butterfly group starts at exactly (1,0); a bounded recurrence
+                    // advances its twiddle without a table loader or runtime trig calls.
+                    const cosine = select(j.eq(0), f64(1), twiddleReal.read());
+                    const sine = select(j.eq(0), f64(0), twiddleImag.read());
+                    const ar = source.real.read(a), ai = source.imag.read(a);
+                    const br = source.real.read(b), bi = source.imag.read(b);
+                    const tr = br.mul(cosine).sub(bi.mul(sine)), ti = br.mul(sine).add(bi.mul(cosine));
+                    target.real.write(a, ar.add(tr));
+                    target.imag.write(a, ai.add(ti));
+                    target.real.write(b, ar.sub(tr));
+                    target.imag.write(b, ai.sub(ti));
+                    twiddleReal.write(cosine.mul(cosineStep).sub(sine.mul(sineStep)));
+                    twiddleImag.write(cosine.mul(sineStep).add(sine.mul(cosineStep)));
+                });
+            }
+            const result = banks[stages % 2], scale = inverse ? 1 / size : 1;
+            return { real: (index) => result.real.read(index).mul(scale), imag: (index) => result.imag.read(index).mul(scale) };
+        },
+    };
+});

package/dist/spectral-freeze.d.ts

@@ -0,0 +1,24 @@
+import { type EveryNSamples, type Node } from '@unworklet/core';
+export interface SpectralFreezeConfig {
+    /** Pass ctx.renderQuantumSize; aligns native dispatch with snapshot boundaries. */
+    renderQuantumSize: number;
+    /** Construction-fixed power of two in [8,1024]. Reference alignment is size samples. */
+    size: number;
+    /** Exactly size/2 or size/4. Rebuild to change. */
+    hopSize: number;
+}
+/** Bin-centered spectral freeze, periodic sqrt-Hann WOLA. Offline CANDIDATE.
+ * Call once per sample inside stride-1 forSample with its everyNSamples.
+ * Finite normalized f32 input [-1,1]. Output is not limited/normalized.
+ * At committed t=mH, a high freeze captures [t-N,t) if not already held.
+ * Held bins advance by +2*pi*k*H/N per frame (no frequency estimation).
+ * A low freeze releases at that frame; existing overlap settles within N.
+ * Input/history continue while frozen. Controls between frames are ignored.
+ * Reset immediately silences/discards input and invalidates the hold, without
+ * rephasing. High freeze recaptures at the next non-reset committed frame.
+ * No finite drain while held. With freeze low, drain 2N zero input samples
+ * after the later of source end and release request. No realtime guarantee.
+ */
+export declare const spectralFreeze: import("@unworklet/core").SubgraphDecl<[config: SpectralFreezeConfig], {
+    tick(input: Node<"f32">, freeze: Node<"bool">, reset: Node<"bool">, everyNSamples: EveryNSamples): Node<"f32">;
+}>;

package/dist/spectral-freeze.js

@@ -0,0 +1,74 @@
+import { defineSubgraph, f64, i32, select, state } from '@unworklet/core';
+import { spectralForEach } from './spectral-fft.js';
+import { createStftIdentity } from './spectral-stft.js';
+/** Bin-centered spectral freeze, periodic sqrt-Hann WOLA. Offline CANDIDATE.
+ * Call once per sample inside stride-1 forSample with its everyNSamples.
+ * Finite normalized f32 input [-1,1]. Output is not limited/normalized.
+ * At committed t=mH, a high freeze captures [t-N,t) if not already held.
+ * Held bins advance by +2*pi*k*H/N per frame (no frequency estimation).
+ * A low freeze releases at that frame; existing overlap settles within N.
+ * Input/history continue while frozen. Controls between frames are ignored.
+ * Reset immediately silences/discards input and invalidates the hold, without
+ * rephasing. High freeze recaptures at the next non-reset committed frame.
+ * No finite drain while held. With freeze low, drain 2N zero input samples
+ * after the later of source end and release request. No realtime guarantee.
+ */
+export const spectralFreeze = defineSubgraph((config) => {
+    // Keep the reviewed framing and FFT unchanged. This persistent modulo-H clock
+    // mirrors its cursor%H, including snapshots and reset (which never rephases).
+    const framing = createStftIdentity(config, 1024, spectrum => {
+        const due = frameClock.read().eq(0);
+        const requested = freezeControl.read().and(resetControl.read().not());
+        captureNow.write(due.and(requested).and(active.read().not()));
+        heldPhase.write(select(due, select(requested, select(active.read(), heldPhase.read().add(1).mod(period), i32(0)), i32(0)), heldPhase.read()));
+        active.write(select(due, requested, active.read()));
+        const captureBin = (k) => {
+            heldReal.write(k, select(captureNow.read(), spectrum.real(k), heldReal.read(k)));
+            heldImag.write(k, select(captureNow.read(), select(k.eq(0).or(k.eq(half)), f64(0), spectrum.imag(k)), heldImag.read(k)));
+        };
+        spectralForEach(half, captureBin);
+        captureBin(i32(half));
+        const bin = (k) => {
+            const index = typeof k === 'number' ? i32(k) : k;
+            const pair = index.min(i32(size).sub(index));
+            // H=N/2 or N/4: the exact unit rotations need no trig or recurrence.
+            const quadrant = pair.mul(heldPhase.read()).mul(4 / period).mod(4);
+            const re = heldReal.read(pair), im = heldImag.read(pair);
+            const real = select(quadrant.eq(0), re, select(quadrant.eq(1), im.neg(), select(quadrant.eq(2), re.neg(), im)));
+            const imag = select(quadrant.eq(0), im, select(quadrant.eq(1), re, select(quadrant.eq(2), im.neg(), re.neg())));
+            return { index, pair, real, imag };
+        };
+        return {
+            real(k) {
+                const value = bin(k);
+                return select(active.read(), value.real, spectrum.real(value.index));
+            },
+            imag(k) {
+                const value = bin(k);
+                const mirrored = select(value.index.gt(half), value.imag.neg(), value.imag);
+                const realOnly = select(value.pair.eq(0).or(value.pair.eq(half)), f64(0), mirrored);
+                return select(active.read(), realOnly, spectrum.imag(value.index));
+            },
+        };
+    });
+    const { size, hopSize } = config, half = size / 2, period = size / hopSize;
+    const heldReal = state.buffer.f64({ size: half + 1 }).expose({ name: 'heldRealScaled', snapshot: 'persistent' });
+    const heldImag = state.buffer.f64({ size: half + 1 }).expose({ name: 'heldImagScaled', snapshot: 'persistent' });
+    const frameClock = state.i32(0).named('frameClock');
+    const heldPhase = state.i32(0).named('heldPhase');
+    const active = state.bool(false).named('active');
+    const freezeControl = state.bool(false).expose({ name: 'freezeControl', snapshot: 'transient' });
+    const resetControl = state.bool(false).expose({ name: 'resetControl', snapshot: 'transient' });
+    const captureNow = state.bool(false).expose({ name: 'captureNow', snapshot: 'transient' });
+    return {
+        tick(input, freeze, reset, everyNSamples) {
+            freezeControl.write(freeze);
+            resetControl.write(reset);
+            active.write(active.read().and(reset.not()));
+            heldPhase.write(select(reset, i32(0), heldPhase.read()));
+            const output = framing.tick(input, reset, everyNSamples);
+            frameClock.write(frameClock.read().add(1).mod(hopSize));
+            return output;
+        },
+    };
+});

package/dist/spectral-gate.d.ts

@@ -0,0 +1,23 @@
+import { type EveryNSamples, type Node } from '@unworklet/core';
+export interface SpectralGateConfig {
+    /** Pass ctx.renderQuantumSize; aligns native dispatch with snapshot boundaries. */
+    renderQuantumSize: number;
+    /** Construction-fixed power of two in [8,1024]. Reference alignment is size samples. */
+    size: number;
+    /** Exactly size/2 or size/4. Rebuild to change. */
+    hopSize: number;
+}
+/** Framewise hard spectral gate; periodic sqrt-Hann WOLA, no ballistics/limiter.
+ * Call once per sample inside stride-1 forSample with its everyNSamples.
+ * Input must be finite normalized f32 [-1,1]; attenuation can raise output peaks.
+ * Threshold: single-sided coherent-window bin amplitude, not RMS or dB.
+ * Floor: linear gain. Controls are sampled only on committed frame boundaries.
+ * NaN threshold becomes 0, NaN floor becomes 1 (all-pass); infinities clamp.
+ * Reference delay is N, but processed transients may spread across each frame.
+ * Drain at least 2*size zero input samples after the source ends.
+ * Reset immediately silences/discards input, without rephasing frame boundaries.
+ * Offline CANDIDATE. No browser/realtime guarantee.
+ */
+export declare const spectralGate: import("@unworklet/core").SubgraphDecl<[config: SpectralGateConfig], {
+    tick(input: Node<"f32">, threshold: Node<"f32">, floorGain: Node<"f32">, reset: Node<"bool">, everyNSamples: EveryNSamples): Node<"f32">;
+}>;

package/dist/spectral-gate.js

@@ -0,0 +1,58 @@
+import { defineSubgraph, f64, i32, select, state } from '@unworklet/core';
+import { spectralForEach } from './spectral-fft.js';
+import { createStftIdentity } from './spectral-stft.js';
+/** Framewise hard spectral gate; periodic sqrt-Hann WOLA, no ballistics/limiter.
+ * Call once per sample inside stride-1 forSample with its everyNSamples.
+ * Input must be finite normalized f32 [-1,1]; attenuation can raise output peaks.
+ * Threshold: single-sided coherent-window bin amplitude, not RMS or dB.
+ * Floor: linear gain. Controls are sampled only on committed frame boundaries.
+ * NaN threshold becomes 0, NaN floor becomes 1 (all-pass); infinities clamp.
+ * Reference delay is N, but processed transients may spread across each frame.
+ * Drain at least 2*size zero input samples after the source ends.
+ * Reset immediately silences/discards input, without rephasing frame boundaries.
+ * Offline CANDIDATE. No browser/realtime guarantee.
+ */
+export const spectralGate = defineSubgraph((config) => {
+    const framing = createStftIdentity(config, 1024, spectrum => {
+        const writeGain = (k) => {
+            const real = spectrum.real(k), imag = spectrum.imag(k);
+            const factor = select(k.eq(0).or(k.eq(half)), f64(1), f64(4));
+            const power = real.mul(real).add(imag.mul(imag)).mul(factor);
+            gains.write(k, select(power.gte(thresholdSquared.read()), f64(scale), floor.read()));
+        };
+        spectralForEach(half, writeGain);
+        writeGain(i32(half));
+        const allPass = thresholdSquared.read().eq(0).or(floor.read().eq(scale));
+        const canonical = (k) => k.min(i32(size).sub(k));
+        return {
+            real: (k) => {
+                const index = typeof k === 'number' ? i32(k) : k, pair = canonical(index);
+                const gated = spectrum.real(pair).mul(gains.read(pair).div(scale));
+                return select(allPass, spectrum.real(index), gated);
+            },
+            imag: (k) => {
+                const index = typeof k === 'number' ? i32(k) : k, pair = canonical(index);
+                const sign = select(index.gt(half), f64(-1), f64(1));
+                const gated = select(pair.eq(0).or(pair.eq(half)), f64(0), spectrum.imag(pair).mul(sign).mul(gains.read(pair).div(scale)));
+                return select(allPass, spectrum.imag(index), gated);
+            },
+        };
+    });
+    const { size } = config, half = size / 2, scale = 2 ** 128;
+    const maxF32 = 3.4028234663852886e38;
+    // Sum of periodic sqrt-Hann: sum_{n=0}^{N-1} sin(pi*n/N).
+    const windowSum = 1 / Math.tan(Math.PI / (2 * size));
+    const thresholdSquared = state.f64(0).expose({ name: 'thresholdSquaredScaled', snapshot: 'transient' });
+    const floor = state.f64(scale).expose({ name: 'floorScaled', snapshot: 'transient' });
+    const gains = state.buffer.f64({ size: half + 1 }).expose({ name: 'gainsScaled', snapshot: 'transient' });
+    return {
+        tick(input, threshold, floorGain, reset, everyNSamples) {
+            // Materialize outer-sample controls before the nested native buffer loops.
+            // Scaling preserves f32 subnormals through 0.4.1's 1e-30 buffer flush.
+            const level = select(threshold.eq(threshold), f64(threshold).max(0).min(maxF32), f64(0)).mul(windowSum * scale);
+            thresholdSquared.write(level.mul(level));
+            floor.write(select(floorGain.eq(floorGain), f64(floorGain).max(0).min(1), f64(1)).mul(scale));
+            return framing.tick(input, reset, everyNSamples);
+        },
+    };
+});

package/dist/spectral-stft.d.ts

@@ -0,0 +1,14 @@
+import { type EveryNSamples, type Node } from '@unworklet/core';
+/** Internal graph-construction-only bin view. Never a runtime JS callback. */
+export interface StftSpectrum {
+    real(index: number | Node<'i32'>): Node<'f64'>;
+    imag(index: number | Node<'i32'>): Node<'f64'>;
+}
+/** Internal construction only. Public wrappers choose their reviewed capacity. */
+export declare function createStftIdentity(config: {
+    size: number;
+    hopSize: number;
+    renderQuantumSize: number;
+}, maximumSize: number, processSpectrum?: (spectrum: StftSpectrum) => StftSpectrum): {
+    tick(input: Node<"f32">, reset: Node<"bool">, everyNSamples: EveryNSamples): Node<"f32">;
+};

package/dist/spectral-stft.js

@@ -0,0 +1,70 @@
+import { f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+import { spectralDispatchPeriod, spectralFft, spectralForEach } from './spectral-fft.js';
+/** Internal construction only. Public wrappers choose their reviewed capacity. */
+export function createStftIdentity(config, maximumSize, processSpectrum) {
+    const { size, hopSize } = config;
+    if (!Number.isInteger(size) || size < 8 || size > maximumSize || !Number.isInteger(Math.log2(size)) ||
+        (hopSize !== size / 2 && hopSize !== size / 4)) {
+        throw new RangeError(`stftIdentity requires power-of-two size [8,${maximumSize}] and hopSize size/2 or size/4`);
+    }
+    const dispatchPeriod = spectralDispatchPeriod(hopSize, config.renderQuantumSize);
+    const fft = instantiate(spectralFft, { size }, { name: 'fft' });
+    // Public 0.4.1 flushes buffer writes below 1e-30. Exact power-of-two
+    // scaling retains finite f32 subnormals without adding an audio threshold.
+    const scale = 2 ** 128;
+    const history = state.buffer.f64({ size }).expose({ name: 'historyScaled', snapshot: 'persistent' });
+    const overlap = state.buffer.f64({ size }).expose({ name: 'overlap', snapshot: 'persistent' });
+    // Separate spectrum avoids aliasing FFT input with its bit-reversal workspace.
+    const real = state.buffer.f64({ size }).expose({ name: 'spectrumReal', snapshot: 'transient' });
+    const imag = state.buffer.f64({ size }).expose({ name: 'spectrumImag', snapshot: 'transient' });
+    const cursor = state.i32(0).named('cursor');
+    const valid = state.i32(0).named('valid');
+    const pendingReset = state.bool(true).named('pendingReset');
+    const window = state.buffer.f64({ size }).expose({ name: 'window', snapshot: 'transient' });
+    const windowReal = state.f64(1).expose({ name: 'windowReal', snapshot: 'transient' });
+    const windowImag = state.f64(0).expose({ name: 'windowImag', snapshot: 'transient' });
+    const cosineStep = Math.cos(Math.PI / size), sineStep = Math.sin(Math.PI / size);
+    const normalization = 2 * hopSize / size;
+    return {
+        tick(input, reset, everyNSamples) {
+            valid.write(select(reset, i32(0), valid.read()));
+            pendingReset.write(pendingReset.read().or(reset));
+            // Native scheduler counters are not snapshot state. The dispatch period
+            // divides both the hop and actual quantum, so a fresh scheduler aligns
+            // after any block-atomic restore. The persistent ring cursor carries H
+            // phase; off-phase FFT results are computed eagerly but never committed.
+            // No CPU-saving claim is attached to the select-based commit condition.
+            everyNSamples(dispatchPeriod, () => {
+                const frameDue = cursor.read().mod(hopSize).eq(0);
+                // sin(pi*n/N) equals the nonnegative periodic sqrt-Hann window.
+                // Reanchor per frame; one native buffer loop replaces N code copies.
+                windowReal.write(1);
+                windowImag.write(0);
+                spectralForEach(size, n => {
+                    const cosine = windowReal.read(), sine = windowImag.read();
+                    window.write(n, sine);
+                    windowReal.write(cosine.mul(cosineStep).sub(sine.mul(sineStep)));
+                    windowImag.write(cosine.mul(sineStep).add(sine.mul(cosineStep)));
+                });
+                const analysis = fft.transform(n => select(valid.read().gte(i32(size).sub(n)), history.read(cursor.read().add(n).mod(size)), f64(0)).mul(window.read(n)), () => f64(0), false);
+                // The absent hook captures exactly the pre-hook identity graph and state.
+                const spectrum = processSpectrum ? processSpectrum(analysis) : analysis;
+                spectralForEach(size, n => { real.write(n, spectrum.real(n)); imag.write(n, spectrum.imag(n)); });
+                const frame = fft.transform(n => real.read(n), n => imag.read(n), true);
+                spectralForEach(size, n => {
+                    const at = cursor.read().add(n).mod(size);
+                    const previous = overlap.read(at);
+                    overlap.write(at, select(frameDue, select(pendingReset.read(), f64(0), previous).add(frame.real(n).mul(window.read(n)).mul(normalization)), previous));
+                });
+                pendingReset.write(pendingReset.read().and(frameDue.not()));
+            });
+            const output = select(reset.or(pendingReset.read()), f32(0), f32(overlap.read(cursor.read()).div(scale)));
+            // Reads in this DSL are captured at use, before the corresponding writes.
+            overlap.write(cursor.read(), f64(0));
+            history.write(cursor.read(), f64(select(reset, f32(0), input)).mul(scale));
+            cursor.write(cursor.read().add(1).mod(size));
+            valid.write(select(reset, i32(0), valid.read().add(1).min(size)));
+            return output;
+        },
+    };
+}

package/dist/spectral-texture.d.ts

@@ -0,0 +1,46 @@
+import { type EveryNSamples, type Node } from '@unworklet/core';
+export interface SpectralBlurConfig {
+    /** Pass ctx.renderQuantumSize; aligns native dispatch with snapshot boundaries. */
+    renderQuantumSize: number;
+    /** Construction-fixed power of two in [8,256]; live reference delay is size. */
+    size: number;
+    /** Exactly size/2 or size/4. */
+    hopSize: number;
+    /** Circular triangular magnitude kernel radius, integer [1,min(8,size/2-1)]. */
+    radius: number;
+}
+export interface SpectralCrossSynthesisConfig {
+    /** Pass ctx.renderQuantumSize; aligns native dispatch with snapshot boundaries. */
+    renderQuantumSize: number;
+    /** Construction-fixed power of two in [8,256]; live reference delay is size. */
+    size: number;
+    /** Exactly size/2 or size/4. */
+    hopSize: number;
+    /** Maximum per-bin carrier gain; finite construction constant in [1,16]. */
+    maxGain: number;
+}
+/** Frequency-magnitude blur, periodic sqrt-Hann WOLA. Offline CANDIDATE.
+ * Call once per sample in stride-1 forSample with its everyNSamples.
+ * Finite normalized f32 input [-1,1]. Amount clamps [0,1], NaN=>0.
+ * Amount is frame-sampled and interpolates raw two-sided magnitudes linearly.
+ * Bins >=2^-20 of the frame peak retain current phase; weaker/zero bins use
+ * phase zero. This can jump at the floor and is not a phase-vocoder/smoothing.
+ * Amount=0 uses the untouched spectrum; previous processed overlap must settle.
+ * Reset immediately silences/discards input, without rephasing. Drain 2N zeros.
+ * Peaks can grow; no limiter, sound approval, browser or realtime guarantee.
+ */
+export declare const spectralBlur: import("@unworklet/core").SubgraphDecl<[config: SpectralBlurConfig], {
+    tick(input: Node<"f32">, blend: Node<"f32">, reset: Node<"bool">, everyNSamples: EveryNSamples): Node<"f32">;
+}>;
+/** Gain-bounded carrier-phase magnitude replacement. Offline CANDIDATE.
+ * Same call/framing/input/reset/amount/drain contract as spectralBlur.
+ * Amount=1 targets modulator magnitudes, capped at maxGain*carrier magnitude.
+ * Zero carrier stays silent; near-zero carrier gain is bounded by maxGain.
+ * Zero modulator at amount=1 suppresses all newly committed carrier bins.
+ * The modulator and carrier are analyzed synchronously; current input excluded.
+ * Full same-graph/config/rate native restore only; never restore half the pair.
+ * No speech-quality, transparent reconstruction, browser or realtime guarantee.
+ */
+export declare const spectralCrossSynthesis: import("@unworklet/core").SubgraphDecl<[config: SpectralCrossSynthesisConfig], {
+    tick(carrier: Node<"f32">, inputModulator: Node<"f32">, blend: Node<"f32">, reset: Node<"bool">, everyNSamples: EveryNSamples): Node<"f32">;
+}>;

package/dist/spectral-texture.js

@@ -0,0 +1,141 @@
+import { defineSubgraph, f64, i32, instantiate, select, state } from '@unworklet/core';
+import { spectralForEach } from './spectral-fft.js';
+import { createStftIdentity } from './spectral-stft.js';
+const scale = 2 ** 128;
+const phaseFloor = 2 ** -20;
+const boundedAmount = (amount) => select(amount.eq(amount), f64(amount).max(0).min(1), f64(0)).mul(scale);
+/** Frequency-magnitude blur, periodic sqrt-Hann WOLA. Offline CANDIDATE.
+ * Call once per sample in stride-1 forSample with its everyNSamples.
+ * Finite normalized f32 input [-1,1]. Amount clamps [0,1], NaN=>0.
+ * Amount is frame-sampled and interpolates raw two-sided magnitudes linearly.
+ * Bins >=2^-20 of the frame peak retain current phase; weaker/zero bins use
+ * phase zero. This can jump at the floor and is not a phase-vocoder/smoothing.
+ * Amount=0 uses the untouched spectrum; previous processed overlap must settle.
+ * Reset immediately silences/discards input, without rephasing. Drain 2N zeros.
+ * Peaks can grow; no limiter, sound approval, browser or realtime guarantee.
+ */
+export const spectralBlur = defineSubgraph((config) => {
+    const { size, radius } = config, half = size / 2;
+    if (!Number.isInteger(radius) || radius < 1 || radius > Math.min(8, half - 1)) {
+        throw new RangeError('spectralBlur radius must be an integer in [1,min(8,size/2-1)]');
+    }
+    const framing = createStftIdentity(config, 256, spectrum => {
+        peak.write(0);
+        const storeMagnitude = (k) => {
+            const re = spectrum.real(k), im = select(k.eq(0).or(k.eq(half)), f64(0), spectrum.imag(k));
+            const magnitude = re.mul(re).add(im.mul(im)).sqrt();
+            magnitudes.write(k, magnitude);
+            peak.write(peak.read().max(magnitude));
+        };
+        spectralForEach(half, storeMagnitude);
+        storeMagnitude(i32(half));
+        const canonical = (index) => index.min(i32(size).sub(index));
+        const processBin = (k) => {
+            let blurred = f64(0);
+            for (let j = -radius; j <= radius; j++) {
+                const at = canonical(k.add(size + j).mod(size));
+                blurred = blurred.add(magnitudes.read(at).mul((radius + 1 - Math.abs(j)) / (radius + 1) ** 2));
+            }
+            const magnitude = magnitudes.read(k), mix = amount.read().div(scale);
+            const target = magnitude.mul(f64(1).sub(mix)).add(blurred.mul(mix));
+            const retained = magnitude.gt(0).and(magnitude.gte(peak.read().mul(phaseFloor)));
+            // select evaluates both branches: sanitize the divisor even for zero bins.
+            const denominator = select(magnitude.gt(0), magnitude, f64(1));
+            real.write(k, select(retained, spectrum.real(k).div(denominator), f64(1)).mul(target));
+            const imaginary = select(k.eq(0).or(k.eq(half)), f64(0), spectrum.imag(k));
+            imag.write(k, select(retained, imaginary.div(denominator), f64(0)).mul(target));
+        };
+        spectralForEach(half, processBin);
+        processBin(i32(half));
+        return {
+            real(k) {
+                const index = typeof k === 'number' ? i32(k) : k;
+                return select(amount.read().eq(0), spectrum.real(index), real.read(canonical(index)));
+            },
+            imag(k) {
+                const index = typeof k === 'number' ? i32(k) : k;
+                const value = imag.read(canonical(index));
+                return select(amount.read().eq(0), spectrum.imag(index), select(index.gt(half), value.neg(), value));
+            },
+        };
+    });
+    const amount = state.f64(0).expose({ name: 'amountScaled', snapshot: 'transient' });
+    const peak = state.f64(0).expose({ name: 'peakScaled', snapshot: 'transient' });
+    const magnitudes = state.buffer.f64({ size: half + 1 }).expose({ name: 'magnitudesScaled', snapshot: 'transient' });
+    const real = state.buffer.f64({ size: half + 1 }).expose({ name: 'blurRealScaled', snapshot: 'transient' });
+    const imag = state.buffer.f64({ size: half + 1 }).expose({ name: 'blurImagScaled', snapshot: 'transient' });
+    return {
+        tick(input, blend, reset, everyNSamples) {
+            amount.write(boundedAmount(blend));
+            return framing.tick(input, reset, everyNSamples);
+        },
+    };
+});
+// A private, separately named native STFT instance preserves all frame statements
+// and tap writes even though its synthesized audio output is unused by the caller.
+const magnitudeTap = defineSubgraph((config) => {
+    const { size } = config, half = size / 2;
+    const framing = createStftIdentity(config, 256, spectrum => {
+        const capture = (k) => {
+            const re = spectrum.real(k), im = select(k.eq(0).or(k.eq(half)), f64(0), spectrum.imag(k));
+            magnitudes.write(k, re.mul(re).add(im.mul(im)).sqrt());
+        };
+        spectralForEach(half, capture);
+        capture(i32(half));
+        return spectrum;
+    });
+    const magnitudes = state.buffer.f64({ size: half + 1 }).expose({ name: 'magnitudesScaled', snapshot: 'transient' });
+    return {
+        tick: framing.tick,
+        magnitude(k) { return magnitudes.read(k); },
+    };
+});
+/** Gain-bounded carrier-phase magnitude replacement. Offline CANDIDATE.
+ * Same call/framing/input/reset/amount/drain contract as spectralBlur.
+ * Amount=1 targets modulator magnitudes, capped at maxGain*carrier magnitude.
+ * Zero carrier stays silent; near-zero carrier gain is bounded by maxGain.
+ * Zero modulator at amount=1 suppresses all newly committed carrier bins.
+ * The modulator and carrier are analyzed synchronously; current input excluded.
+ * Full same-graph/config/rate native restore only; never restore half the pair.
+ * No speech-quality, transparent reconstruction, browser or realtime guarantee.
+ */
+export const spectralCrossSynthesis = defineSubgraph((config) => {
+    const { size, maxGain } = config, half = size / 2;
+    if (!Number.isFinite(maxGain) || maxGain < 1 || maxGain > 16) {
+        throw new RangeError('spectralCrossSynthesis maxGain must be finite in [1,16]');
+    }
+    const modulator = instantiate(magnitudeTap, config, { name: 'modulator' });
+    const framing = createStftIdentity(config, 256, spectrum => {
+        const calculateGain = (k) => {
+            const re = spectrum.real(k), im = select(k.eq(0).or(k.eq(half)), f64(0), spectrum.imag(k));
+            const magnitude = re.mul(re).add(im.mul(im)).sqrt();
+            const denominator = select(magnitude.gt(0), magnitude, f64(1));
+            const ratio = select(magnitude.gt(0), modulator.magnitude(k).div(denominator).min(maxGain), f64(0));
+            const mix = amount.read().div(scale);
+            gains.write(k, f64(1).sub(mix).add(mix.mul(ratio)).mul(scale));
+        };
+        spectralForEach(half, calculateGain);
+        calculateGain(i32(half));
+        const canonical = (index) => index.min(i32(size).sub(index));
+        return {
+            real(k) {
+                const index = typeof k === 'number' ? i32(k) : k, pair = canonical(index);
+                return select(amount.read().eq(0), spectrum.real(index), spectrum.real(pair).mul(gains.read(pair).div(scale)));
+            },
+            imag(k) {
+                const index = typeof k === 'number' ? i32(k) : k, pair = canonical(index);
+                const value = select(pair.eq(0).or(pair.eq(half)), f64(0), spectrum.imag(pair).mul(gains.read(pair).div(scale)));
+                return select(amount.read().eq(0), spectrum.imag(index), select(index.gt(half), value.neg(), value));
+            },
+        };
+    });
+    const amount = state.f64(0).expose({ name: 'amountScaled', snapshot: 'transient' });
+    const gains = state.buffer.f64({ size: half + 1 }).expose({ name: 'gainsScaled', snapshot: 'transient' });
+    return {
+        tick(carrier, inputModulator, blend, reset, everyNSamples) {
+            amount.write(boundedAmount(blend));
+            modulator.tick(inputModulator, reset, everyNSamples);
+            return framing.tick(carrier, reset, everyNSamples);
+        },
+    };
+});

package/dist/spectral.d.ts

@@ -0,0 +1,18 @@
+export interface StftIdentityConfig {
+    /** Pass ctx.renderQuantumSize; aligns native dispatch with snapshot boundaries. */
+    renderQuantumSize: number;
+    /** Construction-fixed power of two in [8,1024]. Latency is size samples. */
+    size: number;
+    /** Exactly size/2 or size/4. Rebuild to change. */
+    hopSize: number;
+}
+/** Graph-native FFT/IFFT identity candidate, periodic sqrt-Hann WOLA.
+ * Call exactly once inside stride-1 forSample, supplying its everyNSamples.
+ * Finite f32 input required. Reset silences immediately and discards that sample.
+ * Reset does not rephase frames. FFT dispatch divides hop, quantum and 128;
+ * the persistent cursor controls frame commits and snapshot phase.
+ * No realtime guarantee.
+ */
+export declare const stftIdentity: import("@unworklet/core").SubgraphDecl<[config: StftIdentityConfig], {
+    tick(input: import("@unworklet/core").Node<"f32">, reset: import("@unworklet/core").Node<"bool">, everyNSamples: import("@unworklet/core").EveryNSamples): import("@unworklet/core").Node<"f32">;
+}>;

package/dist/spectral.js

@@ -0,0 +1,10 @@
+import { defineSubgraph } from '@unworklet/core';
+import { createStftIdentity } from './spectral-stft.js';
+/** Graph-native FFT/IFFT identity candidate, periodic sqrt-Hann WOLA.
+ * Call exactly once inside stride-1 forSample, supplying its everyNSamples.
+ * Finite f32 input required. Reset silences immediately and discards that sample.
+ * Reset does not rephase frames. FFT dispatch divides hop, quantum and 128;
+ * the persistent cursor controls frame commits and snapshot phase.
+ * No realtime guarantee.
+ */
+export const stftIdentity = defineSubgraph((config) => createStftIdentity(config, 1024));

package/dist/state-variable-filter.d.ts

@@ -0,0 +1,17 @@
+import { type Node } from '@unworklet/core';
+export interface StateVariableFilterConfig {
+    sampleRate: number;
+}
+export interface StateVariableFilterOutput {
+    lowpass: Node<'f32'>;
+    /** Constant-peak bandpass: unity at center, independent of Q. */
+    bandpass: Node<'f32'>;
+    highpass: Node<'f32'>;
+    notch: Node<'f32'>;
+    allpass: Node<'f32'>;
+}
+/** Linear TPT SVF. One shared two-integrator history produces five responses. */
+export declare const stateVariableFilter: import("@unworklet/core").SubgraphDecl<[config: StateVariableFilterConfig], {
+    /** Exactly one tick/sample. Cutoff Hz and Q are clamped; reset clears history before this input. */
+    tick(input: Node<"f32">, cutoffHz: Node<"f32">, q: Node<"f32">, reset: Node<"bool">): StateVariableFilterOutput;
+}>;

package/dist/state-variable-filter.js

@@ -0,0 +1,25 @@
+import { defineSubgraph, f32, f64, select, state } from '@unworklet/core';
+import { checkedSampleRate, tangentHalfAngle } from './catalog-filter-math.js';
+/** Linear TPT SVF. One shared two-integrator history produces five responses. */
+export const stateVariableFilter = defineSubgraph((config) => {
+    const maximum = checkedSampleRate(config.sampleRate);
+    // Fixed scaling keeps f32 subnormal histories above the upstream <1e-30 state-write flush.
+    // Even full-scale f32 inputs remain far below f64 overflow after scaling.
+    const historyScale = 2 ** 128;
+    const band = state.f64(0).named('band'), low = state.f64(0).named('low');
+    return {
+        /** Exactly one tick/sample. Cutoff Hz and Q are clamped; reset clears history before this input. */
+        tick(input, cutoffHz, q, reset) {
+            const s1 = select(reset, f64(0), band.read().div(historyScale)), s2 = select(reset, f64(0), low.read().div(historyScale));
+            // This bounded coefficient is scratch storage only, overwritten before use.
+            band.write(tangentHalfAngle(cutoffHz, config.sampleRate, maximum));
+            const g = band.read(), k = f64(1).div(f64(q).clamp(.5, 10)), x = f64(input);
+            const v1 = s1.add(g.mul(x.sub(s2))).div(g.mul(g.add(k)).add(1));
+            const v2 = s2.add(g.mul(v1));
+            band.write(v1.mul(2).sub(s1).mul(historyScale));
+            low.write(v2.mul(2).sub(s2).mul(historyScale));
+            const normalizedBand = k.mul(v1);
+            return { lowpass: f32(v2), bandpass: f32(normalizedBand), highpass: f32(x.sub(normalizedBand).sub(v2)), notch: f32(x.sub(normalizedBand)), allpass: f32(x.sub(normalizedBand.mul(2))) };
+        },
+    };
+});