SonicFrame v1.3.2

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 } },
});