useAudio
Commons
stable
Wire an <audio> element to the Web Audio API for frequency analysis and playback control. Tracks play/pause state, creates an AnalyserNode on first play to feed real-time frequency data (Uint8Array), and reacts to prop changes to reset playback when the audio source changes.
API
Signature
Full TypeScript signature sourced from the composable file.
useAudio is the low-level Web Audio API bridge. <OrigamAudio> wraps it with a full playback UI and waveform visualiser. Use useAudio directly only when building custom audio UIs.
Consumed interfaces
IUseAudioProps
API
Parameters
Input parameters accepted by this composable.
- propsrequiredIUseAudioProps
- Props object with audio (URL of the audio source) and playAudio (boolean flag). When playAudio changes to true the composable calls onPlay(); when it changes to false it calls onStop(). When audio changes, wasPlayed and isPlaying are reset.
API
Return values
Properties and methods exposed by the composable return object.
- audioData
- Shallow ref holding the AnalyserNode's frequency-bin byte array. Updated every animation frame while playing. Bind to a visualiser (e.g. OrigamAudio waveform bars).
- analyser
- The Web Audio AnalyserNode created on first play. Null until onPlay() is called at least once. fftSize is fixed at 256 (128 frequency bins).
- audioRef
- Template ref to assign to the native <audio> element. The composable calls .play() and .pause() on it.
- wasPlayed
- True after the first play invocation. Used to create the AudioContext only once per audio source — re-creating it on every play would leak nodes.
- isPlaying
- Reactive playback state. True while the audio is playing and the animation loop is running.
- onPlay
- Start playback. Creates the AudioContext on first call, starts the requestAnimationFrame loop to fill audioData, and sets isPlaying to true.
- onStop
- Pause playback, stop the animation loop, and set isPlaying to false.
Usage
Examples
Ready-to-paste usage snippets.
Basic audio player with frequency visualiser