SonicFrame v1.3.2

Lock screen and media keys

The system's own controls for a player: the lock screen and the notification on a phone, the media keys and the browser's media controls on a computer. They show the sound's title, artist and picture, and play, pause, skip and seek it. Off until you turn it on.

Turning it on

mediaSession: true names the sound after the player's a11y.label; give your own words and pictures instead. The controls only learn about the sound once it plays.

createPlayer({
    container,
    src: '/sounds/little-elf.mp3',
    a11y: { label: 'The Little Elf' },
    mediaSession: {
        artist: 'John Kendrick Bangs',
        album: 'Poems',
        artwork: [
            { src: '/covers/elf-96.png', sizes: '96x96', type: 'image/png' },
            { src: '/covers/elf-512.png', sizes: '512x512', type: 'image/png' },
        ],
    },
});

Play it, then open your browser's media controls (in Chrome, the music note in the toolbar) or press a media key on the keyboard.

What the controls do

Control What happens
Play, pause Plays or pauses this player's sound. A play the browser refuses becomes the error event.
Skip back, skip forward Moves the step the controls ask for, or the player's look.skip seconds (10 on a frame).
Seek Goes to the time chosen on the controls' own bar, quickly while it is dragged when the browser can.
Stop Pauses and goes back to the start.
Previous, next track The player's tracks, otherwise the chapter before and after, or your own onPrevious and onNext. Without any of them, the controls leave these buttons out.

actions picks the controls offered, from 'play', 'pause', 'seekbackward', 'seekforward', 'seekto' and 'stop'; all six by default.

One sound at a time

A page has one set of system controls. The player that played last owns them; the others leave them alone until they play. When the owner goes, the controls are cleared.

Chapters

A player with chapters hands them to the controls: previous and next track step through them, and browsers that list chapters (Chrome, Edge) show them with their pictures. chapters: false leaves them out; your own onPrevious and onNext win over them.

Changing the track

A player that plays one sound after another tells the controls with set; the details left out stay. The music on the home page does this, and its previous and next track change the song.

const player = createPlayer({
    container,
    media: audio,
    mediaSession: {
        title: tracks[0].title,
        artist: tracks[0].artist,
        onPrevious: () => play(index - 1),
        onNext: () => play(index + 1),
    },
});

function play(at) {
    index = (at + tracks.length) % tracks.length;
    audio.src = tracks[index].src;
    player.mediaSession.set({ title: tracks[index].title, artist: tracks[index].artist });
    audio.play();
}

player.mediaSession is null while the option is off; active says whether this player owns the controls now.

On a frame

The same controls are a plugin, for a frame of your own. Chapters reach it through set.

import { chapters, mediaSession } from 'sonicframe';

const marks = chapters({ src: '/chapters.vtt', onChapters: (list) => controls.set({ chapters: list }) });
const controls = mediaSession({
    title: 'Episode 12',
    onPrevious: () => marks.previous(),
    onNext: () => marks.next(),
});

frame.use(marks);
frame.use(controls);

On the tag

<sonic-player
    src="./sounds/little-elf.mp3"
    media-session
    media-title="The Little Elf"
    media-artist="John Kendrick Bangs"
></sonic-player>

Without media-title, the title is the a11y-label (or the label). A changed media- attribute shows at once, and the sound keeps playing.

Options

Option Default What it does
title the player's a11y.label The sound's name.
artist Who made it.
album What it belongs to.
artwork One picture's address, or a list of { src, sizes, type }.
seekOffset look.skip (10 on a frame) Seconds a skip moves when the controls give no step, from 1 to 120; or a function asked at each skip.
actions all six The controls offered.
onPrevious the chapter before Called by previous track.
onNext the chapter after Called by next track.
chapters true On a player: hand its chapters to the controls. On the plugin: the chapters themselves.
previousNext 'auto' On a player: what previous and next track step through. 'auto' takes the tracks when the player is made with them, otherwise its chapters; 'tracks' or 'chapters' only one of them; false leaves the two buttons out.

What reaches the system

  • Words in one clean line of at most 120 characters, without control or direction characters.
  • At most eight pictures, each from a web, relative or blob: address; sizes and type only when well formed.
  • The position only when the sound has a known length, so a live recording sends none.

Where the browser has no media session, nothing happens and the player plays as always.