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.