Getting Started

Name: libsonare
Author: libraz

libsonare is a dependency-free C++17 audio engine for music information retrieval (MIR), mastering, mixing, editing, creative FX, and browser-native music tools. This page takes you from nothing installed to a printed BPM, key, and chord list in the runtime you already use.

You do not need to choose a feature first: this page works from a blank slate. Once you have a result on screen, the Learning Path picks the area guide for your project.

What You Will Learn

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

explain the sample/sample-rate/mono/stereo vocabulary every API uses;
pick the runtime that matches your project;
install libsonare and print a first analysis result in the browser, Node.js, Python, or a terminal;
know which reference to open next.

Before You Choose A Runtime

Most examples follow the same pattern: load or decode audio, pass Float32Array samples plus a sample rate, then read the result.

Term	Plain meaning
Sample	One amplitude value in the audio waveform
Sample rate	How many samples exist per second, such as 44,100 or 48,000
Mono	One channel of audio
Stereo	Two channels, left and right
WASM	WebAssembly, the runtime the npm package compiles to; it runs in browsers and in Node.js

Audio Basics explains these terms at more length.

Separate the file from the samples

MP3 and WAV are file formats. Most libsonare APIs receive decoded PCM samples (the plain, uncompressed sample values), such as a Float32Array in JavaScript or a sample array in Python. Every runtime below can decode WAV and MP3 for you; for other formats, the browser decodes the file first, and Python needs an FFmpeg-enabled build.

Where Does It Run?

Runtime	Install	Reads files directly?	Reference
Browser	`npm install @libraz/libsonare`, or the CDN build	Decodes WAV/MP3 bytes; other formats go through the browser's decoder	WebAssembly Guide
Node.js (WASM)	`npm install @libraz/libsonare` (Node.js 22.12 or later)	Decodes WAV/MP3 bytes you read with `node:fs`	JavaScript API
Python	`pip install libsonare` (Python 3.11 or later)	Yes, WAV and MP3; more formats with FFmpeg	Python API
CLI	`pip install libsonare`, which installs the `sonare` command	Yes, the same formats as the Python package	CLI Reference

The npm package does not install the sonare command. The Node.js native addon and the C++ library are built from source; see Native Bindings and C++ API.

First Result

Each tab is complete: an install line, the program, and the output it prints. The examples analyze demo.mp3, the track the Music Analysis Studio loads, so you can compare your output with the demo.

BrowserNode.js (WASM)PythonCLI

html

<!-- first.html — serve the folder with any static server (for example `npx serve`)
     and pick demo.mp3 from https://libsonare.libraz.net/demo.mp3 -->
<input type="file" id="file" accept=".mp3,.wav" />
<pre id="out"></pre>
<script type="module">
  import { init, Audio } from 'https://unpkg.com/@libraz/libsonare';

  await init();
  document.getElementById('file').addEventListener('change', async (event) => {
    const bytes = new Uint8Array(await event.target.files[0].arrayBuffer());
    const result = Audio.fromMemory(bytes).analyze();
    document.getElementById('out').textContent = [
      `BPM: ${result.bpm.toFixed(1)}`,
      `Key: ${result.key.name}`,
      `First chords: ${result.chords.slice(0, 8).map((c) => c.name).join(' ')}`,
    ].join('\n');
  });
</script>

<!-- Shows:
BPM: 160.4
Key: C major
First chords: C Am C Bm G G#m Em C
-->

// npm install @libraz/libsonare
// curl -O https://libsonare.libraz.net/demo.mp3
// node first.mjs
import { readFileSync } from 'node:fs';
import { init, Audio } from '@libraz/libsonare';

await init();
const audio = Audio.fromMemory(new Uint8Array(readFileSync('demo.mp3')));
const result = audio.analyze();

console.log('BPM:', result.bpm.toFixed(1));
console.log('Key:', result.key.name);
console.log('First chords:', result.chords.slice(0, 8).map((c) => c.name).join(' '));

// BPM: 160.4
// Key: C major
// First chords: C Am C Bm G G#m Em C

python

# pip install libsonare
# curl -O https://libsonare.libraz.net/demo.mp3
# python first.py
from libsonare import Audio

audio = Audio.from_file("demo.mp3")
result = audio.analyze()

print(f"BPM: {result.bpm:.1f}")
print(f"Key: {result.key.name}")
print("First chords:", " ".join(c.name for c in result.chords[:8]))

# BPM: 160.4
# Key: C major
# First chords: C Am C Bm G G#m Em C

bash

pip install libsonare
curl -O https://libsonare.libraz.net/demo.mp3
sonare analyze demo.mp3

# warning: 2-channel input is downmixed to mono by this CLI command; use the stereo library API for channel-preserving processing
#
#   > Estimated BPM : 160.42 BPM  (conf 80.7%)
#   > Estimated Key : C major  (conf 98.3%)
#   > Time Signature: 4/4
#   > Beats: 192

analyze() returns the whole result in one call: beats, chords, sections and form alongside BPM and key, plus timbre, dynamics, rhythm, and melody. Music Analysis explains each field and when to call a single estimator instead.

The chord list above includes a Bm and a G#m in a song in C major. That is normal: analyze() reports triads only by default (major, minor, diminished, augmented), and a borrowed or misread chord is part of what a chord estimator does. The FAQ explains how to widen or tighten the vocabulary.

Audio.fromMemory and Audio.from_file fold a stereo file to mono, which is what the analysis expects. To decode AAC, OGG, or FLAC in the browser, use Audio.fromMemoryWithBrowserFallback (File Input). A bundled app imports from '@libraz/libsonare' instead of the CDN URL.

Node.js native addon

The N-API addon @libraz/libsonare-native runs libsonare as compiled machine code instead of WebAssembly and loads files from a path. It is not published to npm, so build it from a checkout:

bash

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

typescript

import { Audio } from '@libraz/libsonare-native';

const result = Audio.fromFile('demo.mp3').analyze();
console.log('BPM:', result.bpm, 'Key:', result.key.name);

See Node.js / Native Bindings.

What libsonare Can Do

Area	Example	Start page
Analysis	BPM, key, chords, beats and downbeats, sections, melody	Music Analysis
Editing and repair	Pitch correction, time stretch, note edits, noise and hum reduction	Editing DSP, Audio Repair Workflow
Mixing and mastering	Channel strips, sends and buses; mastering chains with LUFS targets and true-peak limiting	Mixing Engine, Mastering Assistant
Instruments and MIDI	A seventeen-engine synthesizer, a GM/GS fallback bank, a SoundFont 2 player	Sound Sources, Built-in Synthesizer
Projects and realtime	Headless-DAW projects with offline bounce, streaming analysis, a realtime engine	Project Editing, Realtime and Streaming
Room acoustics	RT60 and clarity, room estimates from audio, impulse-response synthesis	Room Acoustics

The Learning Path lists every area with the page written for each goal.

Acronyms in this table

BPM: beats per minute, the tempo of the song.
LUFS / true peak: mastering metrics. LUFS (Loudness Units relative to Full Scale) measures perceived loudness; true peak measures peak safety, including peaks between samples.
RT60: the time a room's reverberation takes to fall by 60 dB.

Try It Now

The chords you just printed come from chroma (how much of each of the 12 notes is sounding) frames matched against chord templates. This demo runs the same chord recognition on a short C–Am–F–G clip, computed by the WASM build you just installed:

CHORD TRACK · DETECT CHORDSIDLE

Chord track — the segments recognition returns

The Demos page has the full browser tools; drop an audio file onto any of them, and nothing is uploaded.

Next Steps

You have one example running. What comes next depends on which of two readers you are.

If you want to build something

Examples — the working pattern closest to your task, in each runtime
Learning Path — a route by goal through the ten subject areas, from analysis to playback
Use Cases — a whole job carried from raw files to a deliverable, as a script you can run
Installation — FFmpeg decoding, source builds, and the Node native addon, once the defaults are not enough

If you want to understand the engine

Introduction — the analysis pipeline from waveform to chords, and the vocabulary every other page assumes
Music Analysis — what each result you just printed means, and which call to reach for when analyze() is too coarse
Sound Sources — why the engine ships no samples, and where its instruments' sound comes from instead
DSP Implementation Notes — how the processors are structured, for when you need to expose their controls or explain a render

Examples

Browser / WASM

JavaScript API

Python API

CLI Reference

Node.js Native API

C++ API

Glossary

Foundations

Analysis Guides

Mixing Guides

Editing Guides

Instruments and MIDI

Arrangement and Projects

Realtime Guides

Room Acoustics

Mastering Concepts

Mastering Guides

Getting Started

What You Will Learn

Before You Choose A Runtime

Where Does It Run?

First Result

What libsonare Can Do

Try It Now

Next Steps

If you want to build something

If you want to understand the engine

Getting Started ​

What You Will Learn ​

Before You Choose A Runtime ​

Where Does It Run? ​

First Result ​

What libsonare Can Do ​

Try It Now ​

Next Steps ​

If you want to build something ​

If you want to understand the engine ​

Getting Started

What You Will Learn

Before You Choose A Runtime

Where Does It Run?

First Result

What libsonare Can Do

Try It Now

Next Steps

If you want to build something

If you want to understand the engine