ScoreBridge

Agent-led sheet-music transcription and MuseScore control. The calling Agent reads PDF/PNG/JPG/TIFF/WebP sources, organizes music, and uses editor tools to produce an editable, playable MSCZ. Audiveris is opt-in assistance.

Default workflow

PDF / images → source preparation → Agent reads the score
→ internal music / command plan → MuseScore editing → MSCZ

The current implementation prepares source images, executes ordered live-plugin commands, and offers a legacy Score IR compilation adapter. It does not yet supply every MuseScore editing operation or prove high-accuracy orchestral transcription end to end. See the actual editor capabilities.

Related MCP server: opendaw-mcp

Install

git clone https://github.com/achou666666-code/ScoreBridge.git
cd ScoreBridge
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[mcp,image,websocket,test]'
.venv/bin/scorebridge doctor
.venv/bin/scorebridge editor-status

Install MuseScore separately. doctor checks dependencies; editor-status actually contacts a running plugin. Audiveris is optional and its absence does not fail the environment check. Install the skill folder skills/scorebridge in your Agent's skill directory, and configure the MCP server with the environment's Python executable and the absolute path to mcp_server/server.py:

.venv/bin/python mcp_server/server.py

The compatible MuseScore QML plugin is included in plugins/. On macOS, install it with:

bash scripts/install_musescore_plugin.sh

Then open a score in MuseScore and choose Plugins > musescore-mcp-websocket. Leave the plugin running while ScoreBridge sends editing commands. Verify the live connection with .venv/bin/scorebridge editor-status.

ScoreBridge includes its compatible MuseScore editor plugin and a WebSocket client. Other implementations such as mcp-score and mcp-musescore use different command sets and wire formats. The bundled plugin must be running for live editing. Set SCOREBRIDGE_MUSESCORE_WS for a custom endpoint (default ws://localhost:8765). Protocol detection uses read-only ping; SCOREBRIDGE_MUSESCORE_PROTOCOL can force action or command. No mutation is automatically retried after a timeout. scorebridge editor-status reads the plugin's declared command list without editing the score. Restart MuseScore after updating the plugin so QML is reloaded. The status response separates verified commands from reserved_commands that are intentionally unavailable on MuseScore 4.7.4. Playback mute and direct sound assignment are reserved until they can be verified. setStaffVisible controls engraving visibility and is never reported as audio mute.

The current live bridge edits and saves an already-open score. New-score creation, opening a path, Save As, and automatic instrument sound assignment remain pending for MuseScore 4.7.4. The lifecycle command names are reserved and return a clear unsupported result until a version-tested implementation is available; ScoreBridge does not claim those operations succeeded.

musescore_open is the supported path-opening helper for an existing MSCZ or MusicXML file. It launches MuseScore with that file and returns the process id; the Agent should then wait for musescore_websocket_status to confirm the plugin before sending edits. Creating a blank score and Save As remain version-dependent. The same operation is available locally as scorebridge open-score INPUT. Before exporting or editing playback, call score_instrument_audit on the internal score plan. It reports unresolved IDs and detects an accidental piano fallback; a part label alone is not evidence of a correct playback sound. addDynamic is implemented in the bundled editor but remains reserved until a clean MuseScore restart verifies dynamic-element insertion on the target version.

Agent entry point

Call score_transcribe(input_path, output_dir) through MCP, or:

scorebridge prepare INPUT --output WORKDIR

This prepares source-linked pages and returns awaiting_agent. The calling multimodal Agent now reads the images; the program does not secretly run OMR or invoke a second model. Original, rendered and enhanced images and their page mapping remain in the working directory. Filename sorting is a convenience; the Agent checks actual page order and identifies non-score pages.

The Agent can keep a compact command plan instead of the legacy Score IR:

scorebridge execute-plan PLAN.json

examples/create-and-save-plan.json shows the recommended lifecycle order for a new score: create, set notation context, write content, then save as MSCZ. The same plan can be sent through musescore_execute_plan; each step has a stable ID so a partial failure can resume from the last acknowledged command.

The MCP equivalent is musescore_execute_plan(input_path). It prevalidates step IDs, executes in order, and reports completed IDs and the failed step. It is not an atomic transaction. Inspect current editor state after a failure before continuing. executed means acknowledged commands, not completed transcription. Use musescore_websocket_command for individual supported operations.

MSCZ delivery

score_finalize remains available for scores expressible in the legacy Score IR. It compiles internal MusicXML, creates MSCZ through MuseScore, and keeps temporary XML and structural audits under .scorebridge/. It no longer exports MIDI or PDF by default. Failed MSCZ export returns error; failed reopen conversion returns incomplete. The audit does not establish source accuracy or correct audible timbre.

The legacy IR cannot represent all notation. Do not silently drop unsupported lyrics, slurs, articulations or performance semantics to make compilation pass. For these, extend the editor adapter or use a documented software-operation fallback and verify the actual saved score.

Optional OMR and developer tools

Use score_transcribe(..., mode="omr") only to select the legacy Audiveris → MusicXML → Score IR → review route. omr_run, review_create, and review_apply remain available for that optional workflow. Agent-led jobs do not require a second recognition pass or human measure-by-measure review.

score_validate, score_compile, score_apply_patch, score_inspect, score_build_mscz, and musescore_convert are lower-level developer tools; their intermediate files are not the default user delivery.

Tests

.venv/bin/pytest -q

Tests include a local WebSocket server for both wire formats, nested plugin errors, partial-plan failures without replay, input preparation without OMR, and compilation checks. These protocol tests are distinct from real MuseScore editing and listening tests.

Demos

demos/image-to-score/ is reserved for a small image-to-editable-score walkthrough. demos/pirates/ is reserved for a later multi-page orchestral case study, screenshots, and validation reports. The public Twinkle smoke run currently produces an evidence package, Audiveris MusicXML, Score IR, and MuseScore round-trip files under demos/image-to-score/output/twinkle-run/. Videos are intentionally added only after they are recorded; source PDFs and other copyrighted material do not belong in the public repository.

Next editor work

Complete and verify create/open/save, instrument playback assignments, multi-voice entry, slurs/articulations/techniques, and layout through an actual MuseScore plugin. Then run the local orchestral regression. Sibelius support is future work.