SonicFrame v1.3.2

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() and previous().
  • add(tracks, at?), remove(index), move(from, to) and setTracks(tracks): the track playing goes on.
  • setShuffle(on), setRepeat(repeat), forget() and destroy().
  • player, tracks, index, order, shuffle and repeat say where it is.
  • Events: trackchange (track, index), listend, trackschange (tracks) and error (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.

November Snow Glory Hotel (lofi)

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 keys on) and the lock screen's previous and next (with its mediaSession on) 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's maxBytes, up to 5 MB), and names are cut to 120 characters.
  • What remember kept is read back as outside input: a value that is not what it should be is left out.