SonicFrame v1.3.2

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