SonicFrame v1.3.2

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.