@denaudio/den 0.0.0-stage → 0.1.0

package/dist/modulation.d.ts

@@ -0,0 +1,132 @@
+import { type MidiOutputHandle, type Node } from '@unworklet/core';
+export type ClockMode = 'free' | 'tempo';
+export interface MusicalClockConfig {
+    sampleRate: number;
+    mode: ClockMode;
+    /** Fixed cycle length, 1..64 steps. */
+    steps: number;
+    /** Tempo mode only: power of two in [1/64,64], default 1. */
+    stepsPerBeat?: number;
+}
+export interface MusicalClockControls {
+    /** Free mode: steps/second. Tempo mode: BPM. Clamped to [0,1000]. */
+    rate: Node<'f32'>;
+    /** Hold at step/phase zero with no tick. First reset-low sample ticks. */
+    reset: Node<'bool'>;
+    /** Rising edge seeks; held high does not pin or retrigger. Reset consumes it. */
+    seek: Node<'bool'>;
+    /** Steps, clamped to +/-1048576 then wrapped into the fixed cycle. */
+    position: Node<'f32'>;
+}
+export interface MusicalClockOutput {
+    step: Node<'f32'>;
+    /** Fraction of the current step, in [0,1). */
+    phase: Node<'f32'>;
+    /** Initial sample, reset release, seek edge, or a step boundary. */
+    tick: Node<'bool'>;
+}
+export interface SequenceStep {
+    value: number;
+    gate: number;
+}
+export interface StepSequenceConfig extends Omit<MusicalClockConfig, 'steps'> {
+    /** Fixed 1..64 steps; values [-1,1], gate fractions [0,1]. */
+    steps: readonly SequenceStep[];
+}
+export interface StepSequenceOutput extends MusicalClockOutput {
+    value: Node<'f32'>;
+    gate: Node<'bool'>;
+}
+export type MsegCurve = 'linear' | 'easeIn' | 'easeOut' | 'smoothstep';
+export interface MsegSegment {
+    seconds: number;
+    target: number;
+    curve: MsegCurve;
+}
+export interface MsegConfig {
+    sampleRate: number;
+    initial: number;
+    /** Fixed 1..16 segments; durations [0,30] s, targets [-1,1]. */
+    segments: readonly MsegSegment[];
+    /** Whole envelope repeats; the final target need not match initial. */
+    loop?: boolean;
+}
+export interface MsegControls {
+    trigger: Node<'bool'>;
+    reset: Node<'bool'>;
+}
+export interface MsegOutput {
+    value: Node<'f32'>;
+    done: Node<'bool'>;
+    segment: Node<'f32'>;
+}
+export interface SampleAndHoldConfig {
+    initial: number;
+}
+export interface RandomModulatorConfig extends SampleAndHoldConfig {
+    seed: number;
+}
+export interface RandomModulatorControls {
+    /** Level-sensitive sample request: advances once on every high sample. */
+    trigger: Node<'bool'>;
+    reset: Node<'bool'>;
+    /** rho in rho*previous+(1-rho)*uniform; clamped [0,1]. */
+    correlation: Node<'f32'>;
+}
+/** Sample clock, no transport or event scheduler. Call exactly once per sample. */
+export declare const musicalClock: import("@unworklet/core").SubgraphDecl<[config: MusicalClockConfig], {
+    tick(c: MusicalClockControls): MusicalClockOutput;
+}>;
+/** Fixed step values and gate fractions; no MIDI generation or smoothing. */
+export declare const stepSequence: import("@unworklet/core").SubgraphDecl<[config: StepSequenceConfig], {
+    tick(c: MusicalClockControls): StepSequenceOutput;
+}>;
+/**
+ * Fixed piecewise envelope. Rising trigger emits the first duration step;
+ * held trigger does not retrigger. Reset consumes trigger and emits initial.
+ * Zero-length segments collapse at their boundary in list order. Loop jumps
+ * from last target to the first segment's first step on the next sample.
+ */
+export declare const mseg: import("@unworklet/core").SubgraphDecl<[config: MsegConfig], {
+    tick(c: MsegControls): MsegOutput;
+}>;
+/** Level-sensitive sampling; full finite f32 range. Native state maps -0 to +0. */
+export declare const sampleAndHold: import("@unworklet/core").SubgraphDecl<[config: SampleAndHoldConfig], {
+    tick(input: Node<"f32">, trigger: Node<"bool">, reset: Node<"bool">): Node<"f32">;
+}>;
+/**
+ * Park-Miller seeded S&H / bounded correlated random. Each high trigger advances
+ * the PRNG, including correlation=1. Reset wins, restores seed/initial, and
+ * never advances. This is a convex random recurrence, not normalized Gaussian
+ * noise or a specified spectral color. All dynamic inputs must be finite.
+ */
+export declare const randomModulator: import("@unworklet/core").SubgraphDecl<[config: RandomModulatorConfig], {
+    tick(c: RandomModulatorControls): Node<"f32">;
+}>;
+export interface ArpeggiatorNote {
+    note: number;
+    velocity: number;
+    gate: number;
+}
+export interface FixedArpeggiatorConfig extends Omit<MusicalClockConfig, 'steps'> {
+    channel: number;
+    /** Fixed order, 1..64 notes. gate=0 is a rest; no incoming chord capture. */
+    notes: readonly ArpeggiatorNote[];
+}
+export interface FixedArpeggiatorControls extends MusicalClockControls {
+    /** Native unsigned 32-bit absolute timestamp bits, carried by an i32 node. */
+    atSample: Node<'i32'>;
+}
+export interface FixedArpeggiatorOutput extends MusicalClockOutput {
+    note: Node<'f32'>;
+    gate: Node<'bool'>;
+}
+/**
+ * Bounded fixed-note arp using a caller-owned native MIDI output. At most one
+ * off then one on per sample. Output capacity >=256 plus per-quantum draining
+ * is required for the conservative burst bound, not guaranteed host delivery.
+ * Rate zero holds a sounding note; reset before stopping/disconnecting.
+ */
+export declare const fixedArpeggiator: import("@unworklet/core").SubgraphDecl<[config: FixedArpeggiatorConfig], {
+    tick(output: MidiOutputHandle, c: FixedArpeggiatorControls): FixedArpeggiatorOutput;
+}>;

package/dist/modulation.js

@@ -0,0 +1,228 @@
+import { bool, defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+function checkRate(rate) {
+    if (!Number.isInteger(rate) || rate < 8000 || rate > 192000)
+        throw new RangeError('modulation sampleRate must be an integer in [8000,192000]');
+}
+function boundedNumber(value, lo, hi, name) {
+    if (!Number.isFinite(value) || value < lo || value > hi)
+        throw new RangeError(`${name} must be finite in [${lo},${hi}]`);
+}
+function checkClock(config) {
+    checkRate(config.sampleRate);
+    if (config.mode !== 'free' && config.mode !== 'tempo')
+        throw new RangeError('clock mode must be free or tempo');
+    if (!Number.isInteger(config.steps) || config.steps < 1 || config.steps > 64)
+        throw new RangeError('clock steps must be an integer in [1,64]');
+    const division = config.stepsPerBeat ?? 1;
+    if (!Number.isFinite(division) || division < 1 / 64 || division > 64 || !Number.isInteger(Math.log2(division))) {
+        throw new RangeError('stepsPerBeat must be a power of two in [1/64,64]');
+    }
+    if (config.mode === 'free' && division !== 1)
+        throw new RangeError('stepsPerBeat applies only to tempo mode');
+}
+// Core 0.4.1 flushes tiny scalar-state writes. Exact power-of-two scaling
+// preserves every finite f32 control, including subnormals, without a new
+// amplitude threshold. Even the largest finite f32 input remains finite here.
+const SCALE = 2 ** 128;
+const PHASE_MAX = 1 - 2 ** -24;
+const clockCore = defineSubgraph((config) => {
+    checkClock(config);
+    const threshold = config.sampleRate * (config.mode === 'tempo' ? 60 : 1);
+    const division = config.mode === 'tempo' ? config.stepsPerBeat ?? 1 : 1;
+    const lastPosition = config.steps - 2 ** (Math.ceil(Math.log2(config.steps)) - 53);
+    const position = state.f64(0).named('positionScaled');
+    const error = state.f64(0).named('errorScaled');
+    const step = state.i32(0).named('step');
+    const pending = state.bool(true).named('pending');
+    const previousSeek = state.bool(false).named('previousSeek');
+    // Explicit materialization keeps capture/compile work bounded for composed
+    // consumers, rather than expanding shared arithmetic recursively.
+    const current = state.f64(0).named('currentScaled');
+    const increment = state.f64(0).named('incrementScaled');
+    const sum = state.f64(0).named('sumScaled');
+    const nextError = state.f64(0).named('nextErrorScaled');
+    return {
+        tick(c) {
+            const seek = c.seek.and(previousSeek.read().not()).and(c.reset.not());
+            const request = f64(c.position.clamp(-1048576, 1048576));
+            const wrapped = request.sub(request.div(config.steps).floor().mul(config.steps)).min(lastPosition);
+            const targetStep = wrapped.floor();
+            const oldStep = select(c.reset, i32(0), select(seek, i32(targetStep), step.read()));
+            current.write(select(c.reset, f64(0), select(seek, wrapped.sub(targetStep).mul(threshold * SCALE), position.read())));
+            const compensation = select(c.reset.or(seek), f64(0), error.read());
+            // A positive compensation at an exactly rounded threshold means the
+            // true position is still below the boundary. Preserve that distinction
+            // for gate=1 and crossing decisions (no epsilon or early sample tick).
+            const phase = current.read().sub(compensation).div(threshold * SCALE).clamp(0, 1 - 2 ** -53);
+            const pulse = c.reset.not().and(seek.or(pending.read()));
+            // Accumulate frequency units, not rounded samples-per-step or repeated
+            // fractional periods. Compensated summation preserves fractional tempos.
+            increment.write(f64(c.rate.clamp(0, 1000)).mul(division * SCALE).sub(compensation));
+            sum.write(current.read().add(increment.read()));
+            nextError.write(sum.read().sub(current.read()).sub(increment.read()));
+            const crossed = sum.read().gt(threshold * SCALE).or(sum.read().eq(threshold * SCALE).and(nextError.read().lte(0)));
+            const next = sum.read().sub(select(crossed, f64(threshold * SCALE), f64(0)));
+            const nextStep = oldStep.add(select(crossed, i32(1), i32(0)));
+            error.write(select(c.reset, f64(0), nextError.read()));
+            position.write(select(c.reset, f64(0), next));
+            step.write(select(c.reset, i32(0), select(nextStep.gte(config.steps), i32(0), nextStep)));
+            pending.write(c.reset.or(crossed));
+            previousSeek.write(c.seek);
+            return { step: f32(oldStep), phase: f32(phase).clamp(0, PHASE_MAX), phase64: phase, tick: pulse };
+        },
+    };
+});
+/** Sample clock, no transport or event scheduler. Call exactly once per sample. */
+export const musicalClock = defineSubgraph((config) => {
+    const clock = instantiate(clockCore, config, { name: 'clock' });
+    return { tick(c) {
+            const value = clock.tick(c);
+            return { step: value.step, phase: value.phase, tick: value.tick };
+        } };
+});
+/** Fixed step values and gate fractions; no MIDI generation or smoothing. */
+export const stepSequence = defineSubgraph((config) => {
+    if (!Array.isArray(config.steps) || config.steps.length < 1 || config.steps.length > 64)
+        throw new RangeError('sequence requires 1..64 steps');
+    const steps = config.steps.map(step => {
+        boundedNumber(step.value, -1, 1, 'step value');
+        boundedNumber(step.gate, 0, 1, 'step gate');
+        return { value: step.value, gate: step.gate };
+    });
+    const clock = instantiate(clockCore, { ...config, steps: steps.length }, { name: 'clock' });
+    return { tick(c) {
+            const t = clock.tick(c);
+            let value = f32(steps[0].value), gate = f64(steps[0].gate);
+            for (let n = 1; n < steps.length; n++) {
+                value = select(t.step.eq(n), f32(steps[n].value), value);
+                gate = select(t.step.eq(n), f64(steps[n].gate), gate);
+            }
+            return { value, step: t.step, phase: t.phase, tick: t.tick,
+                gate: c.reset.not().and(t.phase64.lt(gate)) };
+        } };
+});
+/**
+ * Fixed piecewise envelope. Rising trigger emits the first duration step;
+ * held trigger does not retrigger. Reset consumes trigger and emits initial.
+ * Zero-length segments collapse at their boundary in list order. Loop jumps
+ * from last target to the first segment's first step on the next sample.
+ */
+export const mseg = defineSubgraph((config) => {
+    checkRate(config.sampleRate);
+    boundedNumber(config.initial, -1, 1, 'MSEG initial');
+    if (!Array.isArray(config.segments) || config.segments.length < 1 || config.segments.length > 16)
+        throw new RangeError('MSEG requires 1..16 segments');
+    if (config.loop !== undefined && typeof config.loop !== 'boolean')
+        throw new RangeError('MSEG loop must be boolean');
+    let total = 0, startValue = config.initial;
+    const segments = config.segments.map(segment => {
+        boundedNumber(segment.seconds, 0, 30, 'MSEG seconds');
+        boundedNumber(segment.target, -1, 1, 'MSEG target');
+        if (!['linear', 'easeIn', 'easeOut', 'smoothstep'].includes(segment.curve))
+            throw new RangeError('unknown MSEG curve');
+        const frames = Math.round(segment.seconds * config.sampleRate);
+        const result = { ...segment, start: total, frames, startValue };
+        total += frames;
+        startValue = segment.target;
+        return result;
+    });
+    if (config.loop && total === 0)
+        throw new RangeError('looped MSEG needs at least one duration sample');
+    const frame = state.i32(0).named('frame');
+    const started = state.bool(false).named('started');
+    const previousTrigger = state.bool(false).named('previousTrigger');
+    return { tick(c) {
+            const trigger = c.trigger.and(previousTrigger.read().not()).and(c.reset.not());
+            const active = c.reset.not().and(started.read().or(trigger));
+            const advance = config.loop ? select(frame.read().gte(total), i32(1), frame.read().add(1)) : frame.read().add(1).min(total);
+            frame.write(select(active, select(trigger, i32(Math.min(1, total)), advance), i32(0)));
+            const elapsed = frame.read();
+            let value = f64(config.initial), index = i32(0);
+            for (let n = 0; n < segments.length; n++) {
+                const s = segments[n];
+                const t = f64(elapsed.sub(s.start)).div(Math.max(1, s.frames)).clamp(0, 1);
+                const curve = s.curve === 'easeIn' ? t.mul(t) : s.curve === 'easeOut' ? t.mul(f64(2).sub(t)) : s.curve === 'smoothstep' ? t.mul(t).mul(f64(3).sub(t.mul(2))) : t;
+                const applicable = active.and(s.frames === 0 ? elapsed.gte(s.start) : elapsed.gt(s.start));
+                const next = s.frames === 0 ? f64(s.target) : f64(s.startValue).add(curve.mul(s.target - s.startValue));
+                value = select(applicable, next, value);
+                index = select(applicable, i32(n), index);
+            }
+            started.write(active);
+            previousTrigger.write(c.trigger);
+            return { value: f32(value).clamp(-1, 1), segment: f32(index), done: active.not().or(bool(!config.loop).and(elapsed.gte(total))) };
+        } };
+});
+/** Level-sensitive sampling; full finite f32 range. Native state maps -0 to +0. */
+export const sampleAndHold = defineSubgraph((config) => {
+    boundedNumber(config.initial, -1, 1, 'sampleAndHold initial');
+    const held = state.f64(config.initial * SCALE).named('heldScaled');
+    return { tick(input, trigger, reset) {
+            held.write(select(reset, f64(config.initial * SCALE), select(trigger, f64(input).mul(SCALE), held.read())));
+            return f32(held.read().div(SCALE));
+        } };
+});
+/**
+ * Park-Miller seeded S&H / bounded correlated random. Each high trigger advances
+ * the PRNG, including correlation=1. Reset wins, restores seed/initial, and
+ * never advances. This is a convex random recurrence, not normalized Gaussian
+ * noise or a specified spectral color. All dynamic inputs must be finite.
+ */
+export const randomModulator = defineSubgraph((config) => {
+    boundedNumber(config.initial, -1, 1, 'random initial');
+    if (!Number.isInteger(config.seed) || config.seed < 1 || config.seed > 2147483646)
+        throw new RangeError('random seed must be an integer in [1,2147483646]');
+    const seed = state.f64(config.seed).named('seed');
+    const value = state.f64(config.initial * SCALE).named('valueScaled');
+    return { tick(c) {
+            // Product <= 3.61e13 < 2^53; all integer arithmetic is exactly represented.
+            const product = seed.read().mul(16807);
+            const nextSeed = product.sub(product.div(2147483647).floor().mul(2147483647));
+            seed.write(select(c.reset, f64(config.seed), select(c.trigger, nextSeed, seed.read())));
+            const uniform = seed.read().sub(1).div(2147483645).mul(2).sub(1);
+            const rho = f64(c.correlation.clamp(0, 1));
+            const next = value.read().mul(rho).add(uniform.mul(f64(1).sub(rho)).mul(SCALE));
+            value.write(select(c.reset, f64(config.initial * SCALE), select(c.trigger, next, value.read())));
+            return f32(value.read().div(SCALE)).clamp(-1, 1);
+        } };
+});
+/**
+ * Bounded fixed-note arp using a caller-owned native MIDI output. At most one
+ * off then one on per sample. Output capacity >=256 plus per-quantum draining
+ * is required for the conservative burst bound, not guaranteed host delivery.
+ * Rate zero holds a sounding note; reset before stopping/disconnecting.
+ */
+export const fixedArpeggiator = defineSubgraph((config) => {
+    if (!Number.isInteger(config.channel) || config.channel < 0 || config.channel > 15)
+        throw new RangeError('arp channel must be an integer in [0,15]');
+    if (!Array.isArray(config.notes) || config.notes.length < 1 || config.notes.length > 64)
+        throw new RangeError('arp requires 1..64 notes');
+    const notes = config.notes.map(note => {
+        if (!Number.isInteger(note.note) || note.note < 0 || note.note > 127)
+            throw new RangeError('arp note must be an integer in [0,127]');
+        if (!Number.isInteger(note.velocity) || note.velocity < 1 || note.velocity > 127)
+            throw new RangeError('arp velocity must be an integer in [1,127]');
+        boundedNumber(note.gate, 0, 1, 'arp gate');
+        return { ...note };
+    });
+    const clock = instantiate(clockCore, { ...config, steps: notes.length }, { name: 'clock' });
+    const active = state.bool(false).named('active');
+    const activeNote = state.i32(notes[0].note).named('activeNote');
+    return { tick(output, c) {
+            const t = clock.tick(c);
+            let note = i32(notes[0].note), velocity = i32(notes[0].velocity), fraction = f64(notes[0].gate);
+            for (let n = 1; n < notes.length; n++) {
+                note = select(t.step.eq(n), i32(notes[n].note), note);
+                velocity = select(t.step.eq(n), i32(notes[n].velocity), velocity);
+                fraction = select(t.step.eq(n), f64(notes[n].gate), fraction);
+            }
+            const gate = c.reset.not().and(t.phase64.lt(fraction));
+            const previous = active.read();
+            const off = previous.and(gate.not().or(t.tick));
+            const on = gate.and(previous.not().or(t.tick));
+            output.emitIf(off, { type: 'noteOff', channel: config.channel, note: activeNote.read(), velocity: 0, atSample: c.atSample });
+            output.emitIf(on, { type: 'noteOn', channel: config.channel, note, velocity, atSample: c.atSample });
+            activeNote.write(select(on, note, activeNote.read()));
+            active.write(gate);
+            return { note: f32(note), gate, step: t.step, phase: t.phase, tick: t.tick };
+        } };
+});

package/dist/mpe-expression.d.ts

@@ -0,0 +1,36 @@
+import { type MidiInputHandle, type Node } from '@unworklet/core';
+export interface MpeExpressionConfig {
+    /** Fixed lower zone: native channel 0 is master, 1..memberChannels are members. Default 15. */
+    memberChannels?: number;
+    /** Symmetric semitone range, finite [0,96]. Default 48. No RPN negotiation. */
+    memberBendRange?: number;
+    /** Symmetric semitone range, finite [0,96]. Default 2. */
+    masterBendRange?: number;
+}
+/** Pass the existing allocator voice's active/channel fields without remapping. */
+export interface MpeExpressionVoice {
+    active: Node<'bool'>;
+    channel: Node<'i32'>;
+}
+/** Lower-zone expression routing only: no note allocator or pedal propagation.
+ * Bind once to the same native MIDI input as the existing allocation policy.
+ * See docs/mpe-expression.md for channel reuse, reset and unsupported features.
+ */
+export declare const mpeExpression: import("@unworklet/core").SubgraphDecl<[config: MpeExpressionConfig], {
+    memberChannels: number;
+    memberBendRange: number;
+    masterBendRange: number;
+    reset: (when?: Node<"bool">) => void;
+    bindMidi(input: MidiInputHandle): void;
+    read(voice: MpeExpressionVoice): {
+        inZone: Node<"bool">;
+        memberBend: Node<"f32">;
+        masterBend: Node<"f32">;
+        /** Already includes both bend ranges. Do not add performancePolicy.bend again. */
+        bendSemitones: Node<"f32">;
+        memberPressure: Node<"f32">;
+        masterPressure: Node<"f32">;
+        memberTimbre: Node<"f32">;
+        masterTimbre: Node<"f32">;
+    };
+}>;

package/dist/mpe-expression.js

@@ -0,0 +1,73 @@
+import { bool, defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+/** Lower-zone expression routing only: no note allocator or pedal propagation.
+ * Bind once to the same native MIDI input as the existing allocation policy.
+ * See docs/mpe-expression.md for channel reuse, reset and unsupported features.
+ */
+export const mpeExpression = defineSubgraph((config) => {
+    const members = config.memberChannels ?? 15;
+    const memberRange = config.memberBendRange ?? 48;
+    const masterRange = config.masterBendRange ?? 2;
+    if (!Number.isInteger(members) || members < 1 || members > 15) {
+        throw new RangeError('mpeExpression memberChannels must be an integer in [1,15]');
+    }
+    for (const [name, value] of [['memberBendRange', memberRange], ['masterBendRange', masterRange]]) {
+        if (!Number.isFinite(value) || value < 0 || value > 96)
+            throw new RangeError(`mpeExpression ${name} must be finite in [0,96]`);
+    }
+    const ints = (name) => state.buffer.i32({ size: members + 1 }).expose({ name, snapshot: 'transient' });
+    // Store centered integer MIDI values, so fresh-instance transient defaults
+    // represent bend 8192, pressure 0 and CC74 64. In-place restore leaves
+    // transient state unchanged; reset() is the explicit clearing operation.
+    const bend = ints('bend'), pressure = ints('pressure'), timbre = ints('timbre');
+    const validChannel = (channel) => channel.gte(0).and(channel.lte(members));
+    const valid7 = (value) => value.gte(0).and(value.lte(127));
+    const normalizedBend = (channel) => {
+        const value = bend.read(channel);
+        return f64(value).div(select(value.lt(0), f64(8192), f64(8191)));
+    };
+    function reset(when = bool(true)) {
+        for (let channel = 0; channel <= members; channel++) {
+            bend.write(channel, select(when, i32(0), bend.read(channel)));
+            pressure.write(channel, select(when, i32(0), pressure.read(channel)));
+            timbre.write(channel, select(when, i32(0), timbre.read(channel)));
+        }
+    }
+    return {
+        memberChannels: members, memberBendRange: memberRange, masterBendRange: masterRange,
+        reset,
+        bindMidi(input) {
+            input.onEvent('pitchBend', e => {
+                const channel = e.channel.clamp(0, members);
+                const valid = validChannel(e.channel).and(e.value.gte(0)).and(e.value.lte(16383));
+                bend.write(channel, select(valid, e.value.sub(8192), bend.read(channel)));
+            });
+            input.onEvent('channelPressure', e => {
+                const channel = e.channel.clamp(0, members);
+                pressure.write(channel, select(validChannel(e.channel).and(valid7(e.pressure)), e.pressure, pressure.read(channel)));
+            });
+            input.onEvent('cc', e => {
+                const channel = e.channel.clamp(0, members), valid = validChannel(e.channel).and(valid7(e.value));
+                const clear = valid.and(e.controller.eq(121));
+                bend.write(channel, select(clear, i32(0), bend.read(channel)));
+                pressure.write(channel, select(clear, i32(0), pressure.read(channel)));
+                timbre.write(channel, select(clear, i32(0), select(valid.and(e.controller.eq(74)), e.value.sub(64), timbre.read(channel))));
+            });
+        },
+        read(voice) {
+            const inZone = voice.active.and(voice.channel.gte(1)).and(voice.channel.lte(members));
+            const channel = voice.channel.clamp(1, members);
+            const member = normalizedBend(channel), master = normalizedBend(i32(0));
+            const lane = (value) => select(inZone, value, f32(0));
+            return {
+                inZone,
+                memberBend: lane(f32(member)), masterBend: lane(f32(master)),
+                /** Already includes both bend ranges. Do not add performancePolicy.bend again. */
+                bendSemitones: lane(f32(member.mul(memberRange).add(master.mul(masterRange)))),
+                memberPressure: lane(f32(pressure.read(channel)).div(127)),
+                masterPressure: lane(f32(pressure.read(0)).div(127)),
+                memberTimbre: lane(f32(timbre.read(channel).add(64)).div(127)),
+                masterTimbre: lane(f32(timbre.read(0).add(64)).div(127)),
+            };
+        },
+    };
+});

package/dist/multiband-dynamics.d.ts

@@ -0,0 +1,50 @@
+import { type Node } from '@unworklet/core';
+import { type DynamicsConfig, type DynamicsControls } from './dynamics.js';
+export type MultibandDynamicsBandConfig = Omit<DynamicsConfig, 'sampleRate'>;
+export interface MultibandDynamicsConfig {
+    sampleRate: number;
+    /** Fixed low/mid/high operations and detector modes. */
+    bands: readonly [MultibandDynamicsBandConfig, MultibandDynamicsBandConfig, MultibandDynamicsBandConfig];
+}
+export type MultibandDynamicsBandControls = Omit<DynamicsControls, 'reset'>;
+export interface MultibandDynamicsControls {
+    /** Finite fallbacks 200/2000 Hz, individually clamped and then sorted. Equality is permitted. */
+    lowCutoffHz: Node<'f32'>;
+    highCutoffHz: Node<'f32'>;
+    bands: readonly [MultibandDynamicsBandControls, MultibandDynamicsBandControls, MultibandDynamicsBandControls];
+    reset: Node<'bool'>;
+}
+/** Three phase-compensated LR4 bands with independent linked-stereo dynamics. */
+export declare const multibandDynamics: import("@unworklet/core").SubgraphDecl<[config: MultibandDynamicsConfig], {
+    /** No explicit sample delay. IIR phase/group delay is frequency dependent. */
+    tick(left: Node<"f32">, right: Node<"f32">, controls: MultibandDynamicsControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+        /** Phase-matched unprocessed recombination; not the original dry PCM. */
+        dryLeft: Node<"f32">;
+        dryRight: Node<"f32">;
+        low: {
+            left: Node<"f32">;
+            right: Node<"f32">;
+            envelope: Node<"f32">;
+            gain: Node<"f32">;
+            gainDb: Node<"f32">;
+        };
+        mid: {
+            left: Node<"f32">;
+            right: Node<"f32">;
+            envelope: Node<"f32">;
+            gain: Node<"f32">;
+            gainDb: Node<"f32">;
+        };
+        high: {
+            left: Node<"f32">;
+            right: Node<"f32">;
+            envelope: Node<"f32">;
+            gain: Node<"f32">;
+            gainDb: Node<"f32">;
+        };
+        lowCutoffHz: Node<"f32">;
+        highCutoffHz: Node<"f32">;
+    };
+}>;

package/dist/multiband-dynamics.js

@@ -0,0 +1,60 @@
+import { defineSubgraph, f32, f64, instantiate, select, state } from '@unworklet/core';
+import { crossover } from './crossover.js';
+import { dynamics } from './dynamics.js';
+function finite(input, fallback = 0) {
+    return select(input.eq(input).and(input.abs().lte(3.4028234663852886e38)), input, f32(fallback));
+}
+const sum = (a, b, c) => f32(f64(a).add(f64(b)).add(c ? f64(c) : f64(0)));
+/** Three phase-compensated LR4 bands with independent linked-stereo dynamics. */
+export const multibandDynamics = defineSubgraph((config) => {
+    const { sampleRate } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000) {
+        throw new RangeError('multibandDynamics sampleRate must be an integer in [8000,192000]');
+    }
+    if (!Array.isArray(config.bands) || config.bands.length !== 3)
+        throw new RangeError('multibandDynamics requires exactly three bands');
+    const maximum = Math.min(20000, 0.45 * sampleRate);
+    const splits = ['left', 'right'].map(channel => ({
+        low: instantiate(crossover, { sampleRate }, { name: `${channel}LowSplit` }),
+        high: instantiate(crossover, { sampleRate }, { name: `${channel}HighSplit` }),
+        compensate: instantiate(crossover, { sampleRate }, { name: `${channel}LowCompensation` }),
+    }));
+    // Materialize the existing f32 stage boundaries once. Without these native
+    // scratch buffers, 0.4.1 re-expands returned expressions at every consumer.
+    // Exact binary64 scaling prevents the native <1e-30 buffer-store flush from
+    // changing tiny audio; each slot is overwritten before read on every tick.
+    const scale = 2 ** 128;
+    const scratch = ['left', 'right'].map(channel => state.buffer.f64({ size: 5 })
+        .expose({ name: `${channel}StageScratchScaled`, snapshot: 'transient' }));
+    const processors = config.bands.map((band, i) => instantiate(dynamics, { ...band, sampleRate }, { name: `band${i}` }));
+    return {
+        /** No explicit sample delay. IIR phase/group delay is frequency dependent. */
+        tick(left, right, controls) {
+            const a = finite(controls.lowCutoffHz, 200).clamp(20, maximum);
+            const b = finite(controls.highCutoffHz, 2000).clamp(20, maximum);
+            const lowCutoffHz = a.min(b), highCutoffHz = a.max(b);
+            const bands = [left, right].map((input, ch) => {
+                const first = splits[ch].low.tick(finite(input), lowCutoffHz, controls.reset);
+                const store = (index, value) => scratch[ch].write(index, f64(value).mul(scale));
+                const read = (index) => f32(scratch[ch].read(index).div(scale));
+                store(0, first.low);
+                store(1, first.high);
+                const upper = splits[ch].high.tick(read(1), highCutoffHz, controls.reset);
+                const compensation = splits[ch].compensate.tick(read(0), highCutoffHz, controls.reset);
+                store(2, sum(compensation.low, compensation.high));
+                store(3, upper.low);
+                store(4, upper.high);
+                return [read(2), read(3), read(4)];
+            });
+            const processed = processors.map((unit, i) => unit.tick(bands[0][i], bands[1][i], bands[0][i], bands[1][i], { ...controls.bands[i], reset: controls.reset }));
+            return {
+                left: sum(processed[0].left, processed[1].left, processed[2].left),
+                right: sum(processed[0].right, processed[1].right, processed[2].right),
+                /** Phase-matched unprocessed recombination; not the original dry PCM. */
+                dryLeft: sum(...bands[0]), dryRight: sum(...bands[1]),
+                low: processed[0], mid: processed[1], high: processed[2],
+                lowCutoffHz, highCutoffHz,
+            };
+        },
+    };
+});

package/dist/musical-controls.d.ts

@@ -0,0 +1,76 @@
+import { type Node } from '@unworklet/core';
+export interface CurvedAdsrConfig {
+    sampleRate: number;
+}
+export interface CurvedAdsrControls {
+    gate: Node<'bool'>;
+    /** Level-sensitive; ignored while gate is false. */
+    retrigger: Node<'bool'>;
+    /** Wins over all other controls and consumes the gate level. */
+    reset: Node<'bool'>;
+    /** Seconds, clamped [0,30], rounded to the nearest sample (half up). */
+    attack: Node<'f32'>;
+    decay: Node<'f32'>;
+    sustain: Node<'f32'>;
+    release: Node<'f32'>;
+    /** Latched segment bends [-1,1]: -1 ease-in, 0 linear, +1 ease-out. */
+    attackBend: Node<'f32'>;
+    decayBend: Node<'f32'>;
+    releaseBend: Node<'f32'>;
+}
+export interface CurvedAdsrOutput {
+    level: Node<'f32'>;
+    done: Node<'bool'>;
+}
+/**
+ * Segment-relative curved ADSR. Tick exactly once per sample; finite controls.
+ * C(t,b)=t+b*t*(1-t), with exact endpoints. Segment settings latch on entry;
+ * decay latches at the preceding positive attack endpoint. Sustain follows its
+ * current input in the sustain stage. Retrigger/note-off start at the last
+ * emitted f32 level. Zero attack collapses into decay on the same sample.
+ * Reset > gate-off > retrigger. Reset consumes held gate. No smoothing/tail
+ * threshold; zero sustain remains active. Bend zero is linear, not a promise of
+ * byte identity with the legacy iterative envelope. See the entry contract.
+ */
+export declare const curvedAdsr: import("@unworklet/core").SubgraphDecl<[config: CurvedAdsrConfig], {
+    tick(c: CurvedAdsrControls): CurvedAdsrOutput;
+}>;
+export type MusicalLfoWaveform = 'sine' | 'triangle' | 'saw' | 'square';
+export interface MusicalLfoConfig {
+    sampleRate: number;
+    mode: 'free' | 'tempo';
+    waveform: MusicalLfoWaveform;
+    /** Tempo mode only, power of two in [1/64,64], default 1. */
+    beatsPerCycle?: number;
+}
+export interface MusicalLfoControls {
+    /** Free: Hz [0,20]. Tempo: BPM [0,1000]. */
+    rate: Node<'f32'>;
+    /** Hold the base clock at zero; offset still applies. Consumes seek level. */
+    reset: Node<'bool'>;
+    /** Rising-edge seek, including while held. Reset wins. */
+    seek: Node<'bool'>;
+    /** Seek position in cycles, clamped +/-1048576 then wrapped. */
+    position: Node<'f32'>;
+    /** Live cycles offset, clamped +/-1048576. May deliberately jump. */
+    phaseOffset: Node<'f32'>;
+    /** Stops base-phase integration; seek/reset and live offset still apply. */
+    hold: Node<'bool'>;
+}
+export interface MusicalLfoOutput {
+    value: Node<'f32'>;
+    /** Canonical f32 waveform phase [0,1), capped at 1-2^-24. */
+    phase: Node<'f32'>;
+}
+/**
+ * Fixed-waveform LFO composed from musicalClock. Tick once per sample with finite
+ * inputs. Output precedes integration. Held reset pins base zero; release emits
+ * zero base before resuming. Hold/rate zero preserve base phase. Tempo follows
+ * BPM/(60*beatsPerCycle) exactly within the clock's numerical contract, including
+ * up to 1066 2/3 Hz. Public f32 clock-phase quantization is intentional, not the
+ * legacy sine LFO's internal-f64 phase guarantee. Waveforms are non-bandlimited;
+ * phase/offset/reset changes can jump. No smoothing/depth/routing/transport.
+ */
+export declare const musicalLfo: import("@unworklet/core").SubgraphDecl<[config: MusicalLfoConfig], {
+    tick(c: MusicalLfoControls): MusicalLfoOutput;
+}>;