useWaveform
Headless waveform composable. Decodes the audio file referenced by a reactive URL ref, downsamples its channel-0 amplitude data into a configurable number of normalised peaks (default 200), and exposes the result as a reactive array. SSR-safe. Recomputes automatically when the source URL changes. Errors are captured reactively instead of thrown.
API
Signature
Signature TypeScript complète extraite du fichier du composable.
useWaveform uses OfflineAudioContext to decode the full audio file off-line (without requiring playback). The fetch uses `cache: "force-cache"` so the waveform decode and the player stream typically reuse the same network cache entry. Feature-detects and falls back to webkitOfflineAudioContext for older Safari.
Interfaces consommées
API
Paramètres
Paramètres d'entrée acceptés par ce composable.
- srcRefrequisRef<string | undefined | null>
- Reactive reference to the audio file URL. The composable watches this ref and re-triggers computation whenever the value changes. null / undefined clears the peaks array.
- optionsIUseWaveformOptions{}
- Optional: `bins` (number of peaks to produce, default 200) and `crossOrigin` ("use-credentials" | undefined) for the fetch credentials policy.
API
Valeurs de retour
Propriétés et méthodes exposées par l'objet retourné par le composable.
- peaks
- Array of `bins` values in [0, 1], where 1 is the loudest bucket in the track. Empty while computing or on error.
- isComputing
- True while the fetch + decode round-trip is in progress. Use to render a skeleton or loading indicator.
- error
- Captures fetch errors (non-2xx response), decode errors (corrupt / unsupported audio), and OfflineAudioContext unavailability. null when no error.
- compute
- Manually trigger a recomputation. Normally not needed — the composable re-runs automatically when srcRef changes. Useful for retry-on-error flows.
Usage
Exemples
Extraits de code prêts à coller.
Waveform thumbnail for a playlist track
Using OrigamAudio (recommended)