analyze-music

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

1. Parse the score.
2. Extract global metadata: tempo, meter, key, measure count.
3. Extract part-level metadata: instrument names, ranges, density, likely role.
4. Identify melody candidates.
5. Estimate phrase boundaries.
6. Infer harmonic context, preferably as chord symbols or roman numerals.
7. 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.