Quickstart
In five steps you will have a waveform that plays with its sound, seeks on a click, a drag or the keyboard, and follows your page's colors. It takes about five minutes.
Before you start
You need:
- a page you can edit, with a bundler (Vite, webpack, Next.js…) or plain HTML;
-
a sound file the page can reach, such as
/voice.mp3; - basic HTML and JavaScript. No framework is needed, and any framework works.
1. Install SonicFrame
npm install sonicframe
No bundler? Skip this step and import from a CDN, as Installation shows.
2. Add the sound and a place for the wave
The wave is drawn inside any element you give it. The element keeps its size from your CSS, so give it a height.
<audio id="voice" src="/voice.mp3" preload="metadata"></audio>
<div id="wave" style="height: 3rem"></div>
3. Draw the wave
Create a frame on the element and bind it to the audio.
peaks are the loudest points of the sound,
numbers from 0 to 1. Here they come from a small JSON
file, a list of numbers or
{ peaks, duration }.
loadWaveform reads that, or a ready-made
waveform file, and gives the peaks with their duration.
Peaks shows every way to make
them.
import { SonicFrame, loadWaveform } from 'sonicframe';
const frame = new SonicFrame({
container: document.getElementById('wave'),
media: document.getElementById('voice'),
peaks: () => loadWaveform('/voice.peaks.json'),
a11y: { label: 'Voice note' },
});
4. Add a play button
import { PlayButton } from 'sonicframe';
PlayButton.create({
container: document.getElementById('controls'),
media: document.getElementById('voice'),
});
It is a real <button>: it works with
the keyboard, and screen readers hear "Play" and
"Pause".
5. Or take the whole player at once
Steps 2 to 4 in one call: the play button, the wave and the time, made from the sound's address alone.
import { createPlayer } from 'sonicframe/player';
createPlayer({
container: document.getElementById('player'),
src: '/voice.mp3',
});
Or with no JavaScript of your own, as a tag:
<sonic-player src="/voice.mp3"></sonic-player>
<script type="module">
import { defineSonicPlayer } from 'sonicframe/player';
defineSonicPlayer();
</script>
Try it
This is the result. Press play, click anywhere on the wave, or press Tab until the wave is focused and use the arrow keys, Home and End.
If something is off
-
Nothing shows. The container has no
height. Give it one in CSS (
height: 3rem). -
A thin line instead of bars. The
peaks have not arrived: check the peaks address in
the network panel, and listen to the frame's
errorevent. -
The time says 0:00. The audio has
not loaded its metadata yet. Use
preload="metadata", or pass the length asduration. -
Colors look wrong in dark mode. Set
the
--sonicframe-*variables for your dark scheme; see Colors and CSS.
Next steps
- Player basics: the ready-made player and its parts.
- Themes and palettes: a whole look in one word.
- Accessibility: what is built in, and what to turn on.