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.