Installation

WaveformPlayer is plain, dependency-free JavaScript. Add the stylesheet and the script, and it upgrades any [data-waveform-player] element on the page — no build step required.

CDN (no build step)

<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>

That’s everything. The script auto-initialises on load — see Quick start.

npm

  npm i @arraypress/waveform-player

  pnpm add @arraypress/waveform-player

  yarn add @arraypress/waveform-player

  bun add @arraypress/waveform-player

Then import the core and the stylesheet:

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

Entry points

The package exposes two JavaScript entry points. They are the same library — same class, same options, same events — and differ in one thing: whether importing scans the page.

Import	What loading it does
`@arraypress/waveform-player`	Builds a player for every `[data-waveform-player]` on the page, then hands you the class.
`@arraypress/waveform-player/no-autoinit`	Hands you the class. Nothing else.

The default is what you want on a page you author: drop the markup in, import once, and the players appear.

Reach for /no-autoinit when your code is bundled into a page you don’t author — a CMS block, a WordPress plugin, a widget embedded in someone else’s template. There, the markup on the page isn’t yours to upgrade, and you have no <html> in scope to mark with the data-waveform-autoinit opt-out before your import is evaluated:

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

// Nothing has been initialised. You decide what becomes a player:
new WaveformPlayer( myElement, { url: '/audio/track.mp3' } );
WaveformPlayer.init( myContainer );   // or scan a subtree you own

/no-autoinit was added in 1.27.0. Full detail: choosing an entry point.

Framework wrappers

Using Astro or React? Install the typed wrapper instead — see Astro and React.

For AI agents

The family ships a machine-readable reference at waveformplayer.com/llms.txt — point your coding agent at it and it can wire up a player correctly.