Astro components for WaveformPlayer: the player, the persistent bar, playlists and sound lists. One package, one sub-path per component. Install only the cores you use.
Install this package, plus the core(s) for the components you use:
| Import from | Components | Also install |
|---|---|---|
@arraypress/waveform-astro/player |
WaveformPlayer |
@arraypress/waveform-player |
@arraypress/waveform-astro/bar |
WaveformBar, WaveformBarTrigger |
@arraypress/waveform-bar @arraypress/waveform-player |
@arraypress/waveform-astro/playlist |
WaveformPlaylist |
@arraypress/waveform-playlist @arraypress/waveform-player |
@arraypress/waveform-astro/sounds |
WaveformSounds |
@arraypress/waveform-sounds @arraypress/waveform-player |
# just the player
npm install @arraypress/waveform-astro @arraypress/waveform-playerRequires Astro 7.4+ and the 2.0 cores (^2.0.0; ./sounds needs
@arraypress/waveform-sounds 2.2+), which support Chrome/Edge 111+,
Firefox 114+ and Safari 16.4+. Node 22.12+.
The cores are optional peer dependencies, so npm won't install the ones you
don't import. There is no root import (@arraypress/waveform-astro on its
own): each component loads its own core, and a combined entry would need all
of them.
Each sub-path also exposes its .astro files and types directly, for
example @arraypress/waveform-astro/player/WaveformPlayer.astro and
@arraypress/waveform-astro/player/types.
---
import WaveformPlayer from '@arraypress/waveform-astro/player';
---
<WaveformPlayer src="/track.mp3" title="My Song" artist="The Artist" waveformStyle="mirror" />Every core option is a prop, emitted as its data-* attribute. The 2.0
options:
| Prop | Attribute | |
|---|---|---|
duration |
data-duration |
Track length in seconds, shown as the total until the audio's metadata arrives (with preload="none", until play) |
lazy |
data-lazy |
Build the player now; load audio and peaks, and draw, within 200px of the viewport |
loop, showLoop, loopLabel |
data-loop, … |
Loop the track; a loop toggle button and its name |
showVolume, volume, volumeLabel, muteLabel |
data-show-volume, … |
Mute toggle and volume slider; initial volume (0..1) |
showDownload, downloadUrl, downloadName, downloadLabel |
data-show-download, … |
A download link (default: the track url and its file name) |
waveform takes peaks as an array, a .json URL, or compact wp1: peaks
(about a quarter of the size of a JSON array; @arraypress/waveform-gen
writes them):
<WaveformPlayer url="/track.mp3" preload="none" duration={187} waveform="wp1:M5lm…" />lazy is the core's option. In 1.x it was this component's own (a
data-waveform-player-lazy container promoted by an inline observer script);
<WaveformPlayer lazy> still defers loading the same way, and the player now
exists, at full height, before it is on screen.
There are no callback props: a server-rendered component has no function to
call. Every player dispatches bubbling, composed waveformplayer:*
CustomEvents on its container, typed on DocumentEventMap, so one listener
hears them all. detail.player is the instance.
| Event | detail (besides player, url) |
|---|---|
waveformplayer:ready / load / play / pause / destroy |
— |
waveformplayer:ended |
currentTime, duration |
waveformplayer:timeupdate |
currentTime, duration, progress |
waveformplayer:error |
error |
waveformplayer:seek (2.0) |
currentTime, duration |
waveformplayer:ratechange (2.0) |
playbackRate |
waveformplayer:volumechange (2.0) |
volume, muted |
waveformplayer:loop (2.0) |
loop, start, end |
waveformplayer:next / previous |
— (lock-screen skip buttons) |
waveformplayer:request-play / request-pause / request-seek |
for audioMode="external" controllers |
seek, ratechange, volumechange and loop come from the player's own
<audio>, so they don't fire with audioMode="external".
<script>
document.addEventListener('waveformplayer:seek', (e) => {
console.log(e.detail.currentTime);
});
</script>The detail types are exported from @arraypress/waveform-astro/player
(WaveformSeekEventDetail, …).
---
import { WaveformBar, WaveformBarTrigger } from '@arraypress/waveform-astro/bar';
---
<WaveformBarTrigger url="/audio/track.mp3" title="My Track" artist="Producer" />
<!-- Render once, in your root layout -->
<WaveformBar />A trigger's duration may be seconds (187) or a clock string ('3:07');
waveform-bar 2.0 shows it and passes it to the player. waveform takes
compact wp1: peaks too.
---
import WaveformPlaylist from '@arraypress/waveform-astro/playlist';
import '@arraypress/waveform-player/dist/waveform-player.css';
import '@arraypress/waveform-playlist/dist/waveform-playlist.css';
import wfpJsUrl from '@arraypress/waveform-player/dist/waveform-player.min.js?url';
import wfplJsUrl from '@arraypress/waveform-playlist/dist/waveform-playlist.js?url';
---
<script src={wfpJsUrl} is:inline></script>
<script src={wfplJsUrl} is:inline></script>
<WaveformPlaylist tracks={[{ url: '/a.mp3', title: 'A', artist: 'Artist' }]} />Per track: duration (seconds or '3:45', shown in the list and passed to
the player), downloadUrl / downloadName (with showDownload on the
playlist), and waveform (an array, a URL or wp1: peaks). The playlist
passes showVolume, volume, showDownload and the labels to its player;
it never passes loop, showLoop or the player's lazy, so those aren't
props. The playlist's own lazy prop defers building the whole playlist
until it nears the viewport.
---
import WaveformSounds from '@arraypress/waveform-astro/sounds';
import '@arraypress/waveform-player/styles.css';
import '@arraypress/waveform-sounds/styles.css';
---
<WaveformSounds
sounds={[
{ url: '/previews/kick-01.mp3', title: 'Kick 01', type: 'Drums', bpm: 128, key: 'F minor', duration: 2.4 },
{ url: '/previews/bass-04.mp3', title: 'Bass Loop 04', type: 'Bass', bpm: 128, key: 'Fmin', peaks: 'a1b2c3…' },
]}
pageSize={100}
columns={['type', 'bpm', 'key']}
/>The list is rendered on the server: the toolbar, the rows it starts with
(the first page), and every sound once as an inert
<script type="application/json" data-ws-sounds>; the runtime adopts that
markup and renders further rows as they are revealed. Enharmonic keys
(A#m / Bbm) are one key-menu entry by default; mergeEnharmonicKeys={false}
keeps the spellings apart, on the server and in the browser alike.
The 2.1 playlist and sounds cores also define light-DOM custom elements,
<waveform-playlist> and <waveform-sounds>, and an Astro page can write
those tags directly instead of using the components above. Their attributes
are the cores' data-* options with or without the data- prefix,
and waveformplayer:* / waveformsounds:* events bubble from the tag:
---
import '@arraypress/waveform-player/styles.css';
import '@arraypress/waveform-playlist/styles.css';
import '@arraypress/waveform-sounds/styles.css';
---
<waveform-playlist layout="hero" show-volume continuous>
<div data-track data-url="/intro.mp3" data-title="Intro" data-duration="187"></div>
</waveform-playlist>
<waveform-sounds manifest="/sounds.json" page-size="20"></waveform-sounds>
<script>
import '@arraypress/waveform-player';
import '@arraypress/waveform-playlist'; // registers <waveform-playlist>
import '@arraypress/waveform-sounds'; // registers <waveform-sounds>
</script>The cores' default entries (and their CDN scripts) register the tags unless
the page sets <html data-waveform-autoinit="false">. The components stay
the way to get typed props, sounds rendered on the server, and ClientRouter
handling.
Every prop, the imperative API and SSR notes: docs.waveformplayer.com/frameworks/astro.
MIT © ArrayPress Limited