ray
73 lines
2.8 KiB
Markdown
73 lines
2.8 KiB
Markdown
---
|
|
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
|