How to use
Give it a score, say which bars you want, and ask your question. In ChatGPT you attach the score file; in Claude you choose it in a small card. The rest happens in the chat.
Add it in ChatGPT
Open ChatGPT's plugin directory, search for Sheet Music Analysis and add it. Then attach your score in a chat and ask your question.
Install in Claude
You can add Sheet Music Analysis straight from our GitHub page, which always has the newest version. You need a paid Claude plan (Pro, Max, Team or Enterprise).
On the web or in the Claude desktop app:
- Go to Customize → Plugins, select Add, then Add marketplace, then Add from a repository.
- Enter
Vedat-Ozkan/sheet-music-analysisand add it. - Find Sheet Music Analysis in the list of plugins and select Add.
- Open the plugin, go to its Connectors tab and add the connector it lists. The plugin needs it to make the analysis and to play the music.
- In a chat, ask for an analysis and choose your score file in the card that appears, then press Enter to send the message the card puts in your reply box.
To get new versions, open the marketplace under Customize → Plugins and turn on Sync automatically, or select Check for updates now and then.
If you already added it from Claude's directory, remove that copy first, so you have only one.
On a phone: add the plugin on the web or in the desktop app first. It then works in the Claude app on your phone with the same account.
On a Team or Enterprise plan: your organisation's owner may need to let members add their own plugins.
In Claude Code: plugins you add on the web appear in Claude Code when you sign in with the same account. To add it in Claude Code alone, run /plugin marketplace add Vedat-Ozkan/sheet-music-analysis, then /plugin install sheet-music-analysis@sheetmusicanalysis. If adding it fails because your computer has no GitHub SSH key, set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 and try again.
1. Get a score file
The tool reads MusicXML, a file format that stores the notes and other details of a score: .mxl (compressed) or .musicxml / .xml, up to 10 MB.
- From notation software: MuseScore, Sibelius, Finale and Dorico all export MusicXML (usually under File → Export).
- From online libraries: MuseScore.com and OpenScore offer MusicXML downloads for many public-domain works.
You can also use a PDF of printed sheet music. PDFs saved directly from music-writing software work best. Scanned printed pages can be read too, but tend to have more reading mistakes. Handwritten music, photos and audio are not supported.
- Give the PDF the same way as any score (attach it in ChatGPT; in Claude choose it in the card, see 2. Ask in the chat) and say which bars you want analysed.
- The tool shows you a copy of the music it read from the PDF, before adding any analysis. The card shows the first 2 pages, and Download PDF has them all.
- Bars that may be misread are shaded. The analysis follows straight away, and those bars stay shaded on the analysed page.
- Compare every bar with your original, checking the notes, rests and rhythm. The shading catches some mistakes, not all. If something is wrong, say which bar and what differs, and it will correct the bar and analyse again.
Slurs—the curved lines that group notes into a smooth phrase—are not read, because they are often misread.
A PDF can have any number of pages, but only the first 8 are read. A PDF usually takes a minute or two to read; a long one can take several minutes. For a longer score, use a PDF of just the pages you need. If the chat seems to stop while the PDF is being read, send the same message again and it will pick up the finished reading.
2. Ask in the chat
In Claude, don't attach the file: ask for an analysis, and Claude shows a small card where you choose your score file. The card then puts a short message in your reply box: press Enter to send it, and the analysis starts. If the reply box stays empty, type "I've chosen it" and send that. Claude can't pass a file attached to the chat to the tool, so if you attached one, choose the same file again in the card. (You can also paste a link to your score instead: a link to a MusicXML file or PDF, or a Google Drive or Dropbox link shared so anyone with the link can view it.)
In ChatGPT, attach the file to your message.
Either way, ask the way you would ask a teacher. Some examples:
Analyse the harmony of bars 1–16 of this score. Where are the cadences in this movement, and how do the phrases group? I'm a composition student. What makes the harmony in bars 9–12 surprising, and how could I use the idea? Show only the voice leading in bars 5–8. Is the passage at bar 40 a modulation or just an applied chord? Show bars 1–8 of this symphony as a piano version.You can ask for a whole piece; it comes back as one PDF. The card shows the first two pages; open the PDF for the rest. Long pieces and scores for many instruments take longer to draw.
By default the commentary is written for a student: each label is explained the first time it appears, with the reasoning behind it. Say that you write music, or ask how or why something works, and it skips the definitions and focuses on what is unusual and how the technique could be reused.
3. Read the page
A guide to the marks sits at the foot of the page: at the bottom of the first page in the chat, and at the end of the last page in the PDF. It names each kind of mark and code drawn around the chord symbols, with a small sample of each, but does not explain the chord symbols themselves. The table below is the fuller reference.
| Mark | Meaning |
|---|---|
E♭: at the start of a row | The key. A new key label marks a modulation. |
| Roman numerals under the staves | The chord on each scale degree: upper case major, lower case minor, ° diminished, ø half-diminished. Figures give the inversion (6, 6/4, 6/5…); V7/ii is an applied (secondary) chord. |
| Bracket under the numerals | Harmonic function: tonic, pre-dom. (predominant) or dominant. Where the brackets are too short for words, they are labelled T, PD and D. |
Boxed PAC, IAC, HC, DC | Cadences: perfect authentic, imperfect authentic, half, deceptive. |
| Solid bracket above the system | A phrase, with its label (a, a′, b…). |
| Dashed bracket above the system | A passage named by what it is built on, such as a pedal point, a whole-tone stretch or a mode. |
| Dotted bracket under the numerals, with chords printed below it | A second possible reading of the same bars, one a teacher would also accept. The numbered paragraph in the reply explains it. |
| Circled note with letters | A non-chord tone (a note that does not belong to the chord): PT passing note, NT neighbour note, SUS suspension, APP appoggiatura, ET escape tone, ANT anticipation, RET retardation (a held note that then rises to the chord), PED pedal tone (a held or repeated note under changing chords). |
| Arrow between notes | A voice-leading move worth following, such as a 4–3 suspension or the leading tone rising to the tonic. |
| Red lines, circles or brackets on notes, with a red code | A part-writing slip, checked in music for two to four parts: P5 / P8 two parts move in parallel fifths / octaves; H5 / H8 the top and bottom parts arrive at a fifth / octave moving the same way while the top part leaps; VC two parts cross; VO a part moves past the note its neighbour just held; S two neighbouring upper parts more than an octave apart; r a note outside the part's usual range; D the leading tone (the note just below the home note) doubled; R, with a small red arrow, a note that does not move the way it should, such as a seventh that should step down. These red codes are separate from the black T, PD and D of the brackets. |
| Numbered black disc | A callout. The paragraph with the same number in the reply explains it. |
| Pale yellow shading over a bar | A bar read from a PDF that may be misread, so its analysis may be wrong. Check it against your original. |
| Small instrument names such as Vl. or Tutti (piano version) | Who plays the tune from that point. See 5. Big scores. |
4. Choose a view
The full page shows everything. Ask for one view when you want to focus:
- Harmony: numerals, the brackets naming each chord's job, keys, cadences and any second possible reading.
- Voice leading: non-chord tones and resolution arrows.
- Form: phrases, cadences and named passages.
Every page comes as a PNG image and a PDF you can print or annotate further. Under More downloads the card also offers: MusicXML, the whole score with the Roman numerals written in, to open in your notation software; Blank worksheet, a PDF of the same bars with no analysis marks, to analyse yourself; MIDI, the same bars as a file you can play in music software; Analysis as text, a plain-text file listing the key and the Roman numeral of each chord, bar by bar. The download links last 30 days; ask again for a fresh copy.
5. Big scores: the piano version
For a score with more than four lines of music, such as an orchestra, a band or a large ensemble, the full score is drawn first, and you'll be offered a piano version of the same bars. It condenses every instrument onto two lines, with the tune on top. Small labels such as Fl. (flute), Vl. (violins), Str. (strings) or Tutti (everyone) show who is playing the tune. The analysis is made on the full score and drawn the same way on the piano version. You can also ask for it yourself at any time.
6. Listen to it (Claude)
In Claude, ask to hear the music ("play bars 1–8") and a small piano player appears in the chat, with play, pause and a bar to jump through the passage. It plays what the score marks: the tempo, loud and soft, the pedal and ornaments such as trills. It plays the bars you analysed; ask for other bars or the whole piece and it plays those instead. A score read from a PDF often lacks some of these markings, so it may play without pedal or at an ordinary speed. The piano sound is the Salamander Grand Piano by Alexander Holm (CC BY 3.0).
What it covers, and what it doesn't
- Best at: tonal music from Bach to the late nineteenth century, for piano, voices, chamber groups and orchestra.
- Less precise: modal and impressionist music (Debussy, Ravel, Satie), where it names passages by their scale or texture rather than forcing Roman numerals; and borrowed chords in a major key, which it sometimes reads as a move to the minor.
- Not yet: jazz and popular-music chord symbols as the main lens, photos, handwritten music, and audio.
- Daily limits: the service is free and shared, so each person can send up to 10 new scores a day (a score you already sent does not count again), within a daily capacity shared by everyone. If a limit is reached, the chat will tell you; both reset at midnight UTC.
The analysis is a starting point for your own reading. If you think a label is wrong, say so in the chat: the model will reconsider it against the notes.
Questions
Why should I check the music it read from a PDF? A PDF shows what the music looks like, so the tool has to read the notes and rhythm from the page before it can analyse them. It can miss notes or read them incorrectly, especially on scanned pages, and those mistakes can change the analysis. Compare every bar of the copy it shows you with your original, even bars that are not shaded, and tell it about any differences.
Other questions: email support@sheetmusicanalysis.com.