WaveformPlayer

A lightweight, customizable audio player with waveform visualization. Under 6KB gzipped.

Live Demo | Documentation | NPM Package

!Version
!Size
!License
!Downloads

!WaveformPlayer Demo

Why WaveformPlayer?

- Zero Config - Just add data-waveform-player to any div. No JavaScript required.
- Tiny - 8KB gzipped vs 40KB+ for alternatives
- Real Waveforms - Actual audio analysis, not fake waves
- No Dependencies - No jQuery, no bloat, pure vanilla JS
- Works Everywhere - WordPress, Shopify, React, Vue, or plain HTML
- Ecosystem - Optional playlist and analytics addons available

Quick Start

Simplest possible usage:

``html



`html


`javascript
WaveformTracker.init({
endpoint: '/api/analytics',
events: {
listen: 30 // Track after 30 seconds of listening
}
});
`

Learn more →

Comparison

| Feature | WaveformPlayer | WaveSurfer.js | Amplitude.js |
|---------|----------------|---------------|--------------|
| Size (gzipped) | 8KB | 40KB+ | 35KB+ |
| Zero Config | ✅ | ❌ | ❌ |
| Dependencies | None | None | None |
| Waveform Styles | 6 | 3 | N/A |
| Setup Time | 30 seconds | 5+ minutes | 5+ minutes |
| Real Waveforms | ✅ | ✅ | ❌ |
| Keyboard Controls | ✅ | ✅ | ❌ |
| Media Session API | ✅ | ❌ | ❌ |
| Speed Control | ✅ | ✅ | ❌ |

Usage

$3

const player = new WaveformPlayer('#player', {
url: 'audio.mp3',
waveformStyle: 'mirror',
height: 80,
barWidth: 2,
barSpacing: 1,
markers: [
{time: 30, label: 'Verse', color: '#4ade80'},
{time: 60, label: 'Chorus', color: '#f59e0b'}
]
});
`

Visual Styles

Choose from 6 built-in styles:

- bars - Classic waveform bars
- mirror - SoundCloud-style mirrored waveform
- line - Smooth oscilloscope line
- blocks - LED meter blocks
- dots - Circular dots
- seekbar - Minimal progress bar

Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| url | string | '' | Audio file URL |
| waveformStyle | string | 'bars' | Visual style: bars, mirror, line, blocks, dots, seekbar |
| height | number | 60 | Waveform height in pixels |
| barWidth | number | 3 | Width of waveform bars |
| barSpacing | number | 1 | Space between bars |
| samples | number | 200 | Number of waveform samples |
| waveformColor | string | 'rgba(255,255,255,0.3)' | Waveform color |
| progressColor | string | 'rgba(255,255,255,0.9)' | Progress color |
| buttonColor | string | 'rgba(255,255,255,0.9)' | Play button color |
| showTime | boolean | true | Show time display |
| showBPM | boolean | false | Enable BPM detection |
| showPlaybackSpeed | boolean | false | Show speed control menu |
| playbackRate | number | 1 | Initial playback speed (0.5-2) |
| autoplay | boolean | false | Autoplay on load |
| title | string | '' | Track title |
| subtitle | string | '' | Track subtitle |
| artwork | string | '' | Album artwork URL |
| markers | array | [] | Chapter markers array |
| enableMediaSession | boolean | true | Enable system media controls |

API Methods

`javascript
// Control playback
player.play();
player.pause();
player.togglePlay();

// Seek
player.seekTo(30); // Seek to 30 seconds
player.seekToPercent(0.5); // Seek to 50%

// Volume
player.setVolume(0.8); // 80% volume

// Speed
player.setPlaybackRate(1.5); // 1.5x speed

// Dynamic loading
await player.loadTrack('new-song.mp3', 'New Title', 'New Artist');

// Destroy
player.destroy();
`

Events

`javascript
new WaveformPlayer('#player', {
url: 'audio.mp3',
onLoad: (player) => console.log('Loaded'),
onPlay: (player) => console.log('Playing'),
onPause: (player) => console.log('Paused'),
onEnd: (player) => console.log('Ended'),
onTimeUpdate: (current, total, player) => {
console.log(${current}/${total});
}
});
`

Keyboard Controls

When a player is focused (click on it):

- Space - Play/pause
- ←/→ - Seek backward/forward 5 seconds
- ↑/↓ - Volume up/down
- M - Mute/unmute
- 0-9 - Jump to 0%-90% of track

Advanced Usage

$3

For better performance, generate waveform data server-side:

`javascript
// Generate waveform data once
const waveformData = await WaveformPlayer.generateWaveformData('audio.mp3');

// Use pre-generated data for instant display
new WaveformPlayer('#player', {
url: 'audio.mp3',
waveform: waveformData // Bypass client-side processing
});
`

$3

`javascript
// Get all instances
const players = WaveformPlayer.getAllInstances();

// Find specific player
const player = WaveformPlayer.getInstance('my-player');

// Destroy all players
WaveformPlayer.destroyAll();
`

$3

`css
.waveform-player {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
border-radius: 12px;
}

.waveform-btn {
border-color: #fff;
}
`

Framework Integration

$3