Introduction
An audio waveform player that fits the way you build.
raavl is a TypeScript audio waveform player and annotation toolkit for vanilla JavaScript and React. It separates the playback controller, Canvas waveform, and annotation data so you can compose your own experience.
Choose a complete React AudioPlayer, compose connected controls inside PlayerRoot, or build your own UI with headless hooks and the JavaScript controller. There is no Shadow DOM.
Start here
- Quickstart: add your first waveform in JavaScript or React.
- Skills: a reusable integration workflow for your coding agent.
- Try the live player: play the bundled audio or open a local file.
- Explore all examples: the complete gallery, including the theme builder, annotations, optional modules, and scale lab.
- Styling and themes: keep the player consistent with your app.
What is available
| Area | Capabilities |
|---|---|
| Playback | URL, File/Blob, existing media, play/pause, seeking, volume, speed, looping |
| Waveforms | Min/max peaks, browser decoding, supplied peaks, line/bars, multiple channels |
| Navigation | Fit or numeric zoom, scrolling, playhead following, timeline, minimap |
| Annotations | Regions, markers, labels, selections, dragging, resizing, locks |
| Editing | Controlled documents or a store, validated JSON, grid/magnetic snapping, undo/redo |
| Integration | Typed ESM, optional React adapter, SSR-safe imports, optional CSS |
Browser support
Recording and spectrograms are not implemented. Playback uses the browser's media APIs; range loops use best-effort browser timing.
How the pieces fit
- A player owns or borrows the audio element, loads sources, and exposes state and commands.
- A view borrows that player and draws its waveform. Multiple views can share a player.
- Annotations hold source-bound regions and markers, separately from the audio.
- React controls share a root controller;
AudioPlayerassembles the default layout. Your application can replace the UI and owns persistence.