---
name: audio-sonic-analysis
description: Batch sonic/spectral analysis of music folders — tempo, energy, brightness, key estimation via librosa. Useful for Plex Sonic Analysis prep and music library characterization.
category: media
---

# Audio Sonic Analysis

Batch-extract sonic features from music folders for Plex Sonic Analysis or general library characterization.

## Triggers

- User wants sonic analysis, spectral analysis, or audio feature extraction of a music folder
- User mentions Plex Sonic Analysis for a music library
- User asks for tempo, energy, brightness, or key distribution of a music collection

## Prerequisites

```bash
pip install --break-system-packages librosa
```

## Workflow

### 1. Scope the folder

Count files first to gauge runtime:

```bash
find "/path/to/music/folder" -type f \( -iname "*.mp3" -o -iname "*.flac" -o -iname "*.m4a" \) | wc -l
```

### 2. Run batch analysis

Use the script at `scripts/batch_analyze.py`. It extracts per-track:

- **Tempo** (BPM) — beat tracking
- **RMS energy** — perceived loudness
- **Spectral centroid** (Hz) — brightness/darkness
- **Zero-crossing rate** — noisiness
- **Estimated key** — chroma CQT → pitch class
- **Duration** (seconds)

```bash
python3 scripts/batch_analyze.py "/path/to/music/folder"
```

The script samples the first 45 seconds of each track at 22,050 Hz for speed. Output goes to stdout (summary) and `/tmp/<folder_name>_sonic_results.json` (per-track detail).

### 3. Interpret results for Plex

Key features Plex Sonic Analysis cares about:

| Feature | What it means for Plex |
|---|---|
| Tempo | Fast/slow radio seeding, BPM-based playlists |
| Spectral centroid | "Bright" vs "dark" — acoustic vs electronic, vocal-forward vs bass-heavy |
| RMS energy | Loudness/dynamics — quiet vs intense mood grouping |
| Key | Harmonic mixing compatibility |

Plex computes these server-side via its own analysis pipeline. Running this script is useful for **previewing** what Plex will see before committing to a full library scan, or for libraries Plex can't access directly.

## Pitfalls

- **Go/songsee not available**: The `songsee` skill requires Go (rarely installed). Fall back to librosa — it's Python-only and covers 90% of the same features.
- **Large folders**: 169 tracks took ~10 minutes. For 1000+ tracks, consider sampling (e.g., first 100 tracks) or running in the background with `notify_on_complete=true`.
- **librosa warnings**: `librosa.beat.tempo` moved to `librosa.feature.rhythm.tempo` in 0.10+. The script uses the current path; warnings are cosmetic.
- **Key estimation is approximate**: Chroma CQT works best on tonal music with clear pitch. Electronic/bass-heavy tracks may produce noisy estimates.

## Linked files

- `scripts/batch_analyze.py` — Reusable batch sonic analysis script