SonicFrame v1.3.2

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));