SonicFrame v1.3.2

Markers

Flags on moments of the sound: chapters, comments, the places a teacher wants a student to hear. A click jumps to one, and M steps through them.

Adding markers

import { markers } from 'sonicframe';

const flags = markers({
    items: [
        { time: 2.4, label: 'Title' },
        { time: 9, label: 'Second line' },
        { time: 21, label: 'Last lines', color: 'var(--danger)' },
    ],
});
frame.use(flags);

flags.set([3, 18]); // replace them; plain times work too

Times are in seconds, so markers stay in place when the wave changes size; nothing is drawn while the length is unknown. Markers that crowd together become one pill with a count. flags.items gives them back, in the order given.

Options

Option What it does
items The moments to mark, each { time, label, color, id }; only time (in seconds) is needed.
color Any CSS color or var(--name) for a plain marker.
width Line width in CSS pixels.
groupDistance Markers closer than this many pixels become one pill (12; 0 never groups).
snap A click on a marker seeks to its exact moment.
tooltip Show a tooltip on hover.
keys M and Shift + M (on by default); false turns them off. { letter, backGrace } changes them.
keys.letter Your own letter in place of M ('m'); false turns the keys off.
keys.backGrace Seconds after a marker within which Shift + M goes to the one before (1; 0 lands on it).
onSelect Called with the markers chosen by a click or a key.
max The most markers kept (2000, also the ceiling; anything that is not a number is 2000).
a11y.tooltip.readable Writes the tooltip's text in black or white, whichever reads on its color (4.5:1), as the caption does. Off: the page's color for text on the played color (--sonicframe-on-progress).
a11y.words Your own words over the frame's language: { more, none }: more is the tooltip's last line when a group has more than five markers ("and {count} more"), none what the keys say with no marker that way ("No more markers").

Keys

With the wave focused, M goes to the next marker and Shift + M to the previous, like a player's tracks. Past the last one (or before the first) they say "No more markers". Zoomed in, a marker reached by a key comes into view. Caps Lock changes nothing.

import { PlayButton, SonicFrame, loadWaveform, markers } from 'sonicframe';

const box = document.querySelector('#markers-keys');
box.style.display = 'flex';
box.style.alignItems = 'center';
box.style.gap = '0.75rem';
const media = new Audio('./sounds/little-elf.mp3');

PlayButton.create({ container: box, media });
const wave = document.createElement('div');
wave.style.flex = '1';
wave.style.height = '4rem';
box.append(wave);
const frame = new SonicFrame({
    container: wave,
    media,
    peaks: () => loadWaveform('./sounds/little-elf.dat'),
});

const items = [
    { time: 2.4, label: 'Title' },
    { time: 9, label: 'Second line' },
    { time: 21, label: 'Last lines' },
];
frame.use(markers({ items, keys: { letter: 'k', backGrace: 2 } })); // K and Shift+K

Export and import

Markers go out and come back in the same four formats as regions: JSON, WebVTT, CSV and Audacity's labels, where a marker is a point label. In WebVTT each marker lasts until the next one, and the last until duration (a second without it), so the file serves as chapters.

import { chapters, readMarkers, writeMarkers } from 'sonicframe';

const csv = writeMarkers(flags.items, { format: 'csv' });
flags.set(readMarkers(await file.text())); // a region file gives its starts

const vtt = writeMarkers(flags.items, { format: 'vtt', duration: frame.duration });
frame.use(chapters({ text: vtt })); // the markers as chapters