Waveform Generator

Generate waveform peak data from audio files for WaveformPlayer and WaveformBar.

Pre-generated waveforms mean instant visualization — no client-side audio decoding needed.

Quick Start

# Run directly with npx
npx @arraypress/waveform-gen ./audio/*.mp3 --output ./waveforms/

# Or install globally
npm install -g @arraypress/waveform-gen

CLI Usage

# Generate JSON per audio file
waveform-gen ./audio/*.mp3 --output ./waveforms/

# Directory scan
waveform-gen ./audio/ --recursive --output ./waveforms/

# Custom sample count
waveform-gen ./audio/*.mp3 --output ./waveforms/ --samples 400

# Print peaks to stdout (for piping)
waveform-gen song.mp3 --format inline

Options

Option	Default	Description
--samples <n>	1800	Number of peaks to generate
--precision <n>	2	Decimal places for rounding
--output <dir>	Same as input	Output directory
--format <type>	json	json or inline (stdout)
--recursive	off	Scan directories recursively
--quiet	off	Suppress progress output

Output Format

{
  "peaks": [
    0.2,
    0.37,
    0.41,
    0.55,
    ...
  ]
}

With markers (auto-detected from sidecar file):

{
  "peaks": [
    0.2,
    0.37,
    0.41,
    0.55,
    ...
  ],
  "markers": [
    {
      "time": 0,
      "label": "Intro"
    },
    {
      "time": 30,
      "label": "Chorus"
    }
  ]
}

Markers

Place a .markers.txt file alongside the audio with the same name:

# song.markers.txt
0:00 Intro
0:30 Verse 1
1:15 Chorus
1:02:30 Bridge

Supports SS, MM:SS, and H:MM:SS timestamps. Lines starting with # are ignored. Markers are auto-detected — no flag needed.

Using with WaveformPlayer

<div data-waveform-player
     data-url="song.mp3"
     data-waveform="waveforms/song.json">
</div>

Using with WaveformBar

<div data-wb-play
     data-url="song.mp3"
     data-wb-waveform="waveforms/song.json">
</div>

Library Usage

npm install @arraypress/waveform-gen

import {generatePeaks} from '@arraypress/waveform-gen';

const {peaks} = await generatePeaks('./song.mp3', {
    samples: 1800,
    precision: 2
});

Supported Audio

MP3, WAV, FLAC, OGG, M4A, AAC

Requirements

Node.js 18+

Ecosystem

Package	Description
WaveformPlayer	Core audio player with waveform visualization
WaveformBar	Persistent bottom-bar player with queue, favorites, cart, DJ mode
WaveformGen	CLI tool to pre-generate waveform JSON from audio files
WaveformPlaylist	Playlist and chapter support addon
WaveformTracker	Audio engagement analytics

License

MIT © ArrayPress