@sonoscope/core

WebGL2 and WebAssembly audio visualization engine for the web.

Installation

npm install @sonoscope/core

Quick start

Unified coordinator pattern

import { Sonoscope } from "@sonoscope/core";

const audio = document.querySelector("audio")!;
const waveCanvas = document.querySelector<HTMLCanvasElement>("#wave-canvas")!;
const specCanvas = document.querySelector<HTMLCanvasElement>("#spec-canvas")!;

// 1. Initialize coordinator from audio element
const scope = await Sonoscope.fromAudio(audio, {
  followPlayback: "page",
});

// 2. Attach viewers (automatically render on creation)
const waveform = scope.createWaveform(waveCanvas, {
  colorMap: "magma",
  amplitudeScale: 1.0,
});

const spectrogram = scope.createSpectrogram(specCanvas, {
  colorMap: "magma",
  frequencyScale: "mel",
  valueMode: "db",
});

Standalone visualizer (from URL)

import { Sonoscope } from "@sonoscope/core";

// Initialize purely from URL without an <audio> element
const scope = await Sonoscope.fromUrl("https://example.com/audio.wav");

const viewer = scope.createSpectrogram(document.querySelector<HTMLCanvasElement>("canvas")!, {
  colorMap: "magma",
  frequencyScale: "mel",
  valueMode: "db",
});

Features

• Unified viewport coordinator (Sonoscope). Single source of truth for time bounds, playback position, follow modes (page, smooth, off), and multi-canvas synchronization.
• WASM STFT acceleration. Rust WebAssembly STFT compute backend with multi-worker pool and pure TypeScript fallback.
• WebGL2 shaders, plugins, and 35+ colormaps. Lean, hardware-accelerated tile rasterization, extensible shader plugin architecture (with @sonoscope/halftone-spectrogram, @sonoscope/terrain-spectrogram, @sonoscope/topographic-spectrogram), and 35+ Matplotlib colormaps (Viridis, Magma, Inferno, Turbo, Cividis, and more).
• Multi-scale waveform peak decimation. Multi-resolution pyramid peak decimation for instant waveform envelope rendering.
• Adaptive streaming decoders. On-demand HTTP range-request WAV decoders and WebCodecs streaming MP3 pipelines.
• Canvas navigation. Built-in cursor-centered wheel zoom and drag panning utilities.