Lazy loading
lazy (data-lazy="true") defers a player’s expensive work until it comes
within 200px of the viewport. Every lazy player on the page shares one
IntersectionObserver.
<div data-waveform-player data-lazy="true" data-url="/audio/track.mp3" data-waveform="/audio/track.json"></div>new WaveformPlayer('#player', { url: '/audio/track.mp3', lazy: true });What waits, and what doesn’t
Section titled “What waits, and what doesn’t”The player itself is built at once: it is registered in
WaveformPlayer.instances, its methods work, and WaveformPlayer.init() treats
it as initialised. Until it nears the viewport it shows what it shows while
loading — the title, the loading state and any known duration —
at its full height, so nothing shifts when it loads.
What waits:
- assigning the audio source (so not even a metadata request goes out),
- fetching a
.jsonpeaks sidecar, - decoding the audio for peaks,
- drawing the waveform.
Anything that needs the audio loads it straight away: play() (and so
togglePlay(), the play button and Space), a seek, load() or loadTrack().
autoplay waits for the player to be loaded. In external mode lazy defers the
peaks the same way. Where IntersectionObserver is missing, the player loads as
if it weren’t lazy.
Measured in Chromium against the 2.0 core: a page of 30 lazy players loaded the 2 in view, then all 30 after scrolling through.
Lazy or zero-bandwidth?
Section titled “Lazy or zero-bandwidth?”lazy |
preload: 'none' + duration + inline peaks |
|
|---|---|---|
| Audio requests before play | none until in view, then a metadata request (with the default preload) |
none |
| Peaks | fetched or decoded when in view | inline, drawn at once |
| Best for | players whose peaks are .json files or must be decoded |
catalogues you can generate peaks for |
They combine: lazy on a zero-bandwidth player also postpones drawing until
it’s in view.
In the frameworks and extensions
Section titled “In the frameworks and extensions”- Astro:
<WaveformPlayer lazy>now sets the core’slazyoption (data-lazy). In 1.x it was the component’s own IntersectionObserver (data-waveform-player-lazy), which is gone — see Migrating from 1.x. - React, Vue, Svelte: a
lazyprop on the player component. - WaveformPlaylist never passes
lazyto its player (it would only defer the playlist’s own single player). The playlist’s Astro component keeps its ownlazyprop, which defers building the whole playlist. - WaveformSounds:
lazyhas no effect on its engine, which loads nothing until a sound plays anyway.