Methods

Every WaveformPlayer exposes a small, predictable instance API for playback, seeking, runtime track swaps, theming and teardown, plus a set of static helpers for instance lookup and build-time peak generation. This page documents every public method — its signature, parameters, return value and mode-specific behaviour.

For the option surface those methods read and write, see Options. For the events they emit, see Events.

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

const player = new WaveformPlayer('#player', { url: '/audio/track.mp3' });
player.play();

Self mode vs. external mode

Several methods behave differently — or are no-ops — depending on audioMode. In the default 'self' mode the player owns an <audio> element and these methods drive it directly. In 'external' mode there is no <audio> (player.audio is null): seekTo, seekToPercent, setVolume and setPlaybackRate are no-ops, and play / pause dispatch cancelable waveformplayer:request-* events instead of moving an audio clock. See setPlayingState / setProgress for driving an external player.

Construction

new WaveformPlayer(container, options?)

Creates and mounts a player.

Parameter	Type	Description
container	string | HTMLElement	A CSS selector or an element. The selector is resolved with querySelector.
options	WaveformPlayerOptions	Optional. See Options.

Returns the WaveformPlayer instance. Throws Error('[WaveformPlayer] Container element not found') if the container cannot be resolved.

Configuration is merged in precedence order defaults < data-* attributes < constructor options, then the resolved colour preset and per-style bar sizing (STYLE_DEFAULTS) are applied. Aliases are normalized (style → waveformStyle, src → url; the canonical key wins). The instance is registered in WaveformPlayer.instances, the DOM and audio are initialized, and waveformplayer:ready fires roughly 100 ms later.

// Selector
const a = new WaveformPlayer('#player', { url: '/audio/a.mp3' });

// Element reference
const el = document.querySelector('.my-player');
const b = new WaveformPlayer(el, { url: '/audio/b.mp3', waveformStyle: 'bars' });

Tip

You rarely need new for declarative markup. Any element carrying data-waveform-player is instantiated automatically on DOMContentLoaded, and you can re-scan the DOM at any time with WaveformPlayer.init(). See Installation.

Playback control

These work in both modes. In 'external' mode play / pause are requests, not commands — they dispatch a cancelable event and the controller decides whether to honour it.

play()

Starts playback.

• Self mode — pauses every other instance first if singlePlay is enabled, then returns the native audio.play() promise (Promise<void>).
• External mode — dispatches a cancelable waveformplayer:request-play event and returns undefined. If a listener calls preventDefault(), the request is vetoed.

Returns Promise<void> | undefined.

// Self mode: handle autoplay rejection
player.play()?.catch((err) => console.warn('Autoplay blocked', err));

pause()

Pauses playback. Self mode calls audio.pause(); external mode dispatches a cancelable waveformplayer:request-pause. Returns void.

togglePlay()

Plays if currently paused, pauses if currently playing. Works in both modes. Returns void.

button.addEventListener('click', () => player.togglePlay());

Seeking

Caution

seekTo and seekToPercent only act in self mode (they move the owned <audio> clock). In external mode they are no-ops — drive the position with setProgress instead, or let the canvas/keyboard emit waveformplayer:request-seek.

seekTo(seconds)

Sets the playback position to an absolute time.

Parameter	Type	Description
seconds	number	Target time; clamped to [0, duration].

Refreshes the progress overlay and time displays. No-op when there is no audio or no known duration. Returns void.

seekToPercent(percent)

Seeks to a fraction of the total duration.

Parameter	Type	Description
percent	number	Fraction of duration; clamped to [0, 1].

Returns void.

player.seekTo(30);        // jump to 0:30
player.seekToPercent(0.5); // jump to the midpoint

Loading tracks

load(url)

Loads (or reloads) audio into the existing player: sets the title, fetches or generates and draws the peaks, renders markers, initializes Media Session (self mode), and fires the onLoad callback. Self mode awaits the audio’s loadedmetadata event. Any load, decode or audio error funnels through onError.

Parameter	Type	Description
url	string	Audio file URL.

Returns Promise<void>.

load() is the low-level primitive. For most runtime swaps prefer loadTrack(), which also resets per-track state and updates the info DOM.

loadTrack(url, title?, artist?, options?)

Swaps the current track at runtime. Pauses, resets the audio / error / progress state, resets per-track options (markers → [] and waveform → null), merges the supplied options, updates the artist and artwork DOM, then calls load(). It auto-plays the new track unless options.autoplay === false.

Parameter	Type	Description
url	string	New audio URL.
title	string | null	Optional. Track title; null derives it from the URL filename.
artist	string | null	Optional. Artist row; pass '' to hide it.
options	object	Optional. Per-track overrides merged over current options (e.g. markers, waveform, artwork, bpm, autoplay).

Returns Promise<void>.

await player.loadTrack('/audio/next.mp3', 'Next Track', 'Some Artist', {
  artwork: '/img/next.jpg',
  waveform: WaveformPlayer.getPeaksUrl('/audio/next.mp3'), // skip decode
  markers: [{ time: 12, label: 'Drop' }],
  autoplay: false,
});

Why the per-track reset matters

mergeOptions skips null / undefined, so a later call can’t clear an earlier value by passing null. That is exactly why loadTrack explicitly resets options.waveform = null and options.markers = [] for every track — otherwise the previous track’s peaks and markers would persist and the new track would redraw the old waveform (the 1.8.1 fix). If you add your own per-track options, reset them here too.

Audio settings (self mode)

setVolume(volume)

Sets the audio volume.

Parameter	Type	Description
volume	number	Clamped to [0, 1]. Non-finite input is ignored.

No-op in external mode. Returns void.

setPlaybackRate(rate)

Sets the playback speed.

Parameter	Type	Description
rate	number	Clamped to 0.5–2.

Applies to the audio, persists to options.playbackRate, and refreshes the speed menu UI. No-op in external mode. Returns void.

player.setVolume(0.8);
player.setPlaybackRate(1.5);

Waveform & markers

setWaveformData(data)

Replaces the current peaks and redraws.

Parameter	Type	Description
data	number[] | string	Inline array, comma-separated string, JSON-array string, or a .json URL (fetched asynchronously; embedded { peaks, markers } honoured).

Malformed input normalizes to []. Returns void.

player.setWaveformData([0.1, 0.4, 0.8, 0.5, 0.2]);
player.setWaveformData('/peaks/track.json');

setActiveMarker(index)

Toggles the .active class on a single marker and clears it from the rest. An active marker is highlighted and reveals its label.

Parameter	Type	Description
index	number | null	Marker index to activate; null clears all markers.

Returns void.

Markers activate automatically

During playback the player drives this for you — it highlights the marker the playhead has most recently passed (the greatest time ≤ the current time) and briefly flashes its label, which then fades while the highlight stays (both audio modes). The flash is CSS-overridable via .waveform-marker.show-label — keep the label on with .waveform-marker.active .waveform-marker-tooltip { opacity: 1 }, or hide it with { opacity: 0 !important }. Call setActiveMarker() only when an external controller wants to override which marker is highlighted.

resizeCanvas()

Recomputes the canvas backing size for the current container width and device pixel ratio, then redraws. Returns void.

Redraws are normally driven automatically by a ResizeObserver on the canvas’s parent plus a debounced window-resize handler. A pure DOM move (re-parenting the player without a size change) may not trip the observer — call resizeCanvas() explicitly after relocating a player.

newParent.appendChild(player.container);
player.resizeCanvas(); // force a redraw after the move

Driving an external player

These are the inbound pump for audioMode: 'external': a controller (for example a single shared <audio>, or waveform-bar) calls them to push play-state and progress into the visualization. They are how the canvas stays in sync when the player itself owns no audio.

setPlayingState(playing)

Flips the play/pause visual state without touching any audio.

Parameter	Type	Description
playing	boolean	true shows the playing state, false the paused state.

Emits waveformplayer:play / waveformplayer:pause and runs the matching callback only on a transition (idempotent if the state is unchanged). Returns void.

setProgress(currentTime, duration)

Updates the progress overlay and time displays from an external clock.

Parameter	Type	Description
currentTime	number	Current position in seconds.
duration	number	Total duration in seconds. No-op if <= 0.

Stores the external duration, emits waveformplayer:timeupdate, and synthesizes a one-shot waveformplayer:ended once currentTime / duration >= 1. Returns void.

// External mode: pump from a shared audio element
const player = new WaveformPlayer('#viz', { audioMode: 'external' });

sharedAudio.addEventListener('play',  () => player.setPlayingState(true));
sharedAudio.addEventListener('pause', () => player.setPlayingState(false));
sharedAudio.addEventListener('timeupdate', () =>
  player.setProgress(sharedAudio.currentTime, sharedAudio.duration));

// Honour the canvas's seek request against your own clock
player.container.addEventListener('waveformplayer:request-seek', (e) => {
  sharedAudio.currentTime = e.detail.percent * sharedAudio.duration;
});

Theming

refreshTheme()

Re-detects the page colour scheme and re-applies auto colours, then redraws.

No-op when colorPreset is set explicitly, or when colours were hand-set — only the colours you left null follow the resolved preset. Returns void.

You rarely need to call this by hand: a single shared MutationObserver plus a matchMedia watcher already re-detects on <html> / <body> class, data-theme, data-color-scheme or style changes, and on OS prefers-color-scheme flips, calling refreshTheme() on every instance. Call it manually only when you change the theme through a channel those watchers don’t observe.

Lifecycle

destroy()

Tears the player down completely. It flags itself as destroying, emits waveformplayer:destroy (first, so listeners can release references), pauses playback, stops the animation frame loop, aborts all DOM/document listeners via its AbortController, disconnects the ResizeObserver, removes the resize handler, drops itself from instances and currentlyPlaying, resets and nulls the audio element, and empties the container. Returns void.

player.container.addEventListener('waveformplayer:destroy', () => cleanup());
player.destroy();

Caution

After destroy() the instance is no longer registered and its container is empty. Don’t call further methods on it — create a new player if you need one again.

Static methods

WaveformPlayer.getInstance(idOrElement)

Looks up a live instance.

Parameter	Type	Description
idOrElement	string | HTMLElement	An instance id, an element, or an element’s id.

Returns WaveformPlayer | undefined.

const p = WaveformPlayer.getInstance('#player') ?? WaveformPlayer.getInstance(el);
p?.play();

WaveformPlayer.getAllInstances()

Returns WaveformPlayer[] — every live instance.

WaveformPlayer.getAllInstances().forEach((p) => p.pause());

WaveformPlayer.destroyAll()

Calls destroy() on every live instance and clears the instance map. Returns void. Useful in SPA route teardown or hot-module-reload disposal.

WaveformPlayer.init()

Re-scans the DOM for [data-waveform-player] elements and instantiates any that aren’t yet initialized. Idempotent: the library marks each handled element with data-waveform-initialized="true", so re-running skips them. It also runs automatically on DOMContentLoaded. Returns void.

Call it after injecting new markup (AJAX, client-side routing, a CMS preview pane):

container.innerHTML = '<div data-waveform-player data-src="/audio/new.mp3"></div>';
WaveformPlayer.init(); // mounts the freshly injected player

WaveformPlayer.getPeaksUrl(audioUrl)

Derives the sibling peaks URL for an audio file by swapping its extension to .json — the build-time counterpart to decoding audio in the browser.

Parameter	Type	Description
audioUrl	string | null | undefined	An audio URL ending in mp3, wav, ogg, flac, m4a or aac. Any ?query / #hash is preserved.

Returns string | undefined — the .json URL, or undefined if the extension isn’t recognised. Pass the result as the waveform option to skip the Web Audio decode entirely.

WaveformPlayer.getPeaksUrl('/audio/track.mp3');     // '/audio/track.json'
WaveformPlayer.getPeaksUrl('/audio/track.wav?v=2'); // '/audio/track.json?v=2'
WaveformPlayer.getPeaksUrl(undefined);              // undefined

const player = new WaveformPlayer('#player', {
  url: '/audio/track.mp3',
  waveform: WaveformPlayer.getPeaksUrl('/audio/track.mp3'),
});

WaveformPlayer.generateWaveformData(url, samples?)

Decodes an audio URL to a peaks array without creating a player — handy for pre-rendering peaks or feeding another component.

Parameter	Type	Description
url	string	Audio file URL to decode.
samples	number	Optional, default 200. Peak resolution.

Returns Promise<number[]>.

const peaks = await WaveformPlayer.generateWaveformData('/audio/track.mp3', 256);
new WaveformPlayer('#player', { url: '/audio/track.mp3', waveform: peaks });

Type drift

The runtime resolves to a plain number[] (the peaks). The hand-written index.d.ts currently declares Promise<{ peaks, bpm }> — treat the runtime shape as authoritative.

Static properties

Property	Type	Description
WaveformPlayer.instances	Map<string, WaveformPlayer>	Live instances keyed by id.
WaveformPlayer.currentlyPlaying	WaveformPlayer | null	The instance currently playing (drives singlePlay).

console.log(`${WaveformPlayer.instances.size} players mounted`);
WaveformPlayer.currentlyPlaying?.pause();

Utility bridge

WaveformPlayer.utils

A bag of shared, pure helpers bridged onto the class so sibling packages and CDN consumers can reuse them.

Helper	Signature	Description
formatTime	(seconds: number) => string	Formats seconds as a clock string.
extractTitleFromUrl	(url: string) => string	Derives a display title from a URL filename.
escapeHtml	(str: string) => string	HTML-escapes a string.
isSafeHref	(url: string) => boolean	Validates a URL is safe to use as an href.
parseDataAttributes	(element: HTMLElement) => object	Parses the data-* contract into an options object.

const label = WaveformPlayer.utils.formatTime(95); // '1:35'

Method reference at a glance

Method	Mode	Returns
play()	both	Promise<void> | undefined
pause()	both	void
togglePlay()	both	void
seekTo(seconds)	self	void
seekToPercent(percent)	self	void
load(url)	both	Promise<void>
loadTrack(url, title?, artist?, options?)	both	Promise<void>
setVolume(volume)	self	void
setPlaybackRate(rate)	self	void
setWaveformData(data)	both	void
setActiveMarker(index)	both	void
resizeCanvas()	both	void
setPlayingState(playing)	external	void
setProgress(currentTime, duration)	external	void
refreshTheme()	both	void
destroy()	both	void
WaveformPlayer.getInstance(idOrElement)	static	WaveformPlayer | undefined
WaveformPlayer.getAllInstances()	static	WaveformPlayer[]
WaveformPlayer.destroyAll()	static	void
WaveformPlayer.init()	static	void
WaveformPlayer.getPeaksUrl(audioUrl)	static	string | undefined
WaveformPlayer.generateWaveformData(url, samples?)	static	Promise<number[]>

See also

Options

Every constructor option and data-* attribute these methods read and write. See Options.

Events

The events emitted by play, setProgress, destroy and friends — and the cancelable request-* events external mode dispatches. See Events.