Player options
Every option of createPlayer(options) from
sonicframe/player. Your own options always win
over the theme's.
Options
| Option | Default | What it does |
|---|---|---|
container |
(required) | The element the player is added to. |
src |
none |
The sound's address; the player makes
its own <audio>.
|
preload |
'metadata' |
'none' loads nothing until
play; 'auto'.
|
media |
none | Your own audio or video element instead. |
peaks |
decoded | Peaks or a loader, as for the frame. |
duration |
none | The length, until the media knows its own. |
theme |
none |
A theme's name, or one from
defineTheme.
|
look |
see Parts and layouts | How the player is put together. |
palette |
the theme's |
A name, 'auto',
'default' or your own
colors.
|
wave, bar |
'bars' |
How the sound is drawn. |
font |
the look's |
A stack name, a
font-family list, or
{ family, src, stylesheet, fallback
}.
|
volume |
false |
Show the volume control. |
spectrogram |
false |
A spectrogram under the wave (the sound is decoded once). |
zoom |
false |
The
zoom options, plus buttons.
|
minimap |
false |
true or the
minimap options.
|
chapters |
off |
A chapters file's address, a list, or
the
chapters options
plus list.
|
mediaSession |
off |
The lock screen and the media keys:
true, or the
media session options. Titled by a11y.label,
skipping look.skip.
|
tracks |
none |
The tracks around the sound, for a
player in a list:
{ previous, next, hasPrevious,
hasNext }. With them, the
previousTrack and
nextTrack parts, the
N key and the media controls
go from track to track. A track that is
not there leaves its button unavailable.
|
artist |
none |
Who made the sound, shown by the
artist part, and the media
controls' artist when
mediaSession names none.
Shown as text, one line, up to
maxText characters.
|
maxText |
120 |
The longest name, artist, word or media
controls' detail shown, in characters,
from 1 to 1000. Past either end, a
RangeError names it.
|
decode |
see below | How a sound is decoded for its peaks. |
slot |
none |
Your element for the
slot part.
|
keys |
off |
The player's own keys:
true, or each key your own
and scope; see
Keyboard.
|
remember |
off |
Remember where each sound was left, the
volume and the speed between visits:
true, or the options below.
|
loadError |
on |
When the sound cannot load, a message
over the wave says why, in the player's
language: false or
{ show: false } turns it
off. The error event goes
out either way, with a
SoundError whose
reason is
'network',
'unsupported',
'decode' or
'aborted'.
|
plugins |
[] |
Plugins on the wave. |
a11y |
{} |
See below. |
frame |
{} |
Any other frame option
(lazy, colors,
stepSeconds…).
|
When two options say the same thing
A few things can be given in two places. This is which one wins:
| What | Wins | Over |
|---|---|---|
| The zoom | zoom |
frame.zoom |
| Saying the view after a zoom | a11y.zoom.announce |
frame.a11y.zoom.announce
|
| The minimap as a keyboard slider | a11y.minimap.keys |
minimap.a11y.keys |
| The minimap's height and space |
minimap.height,
minimap.gap
|
The look's
minimapHeight,
minimapGap
|
| Words of the zoom and the minimap |
frame.a11y.zoom.words,
minimap.a11y.words
|
The player's language |
| The player's name | a11y.label |
The player's language |
| The title on the lock screen | mediaSession.title |
a11y.label |
| Any part of the look, the colors |
look, palette,
wave, font
|
The theme's |
Accessibility, a11y
| Option | Default | What it does |
|---|---|---|
lang |
'en' |
'pt', 'pt-PT',
'es', 'fr', a
registered one, or
'auto' (see
Languages); the plugins speak it too, and it
marks the player with lang.
|
label |
'Audio player' |
The player's accessible name, in its
language by default.
setLabel(label) changes it
later.
|
words |
the language's | Your own names and words; see Your own words. |
description |
off |
true, or the
wave in words options
plus button.
|
description.button |
off |
A button that reads it aloud;
{ animation, animationType }
(off, 'pulse').
|
zoom.announce |
false |
Say the new view after a zoom. |
minimap.keys |
false |
The minimap as a keyboard slider. |
keys.announce |
false |
Say what the player's keys change: the volume ("Volume 55%"), the speed, and the place after a skip. |
remember.announce |
false |
Say where a sound resumes, at its first play ("Resuming at 12:30"). |
loadError.announce |
true |
Say why the sound cannot load ("Could not load the sound"), so a person who cannot see the player learns it too. |
sliderName |
'position' |
What names the wave's slider: its word
("Playback position"),
'label' the sound's name,
or 'both' ("Little Elf,
Playback position"). The sound's name is
the one the title part
shows; without one, the slider keeps its
word. frame.label wins.
|
Remembering, remember
A long sound resumes where it was left, and the volume and the speed come back, from one visit to the next. A sound left near its end, or one that ended, starts over; one already under way stays where it is.
| Option | Default | What it does |
|---|---|---|
position,
volume,
speed
|
true |
What to remember;
false leaves one out.
volume
keeps the mute too.
|
key |
'player' |
The name it is kept under (as
sonicframe:player): players
with the same name share their volume
and speed.
|
sound |
the sound's address | The sound's own name for its position, such as an episode's id. |
store |
localStorage |
Where it is kept: any object with
getItem,
setItem and
removeItem, such as
sessionStorage or your own.
|
sounds |
50 |
How many sounds keep their position, the oldest dropped first; from 1 to 5000. |
nearEnd |
5 |
A sound left this many seconds or less from its end starts over; from 0 to 60. |
The position is kept on a pause, a seek, about every 5 seconds of playing and when the page closes. Where the storage is blocked or full (a private window, say), the player plays on without remembering.
Decoding, decode
| Option | Default | What it does |
|---|---|---|
peakCount |
1000 |
Peaks a decoded sound gets (100 to 100,000). |
peaksPerSecond |
100 |
With zoom on, a long sound gets more (up to 1,000,000). |
maxSeconds |
30 minutes | The longest sound read, in seconds, up to 36,000 (10 hours); a longer one is read evenly through. The browser decodes the whole file first, so this saves no memory. |
maxBytes |
50 MiB |
The largest file decoded, up to
268,435,456 bytes (256 MiB). A decoded
hour takes about 635 MB, and a browser
tab falls over past a few GB, sooner on
a phone: for long sounds, give the
player peaks made on a server, or turn
on stream.
|
stream |
false |
true or the options below:
the sound is read in pieces as it
downloads, keeping only its peaks, so
hours fit in a tab. A sound it cannot
read so is decoded whole as above. See
Long sounds.
|
Reading in pieces, decode.stream
| Option | Default | What it does |
|---|---|---|
maxBytes |
1 GiB |
The most bytes downloaded for the peaks,
from 1 to 4,294,967,296 (4 GiB); a
larger sound stops there, with the
player's error event.
|
maxSeconds |
10 hours |
The most seconds read, from 1 to 86,400
(24 hours); the rest of a longer sound
is drawn as silence. Past either end of
either ceiling, a
RangeError names the option
when the player is made.
|
progressive |
true |
The wave grows while the peaks come;
false draws it once, at the
end.
|
webcodecs |
'auto' |
'auto' uses the browser's
WebCodecs decoder where it has one;
false always decodes about
30 seconds at a time with
decodeAudioData.
|
import { createPlayer } from 'sonicframe/player';
createPlayer({
container: document.querySelector('#player-stream'),
src: './sounds/music/november-snow.mp3',
decode: { stream: { maxSeconds: 14_400, progressive: true } },
});