The <waveform-player> element
2.0 adds a custom element. It is the same player as
<div data-waveform-player>, as a tag:
<waveform-player src="/audio/track.mp3" duration="187" waveform-style="bars" show-volume></waveform-player>Attributes
Section titled “Attributes”Every data-* option is an attribute, with or
without the data- prefix: src, url, title, waveform-style,
duration, show-download, … When both forms are present, the plain one wins.
- Booleans: a bare attribute means true, as HTML boolean attributes do —
<waveform-player loop>. (Thedata-form keeps thedata-*rule: only="true"enables it.) style: plainstyleis the element’s CSS, so the waveform-style alias only works asdata-style. Usewaveform-style.- Values are parsed exactly as
data-*values are.
Light DOM
Section titled “Light DOM”The element renders into itself — no shadow root — so:
- the stylesheet applies, as to any
[data-waveform-player]; - server-rendered markup upgrades in place;
waveformplayer:*events bubble from the tag, so one listener ondocumenthears it like any other player.
Like any mount element, its existing children are replaced by the player and its classes are kept.
The stylesheet makes the element a block, and until the script defines it, it
holds a default player’s height (--wfp-element-height, 90px), so the page
doesn’t shift as it upgrades. Set that property for a taller or shorter
configuration.
Scripting it
Section titled “Scripting it”const el = document.querySelector('waveform-player');
el.player; // the WaveformPlayer instance (null while disconnected)el.play(); // play(), pause() and togglePlay() forward to itel.setAttribute('src', '/audio/next.mp3'); // loads the next track- Changing
src,url,title,artist,artwork,waveformorduration(either form) loads the new track, playing on if it was playing. - Changing any other option attribute rebuilds the player. Several changes in one task are batched into one load or rebuild.
- Removing the element destroys its player. Moving it within the DOM does not, and playback carries on.
Registration
Section titled “Registration”The default bundle — the script tag or import '@arraypress/waveform-player' —
registers <waveform-player> before it scans the page, unless the page sets
data-waveform-autoinit="false".
That opt-out switches the registration off too: on such a page the tag stays an
unknown element until you register it.
A <script> page that opted out has no module import to reach
defineWaveformPlayerElement(), so 2.1.0 adds it to the global as
WaveformPlayer.defineElement():
<html data-waveform-autoinit="false"> … <script src="https://unpkg.com/@arraypress/waveform-player@latest/dist/waveform-player.min.js"></script> <script> WaveformPlayer.defineElement(); // <waveform-player> // WaveformPlayer.defineElement('my-audio-player'); // or your own name </script>The /no-autoinit entry point
registers nothing. Call defineWaveformPlayerElement() yourself — optionally
with another tag name:
import { defineWaveformPlayerElement } from '@arraypress/waveform-player/no-autoinit';
defineWaveformPlayerElement(); // <waveform-player>defineWaveformPlayerElement('my-audio-player'); // or your own nameIt returns the registered constructor (or undefined outside a browser), and a
name that is already defined is left alone. The class is exported too, as
WaveformPlayerElement.