| name | hear-music |
| description | Use the hear-music CLI to perceive audio files. Trigger when the user wants to analyze, transcribe, visualize, or inspect music or audio — generating spectrograms, mel/chroma/waveform images, MIDI transcription, JSON note events with onset/tempo/key estimation, ffprobe metadata, or diagnose hear-music install issues. Examples — "what's the BPM of this track", "make a spectrogram of song.mp3", "transcribe this melody to MIDI", "what key is this in", "show me the structure of this audio file". |
hear-music
Use the hear-music CLI to give Claude Code a way to hear an audio file. It produces machine-readable artifacts that can be reasoned about: spectrograms, visualizations, ffprobe metadata, onset times, tempo, key, chroma, note events, and MIDI.
When to use this skill
- The user references an audio file (
.mp3, .wav, .flac, .m4a, etc.) and wants any kind of analysis
- The user asks about tempo, key, BPM, structure, onsets, or notes in a piece of audio
- The user wants a visual representation of audio (spectrogram, waveform, mel, chromagram)
- The user wants to transcribe a melody or extract MIDI
- The user is debugging audio metadata, codec, duration, or tags
Quick start
- Run
hear-music doctor when command resolution, Python environment, or ffmpeg availability is uncertain — it returns JSON describing the install state.
- Run
hear-music info <audio> for a fast read on duration, streams, codec, and tags before heavier work.
- Pick the narrowest command that fits the task:
hear-music analyze <audio> — full pass: normalized WAV, spectrogram, MIDI, and analysis.json (tempo, key, onsets, chroma, notes)hear-music visualize <audio> — waveform + mel spectrogram + chromagram PNG (most reliable on dense audio)hear-music spectrogram <audio> — fast ffmpeg spectrogram onlyhear-music midi-json <file.mid> — turn MIDI into JSON note events
- Always pass explicit output paths or
--out-dir when the input path contains spaces or the user wants predictable artifacts.
Command patterns
Quote absolute paths on Windows when they contain spaces:
hear-music doctor
hear-music info "C:/path/to/song.mp3"
hear-music analyze "C:/path/to/song.mp3" --out-dir "C:/path/to/song_analysis"
hear-music visualize "C:/path/to/song.mp3" --out "C:/path/to/song_analysis/visualization.png"
hear-music midi-json "C:/path/to/transcription.mid"
If the launcher is unavailable but the package is installed, use the fallback:
python -m hear_music --help
Reading analysis.json
The analyze command writes a JSON document with these fields you can reason about:
tempo_bpm — estimated tempo (BPM). Reliable on most material with a clear pulse.tempo_estimated — false means the estimator couldn't decide and fell back to 120.key — {tonic, mode, confidence} from Krumhansl-Schmuckler chroma matching. Confidence above ~0.6 is solid; below that, treat as a guess.onset_count / onset_times — onset positions in seconds, after adaptive thresholding. Useful for slicing audio or counting events.chroma — 12-bin pitch class energy distribution (C, C#, D, ..., B).notes — onset-aware monophonic note events. Reliable on solo voice / whistled melodies / lightly layered material; treat as a sketch on dense produced tracks.librosa — only present when librosa is installed. Adds librosa_tempo_bpm, beat_times, spectral_centroid_mean_hz, and a refined key_librosa. Use these in preference to the lean estimates when present.
Output selection guidance
| User wants… | Command |
|---|
| Quick read on duration, streams, codec, tags | info |
| Structure of a complex track (vocals + drums + harmony) | visualize |
| Tempo, key, BPM, onsets, structured analysis | analyze |
| Just a spectrogram image, fast | spectrogram |
Convert a .mid file to JSON | midi-json |
| Diagnose install / PATH problems | doctor |
Caveats
- Treat note transcription and generated MIDI as approximate. The pitch tracker is monophonic. Best on solo voice, whistled melodies, lightly layered material. Will struggle on dense produced tracks.
tempo_bpm, key, onset_count, and chroma are reliable enough on most material to use directly in reasoning.visualize requires the [visualize] extras (librosa + matplotlib). Run doctor if it fails — the JSON output will tell you what's missing.- Run
doctor whenever the launcher behaves oddly. The most common causes are stale PATH, multiple Python installs, or missing ffmpeg.
Install
If hear-music is not installed:
pipx install "git+https://github.com/codependentai/hear-music.git"
With visualizer extras:
pipx install "hear-music[visualize] @ git+https://github.com/codependentai/hear-music.git"
Requires Python 3.11+ and ffmpeg on PATH.
