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+KExport 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