hermes-config/skills/media/audio-sonic-analysis/SKILL.md

name, description, category

name	description	category
audio-sonic-analysis	Batch sonic/spectral analysis of music folders — tempo, energy, brightness, key estimation via librosa. Useful for Plex Sonic Analysis prep and music library characterization.	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

pip install --break-system-packages librosa

Workflow

1. Scope the folder

Count files first to gauge runtime:

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)

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