Options

Every WaveformPlayer is configured through a single option surface. You can set those options two ways — as JS constructor options (camelCase) or as data-* attributes (kebab-case) on the player element. The two paths are kept in sync: anything you can do in JS, you can do declaratively, and vice versa.

This page is the complete reference. Options are grouped into Source, Appearance, Colors, and Metadata & UI, with the matching data-* attribute and any aliases listed for each.

Here is a fully-loaded player — artwork, title, artist, and live BPM — to anchor the options below:

The two configuration paths

JS (camelCase)

import WaveformPlayer from '@arraypress/waveform-player';
import '@arraypress/waveform-player/dist/waveform-player.css';

const player = new WaveformPlayer('#player', {
  url: '/audio/track.mp3',
  waveformStyle: 'mirror',
  waveformColor: ['#fafafa', '#71717a'],
  showBPM: true,
});

data-* (kebab-case)

<!-- Auto-initialised on DOMContentLoaded — no JS call needed -->
<div
  data-waveform-player
  data-url="/audio/track.mp3"
  data-waveform-style="mirror"
  data-waveform-color='["#fafafa", "#71717a"]'
  data-show-bpm="true"
></div>

Every element carrying data-waveform-player is instantiated automatically when the DOM is ready (and again on any WaveformPlayer.init() call — it is idempotent via a data-waveform-initialized="true" flag the library sets for you).

Precedence

Sources merge in the order defaults < data-* attributes < constructor options. A constructor option always wins over the same data-* attribute on the element. After merging, the resolved color preset and per-style bar sizing are applied.

Aliases

A handful of options accept a shorthand. The canonical name always wins if both are present.

Alias	Canonical	Where
src	url	JS + data-src
style	waveformStyle	JS + data-style
data-color	waveformColor	data-* only (legacy)
data-theme	colorPreset	data-* only (legacy)

The drawer also accepts singular waveformStyle values — bar, block, dot are aliases for bars, blocks, dots.

style is overloaded in framework wrappers

In plain JS and data-*, style/data-style is the waveform-style alias. In the Astro and React wrappers, style stays the framework’s CSS-style prop — there you must use waveformStyle for the visual style. See the wrapper docs.

---

Source

What to load and how to drive it.

Option	Default	Type	Notes
url	''	string	Audio file URL (alias: src). Empty means no auto-load. data-url.
src	—	string	Shorthand alias for url; canonical url wins if both set. data-src.
waveform	null	number[] | string | null	Pre-computed peaks: inline array, comma-separated string, JSON-array string, or a .json URL (fetched; embedded markers applied). Skips Web Audio decode. Reset per-track in loadTrack. data-waveform.
samples	1800	number	Source peak resolution decoded; resampled to fit the visible bars (fidelity headroom, not bar count). data-samples.
preload	'metadata'	'auto' | 'metadata' | 'none'	<audio> preload hint (self mode). data-preload.
audioMode	'self'	'self' | 'external'	'self' owns an <audio>; 'external' is visualization-only. data-audio-mode.
playbackRate	1	number	Initial playback rate (self mode). data-playback-rate.

audioMode: 'external'

External players have no <audio> element — seekTo, seekToPercent, setVolume, setPlaybackRate, and Media Session are no-ops. Instead you drive visuals with setPlayingState() / setProgress(), and play/pause/seek dispatch cancelable waveformplayer:request-* events. See Audio modes.

Supplying peaks instead of decoding

Pass the waveform option to skip the Web Audio decode entirely. Accepted shapes: a number[], a comma-separated string, a JSON-array string, or a .json URL (fetched — any embedded { peaks, markers } is honoured). Use the static getPeaksUrl() helper to derive a sibling .json URL:

const peaksUrl = WaveformPlayer.getPeaksUrl('/audio/track.mp3'); // → '/audio/track.json'

new WaveformPlayer('#player', {
  url: '/audio/track.mp3',
  waveform: peaksUrl, // fetched and drawn; no decode
});

---

Appearance

Layout, button, and waveform-style geometry.

Option	Default	Type	Notes
height	64	number	Waveform height in px (canvas + container). data-height.
waveformStyle	'mirror'	'bars' | 'mirror' | 'line' | 'blocks' | 'dots' | 'seekbar'	Visual style (alias: style). Singular bar/block/dot also accepted. data-waveform-style.
barWidth	2	number	Bar width px. Overridden by per-style defaults when neither option nor data-* set it. data-bar-width.
barSpacing	0	number	Gap between bars px. Overridden by per-style defaults when unset. data-bar-spacing.
barRadius	1	number	Rounded bar-cap radius px (bars/mirror only); 0 = square. data-bar-radius.
layout	'default'	'default' | 'preview'	'preview' centers the title under the waveform and trims the meta row; adds .waveform-layout-preview. data-layout.
buttonStyle	'circle'	'circle' | 'minimal'	'minimal' = bare glyph (.waveform-btn-minimal), no circle. data-button-style.
buttonSize	null	number | string | null	null = stylesheet default; number = px; string ('4rem') used verbatim. Sets --wfp-btn-size, scaling box + glyph. data-button-size.
buttonAlign	'auto'	'auto' | 'top' | 'center' | 'bottom'	Play-button vertical align; 'auto' resolves to 'bottom' for waveformStyle: 'bars', else 'center'. data-button-align.
showPlaybackSpeed	false	boolean	Render the speed menu in the meta row. data-show-playback-speed.
playbackRates	[0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]	number[]	Selectable rates in the speed menu. data-playback-rates (JSON array).

Per-style bar defaults

When you do not set barWidth / barSpacing (via option or data-*), each style seeds its own sensible geometry:

Style	barWidth	barSpacing
bars	3	1
mirror	2	2
line	2	0
blocks	4	2
dots	3	3
seekbar	1	0

Tip

seekbar ignores peaks entirely (it renders a flat progress bar), and barRadius only affects bars and mirror. An unknown waveformStyle falls back to bars.

---

Colors

Every color option defaults to null, meaning “follow the active color preset”. Set any value to override just that token; the rest still track the preset.

Option	Default	Type	Notes
colorPreset	null	'dark' | 'light' | null	null/invalid = auto-detect via detectColorScheme(); an explicit value disables auto-theme re-detection. data-color-preset (legacy: data-theme).
waveformColor	null	string | string[] | null	Unplayed colour; null = preset. Array = gradient stops (axis via waveformGradient), e.g. ['#fafafa','#71717a']. data-waveform-color (legacy: data-color).
progressColor	null	string | string[] | null	Played-through colour; null = preset; array = gradient. data-progress-color.
waveformGradient	'vertical'	'vertical' | 'horizontal' | 'diagonal'	Axis for gradient stop arrays: 'vertical' (top→bottom), 'horizontal' (hue sweep across the wave), 'diagonal'. Ignored for single colours. data-waveform-gradient.

The DOM chrome (button, title, meta text) is themed via CSS variables — --wfp-button-color, --wfp-text-color, --wfp-text-secondary-color — not JS options; override them in your own CSS. See Styling.

Gradients

waveformColor and progressColor accept either a single CSS colour string or an array of stops, rendered as a gradient along the waveformGradient axis (vertical by default; horizontal sweeps the hue across the whole waveform, diagonal corner-to-corner). A single-element array collapses to one colour. Via data-*, pass a JSON array string:

<div
  data-waveform-player
  data-url="/audio/track.mp3"
  data-waveform-color='["#fafafa", "#71717a"]'
  data-progress-color="#6366f1"
></div>

Presets

When colorPreset is null, the library resolves a theme automatically and applies it to only the colours you left null. The two built-in presets:

Token	dark	light
waveformColor	rgba(255,255,255,0.3)	rgba(0,0,0,0.2)
progressColor	rgba(255,255,255,0.9)	rgba(0,0,0,0.8)

Auto-theme opt-out

Auto-detection (and live re-detection on <html>/<body> theme flips or OS prefers-color-scheme changes) only runs while colorPreset is null and a colour is left unset. Setting an explicit colorPreset or any colour opts that out. Call refreshTheme() to re-detect manually.

---

Metadata & UI

Visibility toggles, track metadata, markers, accessibility, and callbacks.

Visibility & behaviour

Option	Default	Type	Notes
autoplay	false	boolean	Play once loaded. data-autoplay.
showControls	true	boolean	Render the play/pause button. data-show-controls.
showInfo	true	boolean	Render the info block (artwork/title/artist/meta). data-show-info.
showTime	true	boolean	Render current/total time display. data-show-time.
showHoverTime	false	boolean	Show a tooltip that follows the pointer over the waveform, displaying the time at that position (self + external modes). data-show-hover-time.
seekHandle	false	boolean	On the seekbar style only: a draggable circular handle that expands on hover (Spotify-style). Drag-to-scrub works on every style regardless. data-seek-handle.
showBPM	false	boolean	Show the BPM badge. data-show-bpm (the data key differs from the option key).
singlePlay	true	boolean	Pause every other instance when this one plays. data-single-play.
playOnSeek	true	boolean	Start playback when seeking via a marker click while paused. data-play-on-seek.
enableMediaSession	true	boolean	Register system Media Session controls (self mode only). data-enable-media-session.

showBPM → data-show-bpm

This is the one option whose data-* key isn’t a literal kebab-casing of the JS name. The JS option is showBPM; the attribute is data-show-bpm.

Track metadata

Option	Default	Type	Notes
title	null	string | null	Track title; null derives from the URL filename via extractTitleFromUrl. data-title.
artist	null	string | null	Artist row; '' hides it in loadTrack. data-artist.
artwork	null	string | null	Artwork image URL (40×40) + Media Session art. data-artwork.
album	''	string	Media Session album metadata only. data-album.
bpm	null	number | null	Known BPM; wins over auto-detection (shows even when peaks are pre-supplied). data-bpm.
errorText	'Unable to load audio'	string	Message shown in the error overlay (escaped). data-error-text.
playIcon	(built-in SVG)	string	Raw SVG markup for the play glyph. data-play-icon.
pauseIcon	(built-in SVG)	string	Raw SVG markup for the pause glyph. data-pause-icon.

Markers

Option	Default	Type	Notes
markers	[]	Array<{ time: number, label: string, color?: string }>	Clickable cue markers. Reset to [] per-track in loadTrack. data-markers (JSON; bad JSON warns + is skipped).
showMarkers	true	boolean	Render markers (needs a known duration). data-show-markers.

new WaveformPlayer('#player', {
  url: '/audio/mix.mp3',
  markers: [
    { time: 0,   label: 'Intro' },
    { time: 32,  label: 'Drop', color: '#ef4444' },
    { time: 96,  label: 'Outro' },
  ],
});

Accessibility

Option	Default	Type	Notes
accessibleSeek	true	boolean	Expose .waveform-container as role="slider" with arrow/page/home/end keyboard seeking. data-accessible-seek.
seekLabel	null	string | null	Slider accessible name; falls back to title, then 'Seek'. data-seek-label.

Keyboard seeking

With accessibleSeek (the default), the waveform is focusable and keyboard-seekable: Arrows ±5s, PageUp/PageDown ±10s, Home/End to the edges, digits 0–9 jump to tenths, and Space toggles playback. See Accessibility.

Callbacks

Each option callback has an event-dispatch twin (see Events); both fire for the same moment.

Option	Type	Fires
onLoad	(player) => void	After a track’s waveform is drawn.
onPlay	(player) => void	On play (both modes).
onPause	(player) => void	On pause (both modes).
onEnd	(player) => void	On track end (synthesized in external mode at progress >= 1).
onError	(error, player) => void	On load/decode/audio error.
onTimeUpdate	(currentTime, duration, player) => void	On progress; same arg order in both modes.

new WaveformPlayer('#player', {
  url: '/audio/track.mp3',
  onLoad: (p) => console.log('ready:', p.options.url),
  onTimeUpdate: (currentTime, duration) => {
    document.title = `${Math.round((currentTime / duration) * 100)}%`;
  },
  onError: (err) => console.error('[demo]', err),
});

---

Per-track resets

When you swap tracks at runtime with loadTrack(), some options are deliberately reset so the new track can’t inherit stale state:

• waveform → null (otherwise the previous track’s peaks would redraw)
• markers → []
• artist → passing '' clears the row

mergeOptions skips null

The internal merge ignores null/undefined, so a later source can’t clear an earlier value by passing null. That’s exactly why loadTrack explicitly resets waveform and markers per track. If you add your own per-track options, reset them the same way.

---

Complete data-* attribute index

Every attribute the parser recognises, including the marker and library-managed flags.

Attribute	Maps to	Coercion
data-waveform-player	(init marker)	Presence triggers auto-init.
data-waveform-initialized	(set by library)	"true" flag for idempotency — not author-set.
data-url / data-src	url	data-url wins.
data-waveform	waveform	peaks string / JSON array / .json URL.
data-samples	samples	int.
data-preload	preload	string.
data-audio-mode	audioMode	string.
data-playback-rate	playbackRate	float.
data-height	height	int.
data-waveform-style / data-style	waveformStyle	data-waveform-style wins.
data-bar-width	barWidth	int.
data-bar-spacing	barSpacing	int.
data-bar-radius	barRadius	int.
data-layout	layout	string.
data-button-style	buttonStyle	string.
data-button-size	buttonSize	bare number → px float; unit string ('4rem') verbatim.
data-button-align	buttonAlign	string.
data-show-playback-speed	showPlaybackSpeed	bool.
data-playback-rates	playbackRates	JSON array.
data-color-preset / data-theme	colorPreset	data-theme is legacy.
data-waveform-color / data-color	waveformColor	CSS colour or JSON gradient array; data-color is legacy.
data-progress-color	progressColor	CSS colour or JSON gradient array.
data-autoplay	autoplay	bool ('true').
data-show-controls	showControls	bool.
data-show-info	showInfo	bool.
data-show-time	showTime	bool.
data-show-hover-time	showHoverTime	bool.
data-seek-handle	seekHandle	bool.
data-show-bpm	showBPM	bool.
data-bpm	bpm	int.
data-single-play	singlePlay	bool.
data-play-on-seek	playOnSeek	bool.
data-enable-media-session	enableMediaSession	bool.
data-show-markers	showMarkers	bool.
data-markers	markers	JSON (warn + skip on bad JSON).
data-accessible-seek	accessibleSeek	bool.
data-seek-label	seekLabel	string.
data-title	title	string.
data-artist	artist	string.
data-album	album	string.
data-artwork	artwork	string.
data-error-text	errorText	string.
data-play-icon	playIcon	raw SVG.
data-pause-icon	pauseIcon	raw SVG.

---

Next steps

Methods & API

Drive players at runtime — loadTrack, seekTo, setProgress, and the static helpers.

Events

The full waveformplayer:* event map and cancelable request-* events — see Events.

Audio modes

self vs external and how to wire a visualization-only player — see Audio modes.

Styling

CSS classes and the --wfp-* custom properties — see Styling.