Installation

Use this page after Getting Started, when you already know which runtime you want.

What You Will Learn

By the end of this page you should be able to:

• install the browser/WASM npm package, Python package, or source build for the right use case;
• understand why the npm package does not install the sonare CLI;
• decide when you need FFmpeg-enabled decoding instead of the default WAV/MP3 support;
• build from source only when wheels or prebuilt packages do not cover your target.

Which Install Do You Need?

You are building...	Install
Browser app	npm install @libraz/libsonare
Python script or notebook	pip install libsonare
Terminal batch workflow	pip install libsonare and use sonare
Node native service or desktop tool	Build bindings/node as @libraz/libsonare-native
C++ integration or custom WASM build	Build from source

Choose by where the app runs

For a browser UI, start with npm / WASM. For notebooks or local scripts, start with PyPI. For terminal checks, use the sonare CLI installed by the PyPI package. Reach for Node native or a C++ build when WASM or Python is not enough for performance, distribution, or existing-code integration.

If you are unsure, pick the path that lets you run one command today:

• Website or Vite/Vue/React app — install the npm package and call await init() before analysis.
• Local data work — install the Python package and start with Audio.from_file(...).
• No code yet — install the Python package and run sonare bpm audio.mp3 or sonare analyze audio.mp3 --json.

You can switch runtimes later. The core analysis and DSP behavior is shared; the install choice mostly decides how you feed audio in and where the results are consumed.

npm (Browser / WASM)

Requires Node.js 18.0.0 or later.

@libraz/libsonare is the WebAssembly package. Most APIs are sample-based: pass decoded mono Float32Array samples. For loading convenience, Audio.fromMemory(...) can decode WAV/MP3 bytes in memory, and Audio.fromMemoryWithBrowserFallback(...) can fall back to the browser codec stack for formats such as AAC, OGG, and FLAC.

This npm package is for browser/WebAssembly use. It does not install the sonare CLI. For the command-line tool, install the Python package from PyPI with pip install libsonare.

npm

npm install @libraz/libsonare

yarn

yarn add @libraz/libsonare

pnpm

pnpm add @libraz/libsonare

WASM package subpaths

The package also publishes subpath exports for worklet and asset-loading use cases. Most app code should import from the main @libraz/libsonare entry.

Import	Use
@libraz/libsonare	Main TypeScript API: initialization, analysis, features, mastering, mixing, and realtime classes
@libraz/libsonare/analysis	Analysis-only module, built without mastering, mixing, realtime, or project bindings — a much smaller download when all you need is MIR (Music Information Retrieval)
@libraz/libsonare/worklet	AudioWorklet bridge helpers, including SonareRealtimeEngineNode, SonareEngine, and worklet-side lifecycle exports
@libraz/libsonare/worker	OfflineWorkerClient, which runs one-shot analysis and mastering calls in a dedicated Worker
@libraz/libsonare/wasm	Raw main WASM asset for bundlers or custom loaders
@libraz/libsonare/schemas/realtime-voice-changer-preset.schema.json	JSON Schema for a voice-changer preset document
@libraz/libsonare/schemas/realtime-voice-changer-preset-pack.schema.json	JSON Schema for a preset pack

Pick the analysis bundle when you only analyze

@libraz/libsonare/analysis compiles the same DSP with the mastering, mixing, realtime, and project surfaces left out. CI records its size in a report, but size growth alone does not fail the build. If your page detects BPM, key, chords, or draws a spectrogram and never masters or mixes, importing it instead of the main entry cuts the WASM download substantially.

Python (pip)

Requires Python 3.11 or later (3.11, 3.12, 3.13).

pip install libsonare

This installs the Python library and the sonare CLI command. See CLI Reference for command-line usage.

The PyPI wheels are built for deterministic installation and decode WAV and MP3 by default. To load M4A, AAC, FLAC, OGG, Opus, or other FFmpeg-supported formats directly, build a wheel from source with FFmpeg enabled. The SONARE_FFMPEG flag is consumed by the wheel-builder script, not by pip, so clone the repository and run the build script:

git clone https://github.com/libraz/libsonare.git
cd libsonare
SONARE_FFMPEG=1 bash bindings/python/build_wheel.sh
pip install bindings/python/dist/*.whl

FFmpeg-enabled builds require FFmpeg development libraries. On macOS, install them with brew install ffmpeg. On Debian/Ubuntu, install libavformat-dev libavcodec-dev libavutil-dev libswresample-dev.

Supported Platforms

The declared supported platforms are Linux, macOS, WebAssembly, and WSL2.

Platform	Notes
Linux	Wheels are built inside matching manylinux 2.28 images, repaired with auditwheel, and checked against glibc 2.31
macOS	Targets macOS 11.0 and later
WebAssembly	Any browser with WebAssembly; no SharedArrayBuffer required for the default path
WSL2	The supported way to build and run on a Windows machine

Native Windows builds are rejected

A Windows CMake configuration fails with a pointer to WSL2 rather than half-configuring. Use WSL2 for native builds on Windows. The npm WebAssembly package works in any browser on Windows — this limit is about compiling the native library, not about running the browser build.

The published artifacts are the WebAssembly npm package, the Python wheel, and the native CLI release archives. Native CLI archives are published for Linux x86_64 and aarch64, and macOS arm64. The Node native binding is marked private and is installed as a local dependency only — see Native Bindings.

Building from Source

What does source build mean?

Instead of using a published npm or PyPI package, you compile the C++ core and bindings on your machine. This is useful for custom FFmpeg support, unsupported platforms, or development changes, but normal package installation is the simpler starting point.

Prerequisites

• CMake 3.16+
• C++17 compatible compiler (GCC or Clang on the supported Linux/macOS targets)
• Optional FFmpeg development libraries for M4A/AAC/FLAC/OGG/Opus decoding
• Emscripten (for WebAssembly build)

Build Steps

# Clone the repository
git clone https://github.com/libraz/libsonare.git
cd libsonare

# Build native library
mkdir build && cd build
cmake ..                         # auto-detect FFmpeg
# cmake .. -DSONARE_WITH_FFMPEG=ON  # require FFmpeg-backed decoding
# cmake .. -DBUILD_ACOUSTIC_SIM=ON  # enable geometric room acoustics (default ON)

cmake --build . --parallel

# Build WebAssembly (run from the repository root, not from build/)
cd .. && make wasm

Rebuild the shared library and the binding together

The Python binding refuses a shared library built from a different tree, so a locally built .so / .dylib and the binding that loads it have to come from the same checkout. After pulling a version that changes a C struct layout, rebuild the library rather than pointing the new binding at the old artifact. Installing the published wheel instead avoids the problem entirely, since it ships a matched pair.

Native Bindings (Python / Node.js)

For desktop use, native bindings provide direct C++ performance. Python is available from PyPI. The Node.js N-API binding is not published to npm — it is marked private and is consumed as a local dependency, so it is always built from source. See the Native Bindings page for details.

The Node.js native binding uses Yarn 4 and requires Node.js 22 or later:

git clone https://github.com/libraz/libsonare.git
cd libsonare/bindings/node
yarn install
yarn build

Usage

Browser

import { init, detectBpm, detectKey, analyze } from '@libraz/libsonare';

// Initialize WASM module
await init();

// Get audio samples from AudioContext
const audioContext = new AudioContext();
const response = await fetch('audio.mp3');
const arrayBuffer = await response.arrayBuffer();
const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
const samples = audioBuffer.getChannelData(0);

// Detect BPM
const bpm = detectBpm(samples, audioBuffer.sampleRate);

// Detect key
const key = detectKey(samples, audioBuffer.sampleRate);

// All-in-one analysis
const result = analyze(samples, audioBuffer.sampleRate);

For stereo files, downmix to mono first instead of passing only one channel if you need both channels represented.

The demo below is the same browser/WASM path in visual form: decoded samples go in, an STFT-style time/frequency view comes out. If this renders in your app, the WASM package, initialization, and sample-rate plumbing are all working.

STFT · SPECTRALIDLE

STFT — seeing time and frequency at once

FREQTIME →

Scroll to load

A tone sweeping from 220 Hz to 4 kHz. Each column is one short-time spectrum; brighter means more energy at that frequency.

Python

from libsonare import Audio

# Reads WAV/MP3 (rebuild with FFmpeg for M4A/FLAC/OGG/Opus)
audio = Audio.from_file("audio.mp3")

# Detect BPM
bpm = audio.detect_bpm()

# Detect key
key = audio.detect_key()

# All-in-one analysis
result = audio.analyze()

The same sonare CLI ships with the package — see the CLI Reference for terminal usage and JSON output.

CLI

pip install libsonare

# Quick terminal checks
sonare bpm audio.mp3
sonare key audio.mp3

# Machine-readable all-in-one analysis
sonare analyze audio.mp3 --json > analysis.json

C++

#include <quick.h>

// Detect BPM
float bpm = sonare::quick::detect_bpm(samples, size, sample_rate);

// Detect key
sonare::Key key = sonare::quick::detect_key(samples, size, sample_rate);

// All-in-one analysis
sonare::AnalysisResult result = sonare::quick::analyze(samples, size, sample_rate);

For acoustic metrics, use sonare::quick::analyze_impulse_response() for measured impulse responses and sonare::quick::detect_acoustic() for blind estimates. For geometric room acoustics:

• include the header for the feature you use: acoustic/rir_synthesizer.h, analysis/room_estimator.h, or effects/acoustic/room_morph.h;
• build with BUILD_ACOUSTIC_SIM=ON.