SonicFrame v1.3.2

Frame methods and events

Everything a frame does after it is made, plus the two controls that come with it: the play button and the volume control.

Methods

Method What it does
SonicFrame.create(options) Same as new SonicFrame(options).
setPeaks(source) New peaks: a list, { peaks, duration }, a loader or null.
bind(media) Follow another media element, or none.
setDuration(seconds) The length to use until the media knows its own.
setProgress(ratio) The position shown while no media is bound.
seekTo(ratio) Move there (the media too) and emit seek.
setView(start, end) Show part of the sound; zoom on only.
zoomTo(level, at?) Zoom to a level around a ratio (or the anchor).
zoomBy(factor, at?) Zoom in (above 1) or out (below 1).
scrollTo(start) Move the view to begin at a ratio, keeping its size.
setBar(bar), setWave(wave), setColors(colors) Change part of the look.
setLabel(label) Change the accessible name.
refresh() Read the colors again after your own theme switch.
exportClip(options) Record a video of a stretch; see clips.
use(plugin) Add a plugin; returns the function that removes it.
on(event, listener) Listen; returns the function that stops.
destroy() Remove everything SonicFrame added. Safe to call twice.

In what unit

Unit Taken by
A ratio: 0 is the start of the whole sound, 1 its end setProgress, seekTo, setView, scrollTo, and the at of zoomTo and zoomBy
Seconds setDuration
A zoom level: 1 shows the whole sound, 2 half of it zoomTo
A factor of the level: 2 zooms in twice as close, 0.5 back out zoomBy

To go to a moment in seconds, divide by the length: frame.seekTo(42 / frame.duration).

Properties

progress (0 to 1), duration (seconds or null), time (seconds or null), peaksDuration, peaks, container and view ({ start, end, level, maxLevel }, the whole sound while zoom is off), all read-only.

time is where the sound is: the media's own time, or, before the media loads (preload="none"), where a seek will start it, while the media itself still says 0. Show it rather than media.currentTime, written by formatPosition(time, duration): a seek can land a hair before the time it asked for (an MP3 asked for 0:15 can start at 14.998), and formatPosition shows that as 0:15, where formatTime would show 0:14.

For more than whole seconds, formatClock(time, clock) writes a time as the player's precise clock does: clock is { precision, fps, hours, decimal, digits, format }, each optional, read as the look's timePrecision, timeFps, timeHours, timeDecimal, timeDigits and timeFormat (decimal is '.' or ','). Tenths, hundredths and milliseconds are rounded to the nearest, a frame is the one the sound is in: formatClock(65.25, { precision: 'hundredths' }) is 1:05.25, and formatClock(65, { format: 'hh[h]mm[m]ss[s]' }) is 00h01m05s. See A precise clock.

Events

Event Arguments When
seek { ratio, time, source } A click, drag, key or seekTo; source is 'pointer', 'keyboard' or 'api'.
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 got its pixels.
rangeend A played range ended or was abandoned.
viewchange view, source The view moved: 'api', 'wheel', 'keys', 'pinch', 'follow', 'edge', 'minimap' or 'button'.
error error Loading peaks or a plugin's work failed.
destroy The frame was destroyed.

The play button

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

const box = document.querySelector('#frame-play');
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,
    shape: 'circle',
    fill: 'solid',
    size: 32,
});
const wave = document.createElement('div');
wave.style.flex = '1';
wave.style.height = '4rem';
box.append(wave);
new SonicFrame({
    container: wave,
    media,
    peaks: () => loadWaveform('./sounds/little-elf.dat'),
});
Option Default What it does
container (required) Where the button goes.
media null What it plays and pauses (disabled without one).
shape 'circle' 'circle', 'rounded' or 'square'.
fill 'solid' 'solid', 'outline' or 'ghost'.
size 32 CSS pixels.
radius null Corner radius instead of the shape's own.
colors the theme's { background, icon }.
exclusive true Starting this media pauses every other exclusive one.
a11y.lang 'en' The language of the names; see Languages.
a11y.words Play / Pause { play, pause }, the accessible names, over the language's.

setLook, bind, on('error', …) (the browser refused to play) and destroy.

The volume control

import { PlayButton, VolumeControl } from 'sonicframe';

const box = document.querySelector('#frame-volume');
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 });
VolumeControl.create({ container: box, media, slider: 'hover' });
Option Default What it does
container, media Where it goes, and what it controls.
slider 'always' 'always' or 'hover' (opens on hover or focus).
size 32 The speaker button, CSS pixels.
width 80 The bar's width, CSS pixels.
step 0.05 How far an arrow key moves the level.
colors the theme's { icon, track, fill }.
a11y.lang 'en' The language of the names; see Languages.
a11y.words the language's { mute, unmute, volume }, and muted, the slider's value while muted.

It follows the media's own volume and muted, so other controls stay in step. Where a page cannot set the volume (iOS), only the mute button shows.