SonicFrame v1.3.2

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' },
});
No peaks file yet? The ready-made player decodes the sound in the browser for you. Step 5 shows it.

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 error event.
  • The time says 0:00. The audio has not loaded its metadata yet. Use preload="metadata", or pass the length as duration.
  • Colors look wrong in dark mode. Set the --sonicframe-* variables for your dark scheme; see Colors and CSS.

Next steps