hkuds--cli-anything/musescore/agent-harness/MUSESCORE.md

MUSESCORE.md — Software-Specific Analysis and SOP

1. Software Overview

MuseScore 4 is a free, open-source music notation editor. It reads and writes .mscz (native), .mxl (compressed MusicXML), .mid (MIDI), and .musicxml formats.

• Homepage: https://musescore.org
• Version tested: 4.6.5
• License: GPL v3

2. Backend Engine

The mscore binary provides all rendering, transposition, and conversion capabilities.

Binary Locations

Platform	Path
macOS	/Applications/MuseScore 4.app/Contents/MacOS/mscore
Linux	/usr/bin/mscore4 or /usr/local/bin/mscore4
Windows	C:\Program Files\MuseScore 4\bin\MuseScore4.exe

Data Model

• .mscz = ZIP archive containing:
  • .mscx XML (score data)
  • score_style.mss (style overrides)
  • audiosettings.json
  • viewsettings.json
  • Thumbnails/thumbnail.png
• .mxl = ZIP archive containing MusicXML score.xml

3. CLI Capabilities

Export (-o)

mscore -o output.pdf input.mscz       # PDF
mscore -o output.mid input.mscz       # MIDI
mscore -o output.mp3 --bitrate 192 input.mscz  # MP3
mscore -o output.png -r 150 input.mscz  # PNG (per page)
mscore -o output.musicxml input.mscz  # MusicXML

Transpose (--transpose + -o)

JSON format:

{
  "mode": "to_key|by_interval|diatonically",
  "direction": "up|down|closest",
  "targetKey": 0,
  "transposeInterval": 0,
  "transposeKeySignatures": true,
  "transposeChordNames": true,
  "useDoubleSharpsFlats": false
}

Key Signature Integer Mapping

-7=Cb -6=Gb -5=Db -4=Ab -3=Eb -2=Bb -1=F
 0=C   1=G   2=D   3=A   4=E   5=B   6=F#  7=C#

Metadata (--score-meta)

Returns JSON: title, composer, keysig, timesig, tempo, duration, measures, pages, parts.

Parts (--score-parts)

Returns JSON with part names and base64-encoded .mscz data per part.

Media (--score-media)

Returns JSON with pngs, svgs, pdf, midi, mxml, metadata.

Batch Jobs (-j)

[{"in": "/path/input.mscz", "out": "/path/output.pdf"}]

Exit Codes

• 0 — success
• 31 — invalid transpose options
• 23 — invalid batch job format

Output Verification (Magic Bytes)

Format	Magic
PDF	%PDF-
MIDI	MThd
MP3	0xfffb or ID3
PNG	\x89PNG
MSCZ	PK (ZIP)

4. GUI-to-CLI Mapping

GUI Action	CLI Equivalent
File → Export → PDF	mscore -o output.pdf input.mscz
Tools → Transpose	mscore --transpose '{...}' -o out.mscz input.mscz
File → Parts	mscore --score-parts input.mscz
File → Score Properties	mscore --score-meta input.mscz

5. CLI Architecture

Command Groups (v1 MVP)

Group	Purpose	Backend
project	open, info, save	MusicXML/MSCX parsing
transpose	by-key, by-interval, diatonic	--transpose + -o
parts	list, extract, generate	--score-parts
export	pdf, png, svg, mp3, flac, wav, midi, musicxml, braille, batch	-o
instruments	list, add, remove, reorder	MSCX XML manipulation
media	probe, diff, stats	--score-meta, --diff
session	status, undo, redo, history	In-memory state + JSON persistence

State Model

• In-memory Session dataclass with undo/redo stacks
• fcntl.flock() for safe concurrent JSON writes
• Session singleton via get_session()