WaveformPlaylist

Turn a track list into an album or podcast.

Name: WaveformPlayer
Author: ArrayPress

A thin orchestration layer that renders playlists, albums and chaptered episodes — switching between list, minimal, hero and grid layouts automatically. Every track loads into one embedded player.

$ npm i @arraypress/waveform-playlist

GitHub

See it live below.

Layouts

Four views, one player underneath.

The playlist picks the best UI automatically: a hero layout with cover + waveform + queue, a grid of cover-art cards, a full track list with expandable chapters, or a compact pill-button switcher for tight spaces.

Hero layout

Cover, embedded player and queue in one view.

Grid layout

Cover-art cards with play overlays and track info.

List & minimal

A full track row with artwork, title and chapters (list); or a row of pill-button track switchers (minimal).

Chapters & markers

Navigation and waveform markers, baked in.

Nest chapter timestamps under each track and they render as an expandable list and (optionally) as markers on the waveform. Click a chapter row to jump the player; the active chapter is highlighted live.

Introduction

The main idea

Going deeper

Wrap-up

Cold open

The interview

Sign-off

Per-track chapters: Chapters are parsed from declarative [data-chapter] elements nested inside each [data-track]. Each chapter becomes a navigable row and (in single-track episodes) a waveform marker.

Tune it

Customize every layout through data-* markup.

Control artwork size, row density, cover position, artist visibility and waveform style — all from the container element or individual tracks.

layout

list, minimal, hero or grid — auto-picked from your content, or force one explicitly.

coverSize

Scale the track artwork in hero and grid layouts.

thumbnailSize

Set artwork dimensions in list rows; also updates --wp-thumb-size CSS var.

density

Toggle between "comfortable" and "compact" row spacing to fit your layout.

coverPosition

In the hero layout, place the cover to the left of the waveform or stacked on top.

barPosition

In the grid layout, dock the now-playing bar above or below the cover grid.

showArtist

Show or hide the artist/description line under each track title.

waveformStyle

Forward any player waveform style (bars, line, solid, etc.) to the embedded player.

continuous

Auto-advance to the next track when the current one finishes.

Getting started

Three elements and a script tag.

Mark a container with data-waveform-playlist, add [data-track] children with optional [data-chapter] grandchildren, and load the scripts. Auto-init on page load — zero JavaScript required.

<!-- Mark a container with data-waveform-playlist -->
<div data-waveform-playlist
     data-layout="hero"
     data-continuous="true"
     data-show-chapter-markers="true">
  <!-- Each track is one data-track child -->
  <div data-track
       data-url="episode-01.mp3"
       data-title="Episode 1: Getting Started"
       data-artist="with Alex Rivera"
       data-artwork="covers/ep01.jpg"
       data-duration="42:15">
    <!-- Chapters nested inside the track (optional) -->
    <div data-chapter data-time="0:00">Introduction</div>
    <div data-chapter data-time="5:30">Main Topic</div>
    <div data-chapter data-time="35:00">Q&A</div>
  </div>
  
  <div data-track
       data-url="episode-02.mp3"
       data-title="Episode 2: Deep Dive"
       data-artist="solo"
       data-artwork="covers/ep02.jpg"
       data-duration="38:45">
    <div data-chapter data-time="0:00">Recap</div>
    <div data-chapter data-time="3:00">New Findings</div>
    <div data-chapter data-time="28:00">Wrap-up</div>
  </div>
</div>

<!-- Load the player first, then the playlist -->
<link rel="stylesheet" href="https://unpkg.com/@arraypress/waveform-player/dist/waveform-player.css">
<script src="https://unpkg.com/@arraypress/waveform-player/dist/waveform-player.js"></script>

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

---
import WaveformPlaylist from '@arraypress/waveform-playlist-astro';
import '@arraypress/waveform-player/dist/waveform-player.css';
import '@arraypress/waveform-playlist/dist/waveform-playlist.css';
import wfpJs from '@arraypress/waveform-player/dist/waveform-player.min.js?url';
import wfplJs from '@arraypress/waveform-playlist/dist/waveform-playlist.min.js?url';
---
<script src={wfpJs} is:inline></script>
<script src={wfplJs} is:inline></script>

<WaveformPlaylist
  layout="hero"
  continuous
  showChapterMarkers
  tracks={[
    {
      url: '/audio/episode-01.mp3',
      title: 'Episode 1: Getting Started',
      artist: 'with Alex Rivera',
      artwork: '/covers/ep01.jpg',
      duration: '42:15',
      chapters: [
        { time: 0, label: 'Introduction' },
        { time: 330, label: 'Main Topic' },
        { time: 2100, label: 'Q&A' },
      ],
    },
  ]}
/>

import { WaveformPlaylist } from '@arraypress/waveform-playlist-react';
import '@arraypress/waveform-player'; // registers window.WaveformPlayer
import '@arraypress/waveform-player/dist/waveform-player.css';
import '@arraypress/waveform-playlist/dist/waveform-playlist.css';

export default function Episodes() {
  return (
    <WaveformPlaylist
      layout="hero"
      continuous
      showChapterMarkers
      tracks={[
        {
          url: '/audio/episode-01.mp3',
          title: 'Episode 1: Getting Started',
          artist: 'with Alex Rivera',
          artwork: '/covers/ep01.jpg',
          duration: '42:15',
          chapters: [
            { time: 0, label: 'Introduction' },
            { time: 330, label: 'Main Topic' },
            { time: 2100, label: 'Q&A' },
          ],
        },
      ]}
    />
  );
}

Read the docs Back to the family