Playlist
Play a list of tracks one after the other. The list is the same one the player's chapters use: a number or the playing bars, the picture with its length, the title and the artist, in the playlist or floating over the page.
Try it
Choose a track, or let one end: the next one plays. The buttons over the list turn the shuffle on and step the repeat through off, all and one.
Adding it
import { createPlaylist } from 'sonicframe/playlist';
const playlist = createPlaylist({
container: document.querySelector('#episodes'),
tracks: [
{ src: 'ep1.mp3', title: 'Pilot', artist: 'The Show', peaks: 'ep1.dat' },
{ src: 'ep2.mp3', title: 'Second', artist: 'The Show', duration: 1830 },
],
});
playlist.on('trackchange', (track, index) => console.log(index, track.title));
sonicframe/playlist is an entry of its own:
an app without a list never loads it. A track takes
src and, when you have them,
title, artist,
album, artwork,
peaks (the numbers, or the address of a
waveform file), duration,
chapters (the address of a chapters file)
and id.
One player, or a player for each track
With layout: 'one' (the default) the
playlist keeps one media element and makes a new player
for each track; the volume, the mute and the speed carry
on. Give your own <audio> or
<video> as media, or the
playlist makes one.
With layout: 'each' every track has its own
player, one under the other, like a feed of voice
messages. One plays at a time: the one that starts
pauses the others and takes their volume and speed.
There is no list then: the players are the list.
The list over the page
list takes the same options as the player's
list of chapters:
type ('inline',
'popover' or 'drawer'),
placement, side,
width, maxHeight,
header, stayOpen,
backdrop, animation,
look, palette,
font and box; plus
place, 'below' (the default)
or 'above' the player. A list that floats
adds its button over the list's place.
Options
| Option | Default | What it does |
|---|---|---|
tracks |
none | A list of tracks, or the text of a JSON or M3U list. |
maxTracks |
1000 |
The most tracks the list keeps, given,
fetched or added: from 1 to 10,000. Past
either end, a
RangeError names it.
|
maxText |
120 |
The longest title, artist, album or id
kept, in characters, from 1 to 1000. A
feed takes its own
maxText.
|
src |
none |
The address of a JSON or M3U list,
fetched when tracks is left
out; relative addresses in it point
beside it.
|
fetch |
cookies to the page's own site only |
credentials and
referrerPolicy of the
request for src.
|
start |
0 |
The track to start on. |
player |
{} |
The options of every track's player
(theme, look, keys, remember...); the
track's address, title, peaks and
chapters win. With
mediaSession, the lock
screen shows each track's title, artist
and picture.
|
layout |
'one' |
'one' or
'each'.
|
advance |
true |
Goes on to the next track when one ends. |
repeat |
'none' |
'all' starts the list over;
'one' starts the track over
when it ends by itself.
|
shuffle |
false |
Plays every track once in a shuffled order, the one playing first. |
random |
Math.random |
The shuffle's numbers, from 0 up to 1. |
previousRestarts |
3 |
"Previous" starts the track over once it has played more than these seconds, from 0 (always goes back) to 30. |
playOnSelect |
true |
A track chosen in the list plays. |
gap |
0 |
Seconds of pause between two tracks, from 0 to 10; choosing a track ends it. |
list |
true |
The list: true,
false or its options (see
above).
|
buttons |
['shuffle', 'repeat'] |
The buttons over the list;
[] for none.
|
remember |
false |
Keeps the track, the shuffle and the
repeat for the next visit:
true or
{ key, store }, kept under
sonicframe:playlist (or
sonicframe:playlist:<key>). Each track's position is the
player's own remember.
|
a11y |
label,
announce (on),
lang and
words.
|
Driving it from your code
-
play(index?),pause(),select(index)(current, without playing),next()andprevious(). -
add(tracks, at?),remove(index),move(from, to)andsetTracks(tracks): the track playing goes on. -
setShuffle(on),setRepeat(repeat),forget()anddestroy(). -
player,tracks,index,order,shuffleandrepeatsay where it is. -
Events:
trackchange (track, index),listend,trackschange (tracks)anderror (error).
Lists in files
readTracks reads a list of tracks,
SonicFrame's JSON or an M3U/M3U8 playlist;
writeTracks(tracks, 'json' | 'm3u') writes
one, so an app can keep the list a person made; and
loadTracks(url) fetches one. All three are
in sonicframe/playlist, and the first two
in sonicframe/analysis too, for servers.
#EXTM3U
#EXTINF:1830,The Show - Pilot
#EXTIMG:covers/ep1.jpg
ep1.mp3
A podcast's feed
createPlaylist({
container,
feed: { src: 'https://example.com/show.xml', order: 'newest', limit: 50 },
});
feed takes a podcast's RSS feed (an
address, or { src, ...options }): each
episode's sound, length, picture (the show's when it has
none), chapters and transcript, newest first by default.
readFeed(text, options) and
loadFeed(url, options) read one by
themselves and give the show's title,
image and tracks. They are in
sonicframe/analysis too, for servers.
Most feeds can't be fetched from another site: their
server doesn't allow it (CORS). Then read the feed on
your server with readFeed and give the
playlist its tracks.
| Option | Default | What it does |
|---|---|---|
order |
'newest' |
'newest' or
'oldest' first, by each
episode's date.
|
limit |
1000 | The most episodes kept, from 1 to 10,000. |
maxSize |
5242880 (5 MB) | The largest feed, in bytes: from 1024 up to 20 MB. Reading takes under 0.1 s for each MB on a desktop computer, more on a phone. |
maxDepth |
100 | The deepest nesting, from 1 to 256. |
maxElements |
200000 | The most elements, from 1 to 1000000 (a feed of 1000 episodes has about 30000). |
maxAttributes |
200 | The most attributes on one element, from 1 to 10000. |
maxNameLength |
1000 | The longest name of an element or an attribute, from 1 to 50000 characters. |
The defaults of the ceilings are the ones the most used
XML readers settled on; your code may raise each up to
the most open of them, never past it. A feed past one,
or an option past its most or under its least, is
refused with a RangeError that names the
option. On the tag: feed,
feed-order, feed-limit,
feed-max-size, feed-max-depth,
feed-max-elements,
feed-max-attributes and
feed-max-name-length. A page's content may
come from anyone who writes in it, so the tag's ceilings
only go down.
The feed is read by SonicFrame's own small XML reader, not the browser's: no script runs, nothing is loaded from it, and it works under a strict Content Security Policy with Trusted Types, and in Node. A feed that declares entities is refused, and every address must be a web address.
On the tag
<sonic-playlist repeat="all" buttons="shuffle repeat" list-place="above">
<a href="ep1.mp3" data-artist="The Show" data-peaks="ep1.dat">Pilot</a>
<a href="ep2.mp3" data-artist="The Show" data-duration="1830">Second</a>
</sonic-playlist>
<script type="module">
import { defineSonicPlaylist } from 'sonicframe/playlist';
defineSonicPlaylist();
</script>
The links work as plain links where scripts never run;
once the playlist stands they are hidden. Or give
src with the address of a list. The
attributes are start, layout,
advance, repeat,
shuffle, gap,
previous-restarts,
play-on-select, list (its
type, or false) and the
list- ones, buttons,
remember with remember-key,
fetch-credentials (same-origin
or omit: a tag never sends cookies to
another site; your code can, with
fetch.credentials) and the
a11y- ones; every attribute of
<sonic-player> but the sound's own
sets each track's player. Events reach the page as
sonicframe:trackchange and the others.
For screen readers and the keyboard
-
The playlist is a named group, and the list a named
navigation with a button per track; the one playing
is marked
aria-current. - The list is one stop in the tab order: the arrows, Home and End move through it, and Enter or Space plays.
-
The live region says "Playing: Title, 3 of 12" at
each change (
a11y.announce). -
Shuffle says its state with
aria-pressed; repeat says its mode in words: "Repeat: off", "Repeat: all", "Repeat: one". -
Each player's track buttons, N and Shift+N (with its
keyson) and the lock screen's previous and next (with itsmediaSessionon) go through the list.
What it trusts
- Titles, artists and names go in as text, never as HTML; a list from anywhere cannot add elements to your page.
-
Every address (the sound, the picture, the peaks,
the chapters, the list itself) must be http, https
or relative; a
javascript:one leaves the track out. -
A list keeps at most 1000 tracks
(
maxTracks, up to 10,000); a list over 512 KB is refused (loadTracks'smaxBytes, up to 5 MB), and names are cut to 120 characters. -
What
rememberkept is read back as outside input: a value that is not what it should be is left out.