Skip to content
qrw512Public

About

Audio analysis toolkit: BPM detection, key finding, mood classification (valence/arousal), spectral features. CLI, Python API, FastAPI server, CSV/HTML export. Built on librosa.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

ย 

History

8 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐ŸŽต Sonoglyph

Extract musical features from audio โ€” tempo, key, mood, spectral data and more.

Python License: MIT Tests

English ยท ะ ัƒััะบะธะน


What is it?

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)

Features

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

Installation

Basic:

pip install sonoglyph

With 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.


Quick start

CLI โ€” analyze one file

sonoglyph analyze track.mp3

Output:

โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ 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    โ”‚      โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

CLI โ€” batch directory

sonoglyph batch ./music/ --pattern "*.mp3" --html report.html --csv library.csv

Generates: progress bar, terminal summary table, report.html (dark-theme modal report) and library.csv.

Python API

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()

REST API

sonoglyph serve --host 127.0.0.1 --port 8000

Then:

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


Real examples

Example 1 โ€” Cloud rap, melancholic

{
  "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.

Example 2 โ€” Trap, energetic

{
  "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 โœ…)

Example 3 โ€” HTML report

sonoglyph batch ./music/ --html report.html

Open 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

Configuration

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=heuristic

Project structure

sonoglyph/
โ”œโ”€โ”€ 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

License

MIT โ€” see LICENSE.


Acknowledgments

Built on: librosa ยท soundfile ยท pydantic ยท Typer ยท Rich ยท FastAPI ยท uvicorn ยท matplotlib

Krumhansl-Kessler tonal profiles from Cognitive Foundations of Musical Pitch (1990).

About

Audio analysis toolkit: BPM detection, key finding, mood classification (valence/arousal), spectral features. CLI, Python API, FastAPI server, CSV/HTML export. Built on librosa.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Contributors

Languages