Getting Started

WaveformPlaylist turns a list of tracks into a navigable playlist, album or chaptered episode — driving a single embedded WaveformPlayer underneath. It parses declarative [data-track] / [data-chapter] markup, renders the list UI, wires up keyboard navigation, and loads each track into the player on demand.

It is a thin orchestration layer: it owns the list/chapter UI and track switching, and forwards everything else — height, waveform style, colours, controls — straight to the inner player.

Here’s a real, playable playlist — pick any track and it loads into the shared player (auto-advance is on). This is the hero layout: a “now playing” unit (the cover doubles as play/pause) over a stripped track queue.

That’s nothing but a [data-waveform-playlist] container wrapping one [data-track] per row — the exact markup covered below. Swap data-layout for list, minimal or grid to change the presentation; everything else is identical.

Requires the core player

WaveformPlaylist is a hard dependency on @arraypress/waveform-player. window.WaveformPlayer must exist at construction time, or the constructor throws [WaveformPlaylist] WaveformPlayer is required but not found. Always load the player first.

Install

Install the playlist alongside the core player (the player is a peer dependency, ^1.24.5 from 1.8.0 — previously ^1.7.2, which the playlist had long outgrown).

npm

npm install @arraypress/waveform-player @arraypress/waveform-playlist

pnpm

pnpm add @arraypress/waveform-player @arraypress/waveform-playlist

yarn

yarn add @arraypress/waveform-player @arraypress/waveform-playlist

bun

bun add @arraypress/waveform-player @arraypress/waveform-playlist

Or load both from a CDN — player first, then the playlist:

<!-- Core player is REQUIRED and must load first -->
<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.js"></script>

<!-- Then the playlist -->
<link rel="stylesheet" href="https://unpkg.com/@arraypress/waveform-playlist@latest/dist/waveform-playlist.css">
<script src="https://unpkg.com/@arraypress/waveform-playlist@latest/dist/waveform-playlist.js"></script>

The IIFE build exposes a global WaveformPlaylist; the package also ships an ESM build (waveform-playlist.esm.js) with a default export, plus a minified IIFE for unpkg.

The play/pause and “now playing” glyphs are inline SVG, so no icon font is needed. (Before 1.9.0 the playlist relied on the page loading the Tabler Icons font, and its icons were blank without it.)

Quick start

Mark a container with data-waveform-playlist and add [data-track] children. The playlist auto-initialises on DOMContentLoaded — zero JavaScript required.

<div data-waveform-playlist data-continuous="true">
  <div data-track
       data-url="episode.mp3"
       data-title="Episode 42"
       data-artist="with Dr. Chen"
       data-artwork="cover.jpg">
    <div data-chapter data-time="0:00">Introduction</div>
    <div data-chapter data-time="5:30">Main Topic</div>
    <div data-chapter data-time="45:00">Q&A</div>
  </div>
</div>

Auto-init timing

Every [data-waveform-playlist] element is initialised on DOMContentLoaded (or immediately if the DOM is already parsed). If window.WaveformPlayer is not present yet, the playlist polls every 100ms for up to 5 seconds. Each element is guarded by data-waveform-playlist-initialized="true" so it is never initialised twice, and construction failures are caught and logged via console.error rather than thrown.

The container contract

A playlist is built from three nested markers:

Element	Role
[data-waveform-playlist]	The container. Its presence triggers auto-init (the attribute value is not read). Carries playlist options and forwarded player options as data-*.
[data-track]	A track. Each [data-track] descendant becomes one track; document order is the track index.
[data-chapter]	A chapter within a track. Each [data-chapter] inside a track becomes a chapter row; the chapter label is the element’s trimmed textContent.

The original [data-track] markup is hidden (display: none) during init and restored in place on destroy(), with any inline display it had put back.

Track attributes

Set on each [data-track] element.

Attribute	Required	Description
data-url	Yes	Audio file URL. If data-title is absent, the title is derived from this filename.
data-title	No	Display title. Defaults to the data-url filename with -/_ converted to spaces, or Untitled if no URL.
data-artist	No	Artist / description line (default empty).
data-artwork	No	Artwork image URL. Renders .wp-artwork-container and enables the play-state overlay on the active row.
data-album	No	Album name, passed to the player for the Media Session metadata.
data-duration	No	Display-only duration string, e.g. 3:45. It is never parsed — only shown when showDuration is on.
data-markers	No	JSON array of explicit waveform markers, e.g. [{"time":30,"label":"Drop","color":"#f00"}]. Explicit markers always take precedence over chapter-derived ones.
data-waveform	No	Pre-computed peaks for this track (1.8.0+): a JSON array of peaks, or a .json peaks URL (e.g. from waveform-gen) passed through for the player to fetch. Skips decoding the audio just to draw it. A malformed JSON array logs a warning and the track falls back to decoding.

data-markers must be valid JSON

data-markers must be a JSON array. Malformed JSON (or anything that isn’t an array) logs a [WaveformPlaylist] Invalid markers … warning and that track simply gets no explicit markers; entries without a numeric time are dropped. The rest of the playlist still renders, but validate it server-side so the markers you meant actually show.

Chapter attributes

Set on each [data-chapter] element.

Attribute	Required	Description
label (text content)	Yes	The chapter label is the element’s trimmed textContent, not an attribute.
data-time	No	Timestamp as M:SS, MM:SS, H:MM:SS (1.8.0+ — earlier versions read 1:05:30 as 1 second), or bare seconds (e.g. 90). A malformed value reads as 0:00. Omitted, the chapter is placed at 0:00 with a console warning.
data-color	No	Optional per-chapter marker colour. Falls back to chapterMarkerColor.