Waveform Renderer

A lightweight and customizable TypeScript library for rendering audio waveforms on HTML canvas. Create beautiful, interactive audio visualizations with ease.

📝 Table of Contents

• Features
• Installation
• Quick Start
• API
  • Configuration Options
  • Events
  • Exports
  • Methods
• Examples
• Browser Support
• Motivation
• Contributing
• License
• Acknowledgements

✨ Features

• 🎨 Highly customizable appearance
• ⚡ Performant canvas-based rendering
• 📱 Responsive and touch-friendly
• 🔄 Real-time progress updates
• 🎯 Interactive seeking
• 💪 Written in TypeScript with full type support
• 📏 Resolution independent with HiDPI/Retina support

🚀 Installation

npm install waveform-renderer
# or
yarn add waveform-renderer

📖 Quick Start

import { WaveformRenderer } from 'waveform-renderer';

// Get your canvas element
const canvas = document.getElementById('waveform') as HTMLCanvasElement;

// Prepare your audio peaks data
const peaks = [...]; // Array of numbers

// Create waveform instance
const waveform = new WaveformRenderer(canvas, peaks, {
  color: '#2196F3',
  backgroundColor: '#E3F2FD',
  progressLine: {
    color: '#1565C0'
  }
});

// Listen to events
waveform.on('seek', (progress) => {
  console.log(`Seeked to ${progress * 100}%`);
});

🛠 API

Configuration Options

WaveformOptions

Option	Type	Default	Description
amplitude	number	1	Amplitude multiplier for the waveform
backgroundColor	string	"#CCCCCC"	Background color of the waveform
barWidth	number	2	Width of each bar in pixels
borderColor	string	"#000000"	Border color of the bars
borderRadius	number	0	Border radius of the bars in pixels
borderWidth	number	0	Border width of the bars in pixels
color	string	"#000000"	Color of the waveform bars
gap	number	1	Gap between bars in pixels
minPixelRatio	number	1	Minimum pixel ratio for rendering
position	"bottom" | "center" | "top"	"center"	Vertical positioning of the waveform
progress	number	0	Initial progress (0-1)
smoothing	boolean	true	Whether to apply smoothing to the rendering
progressLine	ProgressLineOptions	null	Progress line options

ProgressLineOptions

Option	Type	Default	Description
color	string	"#FF0000"	Color of the progress line
heightPercent	number	1	Height of the line as percentage of total height
position	"bottom" | "center" | "top"	"center"	Vertical position of the line
style	"solid" | "dashed" | "dotted"	"solid"	Style of the progress line
width	number	2	Width of the line in pixels

🎯 Events

The waveform renderer emits the following events:

Event	Payload	Description
renderStart	void	Emitted when rendering begins
renderComplete	void	Emitted when rendering is complete
seek	number	Progress value between 0-1 when user seeks
error	Error	Error object when an error occurs
destroy	void	Emitted when the instance is destroyed
ready	void	Emitted when the waveform is ready
resize	{ width: number; height: number }	New dimensions when canvas is resized
progressChange	number	New progress value between 0-1

Example of type-safe event handling:

waveform.on("resize", ({ width, height }) => {
    console.log(`Canvas resized to ${width}x${height}`);
});

waveform.on("seek", progress => {
    // progress is a number between 0-1
    audioElement.currentTime = audioElement.duration * progress;
});

📦 Exports

The library provides the following exports:

Main Component

import { WaveformRenderer } from "waveform-renderer";

Utility Functions

import { getPeaksFromAudioBuffer } from "waveform-renderer";

This utility helps you calculate peaks from an AudioBuffer, useful when you need to generate waveform data from raw audio.

TypeScript Types

import type { WaveformOptions, ProgressLineOptions, WaveformEvents, RenderMode } from "waveform-renderer";

Example of using the utility function:

// Get an AudioBuffer from your audio source
const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);

// Calculate peaks
const peaks = getPeaksFromAudioBuffer(audioBuffer);

// Create waveform with calculated peaks
const waveform = new WaveformRenderer(canvas, peaks, options);

🔧 Methods

Constructor

constructor(
  canvas: HTMLCanvasElement,
  peaks: number[],
  options?: Partial<WaveformOptions>
)

Instance Methods

• setOptions(options: Partial<WaveformOptions>): Updates the waveform options
• setPeaks(peaks: number[]): Updates the waveform peaks data
• setProgress(progress: number): Updates the current progress (0-1)
• destroy(): Cleans up and removes the instance

💡 Examples

Custom Styling

const waveform = new WaveformRenderer(canvas, peaks, {
    color: "#2196F3",
    backgroundColor: "#E3F2FD",
    barWidth: 3,
    gap: 2,
    borderRadius: 2,
    progressLine: {
        color: "#1565C0",
        style: "dashed",
        width: 2,
    },
});

Event Handling

const waveform = new WaveformRenderer(canvas, peaks);

waveform.on("ready", () => {
    console.log("Waveform is ready!");
});

waveform.on("seek", progress => {
    audioElement.currentTime = audioElement.duration * progress;
});

// Cleanup
waveform.off("seek", seekHandler);
// or remove all listeners
waveform.removeAllListeners();

🌐 Browser Support

The library works in all modern browsers that support Canvas and ES6.

💡 Motivation

While wavesurfer.js is an excellent library, we needed a more focused solution. Waveform Renderer was created to be a lightweight alternative that concentrates solely on waveform visualization, eliminating additional features like playback, regions, or spectrograms. This results in:

• 🎯 Focused scope: just waveform rendering
• 📦 Smaller bundle size
• 💪 TypeScript-first development
• ⚡ Optimized performance for waveform rendering

Choose Waveform Renderer when you need efficient waveform visualization without the overhead of a full-featured audio library.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License

🙏 Acknowledgements

• Inspired by wavesurfer.js
• Co-created with the help of Claude