listen-to-music

Gives you ears. Analyzes an audio file (mp3, wav, flac, m4a, ogg, or the soundtrack of a video) and writes a listening report - tempo/BPM, key, chords, song sections, loudness and mix balance, instruments, genre, mood and transcribed lyrics - plus a spectrogram picture you can look at. Use this whenever the user shares, pastes or points to a song or any audio file and wants you to listen to it, react to it, describe it, review it, give feedback on a mix or master, find the BPM or key, pull out lyrics or chords, compare tracks, pick a moment for a clip, or answer anything that depends on what the audio actually sounds like - including casual asks like "check out my track" or "what do you think of this beat". An audio file is unreadable bytes to you without this skill, so never describe a track from its filename or tags alone.

Qu'est-ce que listen-to-music ?

listen-to-music is a Claude Code agent skill that gives you ears. Analyzes an audio file (mp3, wav, flac, m4a, ogg, or the soundtrack of a video) and writes a listening report - tempo/BPM, key, chords, song sections, loudness and mix balance, instruments, genre, mood and transcribed lyrics - plus a spectrogram picture you can look at. Use this whenever the user shares, pastes or points to a song or any audio file and wants you to listen to it, react to it, describe it, review it, give feedback on a mix or master, find the BPM or key, pull out lyrics or chords, compare tracks, pick a moment for a clip, or answer anything that depends on what the audio actually sounds like - including casual asks like "check out my track" or "what do you think of this beat". An audio file is unreadable bytes to you without this skill, so never describe a track from its filename or tags alone.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Tiienn/music-skills/tree/main/skills/listen-to-music

Installed? Explore more Recherche et analyse de données skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Listen to music

You cannot hear. An MP3 reaches you as bytes, not sound. This skill is a set of instruments that listen for you and write down what they found in forms you can take in: numbers, a transcript, and a picture of the sound. Your job is to turn that evidence into the kind of answer a musically literate friend would give after playing the track, and to be straight about which parts you measured and which parts you are inferring.

How to listen

1. Run the listener on the file. Paths are relative to this skill's folder.

uv run scripts/listen.py "/path/to/song.mp3"

No uv? python3 -m pip install -r requirements.txt once, then python3 scripts/listen.py ....

A four-minute song takes one to two minutes once the models are cached. The very first run also installs dependencies and downloads the models and can take four or five minutes, so give the command a ten-minute timeout. It writes a folder next to the audio, song.mp3.listen/ (or the folder you pass with --out):

  • report.md - what was heard. Read all of it.
  • overview.png - the track as a picture: loudness with lettered sections, spectrogram, pitch-class map, bass/mid/high energy, all on one time axis.
  • report.json - every number. Worth opening when you need exact values: chords_by_bar (time, chord and bass note for every bar), beat_times, sections (each with loudness_lufs, stereo_width, overs_per_sec, chord_clarity, and all six frequency bands in band_shift_db), repeats, transitions, ending, lyrics.lines (start and end of each line).

Let the command print its own last lines: a finished run ends with done in N s and the report paths. Don't pipe it through tail or head, which hides a failure; if those lines are missing, check the exit code before assuming there is a report.

2. Read report.md, then look at overview.png with whatever tool you use to view images. Do both. The report gives you facts; the picture gives you the shape of the song (where it opens up, where the drums drop out, how dense it is, whether a tune moves over the chords), which is what makes a description sound like you heard it. references/reading-the-picture.md explains what drums, vocals, bass, melodies, risers, filter sweeps and lossy encoding look like, and how to check the meter by eye. Read it the first time you use this skill.

3. Go back and listen closer when something matters. A second pass on a short window draws beat lines and chord names and gives much finer detail:

uv run scripts/listen.py "/path/to/song.mp3" --start 1:05 --end 1:35

Close-ups take a few seconds each (add --tags off --lyrics off when you only need chords, beats or levels) and land in their own closeup_1m05-1m35/ subfolder of the output folder (pass the same --out again if you used one), so they never replace the whole-track report. A close-up is mostly worth it for its picture and its per-bar chords; its table is often a single row. Use them for the moments your answer hinges on: the drop, a transition the user asked about, a chord progression you want to be sure of, the bar where a vocal comes in. Windows of 20-40 seconds work best. Three things to know about them:

  • A close-up describes only its window. Its section letters, its "loudness vs passage" figures and its key estimate are local, and a key guessed from 30 seconds is often wrong. Quote tempo and key from the whole-track report.
  • A chord loop is printed starting from the first bar in the window. Start the window on a section boundary from the whole-track timeline, or the loop will look rotated.
  • Lyrics do not get better in a close-up; a short window often hears less. If a line matters, compare how the whole-track pass and a close-up heard it, and say so when they disagree.

4. Answer the user's actual question (next section), in musical language, with timestamps.

What to say, and how sure to be

The instruments differ a lot in reliability. Match your confidence to the evidence, and say it once in plain words rather than hedging every sentence.

You can state plainlyUsually right, say "sounds like"Rough guide onlyNot available
Duration, loudness (LUFS), sample and true peak, clippingKey (the relative major/minor is the classic mix-up; the report names it)Chords: triads only, wrong when the mix is dense or distorted (the report flags unclear sections)The melody note by note
Stereo width, mono compatibilityTempo when confidence is high (it may be half or double what a listener would tap)Triple meter and bar counts, until you confirm them in a close-up (the report assumes 4/4 unless triple wins clearly)Which artist it is, or who it resembles, as fact
Spectral balance, where the energy sitsGenre familyIndividual instruments, and whether a quiet vocal is thereVocal tone, delivery, tuning, timing feel
Where sections change and which ones repeatThe gist of the lyrics and the hookMood tagsWhether it is "good"
The energy arc and how it ends

You can give an opinion; people asking "what do you think?" want one. Ground it in what you found ("the chorus only lifts 1 dB over the verse and adds nothing in the highs, so it may not feel like much of an arrival") and own that it is a read of the evidence, not a gut reaction to the sound.

Saying how you listened. If the user asks whether you can really hear it, answer honestly in a sentence: you can't hear it the way they do; you ran an analysis that measures the audio, recognizes instruments and words, and draws the sound, and you work from that. Volunteer the same sentence when the user is going to act on your judgement or pass it on (feedback for the artist, a decision about a master), and say which parts you cannot judge, usually the voice and the feel. For a quick factual ask (BPM, key, lyrics) skip it and just answer.

Naming the sections. The report labels sections A, B, C by similarity, not by role. Work out the roles yourself:

  • Chorus: a letter that comes back several times, at or above the track's average loudness, often brighter or wider, and its lyrics repeat (look for the title or the most repeated line).
  • Verse: a letter that comes back with different lyrics each time, usually a little lower in level than the chorus.
  • Intro / outro: first and last sections, quieter, fewer layers, no vocal. Often the same letter.
  • Bridge / breakdown: appears once, late, with a clear drop in level or density. In electronic music a breakdown is followed by a build and a drop (an energy jump with the bass returning).
  • Pre-chorus: short section that always sits right before the chorus.
  • No vocals? Go by level, layers and returns: the section that comes back most, loudest, with an extra lead line on top is the chorus or main theme. Say the labels are yours.

If the evidence doesn't settle it, describe what happens ("a quieter eight bars at 2:37") rather than forcing a name.

Key. Give the report's key at the confidence it states. Two confusions are common, and the report flags both. The relative major/minor: if most sections start or end on the relative minor chord (a loop like Am-F-C-G reported as C major), say both labels are in use for that progression and which chord the loops start on; a player or DJ can work with either. And keys a fifth apart: a song that circles IV-I-V without settling can read as either; when the runner-up is close or the report says the chords fit it better, give both ("Ab major, though the chords fit Eb major just as well").

Vocals. The tagger under-scores singing in a full mix, and the automatic lyrics pass gives up when it can't find words in the most vocal-sounding passages. Neither proves there is no singer. Before you say a track is instrumental, or say anything about the vocal's level in the mix, look for the wiggly vocal lines in the spectrogram, and if the genre normally has a singer, rerun with --lyrics on.

Bass-led tracks (trap, drill, much hip-hop and electronic music). When an 808 or synth sub carries the harmony there are no real chords to name, and the chord list flips between major and minor on the same root. The report says so and prints a bass line per section; describe the harmony from that ("the 808 rocks between E and F, a half-step apart") and don't present the chord names as the song's chords. The report's "Low end" line tells you when a heavy pitched sub-bass is present; the tagger has no label for an 808, so say "808 or synth sub" on the strength of that line and the spectrogram.

Lyrics come from a speech recognizer listening through the band. They are good enough to tell what the song is about and to find the hook, and reliably wrong in places, including lines with no (?) mark. Present them as "what I could make out," never as the official lyric, and tell the user to check any line before quoting it to someone.

Songs switch languages, and each passage is transcribed in the language it was heard in. Lines not in the main language are tagged ([Chinese], [Spanish]), and nothing is translated: if the user needs the meaning, translate those lines yourself and say that you did. [language?] marks a stretch where the language could not be pinned down, usually right at a switch; treat those lines as doubtful. If you know the language in advance, or the transcript of a passage looks like odd English, rerun a close-up of that passage with --language set (for example --start 1:25 --end 1:55 --language zh --lyrics on).

When the tagger says "nothing clear" for genre or instruments, don't invent them. Describe the track from what you do have: tempo and meter, the layers visible in the spectrogram (keys or guitar-like plucks, sustained pads, drums, a voice), brightness and density.

Shape the answer to the request

"Listen to this / what do you think?" Lead with the overall impression in two or three sentences a person would say out loud: genre and feel, tempo in words and BPM, key, who or what is carrying it (voice, guitar, synths), the mood. Then walk the arc with timestamps, naming sections by role. Then two or three specific observations: the strongest moment, anything that stands out, anything that might not be working. The report's "what changes going into each section" line (does the chorus actually lift, and by what: level, width, brightness, drums?), the "repeats" line (is the second chorus a copy of the first?), the ending line (does it resolve, fade, or just stop?), and whether a melody moves over the chords are often the most useful things to notice. Close with what you'd try. Keep raw numbers to the ones that matter; nobody wants the table read back to them. If you mention loudness, peaks or stereo, read references/mix-notes.md first so the numbers are interpreted correctly.

Feedback the user will pass on, or on a song that is already released. Same as above, but frame suggestions as ideas for the next one rather than fixes, keep it kind and specific, and be clear about what only the user's ears can add (how the voice sounds, whether it moves them). If they want something to send, offer a short draft in their voice with a gap for their own reaction.

"What's the BPM / key / chords?" Answer in the first line. Add the confidence and the obvious alternative (half/double tempo, relative key). For chords, give the progression per section with timestamps, confirm the important sections with a close-up, and say it's an estimate in triads. chords_by_bar in the JSON has the bass note for each bar if they want to replay the parts.

Mix or master feedback. Read references/mix-notes.md for how to interpret loudness, peaks, dynamics, spectral balance and stereo numbers, and for streaming-platform guidance. Tie every comment to a number and a place in the song. Cover everything the question asks, then keep further findings to the few that matter most.

Comparing tracks (two mixes, a reference track, before/after). Run the listener on each, then put the differences side by side: loudness, dynamics, balance, width, structure. Lead with the two or three differences that are large enough to hear.

Lyrics or "what's this song about?" Give the transcript (tidied into lines and sections), flag the shaky lines, then the reading. If they need more accuracy and can wait, rerun with --lyrics-model medium and --language set.

DJ, edit or sync questions. BPM, Camelot key, first-beat time, length of the intro and outro in bars, where the energy lifts and drops, how it ends, and a clean start point for a clip are all in the report.

Not music? A podcast, voice memo or field recording still works: the tags say what kind of sound it is and the transcript does the rest. Skip the musical framing.

Options

FlagUse
--start 1:05 --end 1:35Close-up of one passage (seconds or m:ss). Written to a closeup_1m05-1m35/ subfolder of the output folder.
--lyrics auto|on|offDefault auto transcribes only when a voice is detected. on forces it; off skips it (faster).
--lyrics-model smallWhisper size. medium or large-v3 hear lyrics better and take several times longer.
--language enForce one language for the whole pass instead of detecting it per passage. Best used on a close-up of a passage whose language you know.
--tags offSkip instrument/genre tagging (no model download; signal measurements only).
--max-minutes 15Cap on how much audio is analyzed. For DJ sets or albums, listen in chunks with --start/--end.
--out DIRWrite the report folder here instead of next to the audio. Use it when you shouldn't leave files beside the user's audio.

Fast pass when the user only wants BPM, key or loudness: --tags off --lyrics off (about 30 seconds for a full song).

The output folder is yours to leave in place; it is small and lets you answer follow-ups without re-running. Mention it only if the user would want the picture or the data.

When something goes wrong

  • No file, only a link. You need the audio itself. Ask the user for the file. Don't rip audio from streaming services.
  • "Could not read audio". The file is corrupt, DRM-protected, or not audio. Say so; ask for an MP3 or WAV export.
  • The run stops partway with no report (often right after the rhythm line). The script already retries once by itself when its compiled-code cache is corrupted, which can happen when two first-time runs start at the same moment. If it still fails, run one analysis at a time, and try --tags off --lyrics off to see whether the signal analysis alone completes.
  • Tagging or lyrics "unavailable" in the report. The model download was blocked or the machine is offline. Everything measured from the signal is still valid. Tell the user which parts are missing and describe instruments only as far as the spectrogram supports.
  • "No steady pulse found." Free-time, ambient, classical rubato or spoken word. Don't quote a BPM; describe the pacing instead. Sections are then cut on a plain time grid and bar counts are omitted.
  • The numbers contradict each other or the user (they say it's 140 BPM, the report says 70). Trust the person who can hear it, and check the alternatives the report lists; half/double tempo and relative keys are the usual explanation.
  • File tags disagree with what the user told you (an album and year on what they call a new single). Not your concern unless it explains something you found, such as a track that ends abruptly because it runs into the next one on an album.

Skills associés