Learning Path

This page is the beginner-friendly route through the libsonare docs. You do not need to understand DSP, MIR, WebAssembly, or mastering terminology before starting.

Acronyms you will see early

DSP (digital signal processing) means measuring or changing audio as numbers. MIR (Music Information Retrieval) means reading musical information such as BPM, key, and chords from audio. WASM / WebAssembly is the browser runtime format. API means the functions and classes your app calls. CLI means a terminal command. At this stage, you only need enough vocabulary to choose the next page.

If you want to read the docs linearly, use this order:

1. Introduction for vocabulary and the overall audio-analysis pipeline.
2. Learning Path to choose whether you are building analysis, streaming, editing, mixing, mastering, or research tooling.
3. Getting Started, Installation, and Examples to run one small program.
4. Feature Map to find the right API family.
5. One task guide from Build By Task.
6. One runtime reference from API By Runtime.
7. The evidence pages only when you need implementation details, algorithm references, validation scope, or performance context.

Start With Your Goal

I want to build...	Read first	Then read
A browser app that shows BPM, key, chords, or sections	Getting Started	WebAssembly Guide, JavaScript API
Song-structure, self-similarity, or note-segmentation analysis	Feature Map	JavaScript API, Python API
A Python script or notebook for audio analysis	Getting Started	Python API
A terminal workflow for quick checks or batch analysis	Getting Started	CLI Reference
Pitch, time, voice, or source-separation editing	Editing DSP	JavaScript API
Region-based spectral edits (attenuate, mute, gain, or heal a time-frequency rectangle)	Spectral Editing	Editing DSP
A browser or native mixer	Mixing Engine	Mixing Scene JSON
A mastering UI or automatic mastering workflow	Mastering Assistant	Mastering Processors
A synth or instrument app that renders MIDI to audio	Built-in Instruments	MIDI Input, Realtime and Streaming
A DAW, arrangement, or MIDI-sequencing tool	Project Editing	MIDI Input, Project Bounce
SoundFont (SF2) playback through a built-in player	SoundFont 2 Player	Built-in Instruments, MIDI Input
A live visualizer, rhythm game helper, or AudioWorklet tool	Realtime and Streaming	WebAssembly Guide
A realtime microphone voice changer	Realtime Voice Changer	WebAssembly Guide
Room sound, estimates, or generated room character	Room Acoustics	JavaScript API, Python API
Inverting mel/MFCC features for previews or debugging	Inverse Features	librosa Compatibility
A migration from librosa	librosa Compatibility	Feature Map

How to read the task guides

Each Build By Task page follows the same order:

1. start with the decision criteria;
2. show the smallest useful code path;
3. call out practical caveats and related pages.

When the same workflow can be shown safely in Browser / WASM, Python, and CLI, the page uses a ::: code-group to show all three.

For APIs that are inherently WASM / C++ oriented, such as the realtime engine or AudioWorklet bridge, the docs point to the batch alternative or runtime reference instead of implying that Python / CLI have the same live callback API.

Room acoustics includes room decay, clarity, blind estimates, equivalent-room estimates, RIR (room impulse response) synthesis, and room morphing.

Implementation Checklist

Before implementing from a task page, check these points.

Check	Where to look	How to decide
Whether your input is a file, encoded bytes, decoded samples, or live blocks	The page's "when to use" / "which API" section	Browser / WASM usually takes Float32Array plus sampleRate; use Audio.fromMemory* or browser codecs for encoded bytes. Python / CLI often read files directly.
Which runtime calls the workflow	The Browser / Python / CLI examples in ::: code-group blocks	When all three are shown, compare API names, argument names, and result shapes before porting code.
Whether the terminology is clear enough for UI copy or implementation comments	Inline ::: tip / ::: info / ::: warning / ::: details blocks and the Glossary	Terms that affect implementation decisions stay close to the code; longer background belongs in callouts or glossary pages.
Whether a runtime gap exists	Binding Parity and the runtime references	If a task page does not show an example for a runtime, the API may be unavailable there or the runtime may be the wrong fit.

The Four Layers

libsonare is easier to understand if you separate it into four layers.

Layer	What it means	Pages
Concepts	What BPM, key, STFT, chroma, LUFS, true peak, and related terms mean	Introduction, Glossary
Tasks	What you want to build: analysis, streaming, editing, mixing, mastering	Feature Map, feature guides
Runtime	Where the code runs: browser, Python, Node, CLI, C++	Getting Started, runtime references
Evidence	How the implementation is structured and validated	DSP Implementation Notes, Algorithm References, Implementation Validation

Most users should read the first three layers before opening the evidence pages.

Minimum Path For A First Project

1. Read Introduction for the basic vocabulary.
2. Open Getting Started and choose your runtime.
3. Build one small example from Examples.
4. Use Feature Map when you need to find the right API family.
5. Use Binding Parity only when moving code between runtimes.

When To Read The Deep Dives

Open the implementation pages when you need to expose DSP controls in a UI, explain a render report, check whether a processor is appropriate for realtime use, or cite the basis for an algorithm. They are not required for a first integration.