Player basics
createPlayer puts a play button, the wave and
the time together, and anything else you ask for: speed,
skip buttons, volume, zoom, a minimap. It lives on its own
entry, so an app that only draws waves never loads it.
One call
import { createPlayer } from 'sonicframe/player';
const player = createPlayer({
container: document.querySelector('#player'),
src: '/notes/42.ogg',
});
Given only src, the player makes its own
<audio> and decodes the peaks in the
browser the first time it comes near the screen. Give
peaks (a list, a file loader, or
{ peaks, duration }) to skip the decoding,
and preload: 'none' to load no audio until
play.
Your own media element
Pass media instead of src to
drive an element you already have, a video included. The
player never stops or removes an element it did not
make.
createPlayer({ container, media: document.querySelector('video') });
The parts
A player is a line of parts. The default line is
['play', 'wave', 'time']; add any of these:
| Part | What it is |
|---|---|
play |
The play button. |
wave |
The wave (always there). |
time, elapsed,
remaining,
duration
|
The time, as the look's
time says, or one of its
forms.
|
speed |
Steps through the speeds
(1×, 1.5×,
2×).
|
back, forward
|
Skip a few seconds (the look's
skip, 10).
|
volume |
The volume control; also
volume: true.
|
zoomIn,
zoomOut,
zoomReset
|
Zoom buttons; also
zoom: { buttons: true }.
|
chapter |
The chapter playing, by name; only with chapters. |
previousChapter,
nextChapter
|
The previous chapter (like a previous track) and the next one. |
chapters |
Opens and closes the list of chapters;
only with chapters.list.
|
previousTrack,
nextTrack
|
The track before and after; only for a
player given tracks, each
for the way it is given.
|
title |
The sound's name: the player's
a11y.label, or without one
its file's name (the look's
titleFromFile). Screen
readers hear it on the player already,
so they skip the part.
|
artist |
The player's artist, as
text; skipped by screen readers too.
|
slot |
Your own element (an avatar, say), given back on destroy. |
spacer |
Pushes the next parts to the end. |
createPlayer({
container,
src,
look: { line: ['play', 'back', 'wave', 'forward', 'time', 'speed'] },
});
Parts and layouts covers the rest of the look: sizes, the line under the wave, the wave on top, and the voice-note arrangement on phones.
Changing it later
| Method | What it does |
|---|---|
setTheme(name) |
Another theme; your own options still win. |
setLook(look) |
Part of the look (rebuilds the player). |
setTracks(tracks) |
Other tracks around the sound (rebuilds the player); with none, the track buttons go. |
setPalette(palette) |
Other colors; with no palette, the theme's come back. |
setWave(wave) |
Another drawing; with none, the theme's comes back. |
setFont(font) |
Another font. |
setBar(bar) |
The bars' density and shape; with no bars, the theme's come back. |
setLabel(label) |
The player's accessible name; with no
name, 'Audio player' in its
language comes back.
|
showVolume(show) |
Shows or hides the volume control. |
forget() |
Clears what
remember
kept under the player's name.
|
on(event, listener) |
The wave's events, plus
descriptionchange,
chapterchange and
resume.
|
destroy() |
Gives the container back; a media element the player made is stopped. |
player.frame,
player.button and
player.volume reach the parts, and
player.description gives the sound in words
when it is on.
Next steps
- Themes and palettes: a whole look in one word.
- The HTML tag: the same player with no JavaScript of your own.
- Player options: every option.