Install

npm install @arraypress/waveform-player

Load from a CDN and it auto-initializes every [data-waveform-player] on the page:

<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="track.mp3" data-title="My Song" data-artist="The Artist"></div>

Or drive it from JavaScript:

import WaveformPlayer from '@arraypress/waveform-player';

new WaveformPlayer('#player', { url: 'track.mp3', title: 'My Song', artist: 'The Artist' });

Initializing only what you control

Pages that render markup they don't author — user content, a CMS, an editor canvas — can turn the automatic scan off from the document element:

<html data-waveform-autoinit="false">

Nothing is initialized until you ask for it. Pass init() a root to scan only the subtree you own:

WaveformPlayer.init( document.querySelector( '#my-app' ) );

Constructing players directly still works too; only the scan on import is suppressed.

That attribute is for pages. If you're bundled into a page you don't author — a CMS block, a plugin, a widget dropped into someone else's template — there's no <html> in scope to mark before your import is evaluated. Import the library without the scan instead:

import WaveformPlayer from '@arraypress/waveform-player/no-autoinit';

// Identical in every other way. Nothing is initialized until you say so:
WaveformPlayer.init( myContainer );
new WaveformPlayer( el, { url: 'track.mp3' } );

Same class, same options, same window.WaveformPlayer; ships as ESM and CJS. Pick one entry point per bundle — each carries its own copy of the class and its own instance registry.

This scopes initialization — it isn't a sanitizer. playIcon / pauseIcon (and their data-play-icon / data-pause-icon equivalents) inject raw markup by design, for any player you do build. Untrusted content still needs sanitizing before it reaches the page.

Documentation

Every option, style, event and method is documented on the docs site.

-> docs.waveformplayer.com

Options · Waveform styles · Events · Methods · Accessibility

Extensions: Bar · Playlist · Tracker · Gen — Frameworks: React · Vue · Svelte · Astro

License

MIT © ArrayPress