Quick Start

Sonoscope is available as three specialized packages across JavaScript, React, and Python environments.

Installation

TypeScript / Vanilla JS

npm install @sonoscope/core

React

npm install @sonoscope/react @sonoscope/core

Python (Jupyter / Marimo)

pip install sonoscope
# or with uv
uv add sonoscope

Basic Usage

1. Vanilla TypeScript / JavaScript

Use Sonoscope to manage audio loading and attach visualization viewers.

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

// Initialize Sonoscope from an HTML <audio> element
const audioElement = document.querySelector('audio');
const scope = await Sonoscope.fromAudio(audioElement);

// Render Spectrogram on a canvas
const canvas = document.querySelector('canvas#spectrogram');
const spec = scope.createSpectrogram(canvas, {
  colorMap: 'viridis',
  frequencyScale: 'mel',
  minDb: -80,
  maxDb: 0,
});

// Enable interactive zoom and pan (defaults to both time and frequency axes)
scope.attachNavigation(canvas);

// Or customize navigation axes, modifiers, and sensitivities:
// scope.attachNavigation(canvas, {
//   axis: 'both',
//   wheel: { zoomModifier: 'alt' },
//   drag: { modifier: 'none' },
// });

2. React

Wrap viewers with SonoscopeProvider and compose TimeRuler, Spectrogram, and Waveform.

import { SonoscopeProvider, Spectrogram, Waveform, TimeRuler } from '@sonoscope/react';

export function AudioViewer() {
  return (
    <SonoscopeProvider url="/audio/sample.wav">
      <TimeRuler height={24} />
      <Spectrogram height={300} colorMap="inferno" frequencyScale="mel" showAudioControls />
      <Waveform height={80} />
    </SonoscopeProvider>
  );
}

3. Python (Jupyter / Marimo)

from sonoscope import Sonoscope
import numpy as np

# Create widget from local file
widget = Sonoscope.from_file("recording.wav", cmap="viridis")
display(widget)

# Or create directly from NumPy arrays
sr = 44100
t = np.linspace(0, 3.0, sr * 3, endpoint=False)
signal = np.sin(2 * np.pi * 440 * t)

Sonoscope.from_array(signal, sample_rate=sr, frequency_scale="log")