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; }; /** 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; }; /** 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 `` 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 * * * * ``` */ 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 }, * }); * * * ``` */ 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"); * * * ``` */ 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 };