SonicFrame v1.3.2

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 valueNote instead of a new live message when it describes the position.
  • Put text in as text (textContent), never as HTML.