libsonare

Turn audio into data and back, from Python. Analyze songs (BPM, key, chords, loudness), master and mix to broadcast loudness, and render MIDI through built-in instruments — a fast C++ core whose only Python dependency is NumPy 2.4.6 or later. Mastering ships 95 named DSP processors implemented against published references; analysis defaults match librosa where the two overlap. Apache-2.0, no model weights.

Guides, API reference and CLI docs: libsonare.libraz.net

Installation

pip install libsonare

Supported platforms: Linux (x86_64, aarch64), macOS (Apple Silicon).

Quick Start

import libsonare

audio = libsonare.Audio.from_file("song.mp3")  # or "song.wav"
result = audio.analyze()  # BPM + key + time signature + beats
print(f"BPM: {result.bpm:.1f}  Key: {result.key.root.name} {result.key.mode.name}")

# Master toward a target loudness with a named preset
mastered = libsonare.master_audio(
    audio.data, sample_rate=audio.sample_rate, preset_name="streaming",
)
print(mastered.output_lufs, mastered.applied_gain_db)

Render a MIDI arrangement through a built-in instrument with the headless Project (a context manager):

with libsonare.Project() as project:
    project.set_sample_rate(48000)
    _, clip_id = project.add_midi_clip(0.0, 4.0)
    project.set_midi_events(clip_id, [
        libsonare.Project.midi_note_on(0.0, 0, 0, 60, 100),  # ppq, group, channel, note, velocity
        libsonare.Project.midi_note_off(2.0, 0, 0, 60),
    ])
    audio = project.bounce_with_synth_instrument("saw-lead", num_channels=2)

Samples passed directly must be mono float32 (downmix stereo first); the defaults follow librosa (22050 Hz, n_fft 2048, hop_length 512). See librosa compatibility.

Capabilities

• Analysis — BPM, key, chords, downbeats, sections, melody, tuning, pitch, timbre, spectral features and metering. → Analysis
• Stem decomposition and transcription — decompose_stems splits a mix into stems, and transcribe turns audio into MIDI events. → Analysis, CLI examples
• Mastering — 95 named DSP processors, the configurable mastering_chain, 30 named presets via master_audio, and reference-matching. → Mastering processors
• Restoration — five repair-only presets, vinyl, tapeHiss, fieldRecording, voiceMemo and shellac78, plus repair of any channel count in one call (mastering_repair_analyze / mastering_repair_apply). → Mastering processors
• Mixing — offline mix_stereo, the block-based Mixer with scene presets, and suggest_mix_scene, which suggests a mixer scene with a written explanation without applying it. → Mixing, Mixing assistant
• Editing DSP — time-stretch, pitch-shift, auto_tune, HPSS, phase vocoder, normalize, trim, remix. → Editing DSP
• Note editing and takes — edit the notes of monophonic takes (extract_notes) and polyphonic material (PolyphonicAnalysis), align a take to a reference with align_take_to_reference, and build tuning targets from a MIDI melody with note_targets_from_smf, and edit vocal takes offline with undo/redo through create_vocal_edit_session. → Project editing, Recording and takes
• Room acoustics — blind RT60, impulse-response metrics, estimate_room, synthesize_rir, room_morph, room_morph_stereo. → Room acoustics
• Realtime and streaming — RealtimeEngine with MIDI 1.0 / 2.0 input, bus-to-bus routing with sends, sidechain keys (set_bus_sidechain), StreamAnalyzer, StreamingMasteringChain and RealtimeVoiceChanger (also an insert, voice.changer). → Realtime engine
• Instruments and synthesis — built-in synth, the patch-driven NativeSynth, and a GS-compatible SoundFont (SF2) player that receives GS SysEx and offers two GS insertion-effect realisations (gs_efx_realization), with a selectable rig per part (set_part_rig). The acoustic piano is calibrated; the other physical-model voices are still being tuned and will change in 1.9.x patch releases. → GM and GS, Native synth
• Headless DAW — Project with audio and MIDI tracks, undo/redo, SMF and MIDI 2.0 Clip File I/O, and offline bounce; transcribe_to_clip writes a transcription into a clip, and compile_timeline turns a project into a timeline a stopped RealtimeEngine plays. → Project editing
• Playback — PlaybackRenderer renders PCM up to 7.1 to speakers or HRTF binaural headphones. → Playback
• Parameter descriptors — capability_catalog, mastering_insert_param_info, synth_engine_param_info and synth_patch_param_info describe every parameter's range, default, unit, display scale and the other parameters that bound or switch it, so a host builds its controls without a hand-written table. → Build controls from descriptors

The whole surface is listed in the Python API reference.

CLI

The sonare command exposes the analysis, mastering, mixing, effects and project surfaces.

sonare analyze song.mp3                              # BPM + key summary
sonare master song.wav -o mastered.wav --preset pop  # preset mastering
sonare project bounce --in project.json -o out.wav --synth saw-lead

Run sonare --help, or see the CLI reference.

Supported audio formats

WAV and MP3 decode out of the box. M4A / AAC / FLAC / OGG / Opus need FFmpeg, which the PyPI wheels are built without; build from source with SONARE_FFMPEG=1 to enable it (see the installation guide).

Documentation

Getting started · Python API · CLI · Examples · Binding parity. The wheel bundles the JSON Schemas for realtime voice changer presets; see Realtime voice changer.

Also available

npm install @libraz/libsonare  # JavaScript / TypeScript (WASM)

License

Apache-2.0