@denaudio/den 0.0.0-stage → 0.2.0

package/dist/drive.js

@@ -0,0 +1,116 @@
+import { defineSubgraph, f32, f64, floor, i32, or, pow, select, state } from '@unworklet/core';
+// Exact binary scaling preserves recoverable f32 subnormals through the upstream
+// state-write |x| < 1e-30 flush. Values and arithmetic remain bounded f64.
+const HISTORY_SCALE = 2 ** 100;
+function bounded(value, min, max, fallback) {
+    const x = f64(value);
+    return select(x.eq(x), x, f64(fallback)).clamp(min, max);
+}
+function checkRate(rate) {
+    if (!Number.isFinite(rate) || rate < 8000 || rate > 192000) {
+        throw new RangeError('drive/reduction sampleRate must be finite and in [8000, 192000] Hz');
+    }
+}
+function soft(x) {
+    const z = x.clamp(-1, 1);
+    return z.mul(f64(1.5).sub(z.mul(z).mul(0.5)));
+}
+function softIntegral(x) {
+    const a = x.abs(), z = a.min(1), z2 = z.mul(z);
+    return z2.mul(f64(0.75).sub(z2.mul(0.125))).add(a.sub(1).max(0));
+}
+function shape(x, curve) {
+    if (curve === 'hard')
+        return x.clamp(-1, 1);
+    if (curve === 'soft')
+        return soft(x);
+    if (curve === 'asymmetric')
+        return select(x.lt(0), soft(x.mul(2)).mul(0.5), soft(x));
+    const phase = x.add(1).sub(floor(x.add(1).div(4)).mul(4));
+    // Avoid subtracting nearly equal O(1) values in the linear central segment.
+    return select(x.abs().lte(1), x, f64(1).sub(phase.sub(2).abs()));
+}
+function integral(x, curve) {
+    if (curve === 'hard') {
+        const a = x.abs(), z = a.min(1);
+        return z.mul(z).mul(0.5).add(a.sub(1).max(0));
+    }
+    if (curve === 'soft')
+        return softIntegral(x);
+    if (curve === 'asymmetric')
+        return select(x.lt(0), softIntegral(x.mul(2)).mul(0.25), softIntegral(x));
+    const phase = x.add(1).sub(floor(x.add(1).div(4)).mul(4));
+    const periodic = select(phase.lte(2), phase.mul(phase).mul(0.5).sub(phase), phase.mul(3).sub(phase.mul(phase).mul(0.5)).sub(4)).add(0.5);
+    return select(x.abs().lte(1), x.mul(x).mul(0.5), periodic);
+}
+/** Fixed analytic memoryless waveshaper, optional first-order ADAA and DC block. */
+export const drive = defineSubgraph((config) => {
+    checkRate(config.sampleRate);
+    const { curve, quality = 'adaa', dcBlockHz = 0 } = config;
+    if (!['hard', 'soft', 'asymmetric', 'fold'].includes(curve))
+        throw new RangeError('unknown drive curve');
+    if (quality !== 'direct' && quality !== 'adaa')
+        throw new RangeError('unknown drive quality');
+    if (!Number.isFinite(dcBlockHz) || dcBlockHz < 0 || dcBlockHz > 200)
+        throw new RangeError('drive dcBlockHz must be in [0, 200] Hz');
+    const previous = quality === 'adaa' ? state.f64(0).named('previous-driven-scaled') : undefined;
+    const dryPrevious = quality === 'adaa' ? state.f64(0).named('previous-dry-scaled') : undefined;
+    const dcInput = dcBlockHz > 0 ? state.f64(0).named('dc-input-scaled') : undefined;
+    const dcOutput = dcBlockHz > 0 ? state.f64(0).named('dc-output-scaled') : undefined;
+    const pole = Math.exp(-2 * Math.PI * dcBlockHz / config.sampleRate);
+    return {
+        /** Once per sample. Input [-8,8], linear drive [0,32], wet mix [0,1]. */
+        tick(input, gain, mix, reset) {
+            const dry = bounded(input, -8, 8, 0), x = dry.mul(bounded(gain, 0, 32, 0));
+            const blend = bounded(mix, 0, 1, 0);
+            let wet, alignedDry;
+            if (previous && dryPrevious) {
+                const last = select(reset, f64(0), previous.read().div(HISTORY_SCALE));
+                const lastDry = select(reset, f64(0), dryPrevious.read().div(HISTORY_SCALE));
+                const difference = x.sub(last);
+                const close = difference.abs().lte(1e-5);
+                // Both select branches execute. Protect the unused quotient as well.
+                // A continuous curve with max slope 1.5 has midpoint error <= 3.75e-6
+                // on this interval; smooth cubic interiors have O(difference²) error.
+                wet = select(close, shape(x.add(last).mul(0.5), curve), integral(x, curve).sub(integral(last, curve)).div(select(close, f64(1), difference)));
+                alignedDry = dry.add(lastDry).mul(0.5);
+                previous.write(x.mul(HISTORY_SCALE));
+                dryPrevious.write(dry.mul(HISTORY_SCALE));
+            }
+            else {
+                wet = shape(x, curve);
+                alignedDry = dry;
+            }
+            if (dcInput && dcOutput) {
+                const lastInput = select(reset, f64(0), dcInput.read().div(HISTORY_SCALE));
+                const lastOutput = select(reset, f64(0), dcOutput.read().div(HISTORY_SCALE));
+                const blocked = wet.sub(lastInput).add(lastOutput.mul(pole));
+                dcInput.write(wet.mul(HISTORY_SCALE));
+                dcOutput.write(blocked.mul(HISTORY_SCALE));
+                wet = blocked;
+            }
+            return f32(alignedDry.mul(f64(1).sub(blend)).add(wet.mul(blend)));
+        },
+    };
+});
+/** Signed-PCM quantizer plus sample hold. Aliasing is intentional; no AA claim. */
+export const reduction = defineSubgraph((config) => {
+    checkRate(config.sampleRate);
+    const held = state.f64(0).named('held-scaled');
+    const remaining = state.i32(0).named('remaining');
+    return {
+        /** Bits [2,24], hold period [1,4096] samples, both floored at capture. */
+        tick(input, bits, holdSamples, mix, reset) {
+            const x = bounded(input, -1, 1, 0), blend = bounded(mix, 0, 1, 0);
+            const count = select(reset, i32(0), remaining.read());
+            const capture = or(reset, count.eq(0));
+            const steps = pow(f64(2), floor(bounded(bits, 2, 24, 24)).sub(1));
+            // Exactly 2^bits signed levels: [-1, 1 - 1/steps]. Ties round upward.
+            const quantized = floor(x.mul(steps).add(0.5)).clamp(steps.neg(), steps.sub(1)).div(steps);
+            const wet = select(capture, quantized, held.read().div(HISTORY_SCALE));
+            held.write(wet.mul(HISTORY_SCALE));
+            remaining.write(select(capture, i32(floor(bounded(holdSamples, 1, 4096, 1))).sub(1), count.sub(1)));
+            return f32(x.mul(f64(1).sub(blend)).add(wet.mul(blend)));
+        },
+    };
+});

package/dist/dual-head-delay.d.ts

@@ -0,0 +1,28 @@
+import { type Node } from '@unworklet/core';
+export interface DualHeadDelayConfig {
+    /** Match the enclosing processor's ctx.sampleRate; integer 8000..192000. */
+    sampleRate: number;
+    /** Fixed history allocation, one sample..8 seconds; default 2. */
+    maxDelaySeconds?: number;
+    /** Fixed fade length, integer 2..65536; default 256. Includes both endpoints. */
+    transitionSamples?: number;
+}
+/** Mono fixed-two-head delay-time crossfade. Once/sample, use tick or one read
+ * followed by that read's write. Finite f32 input required. Latest valid requests
+ * coalesce until the current fade completes; active read offsets never move.
+ * No implicit feedback, mix, bypass, pitch-shifting or time-stretching policy.
+ */
+export declare const dualHeadDelay: import("@unworklet/core").SubgraphDecl<[config: DualHeadDelayConfig], {
+    read: (timeSeconds: Node<"f32">, reset: Node<"bool">) => {
+        output: Node<"f32">;
+        timingRejected: Node<"bool">;
+        transitioning: Node<"bool">;
+        /** Call exactly once, after consuming output for current-sample feedback. */
+        write(input: Node<"f32">): void;
+    };
+    tick(input: Node<"f32">, timeSeconds: Node<"f32">, reset: Node<"bool">): {
+        output: Node<"f32">;
+        timingRejected: Node<"bool">;
+        transitioning: Node<"bool">;
+    };
+}>;

package/dist/dual-head-delay.js

@@ -0,0 +1,77 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+const HISTORY_SCALE = 2 ** 128;
+/** Mono fixed-two-head delay-time crossfade. Once/sample, use tick or one read
+ * followed by that read's write. Finite f32 input required. Latest valid requests
+ * coalesce until the current fade completes; active read offsets never move.
+ * No implicit feedback, mix, bypass, pitch-shifting or time-stretching policy.
+ */
+export const dualHeadDelay = defineSubgraph((config) => {
+    const { sampleRate, maxDelaySeconds = 2, transitionSamples = 256 } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000 ||
+        !Number.isFinite(maxDelaySeconds) || maxDelaySeconds < 1 / sampleRate || maxDelaySeconds > 8 ||
+        !Number.isInteger(transitionSamples) || transitionSamples < 2 || transitionSamples > 65536) {
+        throw new RangeError('dualHeadDelay requires integer sampleRate [8000,192000], capacity [one sample,8 seconds], and integer transitionSamples [2,65536]');
+    }
+    // The direct reciprocal capacity check above rejects genuinely sub-sample
+    // configurations; this floor only repairs multiplication at that exact bound.
+    const maximum = Math.max(1, sampleRate * maxDelaySeconds), size = Math.ceil(maximum) + 2;
+    const history = state.buffer.f64({ size }).expose({ name: 'historyScaled', snapshot: 'persistent' });
+    const cursor = state.i32(0).named('cursor'), valid = state.i32(0).named('valid');
+    const initialized = state.i32(0).named('initialized');
+    const current = state.f64(1).named('currentDelaySamples');
+    const target = state.f64(1).named('targetDelaySamples');
+    const queued = state.f64(1).named('queuedDelaySamples');
+    const remaining = state.i32(0).named('remaining');
+    // Materialize the read result before the write commits a completed fade.
+    const wet = state.f64(0).expose({ name: 'wetScaled', snapshot: 'transient' });
+    const active = state.i32(0).expose({ name: 'active', snapshot: 'transient' });
+    function read(timeSeconds, reset) {
+        const fresh = reset.or(initialized.read().eq(0));
+        const accepted = timeSeconds.gte(Math.fround(1 / sampleRate)).and(timeSeconds.lte(Math.fround(maxDelaySeconds)));
+        // Accept nominal representable endpoints but never read outside physical
+        // capacity. Adjacent out-of-range f32 controls are rejected without epsilon.
+        const request = f64(timeSeconds).mul(sampleRate).clamp(1, maximum);
+        queued.write(select(accepted, request, select(fresh, f64(1), queued.read())));
+        current.write(select(fresh, queued.read(), current.read()));
+        const start = remaining.read().eq(0).and(queued.read().eq(current.read()).not());
+        target.write(select(fresh.or(start), queued.read(), target.read()));
+        remaining.write(select(fresh, i32(0), select(start, i32(transitionSamples), remaining.read())));
+        active.write(i32(remaining.read().gt(0)));
+        const writeIndex = select(reset, i32(0), cursor.read());
+        const available = select(reset, i32(0), valid.read());
+        const at = (delay) => {
+            const whole = i32(delay.floor()), fraction = delay.sub(f64(whole));
+            const relative = writeIndex.sub(whole), recentIndex = select(relative.lt(0), relative.add(size), relative);
+            const olderIndex = select(recentIndex.eq(0), i32(size - 1), recentIndex.sub(1));
+            const recent = select(available.gte(whole), history.read(recentIndex), f64(0));
+            const older = select(available.gt(whole), history.read(olderIndex), f64(0));
+            return recent.mul(f64(1).sub(fraction)).add(older.mul(fraction));
+        };
+        const alpha = select(active.read().gt(0), f64(i32(transitionSamples).sub(remaining.read())).div(transitionSamples - 1), f64(0));
+        wet.write(at(current.read()).mul(f64(1).sub(alpha)).add(at(target.read()).mul(alpha)));
+        return {
+            output: f32(wet.read().div(HISTORY_SCALE)),
+            timingRejected: accepted.not(),
+            transitioning: active.read().gt(0),
+            /** Call exactly once, after consuming output for current-sample feedback. */
+            write(input) {
+                // Exact binary scaling keeps every finite f32 (including subnormals)
+                // above native tiny-buffer scrubbing and far below f64 overflow.
+                history.write(writeIndex, f64(input).mul(HISTORY_SCALE));
+                cursor.write(writeIndex.add(1).mod(size));
+                valid.write(available.add(1).min(size));
+                current.write(select(remaining.read().eq(1), target.read(), current.read()));
+                remaining.write(remaining.read().sub(1).max(0));
+                initialized.write(1);
+            },
+        };
+    }
+    return {
+        read,
+        tick(input, timeSeconds, reset) {
+            const tap = read(timeSeconds, reset);
+            tap.write(input);
+            return { output: tap.output, timingRejected: tap.timingRejected, transitioning: tap.transitioning };
+        },
+    };
+});

package/dist/dynamics.d.ts

@@ -0,0 +1,61 @@
+import { type Node } from '@unworklet/core';
+export type DetectorMode = 'peak' | 'rms';
+export interface EnvelopeFollowerConfig {
+    sampleRate: number;
+    mode: DetectorMode;
+}
+export interface EnvelopeFollowerControls {
+    /** Seconds: zero is immediate; positive values use at least one sample, at most 30 s. */
+    attack: Node<'f32'>;
+    release: Node<'f32'>;
+    reset: Node<'bool'>;
+}
+export interface DynamicsGainControls {
+    /** dBFS, clamped to [-120, 24]. */
+    thresholdDb: Node<'f32'>;
+    /** Input/output slope ratio, clamped to [1, 100]. */
+    ratio: Node<'f32'>;
+    /** Full knee width in dB, clamped to [0, 48]. Zero is a hard knee. */
+    kneeDb: Node<'f32'>;
+    /** Maximum attenuation in dB, clamped to [0, 120]. */
+    rangeDb: Node<'f32'>;
+}
+export type DynamicsMode = 'compressor' | 'expander' | 'gate' | 'duck';
+export interface DynamicsConfig extends EnvelopeFollowerConfig {
+    /** Feedforward, linked stereo, no lookahead. */
+    operation: DynamicsMode;
+    /** Gate/duck close below threshold minus this amount; fixed at construction. */
+    hysteresisDb?: number;
+}
+export interface DynamicsControls extends DynamicsGainControls {
+    detectorAttack: Node<'f32'>;
+    detectorRelease: Node<'f32'>;
+    /** Gain ballistics in seconds, separate from detector ballistics. */
+    attack: Node<'f32'>;
+    release: Node<'f32'>;
+    reset: Node<'bool'>;
+}
+/** Rectified-amplitude peak or exponentially averaged power RMS follower. */
+export declare const envelopeFollower: import("@unworklet/core").SubgraphDecl<[config: EnvelopeFollowerConfig], {
+    /** Once per sample. Reset clears history before processing the current input. */
+    tick(input: Node<"f32">, controls: EnvelopeFollowerControls): Node<"f32">;
+}>;
+/** Feedforward downward-compression static gain in dB (never positive). */
+export declare function compressorGainDb(levelDb: Node<'f32'>, controls: DynamicsGainControls): Node<"f32">;
+/** Downward-expansion static gain in dB; ratio is the below-threshold slope. */
+export declare function expanderGainDb(levelDb: Node<'f32'>, controls: DynamicsGainControls): Node<"f32">;
+/**
+ * Single-band feedforward dynamics with max-absolute stereo sidechain linking.
+ * Pass the program L/R as sidechain L/R for internal detection, or supply a key.
+ * Gate/duck are hysteretic keyed switches with smoothed attenuation; ratio and
+ * knee affect only compressor/expander. There is no makeup gain or limiter.
+ */
+export declare const dynamics: import("@unworklet/core").SubgraphDecl<[config: DynamicsConfig], {
+    tick(left: Node<"f32">, right: Node<"f32">, sidechainLeft: Node<"f32">, sidechainRight: Node<"f32">, controls: DynamicsControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+        envelope: Node<"f32">;
+        gain: Node<"f32">;
+        gainDb: Node<"f32">;
+    };
+}>;

package/dist/dynamics.js

@@ -0,0 +1,130 @@
+import { defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+function validate(config) {
+    if (!Number.isInteger(config.sampleRate) || config.sampleRate < 8000 || config.sampleRate > 192000) {
+        throw new RangeError('dynamics sampleRate must be an integer in [8000, 192000] Hz');
+    }
+    if (config.mode !== 'peak' && config.mode !== 'rms')
+        throw new RangeError('dynamics mode must be peak or rms');
+}
+// Reject only nonfinite values. Valid f32 audio, including subnormals and values
+// beyond full scale, is neither clipped nor silently replaced by zero.
+function finite(input, fallback = 0) {
+    return select(input.eq(input).and(input.abs().lte(3.4028234663852886e38)), input, f32(fallback));
+}
+function bounded(input, low, high, fallback) {
+    return finite(input, fallback).clamp(low, high);
+}
+// 0.4.1 scalar state writes flush magnitudes below 1e-30. Keeping the
+// nonnegative history scaled preserves even squared f32 subnormal amplitudes.
+// The exact power-of-two scale avoids rounding during scale/unscale; the
+// largest scaled f32 power is <2**512, safely inside binary64 range.
+const HISTORY_SCALE = 2 ** 256;
+function smoother(sampleRate, name) {
+    const history = state.f64(0).named(`${name}Scaled`);
+    const exponent = state.f64(0).named(`${name}Exponent`);
+    return (target, rise, fall, reset) => {
+        const previous = select(reset, f64(0), history.read().div(HISTORY_SCALE));
+        const seconds = select(target.gt(previous), bounded(rise, 0, 30, 0), bounded(fall, 0, 30, 0));
+        exponent.write(f64(1).div(f64(seconds).mul(sampleRate).max(1)));
+        const x = exponent.read();
+        // 1-exp(-x), 0 < x <= 1. Degree 13, absolute remainder <=1/14!.
+        // Unlike 1-f32(exp(-x)), it retains accurate long time constants.
+        const polynomial = f64(1 / 6227020800).mul(x).sub(1 / 479001600)
+            .mul(x).add(1 / 39916800).mul(x).sub(1 / 3628800)
+            .mul(x).add(1 / 362880).mul(x).sub(1 / 40320)
+            .mul(x).add(1 / 5040).mul(x).sub(1 / 720)
+            .mul(x).add(1 / 120).mul(x).sub(1 / 24)
+            .mul(x).add(1 / 6).mul(x).sub(1 / 2).mul(x).add(1);
+        const coefficient = select(seconds.eq(0), f64(1), x.mul(polynomial));
+        const next = previous.mul(f64(1).sub(coefficient)).add(target.mul(coefficient));
+        history.write(next.mul(HISTORY_SCALE));
+        return history.read().div(HISTORY_SCALE);
+    };
+}
+/** Rectified-amplitude peak or exponentially averaged power RMS follower. */
+export const envelopeFollower = defineSubgraph((config) => {
+    validate(config);
+    const smooth = smoother(config.sampleRate, 'detector');
+    return {
+        /** Once per sample. Reset clears history before processing the current input. */
+        tick(input, controls) {
+            const amplitude = f64(finite(input)).abs();
+            const target = config.mode === 'rms' ? amplitude.mul(amplitude) : amplitude;
+            const level = smooth(target, controls.attack, controls.release, controls.reset);
+            return f32(config.mode === 'rms' ? level.max(0).sqrt() : level);
+        },
+    };
+});
+/** Feedforward downward-compression static gain in dB (never positive). */
+export function compressorGainDb(levelDb, controls) {
+    const delta = f64(bounded(levelDb, -900, 900, -900)).sub(f64(bounded(controls.thresholdDb, -120, 24, 0)));
+    const width = f64(bounded(controls.kneeDb, 0, 48, 0));
+    const slope = f64(1).sub(f64(1).div(f64(bounded(controls.ratio, 1, 100, 1))));
+    const curved = delta.add(width.mul(0.5)).max(0);
+    const reduction = select(delta.gte(width.mul(0.5)), delta.max(0).mul(slope), curved.mul(curved).mul(slope).div(select(width.gt(0), width, f64(1)).mul(2)));
+    return f32(reduction.min(f64(bounded(controls.rangeDb, 0, 120, 120))).neg());
+}
+/** Downward-expansion static gain in dB; ratio is the below-threshold slope. */
+export function expanderGainDb(levelDb, controls) {
+    const below = f64(bounded(controls.thresholdDb, -120, 24, 0)).sub(f64(bounded(levelDb, -900, 900, -900)));
+    const width = f64(bounded(controls.kneeDb, 0, 48, 0));
+    const slope = f64(bounded(controls.ratio, 1, 100, 1)).sub(1);
+    const curved = below.add(width.mul(0.5)).max(0);
+    const reduction = select(below.gte(width.mul(0.5)), below.max(0).mul(slope), curved.mul(curved).mul(slope).div(select(width.gt(0), width, f64(1)).mul(2)));
+    return f32(reduction.min(f64(bounded(controls.rangeDb, 0, 120, 120))).neg());
+}
+/**
+ * Single-band feedforward dynamics with max-absolute stereo sidechain linking.
+ * Pass the program L/R as sidechain L/R for internal detection, or supply a key.
+ * Gate/duck are hysteretic keyed switches with smoothed attenuation; ratio and
+ * knee affect only compressor/expander. There is no makeup gain or limiter.
+ */
+export const dynamics = defineSubgraph((config) => {
+    validate(config);
+    if (!['compressor', 'expander', 'gate', 'duck'].includes(config.operation))
+        throw new RangeError('invalid dynamics operation');
+    const hysteresis = config.hysteresisDb ?? 3;
+    if (!Number.isFinite(hysteresis) || hysteresis < 0 || hysteresis > 24)
+        throw new RangeError('dynamics hysteresisDb must be in [0, 24]');
+    const detector = instantiate(envelopeFollower, { sampleRate: config.sampleRate, mode: config.mode }, { name: 'sidechain' });
+    const active = state.i32(0).named('keyActive');
+    const levelDb = state.f64(0).named('levelDb');
+    const gain = state.f64(1).named('gain');
+    const smooth = smoother(config.sampleRate, 'attenuation');
+    return {
+        tick(left, right, sidechainLeft, sidechainRight, controls) {
+            const key = finite(sidechainLeft).abs().max(finite(sidechainRight).abs());
+            const envelope = detector.tick(key, { attack: controls.detectorAttack, release: controls.detectorRelease, reset: controls.reset });
+            // Floor applies only to the gain-law meter, never the follower or audio.
+            // 1e-30 gives -600 dB; all thresholds are >=-120 dB.
+            levelDb.write(f64(envelope.max(1e-30).log()).mul(20 / Math.LN10));
+            const level = f32(levelDb.read());
+            let target;
+            if (config.operation === 'compressor')
+                target = f64(compressorGainDb(level, controls)).neg();
+            else if (config.operation === 'expander')
+                target = f64(expanderGainDb(level, controls)).neg();
+            else {
+                const threshold = bounded(controls.thresholdDb, -120, 24, 0);
+                const wasActive = active.read().gt(0).and(controls.reset.not());
+                const isActive = level.gte(threshold).or(wasActive.and(level.gt(threshold.sub(hysteresis))));
+                active.write(select(isActive, i32(1), i32(0)));
+                const attenuate = config.operation === 'duck' ? isActive : isActive.not();
+                target = f64(select(attenuate, bounded(controls.rangeDb, 0, 120, 120), f32(0)));
+            }
+            // Gate/expander attack opens the gain, release closes it. Compressor/duck
+            // attack increases attenuation, release returns towards unity.
+            const opens = config.operation === 'gate' || config.operation === 'expander';
+            const reduction = smooth(target, opens ? controls.release : controls.attack, opens ? controls.attack : controls.release, controls.reset);
+            gain.write(f64(f32(reduction.neg().mul(Math.LN10 / 20)).exp()).clamp(0, 1));
+            const linear = gain.read();
+            return {
+                left: f32(f64(finite(left)).mul(linear)),
+                right: f32(f64(finite(right)).mul(linear)),
+                envelope,
+                gain: f32(linear),
+                gainDb: f32(reduction.neg()),
+            };
+        },
+    };
+});

package/dist/envelope.d.ts

@@ -0,0 +1,34 @@
+import { type Node } from '@unworklet/core';
+export interface EnvelopeConfig {
+    sampleRate: number;
+}
+export interface EnvelopeControls {
+    gate: Node<'bool'>;
+    /** One-sample pulse; ignored when gate is false. */
+    retrigger: Node<'bool'>;
+    /** Reset wins over all other controls and consumes the current gate level. */
+    reset: Node<'bool'>;
+    attack: Node<'f32'>;
+    decay: Node<'f32'>;
+    sustain: Node<'f32'>;
+    release: Node<'f32'>;
+}
+/**
+ * Linear ADSR, one instance per voice/use. Call tick exactly once per sample.
+ * Seconds are clamped to [0,30] and rounded to the nearest sample. Durations and
+ * segment targets latch on entry (decay at the preceding attack endpoint);
+ * sustain follows its input in the sustain stage.
+ * A segment emits its first step on the trigger sample, reaching its endpoint on
+ * step N. Zero/sub-half-sample stages collapse immediately, including A+D=0.
+ * Retrigger and note-off start from the previously emitted level. Gate-off wins
+ * over retrigger. Reset silences immediately; a held gate needs a new edge/pulse.
+ * done is true only in idle (initial/reset) or after release reaches zero; sustain
+ * at zero does not end a voice. No asymptotic tail or threshold-based termination.
+ * Controls must be finite. Parameter smoothing/automation belongs to unworklet.
+ */
+export declare const envelope: import("@unworklet/core").SubgraphDecl<[config: EnvelopeConfig], {
+    tick(c: EnvelopeControls): {
+        level: Node<"f32">;
+        done: Node<"bool">;
+    };
+}>;

package/dist/envelope.js

@@ -0,0 +1,62 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+/**
+ * Linear ADSR, one instance per voice/use. Call tick exactly once per sample.
+ * Seconds are clamped to [0,30] and rounded to the nearest sample. Durations and
+ * segment targets latch on entry (decay at the preceding attack endpoint);
+ * sustain follows its input in the sustain stage.
+ * A segment emits its first step on the trigger sample, reaching its endpoint on
+ * step N. Zero/sub-half-sample stages collapse immediately, including A+D=0.
+ * Retrigger and note-off start from the previously emitted level. Gate-off wins
+ * over retrigger. Reset silences immediately; a held gate needs a new edge/pulse.
+ * done is true only in idle (initial/reset) or after release reaches zero; sustain
+ * at zero does not end a voice. No asymptotic tail or threshold-based termination.
+ * Controls must be finite. Parameter smoothing/automation belongs to unworklet.
+ */
+export const envelope = defineSubgraph((config) => {
+    if (!Number.isInteger(config.sampleRate) || config.sampleRate < 1 || config.sampleRate * 30 > 2147483646) {
+        throw new RangeError('envelope sampleRate must be a positive integer with 30 seconds fitting i32 frames');
+    }
+    const stage = state.i32(0).named('stage'); // idle, attack, decay, sustain, release
+    const level = state.f64(0).named('level');
+    const previousGate = state.bool(false).named('previousGate');
+    const remaining = state.i32(0).named('remaining');
+    const target = state.f64(0).named('target');
+    const frames = (seconds) => i32(f64(seconds.clamp(0, 30)).mul(config.sampleRate).add(0.5).floor());
+    return {
+        tick(c) {
+            // Capture old integer history before using its slots as exact temporaries.
+            const oldStage = stage.read();
+            const oldRemaining = remaining.read();
+            const on = c.gate.and(previousGate.read().not().or(c.retrigger));
+            const off = c.gate.not().and(previousGate.read()).and(oldStage.eq(0).not());
+            const a = frames(c.attack), d = frames(c.decay), r = frames(c.release);
+            const s = f64(c.sustain.clamp(0, 1));
+            stage.write(select(off, i32(4), select(on, i32(1), oldStage)));
+            const active = stage.read();
+            const attack = active.eq(1);
+            const attackFrames = select(on, a, oldRemaining);
+            // Collapse zero attack into decay at this sample; a positive attack ends
+            // at 1 and begins decay on the following sample.
+            const decay = active.eq(2).or(attack.and(attackFrames.eq(0)));
+            const enterDecay = decay.and(oldStage.eq(2).not().or(on));
+            const release = active.eq(4);
+            remaining.write(select(release, select(off, r, oldRemaining), select(decay, select(enterDecay, d, oldRemaining), attackFrames)));
+            const count = remaining.read();
+            const destination = select(release, f64(0), select(decay, select(enterDecay, s, target.read()), f64(1)));
+            const start = select(attack.and(attackFrames.eq(0)), f64(1), level.read());
+            const moving = attack.or(decay).or(release);
+            const last = count.lte(1).or(release.and(start.eq(0)));
+            const advanced = select(last, destination, start.add(destination.sub(start).div(f64(count.max(1)))));
+            const value = select(c.reset, f64(0), select(moving, advanced, select(active.eq(3), s, f64(0)))).clamp(0, 1);
+            const nextStage = select(c.reset, i32(0), select(moving.and(last), select(release, i32(0), select(decay, i32(3), i32(2))), select(decay, i32(2), active)));
+            // On a positive attack endpoint, prepare the decay without advancing it.
+            const prepareDecay = attack.and(decay.not()).and(last);
+            remaining.write(select(c.reset, i32(0), select(prepareDecay, d, count.sub(1).max(0))));
+            target.write(select(c.reset, f64(0), select(prepareDecay, s, destination)));
+            level.write(value);
+            stage.write(nextStage);
+            previousGate.write(c.gate);
+            return { level: f32(value), done: nextStage.eq(0) };
+        },
+    };
+});

package/dist/filter.d.ts

@@ -0,0 +1,9 @@
+import { type Node } from '@unworklet/core';
+export interface FilterConfig {
+    sampleRate: number;
+}
+/** Trapezoidal state-variable low-pass. See docs/filter-oscillator.md. */
+export declare const filter: import("@unworklet/core").SubgraphDecl<[config: FilterConfig], {
+    /** Call exactly once per sample. Reset clears history before processing this input. */
+    tick(input: Node<"f32">, cutoff: Node<"f32">, resonance: Node<"f32">, reset: Node<"bool">): Node<"f32">;
+}>;

package/dist/filter.js

@@ -0,0 +1,34 @@
+import { defineSubgraph, f32, f64, select, state } from '@unworklet/core';
+/** Trapezoidal state-variable low-pass. See docs/filter-oscillator.md. */
+export const filter = defineSubgraph((config) => {
+    if (!Number.isFinite(config.sampleRate) || config.sampleRate < 8000 || config.sampleRate > 192000) {
+        throw new RangeError('filter sampleRate must be finite and in [8000, 192000] Hz');
+    }
+    const maximum = Math.min(20000, 0.45 * config.sampleRate);
+    const band = state.f64(0).named('band');
+    const low = state.f64(0).named('low');
+    return {
+        /** Call exactly once per sample. Reset clears history before processing this input. */
+        tick(input, cutoff, resonance, reset) {
+            // read() captures a WASM local in 0.4.1: preserve both histories before
+            // staging g in band. The final writes below retain the original histories.
+            const s1 = select(reset, f64(0), band.read());
+            const s2 = select(reset, f64(0), low.read());
+            // Bounded-angle Taylor coefficients avoid the f32 transcendental lowering in 0.4.1.
+            const angle = f64(cutoff).clamp(20, maximum).mul(Math.PI / config.sampleRate);
+            const z = angle.mul(angle);
+            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);
+            // Materialize only this bounded coefficient (g > 3e-4 over the configured range).
+            // No new snapshot slot, and no extra <1e-30 flush of audio intermediates.
+            band.write(sine.div(cosine));
+            const g = band.read();
+            const k = f64(1).div(f64(resonance).clamp(0.5, 10));
+            const v1 = s1.add(g.mul(f64(input).sub(s2))).div(g.mul(g.add(k)).add(1));
+            const v2 = s2.add(g.mul(v1));
+            band.write(v1.mul(2).sub(s1));
+            low.write(v2.mul(2).sub(s2));
+            return f32(v2);
+        },
+    };
+});

package/dist/filterbank-vocoder.d.ts

@@ -0,0 +1,35 @@
+import { type Node } from '@unworklet/core';
+export interface FilterBankVocoderBand {
+    /** Fixed center in [20, min(20000, .45 * sampleRate)] Hz. */
+    frequencyHz: number;
+    /** Fixed Q in [.5, 10]; each analysis/synthesis bandpass has unity peak. */
+    q: number;
+    /** Explicit linear synthesis gain in [0, 4], with no band-count normalization. */
+    gain: number;
+}
+export interface FilterBankVocoderConfig {
+    /** Integer in [8000, 192000] Hz; must match the processing sample rate. */
+    sampleRate: number;
+    /** 1–8 fixed bands with strictly increasing centers; sparse arrays are invalid. */
+    bands: readonly FilterBankVocoderBand[];
+}
+export interface FilterBankVocoderControls {
+    /** Envelope time constants in seconds: zero immediate, positive at least one sample, maximum 30 s. */
+    attack: Node<'f32'>;
+    release: Node<'f32'>;
+    /** Clears both banks and every detector before processing this sample. */
+    reset: Node<'bool'>;
+}
+export interface FilterBankVocoderOutput {
+    output: Node<'f32'>;
+    /** Uncalibrated rectified-amplitude envelopes in configuration order. */
+    envelopes: readonly Node<'f32'>[];
+}
+/**
+ * Mono fixed filter-bank vocoder: sum(gain * carrier bandpass * modulator envelope).
+ * No carrier source, dry mix, limiter, automatic normalization, or speech-quality promise.
+ */
+export declare const filterBankVocoder: import("@unworklet/core").SubgraphDecl<[config: FilterBankVocoderConfig], {
+    /** Exactly once per sample. NaN/±Infinity audio becomes zero; finite audio is not clipped. */
+    tick(modulator: Node<"f32">, carrier: Node<"f32">, controls: FilterBankVocoderControls): FilterBankVocoderOutput;
+}>;

package/dist/filterbank-vocoder.js

@@ -0,0 +1,52 @@
+import { defineSubgraph, f32, f64, instantiate, select } from '@unworklet/core';
+import { stateVariableFilter } from './state-variable-filter.js';
+import { envelopeFollower } from './dynamics.js';
+import { checkedSampleRate } from './catalog-filter-math.js';
+function finiteAudio(input) {
+    return select(input.eq(input).and(input.abs().lte(3.4028234663852886e38)), input, f32(0));
+}
+/**
+ * Mono fixed filter-bank vocoder: sum(gain * carrier bandpass * modulator envelope).
+ * No carrier source, dry mix, limiter, automatic normalization, or speech-quality promise.
+ */
+export const filterBankVocoder = defineSubgraph((config) => {
+    const maximum = checkedSampleRate(config.sampleRate);
+    if (!Number.isInteger(config.sampleRate))
+        throw new RangeError('vocoder sampleRate must be an integer');
+    if (!Array.isArray(config.bands) || config.bands.length < 1 || config.bands.length > 8) {
+        throw new RangeError('vocoder requires 1–8 fixed, densely specified bands');
+    }
+    let previous = 0;
+    // Validate every index before creating any state; Array#map alone skips holes.
+    for (const band of config.bands) {
+        if (band === null || typeof band !== 'object' ||
+            !Number.isFinite(band.frequencyHz) || band.frequencyHz < 20 || band.frequencyHz > maximum || band.frequencyHz <= previous ||
+            !Number.isFinite(band.q) || band.q < .5 || band.q > 10 ||
+            !Number.isFinite(band.gain) || band.gain < 0 || band.gain > 4) {
+            throw new RangeError('vocoder bands require increasing bounded frequencyHz, Q, and gain');
+        }
+        previous = band.frequencyHz;
+    }
+    const bands = config.bands.map((band, index) => ({
+        frequency: f32(band.frequencyHz), q: f32(band.q), gain: band.gain,
+        analysis: instantiate(stateVariableFilter, { sampleRate: config.sampleRate }, { name: `analysis${index}` }),
+        synthesis: instantiate(stateVariableFilter, { sampleRate: config.sampleRate }, { name: `synthesis${index}` }),
+        detector: instantiate(envelopeFollower, { sampleRate: config.sampleRate, mode: 'peak' }, { name: `envelope${index}` }),
+    }));
+    return {
+        /** Exactly once per sample. NaN/±Infinity audio becomes zero; finite audio is not clipped. */
+        tick(modulator, carrier, controls) {
+            const analysisInput = finiteAudio(modulator), synthesisInput = finiteAudio(carrier);
+            const envelopes = [];
+            let sum = f64(0);
+            for (const band of bands) {
+                const analysis = band.analysis.tick(analysisInput, band.frequency, band.q, controls.reset).bandpass;
+                const synthesis = band.synthesis.tick(synthesisInput, band.frequency, band.q, controls.reset).bandpass;
+                const envelope = band.detector.tick(analysis, controls);
+                envelopes.push(envelope);
+                sum = sum.add(f64(synthesis).mul(f64(envelope)).mul(band.gain));
+            }
+            return { output: f32(sum), envelopes };
+        },
+    };
+});