Metadata-Version: 2.4
Name: libretta
Version: 0.1.2
Summary: Audio analysis pipeline: stem separation, MIDI transcription, spectral analysis, chord detection, ghost frequency diagnostics, and spectrogram visualization.
Author: lie
License-Expression: MIT
Project-URL: Homepage, https://aevrasounds.com
Keywords: audio,music,analysis,midi,transcription,spectrogram,stems
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: librosa>=0.10
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: soundfile
Requires-Dist: matplotlib
Requires-Dist: torch
Requires-Dist: torchaudio
Provides-Extra: stems
Requires-Dist: demucs; extra == "stems"
Provides-Extra: transcribe
Requires-Dist: basic-pitch==0.3.3; extra == "transcribe"
Requires-Dist: onnxruntime; extra == "transcribe"
Provides-Extra: all
Requires-Dist: demucs; extra == "all"
Requires-Dist: basic-pitch==0.3.3; extra == "all"
Requires-Dist: onnxruntime; extra == "all"
Dynamic: license-file

# libretta

An AI-oriented music analysis pipeline built on librosa, Demucs, and Basic Pitch.

Stem separation, MIDI transcription, spectral analysis, chord detection, ghost frequency diagnostics, and spectrogram visualization, all from one command. Outputs structured JSON that language models can reason over.

## What it does

1. **Stem separation** (Demucs) splits a mix into vocals, drums, bass, and other
2. **MIDI transcription** (Basic Pitch) detects notes and exports MIDI files with pitch bends
3. **Feature extraction** (librosa) pulls tempo, key, chroma, spectral features, dynamics, MFCCs, beat timing, harmonic/percussive ratio
4. **Chord detection** estimates chords at each beat using chroma template matching
5. **Ghost frequency detection** finds inaudible subsonic/ultrasonic energy eating your headroom
6. **Spectrogram rendering** generates mel spectrograms, chromagrams, piano rolls, waveforms, and frequency spectrum plots

Each step runs on both the full mix and each individual stem for maximum accuracy.

> **Note:** Demucs and Basic Pitch download model weights on first run. Demucs pulls ~80MB from Meta's CDN, Basic Pitch pulls its ONNX model automatically. After that, they're cached locally.

## Install

```bash
pip install libretta
```

For full features (stem separation + better MIDI transcription):

```bash
pip install libretta[all]
```

On Windows, if basic-pitch gives you trouble:

```bash
pip install onnxruntime
pip install "basic-pitch==0.3.3" --no-build-isolation
```

For GPU acceleration (recommended), install PyTorch with CUDA:

```bash
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121
```

## Quick test

```bash
# verify the install works
python -m libretta.cli --help
```

## Usage

### Command line

```bash
# full analysis
libretta song.mp3

# skip stem separation (faster, just analyze the mix)
libretta song.wav --no-stems

# skip spectrogram images
libretta song.flac --no-images

# use the fine-tuned demucs model (better quality, slower)
libretta song.mp3 --model htdemucs_ft

# force CPU
libretta song.mp3 --cpu

# custom output directory
libretta song.mp3 -o ./my_analysis
```

### Python API

```python
from libretta import analyze, separate_stems, render_spectrograms

# analyze a single file
result = analyze("song.mp3", tag="mix")
print(result["key"])       # "F major"
print(result["bpm"])       # 120.5
print(result["chords"])    # [{"time": 0.0, "chord": "Fmaj", "conf": 0.89}, ...]
print(result["notes"])     # [{"start": 0.5, "end": 1.2, "pitch": 69, "name": "A4", "vel": 0.7}, ...]

# separate stems
stems = separate_stems("song.mp3", "./stems")
# returns {"drums": "./stems/drums.wav", "bass": "./stems/bass.wav", ...}

# render spectrograms
render_spectrograms("song.mp3", "mix", "./images", notes=result["notes"])
```

## Output

Running `libretta song.mp3` creates:

```
analysis_song/
  analysis.json          # all data, structured, feedable to an LLM
  report.txt             # human readable summary
  stems/
    drums.wav
    bass.wav
    other.wav
    vocals.wav
    other.mid            # MIDI transcription per stem
    bass.mid
    vocals.mid
  images/
    mix_overview.png     # mel spectrogram + chromagram + piano roll + waveform
    mix_spectrum.png     # frequency spectrum with ghost frequency zones
    drums_overview.png
    drums_spectrum.png
    ...
```

## Ghost frequencies

libretta detects inaudible subsonic (below 20Hz) and ultrasonic (above 18kHz) energy that eats headroom and confuses limiters. It filters these out before analysis so the readings are accurate, but flags them in the report so you know your mix has a problem to fix.

Silent stems (like when Demucs splits a solo piano into "drums" and gets basically nothing) are automatically detected via RMS threshold and marked as unreliable.

## Requirements

- Python 3.10+
- librosa, numpy, scipy, soundfile, matplotlib, torch, torchaudio (core)
- demucs (optional, for stem separation)
- basic-pitch + onnxruntime (optional, for MIDI transcription, falls back to pyin)
- CUDA GPU recommended but not required

## License

MIT
