Skip to content

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.

<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.

You don’t have to write those attributes by hand. WaveformGen 3.0 prints one snippet per file with --html:

  1. Print the players

    Terminal window
    npx @arraypress/waveform-gen ./public/audio/*.mp3 --html --base-url /audio/

    Each line is a <div data-waveform-player> with data-url, data-waveform (compact peaks), data-duration, data-preload="none" and data-title, attributes HTML-escaped, in path order. URLs follow --root and --base-url. No JSON is written unless --output asks for it.

  2. Paste them into the page, or write them out at build time from a template.

  3. 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.

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.

  • WaveformBar 2.0 passes a trigger’s data-duration (seconds or 3:07) and wp1: data-waveform to 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 — one data-duration serves both.
  • WaveformPlaylist 2.0 passes each track’s data-duration (3:45, 1:02:03 or bare seconds) and wp1: data-waveform to its player.
  • WaveformSounds passes a sound’s duration to its engine player.