# WaveformPlayer

> A small, zero-dependency family of vanilla-JS audio components for the web:
> a canvas waveform player, a persistent bottom bar, playlists, listen
> analytics, and build-time peak tooling. The core auto-initializes from HTML
> `data-*` attributes — no framework or build step required — and ships typed
> Astro and React wrappers. This file is a machine-readable reference for AI
> coding agents: read it, then add or configure a player for the user.

All packages are published under the `@arraypress` npm scope, MIT licensed.
The core player is ~10KB gzipped with zero runtime dependencies.

## Quickstart (no build step)

Add the stylesheet + script, then drop a `div` with `data-waveform-player`.
The script scans the DOM on load and upgrades every matching element.

```html
<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.min.js"></script>

<div
  data-waveform-player
  data-url="/audio/track.mp3"
  data-title="Midnight Dreams"
  data-artist="The Wavelength"
  data-waveform-style="mirror"
  data-height="64"
></div>
```

That is a complete, working player. Everything else is optional configuration.

## Core concepts

- **Two equivalent configuration paths:** every option is settable as a JS
  constructor option (camelCase) OR as a `data-*` attribute (kebab-case). e.g.
  `waveformStyle: 'mirror'` === `data-waveform-style="mirror"`.
- **Aliases:** `style` → `waveformStyle`, `src` → `url` (the canonical name
  wins if both are present).
- **Auto theme:** with no `colorPreset`/colors set, the player detects the page
  theme (Tailwind `class="dark"`, `data-theme`, `prefers-color-scheme`, body
  brightness) and re-detects live when the user toggles light/dark.
- **Pre-computed peaks:** point `data-waveform` at a peaks JSON file (produced
  by `@arraypress/waveform-gen`) to paint instantly with no client-side decode.

## Common data-* attributes (player)

- `data-url` — audio file URL (alias: `data-src`). Required unless visualization-only.
- `data-waveform` — URL to a pre-generated peaks JSON file (skips Web Audio decode).
- `data-waveform-style` — `mirror` (default), `bars`, `line`, `blocks`, `dots`, `seekbar`.
- `data-height` — pixel height of the waveform (default `64`).
- `data-samples` — number of bars/points to render (default `256`).
- `data-title`, `data-artist`, `data-album`, `data-artwork` — track metadata.
- `data-layout` — `default` or `preview` (centered title, for sample/preview cards).
- `data-button-style` — `circle` (default) or `minimal` (bare play glyph, no ring).
- `data-color-preset` — named preset, or omit for auto light/dark detection.
- `data-waveform-color`, `data-progress-color` — explicit waveform/progress colors (override the preset).
- DOM chrome (button, title, meta text) is themed via CSS variables — `--wfp-button-color`, `--wfp-text-color`, `--wfp-text-secondary-color` — not data attributes; override them in your own CSS.
- `data-bar-width`, `data-bar-spacing`, `data-bar-radius` — bar geometry.
- `data-bpm` + `data-show-bpm="true"` — show a BPM badge (or let it auto-detect on decode).
- `data-autoplay`, `data-preload`, `data-show-time`, `data-show-info`, `data-show-playback-speed` — toggles.
- `data-markers` — JSON array of `{ time, label, color }` cue markers.

## JavaScript API

```js
import { WaveformPlayer } from '@arraypress/waveform-player';

const player = new WaveformPlayer(document.querySelector('#el'), {
  url: '/audio/track.mp3',
  waveformStyle: 'mirror',
  height: 64,
  samples: 256,
});

player.play();
player.pause();
player.seek(0.5);              // 0..1
player.loadTrack({ url, title, artist, artwork, waveform });

// Events (dispatched on the element, all prefixed `waveformplayer:`)
el.addEventListener('waveformplayer:play', (e) => {});
el.addEventListener('waveformplayer:pause', (e) => {});
el.addEventListener('waveformplayer:ended', (e) => {});
el.addEventListener('waveformplayer:timeupdate', (e) => e.detail.currentTime);
```

`audioMode: 'external'` makes the player visualization-only (no `<audio>`); you
drive it with `setPlayingState()` / `setProgress()` and listen for
`waveformplayer:request-play` / `request-pause`. Used by WaveformBar.

## Framework wrappers (typed)

```astro
---
import WaveformPlayer from '@arraypress/waveform-player-astro';
---
<WaveformPlayer url="/audio/track.mp3" waveformStyle="mirror" height={64} title="Midnight Dreams" />
```

```tsx
import { WaveformPlayer } from '@arraypress/waveform-player-react';

<WaveformPlayer url="/audio/track.mp3" waveformStyle="mirror" height={64} title="Midnight Dreams" />;
```

Prop types are derived from the core's `WaveformPlayerOptions`, so they never
drift. Note: use `waveformStyle` for the visual style (`style` stays the CSS prop).

## The family

- **@arraypress/waveform-player** — the core canvas player (above).
- **@arraypress/waveform-bar** — persistent Spotify-style bottom bar: queue, volume, repeat, favorites, cart, DJ markers, cross-page session persistence. `window.WaveformBar.init(config)`; drives inline `external`-mode players via `data-wb-*` triggers.
- **@arraypress/waveform-playlist** — playlist + chapter navigation (albums, podcasts, courses, audiobooks). Container `data-waveform-playlist` with child `data-track` elements; keyboard-accessible (N / P / 1–9). Requires the player script loaded first.
- **@arraypress/waveform-tracker** — privacy-first listen analytics: credits real media-time engagement, ignores seeks, no cookies; send to any endpoint.
- **@arraypress/waveform-gen** — Node CLI + library to pre-generate waveform peaks (and BPM) from audio files for instant render.
- **Wrappers:** `@arraypress/waveform-player-astro`, `-player-react`, `-bar-astro`, `-bar-react`, `-playlist-astro`, `-playlist-react`.

## Links

- Docs: https://waveformplayer.com/docs
- Examples: https://waveformplayer.com/examples
- Config builder: https://waveformplayer.com/builder
- npm org: https://www.npmjs.com/org/arraypress
- GitHub: https://github.com/arraypress/waveform-player