The HTML tag
<sonic-player> is the ready-made player
as a custom element. Write it in any page, template or
framework; its attributes are the options.
Using it
<sonic-player src="/notes/42.ogg" theme="bubble" palette="ocean" volume></sonic-player>
<script type="module">
import { defineSonicPlayer } from 'sonicframe/player';
defineSonicPlayer(); // once; importing alone registers nothing
</script>
defineSonicPlayer('my-player') registers it
under another name. Changing an attribute updates the
player; removing the element destroys it, and putting it
back builds it again.
Attributes
| Attribute | What it does |
|---|---|
src |
The sound's address. |
preload |
none,
metadata (the default) or
auto.
|
peaks |
A waveform file: .dat, the
audiowaveform JSON or a peaks list.
|
peaks-channel,
peaks-max,
peaks-normalize
|
How that file is read. |
theme,
palette, wave
|
The look, by name. |
font,
font-src,
font-stylesheet
|
A stack name, or a font you bring. |
a11y-label,
label
|
The player's accessible name;
a11y-label wins.
|
volume,
spectrogram
|
Switches: present means on. |
zoom |
Words turn on its ways:
wheel scroll pinch keys follow
center edge-scroll buttons.
|
zoom-max |
The largest zoom. |
minimap |
The strip; words:
above auto-hide wheel.
|
a11y-lang |
The language of the player's words
(pt-BR, pt-PT,
es, fr,
auto…).
|
a11y-description |
The wave in words; words:
keys pause-in-value speech announce
button animation fade.
|
chapters,
chapters-options
|
A chapters file's address, and its
extras:
list popover drawer left backdrop
open stay-open animation slide swipe
lane above images links no-keys
no-lines.
|
a11y-chapters |
What a screen reader hears of the
chapters:
announce readable
no-value-note.
|
a11y-zoom,
a11y-minimap
|
announce says a zoom;
keys makes the minimap a
slider.
|
media-session,
media-title,
media-artist,
media-album,
media-artwork
|
The lock screen and the media keys, and what they show (Lock screen and media keys). |
background-color,
background-image,
background-animation and
the other
background- attributes
|
The player's own background (Backgrounds). |
Every attribute, with its values, is in Tag attributes.
Untrusted values are safe
Attributes are read as untrusted input: an unknown name falls back to the default, text goes in only as text, and a font address is used only when it is safe. A tag built from user content cannot inject markup or styles.
Events
The player's events reach the element as DOM events,
with the arguments in event.detail:
document.querySelector('sonic-player').addEventListener('sonicframe:seek', (event) => {
const [{ time }] = event.detail;
console.log('Moved to', time);
});
sonicframe:seek,
sonicframe:hover,
sonicframe:timeupdate,
sonicframe:durationchange,
sonicframe:peakschange,
sonicframe:resize,
sonicframe:rangeend,
sonicframe:viewchange,
sonicframe:error,
sonicframe:descriptionchange and
sonicframe:chapterchange.
The player inside
The tag's player property gives the player
it built, to reach what no attribute does. It is
null while the tag is off the page.
const tag = document.querySelector('sonic-player');
tag.player?.chapters?.go(2);
tag.player?.setLook({ fontWeight: 600 });
TypeScript knows the tag: the
SonicPlayerElement type comes from
document.createElement('sonic-player') and
querySelector. The type
PlayerAttribute names every attribute it
reads.