| name | analyze-music |
| description | Use when an arranged MusicXML score needs to be parsed into music_analysis.json — extracting tempo, meter, key, parts, phrases, melody candidates, and harmony — for downstream vocal planning. Does not read lyrics or alter the score. |
| allowed-tools | Read Bash Grep Glob Write |
| argument-hint | ["musicxml-file"] |
| effort | medium |
Skill 1: analyze_music
Purpose
Turn arranged_music.xml into a compact musical representation that an LLM can reason over without reading raw MusicXML.
This skill is music-analysis-only. It should not read lyrics and should not alter the score.
Inputs
arranged_music.xml
Optional config:
{
"preferred_vocal_range": ["C4", "A5"],
"target_style": "gentle children's song",
"language_hint": "English"
}
Tools
music21
Use music21 to:
- parse MusicXML
- list parts and instruments
- extract measures, notes, rests, voices, and durations
- infer key and meter
- read tempo markings
- chordify the arrangement to infer harmonic context
- find candidate melody lines
- compute ranges and singability features
Core responsibilities
- Parse the score.
- Extract global metadata: tempo, meter, key, measure count.
- Extract part-level metadata: instrument names, ranges, density, likely role.
- Identify melody candidates.
- Estimate phrase boundaries.
- Infer harmonic context, preferably as chord symbols or roman numerals.
- Emit
music_analysis.json.
Output
Write music_analysis.json matching schemas/music_analysis.schema.json.
Example:
{
"score": {
"tempo_bpm": 96,
"meter": "4/4",
"key": "C major",
"measure_count": 16,
"parts": [
{
"id": "P1",
"name": "piano",
"range": ["C3", "G5"],
"role_guess": "accompaniment",
"density_score": 0.72
},
{
"id": "P2",
"name": "flute",
Why this output is useful
The next skill needs to decide where and how to sing. It needs compact facts:
- which part probably carries the tune
- where phrases start and end
- whether the melody fits a singable range
- how many melody notes are available
- whether accompaniment conflicts with the vocal register
Suggested CLI
./bin/analyze_music arranged_music.xml --out music_analysis.json
Failure modes
Return a nonzero exit code and diagnostic JSON if:
- MusicXML cannot be parsed
- no usable note material is found
- lyrics are empty
- tempo cannot be determined and no default is supplied
If key, chords, or phrases are uncertain, emit warnings instead of failing.
