`hooks/use-parameter`

(no submodules)

Purpose

useParameter(plugin, paramId) is the canonical read/write hook for a single declared parameter on any AudioFxPlugin. It returns the parameter's current value (sampled at frame rate) and three write-paths: an immediate set, a curve for ramps/automation, and a scheduleAt for transport-anchored value changes.

The hook throws ReactAudioError(REACT_AUDIO.UNKNOWN_PARAMETER) synchronously on first render if the paramId is not declared in the plugin's parameterIndex — so a typo fails fast in the render tree rather than silently dropping writes.

Features

Frame-rate sampled value (60 Hz default, configurable via provider sampleRateHz).
set(v) → plugin.setParameter(paramId, v).
curve(c) → plugin.setParameterCurve(paramId, c).
scheduleAt(v, t) → plugin.setParameterAt(paramId, v, t).
Throws REACT_AUDIO.UNKNOWN_PARAMETER on first render for an unknown paramId, carrying the available ids in context.
SSR-consistent snapshots (both getSnapshot and getServerSnapshot read plugin.getParameter(paramId)).

Usage: Basic

import { useParameter } from "@suaveplan/react-audio";

function GainKnob({ plugin }: { plugin: AudioFxPlugin }) {
    const { value, set } = useParameter(plugin, "gain");
    return (
        <input
            type="range"
            min={0}
            max={1}
            step={0.01}
            value={value}
            onChange={(e) => set(Number(e.currentTarget.value))}
        />
    );
}

Usage: Advanced

import { useParameter } from "@suaveplan/react-audio";

function Sweep({ plugin }: { plugin: AudioFxPlugin }) {
    const { curve, scheduleAt } = useParameter(plugin, "cutoff");
    return (
        <>
            <button
                type="button"
                onClick={() =>
                    curve({
                        kind: "linear",
                        startValue: 200,
                        endValue: 8000,
                        duration: 4,
                    })
                }
            >
                Linear sweep
            </button>
            <button type="button" onClick={() => scheduleAt(440, 2)}>
                Set to 440 at t=2s
            </button>
        </>
    );
}

API Reference

useParameter(plugin, paramId): { value, set, curve, scheduleAt }.

Implementation Notes

Parameter automation can change values per audio block (~689 Hz at 128/88.2k); the React commit cycle cannot run at that rate. The hook samples the live value at sampleRateHz (60 Hz default) via a useSyncExternalStore subscription whose subscribe path schedules a setInterval and getSnapshot path reads plugin.getParameter(paramId). setInterval is used rather than requestAnimationFrame so the sampling behaves deterministically in tests (happy-dom RAF is synchronous-per-microtask which makes the per-frame-cap test impossible). The unknown-param check runs on every render — parameter indices are immutable on a typical plugin so the lookup is O(1) and the throw site is the same.

3.1 KiB Raw Blame History

hooks/use-parameter