sonoscope

Interactive WebGL2 and WebAssembly audio visualization widget for JupyterLab, VS Code, Google Colab, and Marimo.

pip install sonoscope

or with uv:

uv add sonoscope

Usage

import numpy as np
from sonoscope import Sonoscope

# 1. From local file path (no HTTP server required, syncs via binary traitlets)
widget = Sonoscope.from_file("soundscape.wav")

# 2. From NumPy array and sample rate
sr = 22050
y = np.sin(2 * np.pi * 440 * np.linspace(0, 5, sr * 5, endpoint=False))
widget = Sonoscope.from_array(y, sample_rate=sr, cmap="plasma", frequency_scale="mel")

# 3. From remote URL
widget = Sonoscope.from_url("https://example.com/soundscape.mp3")

# Display in notebook
widget

Development

We recommend using uv for development. It will automatically manage virtual environments and dependencies for you.

uv run jupyter lab example.ipynb

Alternatively, create and manage your own virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
jupyter lab example.ipynb

The widget front-end code bundles its JavaScript dependencies. After setting up Python, make sure to install these dependencies locally:

npm install

While developing, you can run the following in a separate terminal to automatically rebuild JavaScript as you make changes:

npm run dev

Open example.ipynb in JupyterLab, VS Code, or your favorite editor to start developing. Changes made in js/ will be reflected in the notebook.