Writing a plugin
Every built-in feature beyond the bars is a plugin, and yours get the same tools: draw under or over the bars, take presses and keys, add lanes, and speak to screen readers.
The shape of a plugin
import { PlayButton, SonicFrame, loadWaveform } from 'sonicframe';
const box = document.querySelector('#plugin-glow');
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 playhead = {
name: 'playhead-glow',
layer: 'over', // or 'under', before the bars
setup(_host) {
// Called once; keep the host to ask for a redraw later.
},
draw(paint) {
const x = paint.xAt(paint.progress);
const ctx = paint.ctx;
ctx.fillStyle = paint.color('var(--sonicframe-progress, #2f6fdb)');
ctx.fillRect(
x - 2 * paint.pixelRatio,
0,
4 * paint.pixelRatio,
paint.height,
);
},
destroy() {},
};
frame.use(playhead); // returns the function that removes it
A plugin is an object with a name and any
of the hooks below. One that throws from any hook is
parked and the error event says why, so one
broken plugin never breaks the wave.
Hooks
| Hook | When |
|---|---|
setup(host) |
Once, when added. |
draw(paint) |
Every repaint, in device pixels. |
resize(geometry) |
The wave changed size. |
pointerDown,
pointerMove,
pointerUp,
pointerCancel
|
Presses.
pointerDown returns
'take' to own it now, or
'drag' to own it once it
moves (a tap still seeks).
|
pointerHover |
The pointer moved; return a CSS cursor. |
keyDown |
Before the slider keys; return whether you used the key. |
valueNote(time, ratio) |
A short note added to the wave's value in words. |
destroy() |
Removed, or the frame destroyed. |
What paint gives
The canvas context, ctx, in device pixels,
width, height,
pixelRatio, progress,
duration, hover,
view, xAt(ratio),
ratioAt(x) and color(value)
(any CSS color or variable, resolved).
What host gives
| Member | What it does |
|---|---|
container,
media, peaks,
duration,
progress,
geometry, view
|
The frame's state. |
lang |
The tag of the frame's language ('en'
unless the app picks one), to choose
your own words by. See
Languages.
|
invalidate() |
Ask for a repaint. |
on(event, listener) |
The frame's events. |
color(value) |
Resolve a color. |
addLane(side, px) |
A strip above or below the bars; the wave shrinks. |
overlay() |
A layer over the bars, for text. |
seekTo(ratio, source) |
Seek; pass 'keyboard' for a
key's seek, so the view follows it.
|
setView(start, end, source)
|
Move the view (zoom on). |
playRange(start, end),
stopRange()
|
Play a stretch. |
setValues(values) |
Override the bar heights (null
gives them back).
|
announce(text) |
Say something through the shared live region. |
updateValueText() |
Ask for the wave's value in words again. |
reportError(error) |
A failure outside the hooks (a
download), heard as error.
|
Ready for zoom
Place things with paint.xAt(ratio), which
goes through the view (a position out of view lands off
the canvas), and read presses from
point.ratio and point.time,
which are already the sound's. Listen to
host.on('viewchange', …) when something
outside the canvas must follow the view.
Accessible by design
-
Anything a press does, a key should do too
(
keyDown). -
Say what changed with
host.announce, briefly, and only after the person acted. -
Add to the wave's value with
valueNoteinstead of a new live message when it describes the position. -
Put text in as text (
textContent), never as HTML.