Events
on(event, listener) listens and gives back the
function that stops listening. Events never fire once per
animation frame, so listening is cheap.
Listening
import {
PlayButton,
SonicFrame,
formatPosition,
loadWaveform,
} from 'sonicframe';
const box = document.querySelector('#events-clock');
const media = new Audio('./sounds/little-elf.mp3');
const row = document.createElement('div');
row.style.display = 'flex';
row.style.alignItems = 'center';
row.style.gap = '0.75rem';
const clock = document.createElement('p');
clock.textContent = 'Press play, or click the wave.';
box.append(row, clock);
PlayButton.create({ container: row, media });
const wave = document.createElement('div');
wave.style.flex = '1';
wave.style.height = '4rem';
row.append(wave);
const frame = new SonicFrame({
container: wave,
media,
peaks: () => loadWaveform('./sounds/little-elf.dat'),
});
frame.on('timeupdate', (time) => {
clock.textContent = formatPosition(time);
});
frame.on('error', (error) => {
clock.textContent = `Something went wrong: ${error.message}`;
});
The player has the same on, with every
frame event plus description; the
<sonic-player> tag dispatches them as
DOM events named sonicframe:seek,
sonicframe:timeupdate and so on, with the
arguments in event.detail.
Every event
| Event | Arguments | When |
|---|---|---|
seek |
{ ratio, time, source }
|
A click, a drag, a key or
seekTo moved the position.
|
hover |
ratio, time |
The mouse moved over the wave (null
when it left).
|
timeupdate |
time, ratio |
The media moved, at its own pace. |
durationchange |
duration |
The length became known or changed. |
peakschange |
peaks |
The peaks arrived, were replaced or went. |
resize |
geometry |
The wave changed size, or a lazy frame got its pixels. |
rangeend |
A range being played ended or was abandoned. | |
viewchange |
view, source |
The view moved (zoom on), and what moved it. |
error |
error |
Loading peaks or a plugin's work failed. |
destroy |
The frame was destroyed. |
The ready-made player tells these too, and three of its
own: descriptionchange (the sound in
words), chapterchange (the chapter playing)
and resume (time: a sound
resumed where it was left, with
remember). On <sonic-player> each one is
sonicframe:<event>.
Errors never break the page
A failed download, a plugin that throws, a peaks file
that does not parse: each one reaches the
error event, and the rest of the frame
keeps working. A plugin that throws is parked, so one
broken plugin never breaks the wave.
frame.on('error', (error) => report(error));