music-analysis

# Music Analysis (Local, No External APIs)

Analyze audio files using signal processing. Two tools:

## 1. Quick Analysis — snapshot of the whole track

```bash
python3 skills/music-analysis/scripts/analyze_music.py /path/to/audio.mp3
python3 skills/music-analysis/scripts/analyze_music.py track.mp3 --json
```

**Reports:** duration, sample rate, tempo (BPM), key estimate, energy stats (RMS mean/std/p95), spectral summary (centroid, rolloff, contrast), coarse section boundaries.

## 2. Temporal Listen — experience the track as a journey

```bash
python3 skills/music-analysis/scripts/temporal_listen.py /path/to/audio.mp3
python3 skills/music-analysis/scripts/temporal_listen.py track.mp3 --json
```

**Reports:** sliding-window analysis (4s windows, 2s hops) producing a full timeline of:
- Energy level (relative to track average)
- Mood labels (simmering, soaring, erupting, full force, submerged, ethereal, etc.)
- Transitions (drop hits, pulls back, shifts color, evolves)
- Texture decomposition (harmonic/percussive ratio, onset density, roughness)
- Tension model (sustained intensity tracking)
- Narrative arc (mountain, ascending, descending, plateau, wave)
- Peak moment, quietest moment, mood journey summary

### How it works

No AI/ML models — pure signal processing via librosa:
- **RMS energy** per window (relative to global average)
- **Spectral centroid** (brightness), rolloff, flatness
- **Harmonic/percussive source separation** (HPSS)
- **Onset detection** (rhythmic activity density)
- **Zero-crossing rate** (texture roughness)
- Mood labels are rule-based mappings from these features

### Mood vocabulary

| Mood | Condition |
|------|-----------|
| submerged | Low energy, dark frequencies |
| ethereal | Low energy, high harmonic ratio |
| breathing | Low energy, other |
| simmering | Mid-low energy, warm |
| restless | Mid-low energy, high onset density |
| floating | Mid-low energy, bright |
| driving | Mid energy, percussive |
| soaring | Mid energy, harmonic...