2.0 — WaveformPlayer 2.0: zero-bandwidth pages, looping, volume and one package per framework. What's new →
v2.1.0 2.0: zero-bandwidth pages, looping and TypeScript

Beautiful audio visualization, no JavaScript required.

A small, zero-dependency family for the web — a canvas waveform player, a persistent bottom bar, playlists, a sample-pack sound browser, analytics and build-time tooling. Add a few data attributes and ship.

$ npm i @arraypress/waveform-player

Pick your package manager — or hand it to your agent.

~18KB gzipped · Zero dependencies · 6 visual styles · MIT licensed

52 GitHub stars 656k downloads/mo 10 packages

In WordPress core

The Playlist block in WordPress 7.1 draws its waveforms with WaveformPlayer.

WordPress 7.1 "Mary Lou" shipped on 19 August 2026 with a Playlist block in core, and the waveform inside it is @arraypress/waveform-player, bundled straight into the core block library — no plugin, no build step. The block's Visualization style dropdown is the same six styles you get here: bars, mirror, line, blocks, dots and seekbar.

Zero config

Drop in a <div>. That's the whole setup.

No bundler, no framework, no init call. Include the script, add attributes, and every matching element becomes a player on load.

index.html
<link rel="stylesheet"
  href="https://unpkg.com/@arraypress/waveform-player/dist/waveform-player.css">
<script src="https://unpkg.com/@arraypress/waveform-player"></script>

<div data-waveform-player
     data-url="track.mp3"
     data-artwork="cover.webp"
     data-title="Midnight Dreams"
     data-artist="The Wavelength"
     data-waveform-style="mirror"
     data-show-bpm="true"
     data-bpm="120"></div>

Six visual styles

One attribute switches the look.

bars · mirror · line · blocks · dots · seekbar — every style reads the same waveform data and adapts to your theme.

Bars data-waveform-style="bars"
Mirror data-waveform-style="mirror"
Line data-waveform-style="line"
Blocks data-waveform-style="blocks"
Dots data-waveform-style="dots"
Seekbar data-waveform-style="seekbar"

Preview layout

A compact layout for sample packs.

The preview layout centers the title under the waveform and trims the controls — drop a grid of them into any sample or beat store.

Built for the modern web

Everything you need, nothing you don't.

Zero JavaScript

Add a few data attributes to any element. Auto-initializes on load — no build step, no wiring.

~18KB gzipped

The whole core, zero dependencies. Canvas rendering, controls and keyboard support included.

Media Session

Lock-screen artwork and hardware media keys via the Media Session API, out of the box.

Keyboard ready

Space, arrows, number keys and an accessible seek slider — fully operable without a mouse.

Playback speed

Per-player speed control with configurable rates — built for podcasts and courses.

Auto theme

Detects the surrounding background and adapts its palette. Dark, light, or anything between.

New in 2.0

Lighter pages, more control.

The same player and the same markup, rewritten in TypeScript — most pages upgrade without a change. The player below knows its length and its waveform before any audio loads: nothing is fetched until you press play.

Zero-bandwidth pages

Give a player its duration and compact peaks and it shows its waveform and length with no audio downloaded until play.

Lazy loading

data-lazy holds a player back until it nears the viewport — a long catalogue only draws what people scroll to.

Looping

Loop the whole track or a section between two points, with an optional loop toggle in the controls.

Volume

An optional volume slider and mute button, with setVolume() and setMuted() for your own controls.

Download link

showDownload adds a download link to the player, pointing at the track or a file of your choice.

Custom elements

<waveform-player>, <waveform-playlist> and <waveform-sounds> take every option as an attribute — the same components, as tags.

One package per framework

waveform-react, -vue, -svelte and -astro, with a sub-path per component, replace sixteen wrappers.

TypeScript

Every package is written in TypeScript and ships its generated types, so editors know every option.

Upgrading from 1.x? Read what changes in 2.0 — and who has to change anything.

The family

One core. A whole audio toolkit.

The player is the foundation — extensions snap on to cover real-world products: a persistent bar, playlists, a sound browser, analytics, and a peaks generator.

WaveformBar v2.0.0

A persistent, Spotify-style bottom bar.

Queue, volume, repeat, favorites, cart and DJ markers — with cross-page session persistence. Pick a track to launch the real bar.

  • Play queue
  • Favorites & cart
  • Repeat modes
  • Session persistence
Explore the bar
WaveformPlaylist v2.1.0

Playlists and chapters, from markup.

Turn a list of tracks into a full album or podcast player with artwork, durations and chapter navigation — keyboard-accessible out of the box.

  • Track list + artwork
  • Chapter markers
  • Continuous play
  • N / P / 1–9 keys

Album

Podcast series · tracks + chapters

Introduction
The main idea
Going deeper
Wrap-up
Cold open
The interview
Sign-off
WaveformSounds v2.2.0

A sound browser for sample packs.

A searchable, filterable list of previews with a mini waveform per row — and one shared player underneath, however many sounds the pack has. Play one, then press ↓ to hear the next.

  • Search + filters
  • Type, key, BPM
  • ↑ / ↓ auditioning
  • One audio engine
Explore the sound browser
  • Drum LoopDrum loops, 128 BPM, 0:03, Loop
  • Electric PianoKeys, 126 BPM, 0:07
  • House PianoKeys, 126 BPM, key C sharp minor, 0:07
  • Too YoungLeads, 121 BPM, 0:07
  • PlankPlucks, 121 BPM, key E flat major, 0:07
  • Spaces In BetweenPlucks, 121 BPM, key B flat major, 0:07
  • Too YoungPlucks, 121 BPM, key G minor, 0:07

WaveformTracker v2.0.0

Know what's actually heard.

Privacy-first engagement analytics — credits real media-time, ignores seeks, no cookies. Send to any endpoint or handler.

Listens · last 7 days 18%
12,480
WaveformGen v3.1.0

Pre-compute peaks at build time.

A tiny Node CLI that turns audio into peak JSON (and BPM) so players paint instantly — no client-side Web Audio decode.

Generating peaks… 1800 samples

Framework components

Typed components for Astro, React, Vue, and Svelte.

One package per framework, with a sub-path for each component — /player, /bar, /playlist, /sounds — over only the cores you install. Every option as a typed prop, SSR-safe, with the core left untouched.

Player.astro
---
// npm i @arraypress/waveform-astro @arraypress/waveform-player
import WaveformPlayer from '@arraypress/waveform-astro/player';
---
<WaveformPlayer
  src="/track.mp3"
  title="Midnight Dreams"
  waveformStyle="mirror"
  showBPM
/>
Track.tsx
// npm i @arraypress/waveform-react @arraypress/waveform-player
import { WaveformPlayer } from '@arraypress/waveform-react/player';
import '@arraypress/waveform-player/styles.css';

export function Track() {
  return (
    <WaveformPlayer
      url="/track.mp3"
      title="Midnight Dreams"
      waveformStyle="mirror"
      showBPM
    />
  );
}

10 packages

The whole family, on npm.

Mix and match — install only what you need. Every package is public, MIT-licensed and dependency-light.

v2.1.0

WaveformPlayer~18KB

The zero-config core. Canvas waveform player with six visual styles, keyboard control, Media Session and a <waveform-player> element — TypeScript, zero dependencies.

Core
v2.0.0

WaveformBar~13KB

Persistent Spotify-style bottom bar — queue, volume, repeat, favorites, cart, DJ markers and cross-page session persistence.

Extension
v2.1.0

WaveformPlaylist~8KB

Playlist and chapter navigation — podcasts, courses, albums and audiobooks — as markup or a <waveform-playlist> element. Fully keyboard-accessible.

Extension
v2.2.0

WaveformSounds~19KB

Searchable, filterable sound list for sample packs — a mini waveform per row, type / key / BPM filters, keyboard auditioning, one shared audio engine and a <waveform-sounds> element.

Extension
v2.0.0

WaveformTracker~2KB

Privacy-first listen analytics. Credits real media-time engagement, ignores seeks, no cookies — send to any endpoint.

Extension
v3.1.0

WaveformGen

Node CLI + library to pre-generate waveform peaks (and BPM) from audio files — compact wp1: peaks, sound manifests and ready-made player HTML. Instant render, no client-side decode.

Tooling
v2.2.0

React

React 19 components — /player, /bar, /playlist and /sounds, each over the core you install. Every option a typed prop, onSeek / onLoop / onVolumeChange callbacks and a ref handle.

Framework
v2.2.0

Vue

Vue 3 components — /player, /bar, /playlist and /sounds, each over the core you install. Typed props, @seek / @loop / @volumechange emits and an exposed API.

Framework
v2.2.0

Svelte

Svelte 5 components — /player, /bar, /playlist and /sounds, each over the core you install. Typed props, onseek / onloop / onvolumechange callbacks and bind:this methods.

Framework
v2.2.0

Astro

Astro components — /player, /bar, /playlist and /sounds, each over the core you install. Server-rendered markup, every option a typed prop, and View Transitions-safe.

Framework

Use cases in 2026

What people build with it in 2026.

From sample packs and beat stores to podcasts, audiobooks and AI voice — a lightweight waveform audio player that drops into any product with a script and a <div>. Accessible, keyboard-first and MIT-licensed.

Sample & loop stores

Preview sample packs, loops and one-shots on Shopify, WooCommerce or any storefront — pre-computed peaks paint the waveform instantly, no decode.

Beat marketplaces

Sell beats and type beats with a persistent play bar, queue and add-to-cart triggers — straight from markup, no framework required.

Podcasts

Ship podcast episode players with chapters, variable playback speed and Media Session lock-screen controls out of the box.

Audiobooks

Long-form audiobook and chaptered narration players with resumable position and keyboard-first seeking.

AI voice & TTS

Showcase AI voiceovers, text-to-speech and voice-cloning demos with a clean waveform and instant scrubbing.

Courses & e-learning

Audio lessons, language practice and lecture recordings with chapters and full keyboard control — accessible to every learner.

Musicians & labels

Embed releases, EPs and demos as album playlists with per-track artwork and BPM — from plain HTML.

DJ mixes & radio

Continuous DJ mixes and radio shows with cue markers, gapless queue advance and cross-page playback persistence.

Sound effects & SFX

Browse sound-effect and foley libraries where the waveform shape is the fastest way to find the right hit.

Meditation & wellness

Sleep sounds, ambient tracks and guided-meditation apps with a calm, monochrome player that matches any theme.

Publishers & news

Listen-to-this-article audio and AI voice summaries that adapt to light or dark page themes automatically.

Voice notes & social

Voice messages, audio comments and UGC waveforms in social and messaging apps — tiny footprint, framework-agnostic.

How it compares

A toolkit, not just a waveform.

WaveformPlayer WaveSurfer.js Amplitude.js
Zero-config HTML
Canvas waveform
Six visual styles
Media Session API
Persistent bottom bar
Playlist + chapters
Filterable sound list
Listen analytics
Accessibility + keyboard
Framework components
Zero dependencies

Capability comparison; each library has its own strengths.

Framework agnostic

Works anywhere a <script> does.

HTML
React
Vue
Svelte
Astro
WordPress
Shopify

Start shipping beautiful audio.

Free, open-source and ~18KB — add a div and go.

Read the docs

API reference, guides and recipes for all nine packages.

Browse docs

Open the builder

Configure a player visually and copy the HTML, JS or React.

Try it

Star on GitHub

MIT-licensed, open source, zero dependencies.

View source