Sonome

Read a song's acoustic DNA and build the lineup — honest MIR on top of librosa.

Sonome extracts music-information-retrieval (MIR) features from an audio file and translates them into human-readable, Pandora-flavored descriptors — tempo feel, key/mode, brightness, energy, acousticness, mood quadrant — then scores tracks by sonic similarity so you can seed a lineup of songs that share a seed's character.

It is a small, dependency-light Python library + CLI. Audio in → a structured, versioned fingerprint (raw numbers + interpreted genome) out. No API keys, no 403s, no black boxes — local-first and hackable.

• Open source, Apache-2.0, under the Kovir Labs umbrella.
• Built for people who want an honest, local music-DNA tool on top of librosa.

Status: pre-alpha. All logic currently lives in the single-file seed songgenome.py. The layered sonome/ package and the sonome CLI described below under Roadmap do not exist yet. Use python songgenome.py for now.

---

Scientific honesty

The subjective attributes DSP cannot measure — genre, mood label, danceability, instrumentalness/vocalness — are not faked in the core. They need trained models, and live behind an optional Essentia plugin point (highlevel_essentia), unimplemented by default so the base tool has zero heavy dependencies.

Hard rule: if a value is an estimate rather than a measurement, its key ends in _est and it is documented as heuristic (e.g. acousticness_est, valence_est, arousal_est). We do not launder guesses as facts.

---

Install

Requires Python ≥ 3.10. The core depends only on librosa, numpy, and soundfile.

uv sync                              # or: uv pip install librosa numpy soundfile

Usage (today)

Phase 0 has shipped: the sonome CLI takes positional audio files plus flags (no analyze/lineup subcommands yet — those are on the roadmap).

uv run sonome track.wav                     # analyze, print the genome report
uv run sonome track.wav --json out.json     # also write the fingerprint JSON
uv run sonome track.wav --db genome.sqlite  # append to a SQLite catalog
uv run sonome --batch ./music --db genome.sqlite   # analyze a whole directory
uv run sonome --similar a.json b.json       # pairwise similarity, 0..1
uv run sonome track.wav --quiet             # suppress the readable report

--similar and --help stay import-light (numpy only); librosa is imported lazily, so you only need it installed to actually analyze audio.

What you get

Each analyzed track produces a fingerprint with two parts:

• features — raw MIR numbers: BPM, onset rate, RMS, dynamic range, spectral centroid/rolloff/bandwidth/flatness/contrast, zero-crossing rate, percussive ratio, tonal clarity, key strength, 13 MFCC means, and the _est heuristics. This is the similarity vector.
• genome — human-readable descriptors bucketed from those numbers: tempo feel, key & mode, rhythmic feel/density, energy, dynamics, brightness, texture, tonality, acousticness, roughness, and a coarse mood quadrant.

Similarity blends a Euclidean feature distance (75%) with mean-centered MFCC cosine for timbre (25%), yielding a 0..1 score where higher is closer.

---

Roadmap

The single-file seed is being split into a layered package where extraction, interpretation, similarity, storage, and presentation are orthogonal:

sonome/
  features.py    # audio ➜ raw MIR numbers        (pure, deterministic)
  genome.py      # raw numbers ➜ human descriptors (pure, bucketing)
  similarity.py  # fingerprint ➜ distance + lineup ranking
  catalog.py     # fingerprint ⇄ SQLite (the only place with side effects)
  report.py      # fingerprint ➜ formatted string
  highlevel.py   # optional Essentia plugin (ML attributes) behind a Protocol
  cli.py         # thin argparse orchestration

Once the package lands, the installed sonome command becomes the entry point:

uv run sonome analyze track.mp3
uv run sonome lineup seed.mp3 --n 25

See CLAUDE.md for the architecture, coding principles, and the current-vs-target state in detail.

---

Optional: high-level ML attributes

The subjective attributes (genre, mood tags, danceability, instrumentalness) come from Essentia — which is AGPL-3.0. To keep Sonome's Apache-2.0 grant clean, Essentia is not an extra of this package; it ships as a separate, out-of-tree plugin you install deliberately:

pip install sonome-essentia   # separate AGPL-3.0 package, planned; not yet released

Licensing note: Essentia's code is AGPL-3.0 and several of its pretrained models are research / non-commercial only. Keeping it out-of-tree means installing it is your explicit choice and never taints Sonome's Apache-2.0 distributable. See brainstorm.md for the full license audit.

---

Contributing

Tooling is uv + ruff + mypy + pytest. Definition of done for any change: ruff check clean, mypy clean, tests green, and a test added or updated that would fail without your change. Test fixtures are synthesized or CC0 — never commit copyrighted audio.

License

Apache License 2.0. Copyright © Kovir Labs.