Extract musical features from audio โ tempo, key, mood, spectral data and more.
Sonoglyph is a Python library and CLI tool that analyzes audio files and extracts musical features: tempo, key, mood, spectral characteristics, energy, and more. Works out of the box with no ML dependencies, optionally plugs in neural network backends for higher accuracy.
Use cases:
- ๐ง Build smart playlists by tempo, key or mood
- ๐ Analyze your music library in batch (CSV/HTML reports)
- ๐ค Add music understanding to your app via REST API
- ๐ฌ Research Music Information Retrieval (MIR)
| Feature | Description |
|---|---|
| ๐ฅ Tempo / BPM | Beat tracking with confidence estimation |
| ๐ผ Key detection | Krumhansl-Kessler profiles, tonic + mode |
| ๐จ Spectral features | Centroid, rolloff, ZCR, 13 MFCC coefficients |
| โก Energy | RMS mean/std, dynamic range in dB |
| ๐ Mood | Valence/Arousal + labels + tags |
| ๐ญ Extended mood map | Distinguishes melancholic from angry via spectral flatness |
| ๐พ Disk cache | SHA-256 keyed, avoids recomputation |
| โก Parallel batch | ProcessPoolExecutor, uses all CPU cores |
| ๐ค CSV export | Flat table, Excel-friendly (utf-8-sig) |
| ๐ HTML report | Dark theme, sortable, filterable, modal with spectrogram |
| ๐ REST API | FastAPI server for language-agnostic integration |
Basic:
pip install sonoglyphWith HTML reports:
pip install "sonoglyph[html]"With REST API server:
pip install "sonoglyph[server]"Everything:
pip install "sonoglyph[html,server,ml]"From source:
git clone https://github.com/sonoglyph/sonoglyph.git
cd sonoglyph
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,html,server]"On Windows, activate the venv with .venv\Scripts\activate instead.
sonoglyph analyze track.mp3Output:
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ Sonoglyph โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ track.mp3 โ
โ 2:34 ยท 22050 Hz ยท 1ch ยท MP3 โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โญโโโโโโโ ๐ฅ Tempo โโโโโโโโโฎ โญโโโโโโโโ ๐ผ Key โโโโโโโโโโฎ
โ 117.5 BPM โ โ D# minor โ
โ 292 beats ยท conf 0.97 โ โ โญ minor ยท conf 0.55 โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โญโโโโโโโโโโโโโโโโโโโโโโโโโโ ๐ Mood โโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ MELANCHOLIC (backend: heuristic) โ
โ #atmospheric #dark โ
โ โ
โ Valence โโโโโโโโโโโโโโโโโโโโโโโโ 0.40 โ
โ Arousal โโโโโโโโโโโโโโโโโโโโโโโโ 0.63 โ
โ โ
โ Flatness โโโโโโโโโโโโโโโโ 0.0425 โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โญโโโโโโ ๐จ Spectral โโโโโโโฎ โญโโโโโโโโโ โก Energy โโโโโโโโโโโฎ
โ Centroid 2260 Hz โ โ RMS 0.1900 ยฑ 0.1015 โ
โ Rolloff 4650 Hz โ โ Dynamic 69.6 dB โ
โ ZCR 0.0963 โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
sonoglyph batch ./music/ --pattern "*.mp3" --html report.html --csv library.csvGenerates: progress bar, terminal summary table, report.html (dark-theme modal report) and library.csv.
from sonoglyph import analyze, analyze_batch
from sonoglyph.exporters import to_csv, to_html
def main() -> None:
# Single track
result = analyze("1.mp3")
print(f"BPM: {result.tempo.bpm:.1f}")
print(f"Key: {result.key.name}")
print(f"Mood: {result.mood.label}")
print(f"Tags: {result.mood.tags}")
print(f"Valence: {result.mood.valence:.2f}")
print()
# Batch โ must be inside main() on Windows
results = analyze_batch(
["1.mp3", "2.mp3", "3.mp3"],
features=["tempo", "mood"],
)
to_csv(results, "library.csv")
to_html(results, "report.html", include_spectrograms=True)
print(f"Done: {len(results)} tracks analyzed.")
if __name__ == "__main__":
main()sonoglyph serve --host 127.0.0.1 --port 8000Then:
curl http://127.0.0.1:8000/api/health
curl -X POST http://127.0.0.1:8000/api/analyze-by-path -H "Content-Type: application/json" -d '{"path": "track.mp3", "features": ["tempo", "mood"]}'
curl -X POST http://127.0.0.1:8000/api/analyze -F "file=@track.mp3" -F "features=tempo,mood"Interactive docs: http://127.0.0.1:8000/docs
{
"tempo": { "bpm": 117.45, "confidence": 0.97, "beat_count": 292 },
"key": { "name": "D# minor", "confidence": 0.55 },
"mood": {
"label": "melancholic",
"valence": 0.40,
"arousal": 0.63,
"tags": ["atmospheric", "dark"],
"spectral_flatness": 0.0425
}
}Why "melancholic" and not "angry": the track has energetic 808 bass and sharp hi-hats, but also a diffuse, reverberant atmosphere. Sonoglyph uses spectral flatness (p90 percentile) to distinguish the "atmospheric + energetic" quadrant from "aggressive" โ a classic mistake for naive valence/arousal classifiers.
{
"tempo": { "bpm": 143.55, "confidence": 0.96, "beat_count": 501 },
"key": { "name": "E minor", "confidence": 0.59 },
"mood": {
"label": "happy",
"valence": 0.57,
"arousal": 0.82,
"arousal_rhythmic": 0.66,
"arousal_harmonic": 0.71,
"tags": ["upbeat"],
"spectral_flatness": 0.0204
}
}Beat stability analysis (from HTML modal):
| Metric | Value |
|---|---|
| Mean interval | 418.0 ms |
| Median interval | 417.9 ms |
| Std deviation | 33.2 ms |
| CV (stability) | 0.0793 |
| BPM from intervals | 143.52 (matches bpm 143.55 โ
) |
sonoglyph batch ./music/ --html report.htmlOpen report.html in a browser. Features:
- Filter by track name, key, tag
- Sort by BPM, mood, valence, arousal
- Click a track โ modal with waveform + beat markers, mel spectrogram, beat interval histogram, beat positions timeline, and all stats
| Variable | Default | Description |
|---|---|---|
SONOGLYPH_CACHE_DIR |
~/.cache/sonoglyph |
Cache directory |
SONOGLYPH_MOOD_BACKEND |
auto |
auto / heuristic / vibenet |
export SONOGLYPH_CACHE_DIR=/tmp/sonoglyph-cache
export SONOGLYPH_MOOD_BACKEND=heuristicsonoglyph/
โโโ src/sonoglyph/
โ โโโ analyzers/ # Tempo, key, spectral, energy, mood
โ โโโ exporters/ # CSV, HTML
โ โโโ server/ # FastAPI app
โ โโโ api.py # Public API
โ โโโ cache.py # Disk cache
โ โโโ cli.py # Typer CLI
โ โโโ io.py # Audio loading
โ โโโ schemas.py # Pydantic models
โโโ tests/ # 18 tests
โโโ examples/
โโโ benchmarks/
โโโ pyproject.toml
MIT โ see LICENSE.
Built on: librosa ยท soundfile ยท pydantic ยท Typer ยท Rich ยท FastAPI ยท uvicorn ยท matplotlib
Krumhansl-Kessler tonal profiles from Cognitive Foundations of Musical Pitch (1990).