Zero-bandwidth pages
A catalogue, a podcast archive or a beat store can put dozens of players on one page. With 2.0, each of them can show its waveform, its title and its length while the page downloads no audio at all — nothing is fetched until someone presses play, and then only that one track.
Three options do it together:
| Option | What it removes |
|---|---|
preload: 'none' (data-preload="none") |
The browser’s metadata request for every <audio>. |
waveform with compact wp1: peaks |
The Web Audio decode, and — because the peaks are inline — the .json sidecar request. |
duration (data-duration) |
The one thing preload: 'none' used to cost you: without metadata, 1.x players showed 0:00 and couldn’t place markers until play. |
Measured in Chromium against the 2.0 core: a page of 50 players built this way makes 0 audio requests until one is played.
The markup
Section titled “The markup”<div data-waveform-player data-url="/audio/little-paris.mp3" data-preload="none" data-duration="122" data-waveform="wp1:AAAAAAAAAAAAAbxcUcRoU0I9ODAqIx8d…" data-title="Little Paris"></div>The time readout shows 0:00 / 2:02 at once. Until the audio’s own metadata
arrives — which with preload: 'none' is only once playback starts — the
duration is the total: markers are placed against it, and the hover time,
the accessible seek slider and the Media Session scrubber use it. A seek in that
window (a click or key on the waveform, a marker, seekTo()) moves the playhead
at once and is applied to the audio as soon as it can seek. When the real
duration arrives it replaces yours.
Generate it
Section titled “Generate it”You don’t have to write those attributes by hand. WaveformGen
3.0 prints one snippet per file with --html:
-
Print the players
Terminal window npx @arraypress/waveform-gen ./public/audio/*.mp3 --html --base-url /audio/Each line is a
<div data-waveform-player>withdata-url,data-waveform(compact peaks),data-duration,data-preload="none"anddata-title, attributes HTML-escaped, in path order. URLs follow--rootand--base-url. No JSON is written unless--outputasks for it. -
Paste them into the page, or write them out at build time from a template.
-
Load the player once:
<link rel="stylesheet" href="https://unpkg.com/@arraypress/waveform-player@latest/dist/waveform-player.css"><script src="https://unpkg.com/@arraypress/waveform-player@latest/dist/waveform-player.min.js"></script>
Rather keep JSON sidecars? --compact writes { "peaks": "wp1:…", "duration": 122 }
files (about 2.4 KB each instead of ~18 KB). The player reads both the peaks
and the duration from a sidecar, so the length shows as soon as the small JSON
file arrives — still no audio until play. data-duration in the markup also
works, and shows before the sidecar is fetched.
In JavaScript and the frameworks
Section titled “In JavaScript and the frameworks”new WaveformPlayer('#player', { url: '/audio/little-paris.mp3', preload: 'none', duration: 122, waveform: 'wp1:AAAAAAAAAAAAAbxcUcRoU0I9ODAqIx8d…',});The framework components take the same props — preload="none",
duration={122}, waveform="wp1:…" — in React,
Vue, Svelte and
Astro. The <waveform-player> element
takes them as attributes.
Bar and playlist
Section titled “Bar and playlist”- WaveformBar 2.0 passes a trigger’s
data-duration(seconds or3:07) andwp1:data-waveformto its player, so the bar shows the length before any audio loads. On the usual markup — one element that is both the inline player and the trigger — onedata-durationserves both. - WaveformPlaylist 2.0 passes each track’s
data-duration(3:45,1:02:03or bare seconds) andwp1:data-waveformto its player. - WaveformSounds passes a sound’s
durationto its engine player.