or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

audio-processing.mdaudio-recording.mdcore-waveform-control.mdevent-system.mdindex.mdplugin-system.mdregions-plugin.mdtimeline-navigation.mdvisual-customization.md
tile.json

tessl/npm-wavesurfer-js

Interactive audio waveform rendering and playback library for web applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/wavesurfer.js@7.10.x

To install, run

npx @tessl/cli install tessl/npm-wavesurfer-js@7.10.0

index.mddocs/

WaveSurfer.js

WaveSurfer.js is an interactive audio waveform rendering and playback library for web applications. It leverages modern web technologies including HTML5 Audio and Web Audio APIs to create responsive, customizable waveform visualizations with extensive plugin architecture supporting regions, timeline, minimap, and advanced audio analysis features.

Package Information

  • Package Name: wavesurfer.js
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install wavesurfer.js

Core Imports

import WaveSurfer from "wavesurfer.js";

For CommonJS:

const WaveSurfer = require("wavesurfer.js");

Plugin imports:

import Regions from "wavesurfer.js/dist/plugins/regions.esm.js";
import Timeline from "wavesurfer.js/dist/plugins/timeline.esm.js";

Basic Usage

import WaveSurfer from "wavesurfer.js";

// Create waveform instance
const wavesurfer = WaveSurfer.create({
  container: "#waveform", // Required: target element
  waveColor: "#4F4A85",
  progressColor: "#383351",
  url: "/audio.mp3", // Audio file to load
});

// Control playback
await wavesurfer.play();
wavesurfer.pause();
wavesurfer.stop();

// Listen to events
wavesurfer.on("ready", (duration) => {
  console.log("Audio loaded, duration:", duration);
});

wavesurfer.on("play", () => {
  console.log("Playback started");
});

wavesurfer.on("pause", () => {
  console.log("Playback paused");
});

Architecture

WaveSurfer.js is built around several key components:

  • Core WaveSurfer Class: Main API providing waveform rendering, audio playback, and event management
  • Player System: Audio playback abstraction supporting both MediaElement and WebAudio backends
  • Renderer: Canvas-based waveform visualization with customizable styling and interaction
  • Plugin Architecture: Extensible system with official plugins for regions, timeline, recording, and more
  • Event System: Comprehensive event emitter for lifecycle, playback, and interaction events
  • Audio Processing: Built-in audio decoding, peaks generation, and Web Audio integration

Capabilities

Core Waveform Control

Primary waveform creation, audio loading, and playback control functionality.

class WaveSurfer {
  static create(options: WaveSurferOptions): WaveSurfer;
  
  // Audio loading
  load(url: string, peaks?: Array<Float32Array | number[]>, duration?: number): Promise<void>;
  loadBlob(blob: Blob, peaks?: Array<Float32Array | number[]>, duration?: number): Promise<void>;
  
  // Playback control
  play(start?: number, end?: number): Promise<void>;
  pause(): void;
  playPause(): Promise<void>;
  stop(): void;
  
  // Navigation
  setTime(time: number): void;
  seekTo(progress: number): void;
  getCurrentTime(): number;
  getDuration(): number;
}

Core Waveform Control

Visual Customization

Waveform appearance configuration including colors, styling, zoom, and display options.

interface WaveSurferOptions {
  // Required
  container: HTMLElement | string;
  
  // Visual appearance
  height?: number | 'auto';
  width?: number | string;
  waveColor?: string | string[] | CanvasGradient;
  progressColor?: string | string[] | CanvasGradient;
  cursorColor?: string;
  cursorWidth?: number;
  
  // Bar visualization
  barWidth?: number;
  barGap?: number;
  barRadius?: number;
  barHeight?: number;
  barAlign?: 'top' | 'bottom';
}

Visual Customization

Audio Processing

Audio decoding, peaks generation, and Web Audio integration for advanced audio manipulation.

interface WaveSurfer {
  // Audio data
  getDecodedData(): AudioBuffer | null;
  exportPeaks(options?: ExportPeaksOptions): Array<number[]>;
  
  // Zoom and navigation
  zoom(minPxPerSec: number): void;
  getScroll(): number;
  setScroll(pixels: number): void;
  setScrollTime(time: number): void;
}

interface ExportPeaksOptions {
  channels?: number;
  maxLength?: number;
  precision?: number;
}

Audio Processing

Event System

Comprehensive event handling for lifecycle, playback, and user interaction events.

interface WaveSurferEvents {
  // Lifecycle
  init: [];
  ready: [duration: number];
  destroy: [];
  
  // Loading
  load: [url: string];
  loading: [percent: number];
  decode: [duration: number];
  
  // Playback
  play: [];
  pause: [];
  finish: [];
  timeupdate: [currentTime: number];
  seeking: [currentTime: number];
  
  // Interaction
  click: [relativeX: number, relativeY: number];
  drag: [relativeX: number];
  scroll: [visibleStartTime: number, visibleEndTime: number, scrollLeft: number, scrollRight: number];
  zoom: [minPxPerSec: number];
}

Event System

Plugin System

Extensible plugin architecture with official plugins for regions, timeline, recording, and visualization.

interface WaveSurfer {
  registerPlugin<T extends GenericPlugin>(plugin: T): T;
  unregisterPlugin(plugin: GenericPlugin): void;
  getActivePlugins(): GenericPlugin[];
}

class BasePlugin<EventTypes, Options> {
  constructor(options: Options);
  destroy(): void;
}

Plugin System

Regions Plugin

Visual overlays and markers for audio segments with interactive drag, resize, and content support.

class RegionsPlugin extends BasePlugin<RegionsPluginEvents, RegionsPluginOptions> {
  addRegion(params: RegionParams): Region;
  clearRegions(): void;
  getRegions(): Region[];
  enableDragSelection(options?: DragSelectionOptions): () => void;
}

interface Region {
  id: string;
  start: number;
  end: number;
  play(end?: number): Promise<void>;
  setOptions(params: Partial<RegionParams>): void;
  remove(): void;
}

Regions Plugin

Audio Recording

Real-time audio recording with waveform visualization and MediaRecorder integration.

class RecordPlugin extends BasePlugin<RecordPluginEvents, RecordPluginOptions> {
  startRecording(options?: StartRecordingOptions): Promise<void>;
  stopRecording(): Blob;
  pauseRecording(): void;
  resumeRecording(): void;
  getRecordedData(): Blob | null;
}

Audio Recording

Timeline and Navigation

Timeline display, minimap navigation, and zoom controls for enhanced waveform interaction.

class TimelinePlugin extends BasePlugin<TimelinePluginEvents, TimelinePluginOptions> {
  // Automatically renders time labels and notches
}

class MinimapPlugin extends BasePlugin<MinimapPluginEvents, MinimapPluginOptions> {
  // Provides overview waveform for navigation
}

class ZoomPlugin extends BasePlugin<ZoomPluginEvents, ZoomPluginOptions> {
  zoomIn(): void;
  zoomOut(): void;
}

Timeline and Navigation

Types

interface WaveSurferOptions {
  // Required
  container: HTMLElement | string;
  
  // Visual options
  height?: number | 'auto';
  width?: number | string;
  waveColor?: string | string[] | CanvasGradient;
  progressColor?: string | string[] | CanvasGradient;
  cursorColor?: string;
  cursorWidth?: number;
  barWidth?: number;
  barGap?: number;
  barRadius?: number;
  barHeight?: number;
  barAlign?: 'top' | 'bottom';
  
  // Audio options
  url?: string;
  peaks?: Array<Float32Array | number[]>;
  duration?: number;
  media?: HTMLMediaElement;
  mediaControls?: boolean;
  autoplay?: boolean;
  audioRate?: number;
  backend?: 'WebAudio' | 'MediaElement';
  
  // Interaction options
  interact?: boolean;
  dragToSeek?: boolean | { debounceTime: number };
  hideScrollbar?: boolean;
  autoScroll?: boolean;
  autoCenter?: boolean;
  
  // Rendering options
  fillParent?: boolean;
  minPxPerSec?: number;
  sampleRate?: number;
  normalize?: boolean;
  splitChannels?: Array<Partial<WaveSurferOptions> & { overlay?: boolean }>;
  renderFunction?: (peaks: Array<Float32Array | number[]>, ctx: CanvasRenderingContext2D) => void;
  
  // Advanced options
  plugins?: GenericPlugin[];
  fetchParams?: RequestInit;
  cspNonce?: string;
  blobMimeType?: string;
}

type GenericPlugin = BasePlugin<BasePluginEvents, unknown>;

interface BasePluginEvents {
  destroy: [];
}