@litlab/audx 0.0.1 → 0.5.5

package/dist/react.d.ts

@@ -0,0 +1,583 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** Standard oscillator waveform source with optional FM synthesis. */
+type OscillatorSource = {
+    type: "sine" | "triangle" | "square" | "sawtooth";
+    /** Fixed frequency in Hz, or a `{ start, end }` range for a pitch sweep. */
+    frequency: number | {
+        start: number;
+        end: number;
+    };
+    /** Detune in cents. */
+    detune?: number;
+    /** Frequency modulation: `ratio` is the modulator-to-carrier ratio, `depth` is the modulation index. */
+    fm?: {
+        ratio: number;
+        depth: number;
+    };
+};
+/** Procedural noise source (white, pink, or brown). */
+type NoiseSource = {
+    type: "noise";
+    /** @defaultValue `"white"` */
+    color?: "white" | "pink" | "brown";
+};
+/** Custom waveform built from a harmonic series via `createPeriodicWave`. */
+type WavetableSource = {
+    type: "wavetable";
+    /** Amplitude of each harmonic (index 0 = fundamental). */
+    harmonics: number[];
+    /** Fixed frequency in Hz, or a `{ start, end }` range for a pitch sweep. */
+    frequency: number | {
+        start: number;
+        end: number;
+    };
+};
+/** Plays a pre-recorded audio sample from a URL or an existing `AudioBuffer`. */
+type SampleSource = {
+    type: "sample";
+    /** URL of the audio file to fetch and decode. Cached after first load. */
+    url?: string;
+    /** Pre-decoded buffer to use directly. */
+    buffer?: AudioBuffer;
+    /** Playback speed multiplier. @defaultValue `1` */
+    playbackRate?: number;
+    /** Detune in cents. */
+    detune?: number;
+    /** Whether the sample loops. */
+    loop?: boolean;
+    /** Loop region start in seconds. */
+    loopStart?: number;
+    /** Loop region end in seconds. */
+    loopEnd?: number;
+};
+/** Live audio input from a `MediaStream` (e.g. microphone). Requires a real-time `AudioContext`. */
+type StreamSource = {
+    type: "stream";
+    stream: MediaStream;
+};
+/** DC offset source, useful for control signals and modulation. */
+type ConstantSource = {
+    type: "constant";
+    /** @defaultValue `1` */
+    offset?: number;
+};
+/** Union of all audio source types that can drive a {@link Layer}. */
+type Source = OscillatorSource | NoiseSource | WavetableSource | SampleSource | StreamSource | ConstantSource;
+/** Biquad filter type identifiers matching the Web Audio API `BiquadFilterNode.type`. */
+type BiquadFilterType = "lowpass" | "highpass" | "bandpass" | "notch" | "allpass" | "peaking" | "lowshelf" | "highshelf";
+/** Time-varying envelope applied to a filter's cutoff frequency. */
+type FilterEnvelope = {
+    /** Time in seconds to ramp from the base frequency to `peak`. @defaultValue `0` */
+    attack?: number;
+    /** Target frequency in Hz at the peak of the envelope. */
+    peak: number;
+    /** Time in seconds to decay from `peak` back to the base frequency. */
+    decay: number;
+};
+/** Standard biquad filter with optional frequency envelope. */
+type BiquadFilter = {
+    type: BiquadFilterType;
+    /** Cutoff or center frequency in Hz. */
+    frequency: number;
+    /** Q factor (resonance). @defaultValue `1` */
+    resonance?: number;
+    /** Gain in dB (only applies to peaking / shelf types). */
+    gain?: number;
+    /** Optional frequency envelope that sweeps the cutoff over time. */
+    envelope?: FilterEnvelope;
+};
+/** Arbitrary IIR filter defined by feedforward and feedback coefficients. */
+type IIRFilter = {
+    type: "iir";
+    feedforward: number[];
+    feedback: number[];
+};
+/** Union of supported filter types. */
+type Filter = BiquadFilter | IIRFilter;
+/**
+ * Amplitude envelope (ADSR).
+ *
+ * Only `decay` is required. Omitting `attack` makes the sound start at full
+ * volume; omitting `sustain` lets it fade to silence after the decay phase.
+ */
+type Envelope = {
+    /** Time in seconds to ramp from silence to peak volume. @defaultValue `0` */
+    attack?: number;
+    /** Time in seconds for the decay phase. */
+    decay: number;
+    /** Sustain level as a fraction of peak volume (0 – 1). @defaultValue `0` */
+    sustain?: number;
+    /** Time in seconds for the release phase after sustain. @defaultValue `0` */
+    release?: number;
+};
+/** Parameter that an {@link LFO} can modulate. */
+type LFOTarget = "frequency" | "detune" | "gain" | "pan" | "filter.frequency" | "filter.detune" | "filter.Q" | "filter.gain" | "playbackRate";
+/** Low-frequency oscillator for periodic modulation of a target parameter. */
+type LFO = {
+    /** Waveform shape of the modulator. */
+    type: "sine" | "triangle" | "square" | "sawtooth";
+    /** Modulation rate in Hz. */
+    frequency: number;
+    /** Modulation depth (units depend on the target parameter). */
+    depth: number;
+    /** Which parameter this LFO modulates. */
+    target: LFOTarget;
+};
+/** 3D spatial panner configuration using the Web Audio `PannerNode`. */
+type Panner3D = {
+    positionX: number;
+    positionY: number;
+    positionZ: number;
+    orientationX?: number;
+    orientationY?: number;
+    orientationZ?: number;
+    /** @defaultValue `"HRTF"` */
+    panningModel?: "equalpower" | "HRTF";
+    /** @defaultValue `"inverse"` */
+    distanceModel?: "linear" | "inverse" | "exponential";
+    maxDistance?: number;
+    refDistance?: number;
+    rolloffFactor?: number;
+    coneInnerAngle?: number;
+    coneOuterAngle?: number;
+    coneOuterGain?: number;
+};
+/** Position and orientation of the audio listener for 3D spatialization. */
+type Listener = {
+    positionX: number;
+    positionY: number;
+    positionZ: number;
+    forwardX?: number;
+    forwardY?: number;
+    forwardZ?: number;
+    upX?: number;
+    upY?: number;
+    upZ?: number;
+};
+/** Algorithmic reverb generated from an exponentially-decaying noise impulse. */
+type ReverbEffect = {
+    type: "reverb";
+    /** Tail length in seconds. @defaultValue `0.5` */
+    decay?: number;
+    /** Delay in seconds before the reverb onset. @defaultValue `0` */
+    preDelay?: number;
+    /** High-frequency damping (0 – 1). @defaultValue `0` */
+    damping?: number;
+    /** Multiplier on the decay length. @defaultValue `1` */
+    roomSize?: number;
+    /** Dry/wet mix (0 = fully dry, 1 = fully wet). @defaultValue `0.3` */
+    mix?: number;
+};
+/** Convolution reverb using a provided impulse response buffer or URL. */
+type ConvolverEffect = {
+    type: "convolver";
+    /** URL of the impulse response audio file. */
+    url?: string;
+    /** Pre-decoded impulse response buffer. */
+    buffer?: AudioBuffer;
+    /** @defaultValue `0.5` */
+    mix?: number;
+};
+/** Feedback delay with optional filter in the feedback path. */
+type DelayEffect = {
+    type: "delay";
+    /** Delay time in seconds. @defaultValue `0.25` */
+    time?: number;
+    /** Feedback gain (0 – 1). @defaultValue `0.3` */
+    feedback?: number;
+    /** Optional filter applied in the feedback loop. */
+    feedbackFilter?: {
+        type: BiquadFilterType;
+        frequency: number;
+        Q?: number;
+    };
+    /** @defaultValue `0.3` */
+    mix?: number;
+};
+/** Waveshaper-based distortion using a `tanh` transfer curve. */
+type DistortionEffect = {
+    type: "distortion";
+    /** Drive amount (higher = more distortion). @defaultValue `50` */
+    amount?: number;
+    /** @defaultValue `0.5` */
+    mix?: number;
+};
+/** Stereo chorus using two LFO-modulated delay lines. */
+type ChorusEffect = {
+    type: "chorus";
+    /** LFO rate in Hz. @defaultValue `1.5` */
+    rate?: number;
+    /** LFO depth in seconds. @defaultValue `0.003` */
+    depth?: number;
+    /** @defaultValue `0.3` */
+    mix?: number;
+};
+/** Flanging effect via a short LFO-modulated delay with feedback. */
+type FlangerEffect = {
+    type: "flanger";
+    /** LFO rate in Hz. @defaultValue `0.5` */
+    rate?: number;
+    /** LFO depth in seconds. @defaultValue `0.002` */
+    depth?: number;
+    /** Feedback gain (0 – 1). @defaultValue `0.5` */
+    feedback?: number;
+    /** @defaultValue `0.5` */
+    mix?: number;
+};
+/** Multi-stage allpass phaser with LFO sweep. */
+type PhaserEffect = {
+    type: "phaser";
+    /** LFO rate in Hz. @defaultValue `0.5` */
+    rate?: number;
+    /** LFO depth in Hz. @defaultValue `1000` */
+    depth?: number;
+    /** Number of allpass stages. @defaultValue `4` */
+    stages?: number;
+    /** Feedback gain (0 – 1). @defaultValue `0.5` */
+    feedback?: number;
+    /** @defaultValue `0.5` */
+    mix?: number;
+};
+/** Amplitude modulation (volume tremolo). */
+type TremoloEffect = {
+    type: "tremolo";
+    /** LFO rate in Hz. @defaultValue `4` */
+    rate?: number;
+    /** Modulation depth (0 – 1). @defaultValue `0.5` */
+    depth?: number;
+};
+/** Pitch vibrato via a short modulated delay line. */
+type VibratoEffect = {
+    type: "vibrato";
+    /** LFO rate in Hz. @defaultValue `5` */
+    rate?: number;
+    /** LFO depth in seconds. @defaultValue `0.002` */
+    depth?: number;
+};
+/** Bit-depth reduction and optional sample-rate decimation. */
+type BitcrusherEffect = {
+    type: "bitcrusher";
+    /** Bit depth. @defaultValue `8` */
+    bits?: number;
+    /** Sample rate reduction factor. @defaultValue `1` */
+    sampleRateReduction?: number;
+    /** @defaultValue `1` */
+    mix?: number;
+};
+/** Dynamics compressor wrapping the native `DynamicsCompressorNode`. */
+type CompressorEffect = {
+    type: "compressor";
+    /** Threshold in dB. @defaultValue `-24` */
+    threshold?: number;
+    /** Knee width in dB. @defaultValue `30` */
+    knee?: number;
+    /** Compression ratio. @defaultValue `4` */
+    ratio?: number;
+    /** Attack time in seconds. @defaultValue `0.003` */
+    attack?: number;
+    /** Release time in seconds. @defaultValue `0.25` */
+    release?: number;
+};
+/** A single band in a parametric EQ. */
+type EQBand = {
+    type: "lowshelf" | "highshelf" | "peaking";
+    /** Center or corner frequency in Hz. */
+    frequency: number;
+    /** Gain in dB. */
+    gain: number;
+    /** Q factor. @defaultValue `1` */
+    Q?: number;
+};
+/** Multi-band parametric equalizer built from chained `BiquadFilterNode`s. */
+type EQEffect = {
+    type: "eq";
+    bands: EQBand[];
+};
+/** Simple gain stage. */
+type GainEffect = {
+    type: "gain";
+    /** Linear gain value. */
+    value: number;
+};
+/** Stereo panner effect. */
+type StereoPanEffect = {
+    type: "pan";
+    /** Pan position from -1 (full left) to 1 (full right). */
+    value: number;
+};
+/** Union of all effect types that can be applied to a {@link Layer} or globally. */
+type Effect = ReverbEffect | ConvolverEffect | DelayEffect | DistortionEffect | ChorusEffect | FlangerEffect | PhaserEffect | TremoloEffect | VibratoEffect | BitcrusherEffect | CompressorEffect | EQEffect | GainEffect | StereoPanEffect;
+/**
+ * A single audio layer combining a source, envelope, filter chain, effects,
+ * LFO modulation, and spatial positioning.
+ */
+type Layer = {
+    /** The audio source that generates the signal. */
+    source: Source;
+    /** One or more filters applied before the envelope. */
+    filter?: Filter | Filter[];
+    /** Amplitude envelope (ADSR). Defaults to a short 0.5 s fade if omitted. */
+    envelope?: Envelope;
+    /** Output gain (0 – 1). @defaultValue `0.5` */
+    gain?: number;
+    /** Stereo pan (-1 left, 0 center, 1 right). */
+    pan?: number;
+    /** 3D spatialization config. Mutually exclusive with `pan`. */
+    panner?: Panner3D;
+    /** Start delay in seconds relative to the sound's trigger time. */
+    delay?: number;
+    /** One or more LFOs for periodic modulation. */
+    lfo?: LFO | LFO[];
+    /** Per-layer effects chain applied after the envelope. */
+    effects?: Effect[];
+};
+/** A sound built from multiple parallel {@link Layer}s with an optional global effects chain. */
+type MultiLayerSound = {
+    layers: Layer[];
+    /** Effects applied to the summed output of all layers. */
+    effects?: Effect[];
+};
+/**
+ * Top-level sound definition: either a single {@link Layer} or a
+ * {@link MultiLayerSound} with multiple layers.
+ */
+type SoundDefinition = Layer | MultiLayerSound;
+/** Handle returned by the engine for stopping an in-flight voice. */
+type VoiceHandle = {
+    /**
+     * Stops the voice with an optional fade-out.
+     *
+     * @param releaseTime - Fade-out duration in seconds. @defaultValue `0.015`
+     */
+    stop: (releaseTime?: number) => void;
+};
+/** Runtime overrides passed when triggering a sound. */
+type PlayOptions = {
+    /** Volume multiplier (0 – 1). */
+    volume?: number;
+    /** Stereo pan override (-1 left, 0 center, 1 right). */
+    pan?: number;
+    /** Detune in cents, added to the source's existing detune. */
+    detune?: number;
+    /** Playback rate multiplier. */
+    playbackRate?: number;
+    /** Velocity sensitivity (0 – 1). Scales gain and can dim filter cutoffs. */
+    velocity?: number;
+    /**
+     * Per-voice random variation applied once on every trigger, so repeated
+     * plays of the same sound don't feel identical. Each field is the maximum
+     * symmetric offset (`±value`). Omitted fields are not jittered.
+     *
+     * @example
+     * ```ts
+     * // ±60 cents of pitch and ±10% volume on every click
+     * click({ jitter: { detune: 60, volume: 0.1 } });
+     * ```
+     */
+    jitter?: {
+        /** Random detune in cents, applied as ±value. E.g. `50` = ±50 cents. */
+        detune?: number;
+        /** Random volume multiplier, applied as ±value (0 – 1). E.g. `0.1` = ±10%. */
+        volume?: number;
+        /** Random playback rate offset, applied as ±value. E.g. `0.05` = ±5%. */
+        playbackRate?: number;
+    };
+};
+/** A single step in a {@link playSequence} timeline. */
+type SequenceStep = {
+    /** A sound definition to render, or a pre-bound play function. */
+    sound: SoundDefinition | ((opts?: PlayOptions) => VoiceHandle | undefined);
+    /** Absolute time in seconds within the sequence. */
+    at?: number;
+    /** Relative offset in seconds from the previous step. */
+    wait?: number;
+    /** Per-step volume override. */
+    volume?: number;
+};
+/** Options for sequence playback. */
+type SequenceOptions = {
+    /** Whether the sequence loops indefinitely. */
+    loop?: boolean;
+    /** Total loop duration in seconds (used when `loop` is true). */
+    duration?: number;
+};
+/** JSON-serializable patch containing named sound definitions. */
+type SoundPatch = {
+    /** Optional JSON Schema reference for validation. */
+    $schema?: string;
+    /** Display name of the patch. */
+    name: string;
+    author?: string;
+    version?: string;
+    description?: string;
+    tags?: string[];
+    /** Map of sound names to their definitions. */
+    sounds: Record<string, SoundDefinition>;
+};
+/** Configuration for creating an {@link AudioAnalyser}. */
+type AnalyserOptions = {
+    /** FFT window size (must be a power of 2). @defaultValue `2048` */
+    fftSize?: number;
+    /** Smoothing between consecutive frames (0 – 1). @defaultValue `0.8` */
+    smoothingTimeConstant?: number;
+    /** Minimum dB range for frequency data. */
+    minDecibels?: number;
+    /** Maximum dB range for frequency data. */
+    maxDecibels?: number;
+};
+
+/**
+ * Wrapper around the native `AnalyserNode` with pre-allocated typed arrays
+ * for zero-allocation reads in animation loops.
+ */
+type AudioAnalyser = {
+    /** The underlying Web Audio `AnalyserNode`. */
+    node: AnalyserNode;
+    /** Returns byte-scaled frequency magnitudes (0 – 255). */
+    getFrequencyData: () => Uint8Array;
+    /** Returns byte-scaled time-domain waveform (0 – 255). */
+    getTimeDomainData: () => Uint8Array;
+    /** Returns frequency magnitudes in dB. */
+    getFloatFrequencyData: () => Float32Array;
+    /** Returns time-domain waveform as floats (-1 to 1). */
+    getFloatTimeDomainData: () => Float32Array;
+    /** Number of frequency bins (half of `fftSize`). */
+    frequencyBinCount: number;
+    /** Disconnects the analyser and releases resources. */
+    dispose: () => void;
+};
+
+/**
+ * A loaded sound patch with methods to play individual sounds by name.
+ *
+ * @example
+ * ```typescript
+ * const patch = await loadPatch("https://example.com/ui-sounds.json");
+ * patch.play("click");
+ * ```
+ */
+type AudioPatch = {
+    /** `true` once the patch data has been loaded and parsed. */
+    ready: boolean;
+    name: string;
+    author?: string;
+    version?: string;
+    description?: string;
+    tags?: string[];
+    /** Names of all sounds contained in this patch. */
+    sounds: string[];
+    /**
+     * Plays a named sound from the patch.
+     *
+     * @param name - Sound name (must exist in {@link sounds})
+     * @param opts - Runtime overrides
+     * @throws {Error} If the sound name is not found in the patch
+     */
+    play: (name: string, opts?: PlayOptions) => VoiceHandle;
+    /** Returns the raw {@link SoundDefinition} for a named sound, or `undefined`. */
+    get: (name: string) => SoundDefinition | undefined;
+    /** Returns a deep-cloned copy of the underlying {@link SoundPatch} data. */
+    toJSON: () => SoundPatch;
+};
+
+/**
+ * Context provider that controls global sound state for all descendant hooks.
+ *
+ * Wrap your app (or a subtree) with `<SoundProvider>` to enable
+ * {@link useSound}, {@link useSequence}, and {@link usePatch} to respect
+ * a shared enabled/volume state.
+ *
+ * @param props.enabled - Whether sounds are allowed to play. @defaultValue `true`
+ * @param props.volume - Master volume multiplier (0 – 1). @defaultValue `1`
+ * @param props.onEnabledChange - Called when a child requests an enabled change
+ * @param props.onVolumeChange - Called when a child requests a volume change
+ *
+ * @example
+ * ```tsx
+ * <SoundProvider enabled={soundsOn} volume={0.8}>
+ *   <App />
+ * </SoundProvider>
+ * ```
+ */
+declare function SoundProvider({ children, enabled, volume, onEnabledChange, onVolumeChange, }: {
+    children: React.ReactNode;
+    enabled?: boolean;
+    volume?: number;
+    onEnabledChange?: (enabled: boolean) => void;
+    onVolumeChange?: (volume: number) => void;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Returns a stable callback that plays the given sound definition.
+ *
+ * Respects the nearest {@link SoundProvider}'s enabled/volume state and
+ * the user's `prefers-reduced-motion` preference. The callback reference
+ * never changes between renders (values are read from refs).
+ *
+ * @param definition - The sound to play
+ * @param opts - Default play options (can be overridden at call time)
+ * @returns A function that triggers the sound and returns a {@link VoiceHandle}, or `undefined` if muted
+ *
+ * @example
+ * ```tsx
+ * const play = useSound({
+ *   source: { type: "sine", frequency: 440 },
+ *   envelope: { decay: 0.1 },
+ * });
+ *
+ * <button onClick={play}>Beep</button>
+ * ```
+ */
+declare function useSound(definition: SoundDefinition, opts?: PlayOptions): () => VoiceHandle | undefined;
+/**
+ * Returns stable `play` and `stop` callbacks for a sound sequence.
+ *
+ * Calling `play()` starts the sequence; calling `stop()` halts it.
+ * Both callbacks are referentially stable across renders.
+ *
+ * @param steps - Ordered list of {@link SequenceStep}s
+ * @param options - Loop and duration settings
+ * @returns An object with `play` and `stop` functions
+ */
+declare function useSequence(steps: SequenceStep[], options?: SequenceOptions): {
+    play: () => void;
+    stop: () => void;
+};
+/**
+ * Creates and returns an {@link AudioAnalyser} connected to the master bus.
+ *
+ * The analyser is initialized once (lazy state) and automatically disposed
+ * when the component unmounts.
+ *
+ * @param opts - FFT size, smoothing, and dB range overrides
+ */
+declare function useAnalyser(opts?: AnalyserOptions): AudioAnalyser;
+/**
+ * Loads a sound patch and returns a context-aware {@link AudioPatch}.
+ *
+ * The returned patch's `play()` method automatically respects the nearest
+ * {@link SoundProvider}'s enabled/volume state and reduced-motion preference.
+ * While the patch is loading, an empty no-op patch is returned (`ready: false`).
+ *
+ * @param source - URL string or in-memory {@link SoundPatch} object
+ * @returns An `AudioPatch` (initially empty until loaded)
+ *
+ * @example
+ * ```tsx
+ * const patch = usePatch("https://example.com/ui.json");
+ *
+ * <button onClick={() => patch.play("click")}>Click</button>
+ * ```
+ */
+declare function usePatch(source: string | SoundPatch): AudioPatch;
+/**
+ * Synchronizes the 3D audio listener with the given position and orientation.
+ *
+ * The effect only re-runs when individual primitive values change, not when
+ * the `listener` object reference changes.
+ *
+ * @param listener - Listener position and orientation
+ */
+declare function useListener(listener: Listener): void;
+
+export { SoundProvider, useAnalyser, useListener, usePatch, useSequence, useSound };