librosa

librosa is a Python package for analyzing audio and music. It provides the foundational algorithms — spectral transforms, feature extraction, beat and onset detection, harmonic-percussive separation — that music information retrieval (MIR) systems are built on, exposed as a consistent set of functions that take and return numpy arrays.

Under the hood it wraps numba-accelerated DSP primitives, scipy/scikit-learn for signal processing and clustering, soundfile and soxr for audio I/O and resampling, and matplotlib (optional) for spectrogram and waveform visualization. It has been the de facto reference implementation for Python audio analysis since 2012, cited in hundreds of MIR papers and installable from both PyPI and conda-forge.

What You Get

• Audio I/O with resampling — load() reads most common audio formats via soundfile and resamples through soxr or the lazily-loaded resampy/samplerate backends
• Spectral representations — STFT, constant-Q/variable-Q transforms, mel spectrograms, and chromagrams in core.spectrum and core.constantq
• Feature extraction — MFCCs, spectral contrast, tonnetz, and rhythm features under librosa.feature, ready to feed into ML models
• Beat and onset detection — tempo estimation and onset/beat tracking algorithms in beat.py and onset.py
• Effects and source separation — time stretching, pitch shifting, and harmonic-percussive separation in effects.py and decompose.py
• Built-in visualization — display.py integrates directly with matplotlib for spectrogram and waveform plots
• Fast imports via lazy loading — lazy_loader defers submodule imports until first use, keeping import time low despite heavy dependencies like numba and scipy
• Joblib-backed caching — expensive computations are memoized through a configurable cache layer in _cache.py

Common Use Cases

• Music information retrieval research — building and benchmarking MIR systems for genre classification, tempo estimation, and structure analysis
• Audio feature extraction for ML pipelines — generating MFCCs or mel-spectrograms as input features for downstream deep learning models
• Beat tracking and music production tooling — detecting tempo and beat positions to drive automatic mixing or DJ software
• General bioacoustics and signal analysis — reusing librosa’s core DSP primitives (STFT, CQT, resampling) outside the music domain

Under The Hood

Architecture librosa’s __init__.py uses lazy_loader.attach_stub so submodules aren’t imported until an attribute is first accessed, keeping startup fast despite depending on numba, scipy, and scikit-learn. The package is layered: core/ (audio.py, spectrum.py, constantq.py, convert.py, pitch.py, harmonic.py, intervals.py, notation.py) holds low-level DSP primitives operating directly on numpy arrays, with numba (@jit, @guvectorize, @stencil) accelerating hot loops in core/audio.py; feature/ (spectral.py, rhythm.py, inverse.py) builds higher-level feature extractors on top of core; and top-level modules (beat.py, onset.py, decompose.py, effects.py, segment.py, sequence.py, filters.py, display.py) compose core and feature into task-specific algorithms. There’s no dependency injection or class hierarchy — the design is purely functional, with util/_cache.py’s joblib-based @cache decorator applied throughout core and feature for memoization. core.convert (unit conversion between frames, samples, and time) is imported nearly everywhere and functions as the shared coordinate system — changes there would ripple through the entire package.

Tech Stack Requires Python >=3.12 with a tightly version-pinned dependency set: numba >=0.61 for JIT compilation, numpy >=2.1 and scipy >=1.15 for array math and signal processing, scikit-learn >=1.6 for clustering/decomposition, joblib >=1.2 for caching, soundfile >=0.12.1 (libsndfile binding) for audio I/O, pooch >=1.7 for fetching bundled example data, soxr >=1.0 for high-quality resampling, lazy_loader >=0.3 for deferred imports, and msgpack >=1.0.5 to serialize precomputed lookup tables such as core/intervals.msgpack. Optional extras add matplotlib for display, and lazily-loaded resampy/samplerate as alternate resamplers. The build uses setuptools, ruff for linting with an extensive rule set (including numpy-specific NPY checks and numpydoc-convention docstring validation), and GitHub Actions for CI, docs builds, and PyPI/conda-forge publishing.

Code Quality The tests/ directory has 19 test modules covering core DSP, beat tracking, decomposition, display, dynamic time warping, effects, filters, and feature extraction, run with pytest plus pytest-mpl for image-comparison baseline tests (tests/baseline_images/) and pytest-cov for coverage reporting to Codecov; xfail_strict = true is set in setup.cfg. mypy is configured with strict = True and check_untyped_defs = True, though disallow_untyped_defs = False allows gradual typing. Ruff enforces a broad rule set spanning security (S), docstrings (D, numpydoc convention), import sorting (I), and bug patterns (B, SIM). CI runs linting and the full test suite on every push via GitHub Actions.

API Design The library’s central design choice is exposing decades of academic MIR algorithms — constant-Q/variable-Q transforms, harmonic-percussive separation, chroma and tonnetz features, beat/onset detection — through one uniform, numpy-array-in/numpy-array-out function API, validated against reference outputs (e.g. mir_eval comparisons in the test suite, precomputed pitch/interval tables bundled as msgpack fixtures). Combined with numba JIT acceleration for the DSP-heavy inner loops and lazy imports to keep startup cheap, this makes librosa function less as a novel-algorithms library and more as the standard interoperability layer for audio DSP in Python — the reference most MIR papers and tooling build on top of.