Dorico Maestro
# Dorico Maestro
> An AI composition and orchestration partner for **Steinberg Doricoยฎ**. Speak in natural language to write notes directly into your score, audit voice leading, analyze harmony, check instrument ranges, and manage engraving layouts, right inside your open project.
[](LICENSE) [](https://www.python.org/) [](https://www.steinberg.net/dorico/) [](#your-music-stays-yours) [](https://glama.ai/mcp/servers/romanstark/dorico-maestro)
---
## Stay in the creative flow
Composing and engraving music in a notation program requires deep focus, but constantly breaking your train of thought to navigate popovers, click through staves, and proofread voice leading can pull you out of the zone.
**Dorico Maestro** acts like an assistant orchestrator and copyist sitting beside you at the scoring desk:
- **Keep your eyes on the score:** Dorico stays open in front of you. You watch the notation appear, evaluate voicing and balance, and make the musical decisions.
- **Natural scoring dialogue:** Ask for chord voicings, chorale harmonizations, counterpoint audits, transpositions, or layout adjustments in plain musical language.
- **Real notation, real scores:** Nothing is simulated or pre-rendered. Everything is written directly into your active Dorico project through the live caret or standard MusicXML as editable Steinberg Dorico notation events.
---
## How it feels at the scoring desk
Here is what collaborating with Maestro looks like during a scoring session:
### 1. Score Writing & Harmony
> **You:** *"Write a 4-part chorale phrase in D minor at the caret. Soprano starts on F4 and moves step-wise down to D4. Build a classical SATB voicing with smooth contrary motion."*
>
> **Assistant:** Entered a 4-bar phrase in D minor across Soprano, Alto, Tenor, and Bass staves:
> - **Soprano:** F4 (half note) -> E4 (quarter note) -> D4 (half note).
> - **Alto / Tenor:** Inner voices provide full triadic harmony with step-wise motion.
> - **Bass:** Contrary root motion resolving firmly to the final tonic cadence.
> - **Verification:** Audited voice leading: no parallel fifths or octaves detected.
>
> Notes are in your score and ready to play.
### 2. Voice Leading & Counterpoint Audit
> **You:** *"Check the active string quartet passage for voice crossing, parallel octaves, and unresolved leading tones."*
>
> **Assistant:**
> - Audited the four parts using local music theory analysis.
> - **Result:** Detected parallel octaves between Violin 2 and Cello on beat 3 of bar 14 (A3->B3 and A2->B2).
> - **Voice Leading:** Unresolved leading tone in Viola (G#4 steps down to E4 instead of resolving up to A4).
> - **Recommendation:** Resolve Viola up to A4 to complete the cadence and hold Violin 2 on E4 to eliminate the octave parallel.
### 3. Orchestration & Engraving
> **You:** *"Check if the Cor Anglais part is within comfortable range, transpose the French Horn in F down a minor third, and export the current layout to PDF."*
>
> **Assistant:**
> - Verified Cor Anglais compass: all notes fall between G3 and C6 (well within comfortable orchestral range).
> - Transposed the French Horn selection down a minor third using chromatic transposition with flat-enharmonic spelling.
> - Exported the current layout directly to PDF into your project directory without opening a modal dialog.
---
## What you can do
| Workflow | Example prompt | What Maestro does |
|---|---|---|
| **โ๏ธ Caret Note Entry** | *"Input a 4-bar melody at the caret in G major with dotted quarters and eighths"* | Steps through the score at the caret, sets durations and pitches, applies accidentals and ties |
| **๐ผ Full-Score Writing** | *"Create a string quartet sketch with Violin 1, Violin 2, Viola, and Cello"* | Generates complete multi-part scores with staves, voices, key signatures, and meters |
| **๐ Harmony & Analysis** | *"Analyze the Roman numeral harmony of this progression in E-flat major"* | Performs local key detection, chord labeling, and harmonic analysis |
| **๐ Voice Leading & Rules** | *"Audit this counterpoint passage against first-species voice leading rules"* | Identifies parallel fifths, octaves, voice crossing, and forbidden melodic leaps |
| **๐บ Orchestration & Range** | *"Check whether the Trumpet 1 line exceeds the comfortable orchestral range"* | Validates instrument compasses and warns of difficult register extremes |
| **๐จ๏ธ Engraving & Layout** | *"Switch to Print mode and export the full score layout as PDF"* | Navigates Dorico modes, switches views, and runs unattended PDF exports |
| **๐ Offline Project Inspection** | *"Read the flows, players, and metadata from this .dorico file"* | Inspects `.dorico` project archives directly on disk without launching Dorico |
| **๐ Reading Your Open Score** | *"Read the score I have open, then add a viola line that fits"* | Inspects the active flow via one-click MusicXML export to extract key, meter, bar count, and upbeat presence for exact subsequent caret operations |
| **๐ป Playback Setup** | *"Load a sampler into slot 3, put the violas on channel 3 and give them the keyswitch expression map"* | Activates playback, loads and removes VST instruments, routes instruments to channels and sets expression maps, reading back what Dorico took |
| **๐ Dynamics & Tempo at a Bar** | *"Put an mf in bar 12 of the cellos and q = 70 at bar 41"* | Places the caret and writes the marking directly, no popover to type into |
| **๐ฉบ Playback Check & Plugin State** | *"Why is the viola silent? Check the saved project, then put this preset into slot 2"* | Compares Dorico's rack with what the audio engine really hosts, finds instruments routed to empty slots, and sets a slot's plugin state in a closed project, with a backup |
| **๐๏ธ Flows & Project Files** | *"Delete the flow the last import added, then save and wait until the file is written"* | Lists, renames and deletes flows, opens, saves as, closes and reverts projects, and reports when the file on disk is complete |
| **๐ Enharmonic & Transpose** | *"Transpose selected notes up a whole tone and respell using sharps"* | Dispatches diatonic/chromatic transpositions and enharmonic respelling |
---
## Why Maestro is reliable
Most AI music tools generate raw MIDI or static audio files without understanding the underlying notation rules.
Dorico Maestro is built on a **robust, safety-first architecture**:
- **Lifecycle & Caret Safety:** Note input commands use strict session context managers (`try ... finally: NoteInput.Exit`). Even if an operation fails or arguments are malformed, Dorico is never left stranded in an open note-input state.
- **Destructive Command Guard:** Commands that could discard musical work (`Edit.Delete`, `File.Close`, `File.Quit`) are automatically blocked unless explicitly authorized with `confirm=True`.
- **Overwrite Mode Transparency:** Because Dorico defaults to Overwrite mode and the Remote Control API cannot read bar contents back, Maestro monitors `noteInputMode` and flags `displaces_existing: true` in its response whenever notes land in Overwrite mode.
- **Data-Driven & Verified:** Built on a comprehensive catalog of 369 commands, with **196 of 354** commands verified live against Dorico 6.
- **Dual Writing Paths:** Offers direct live caret input for fast interactive editing, and native MusicXML generation powered by music21 for complete multi-voice orchestral scores.
---
## Quick start
You need Steinberg Dorico 4, 5, or 6 and [uv](https://docs.astral.sh/uv/). No repository, no virtual environment, no Python knowledge.
### 1. Install it
```powershell
uv tool install git+https://github.com/romanstark/dorico-maestro.git
```
### 2. Connect to Dorico
1. Open **Steinberg Dorico** and open any project. Dorico automatically listens on local WebSocket port `4560`.
2. On first connection, Dorico will display a permission prompt (*"Do you want to allow Dorico Maestro to connect?"*). Click **Authorize**. A persistent session token is saved automatically (`%APPDATA%\dorico-maestro\session_token.json` on Windows, `~/Library/Application Support/dorico-maestro/session_token.json` on macOS) for future sessions.
### 3. Connect your AI assistant
Add Dorico Maestro to your MCP client configuration (Claude Desktop, Cursor, Antigravity IDE):
```json
{
"mcpServers": {
"dorico-maestro": {
"command": "dorico-maestro"
}
}
}
```
To run it without installing anything permanently, let `uvx` fetch it per launch:
```json
{
"mcpServers": {
"dorico-maestro": {
"command": "uvx",
"args": ["--from", "git+https://github.com/romanstark/dorico-maestro.git", "dorico-maestro"]
}
}
}
```
Open a project in Dorico, connect, and start with: *"What mode is Dorico currently in?"*
---
## Your music stays yours
- **100% Local:** All communication between your AI assistant and Dorico takes place over a local loopback WebSocket connection (`127.0.0.1:4560`) on your machine.
- **No Telemetry or Cloud Tracking:** Dorico Maestro collects zero analytics and transmits no prompts, scores, or project files to any external server.
- **Local Storage:** Your music, `.dorico` archives, and MusicXML files remain strictly on your local disk.
---
## What stays in your hands
Dorico's Remote Control API is powerful, but certain tasks are intentionally reserved for you in the Dorico interface:
| Task | Why | How to do it |
|---|---|---|
| **Typing into Popovers** | Remote API opens popovers (Shift+D, Shift+T, etc.) but cannot type text into them | Dynamics and tempo go in directly with `add_marking`; for other popovers Maestro opens them and tells you the exact value, or use `write_score(method="musicxml")` |
| **Plugin Windows** | A sampler's own window belongs to Dorico's audio engine, which no assistant can operate | Load and route instruments with Maestro; to set sounds without the window, export a slot's state from a project where it is right and import it into the closed project with `plugin_state` |
| **Confirming Deletions** | Deleting a flow and reverting a project ask for confirmation in Dorico | Click OK in Dorico; Maestro waits and reports the result |
| **Modal Dialog Confirmation** | Dorico requires manual confirmation for file open and export dialogs | Press Enter on the export prompt once, and `read_open_score` automatically ingests the resulting MusicXML (use `export_pdf` for unattended PDF export) |
| **Initial Connection Approval** | Dorico security model requires one-time user authorization | Click **Authorize** on the Dorico permission prompt on first run |
| **Artistic Judgment** | AI can check rules and draft parts, but musical intent and taste belong to you | Guide the score, listen to playback, and refine the music |
---
## Current Verification Status
Verified live (211 commands), grouped by category:
- `NoteInput` 101 of 125: Pitches, durations, accidentals, articulations, chords, tuplets, and popovers.
- `Window` 26 of 29: Window modes, layout views, panels, toolbar, and zoom controls.
- `Play` 32 of 40: Transport, playhead placement, mixer controls, and the playback setup: activating, loading and removing VST instruments, routing, expression maps.
- `View` 13 of 16: Viewport scrolling and zoom operations.
- `NoteEdit` 8 of 8: Diatonic, chromatic, and octave transposition, plus enharmonic respelling.
- `Edit` 6 of 17: Selection, copy, delete, and undo operations.
- `EventEdit` 4 of 57: Selection navigation commands (`Navigate*`).
- `File` 7 of 12: Save, save as, close and revert, and MusicXML import/export filters.
- `UI` 3 of 7: Panel focusing commands.
- `Print` 1 of 7: Unattended PDF export (`Print.ExportCurrentLayoutAsPDF`).
- `Project` 4 of 12: Adding, renaming and deleting flows, renaming players.
- `MusicalManipulation` 6 of 6: Retrograde of pitches, rhythm or both; the inversion commands open a dialog to confirm.
The remaining 11 categories are currently untested.
### Testing & Environment
Empirical testing was conducted against **Dorico Elements 6.2.30 and 6.2.40** on Windows 11 and macOS. Dorico restricts commands depending on product tier (SE, Elements, Pro). Commands requiring Pro (such as Lua scripting) return `kUnknownCommand` and are classified as `unavailable` rather than `broken`.
Dorico Maestro exposes **40 tools** and one resource (`dorico://commands`) for complete command discovery.
### A note to Steinberg (and Dorico Pro users)
Dorico Maestro is an independent open-source project developed with a personal **Dorico Elements** license. Advanced features exclusive to **Dorico Pro** (such as Lua scripting via `Script.*`, full engraving options, and advanced dialog automation) are currently classified as `unavailable` or `untested` simply because they cannot be executed on Elements.
If anyone from Steinberg discovers this project and would like to support bringing first-class AI integration to Dorico: an NFR or developer license for **Dorico Pro** would be immensely appreciated to test, verify, and unlock the remaining Pro-specific commands for the entire community. Feel free to get in touch via GitHub or email at [mail@romanstark.de](mailto:mail@romanstark.de)!
---
## Related Maestro projects
- [Live Maestro](https://github.com/romanstark/live-maestro) controls Ableton Live,
musical timing, MIDI and sample placement.
- [UVR Maestro](https://github.com/romanstark/uvr-maestro) separates and restores
local audio with UVR5 models.
Each server works independently. Use ordinary MIDI, audio and JSON files when
combining their workflows.
---
## Development
Working on the server itself rather than composing with it:
```bash
git clone https://github.com/romanstark/dorico-maestro.git
cd dorico-maestro
python -m venv .venv
```
Activate the environment with `.venv\Scripts\activate` on Windows or `source .venv/bin/activate` on macOS and Linux, then install dependencies:
```bash
pip install -e ".[dev]"
```
Verify tests without needing Dorico:
```bash
pytest
```
Point your MCP client at the checkout's interpreter while you work on it:
```json
{
"mcpServers": {
"dorico-maestro": {
"command": "/absolute/path/to/dorico-maestro/.venv/Scripts/python.exe",
"args": ["-m", "dorico_maestro.server"]
}
}
}
```
On macOS and Linux the interpreter is `.venv/bin/python` rather than `.venv/Scripts/python.exe`.
---
## Documentation & Developer Resources
For architectural details, wire protocols, and contributor information:
- [docs/architecture.md](docs/architecture.md) โ Internal architecture and multi-layer design
- [docs/protocol.md](docs/protocol.md) โ Dorico Remote Control WebSocket protocol specification
- [docs/dorico_command_catalog.md](docs/dorico_command_catalog.md) โ Complete base key-command catalog (340 commands)
- [CONTRIBUTING.md](CONTRIBUTING.md) โ Guidelines for contributing and command verification
- [THIRD-PARTY.md](THIRD-PARTY.md) โ Third-party notices, dependencies, and trademark attributions
- [LICENSE](LICENSE) โ AGPL-3.0 License
---
## Legal & Trademarks
Steinberg and Dorico are trademarks or registered trademarks of Steinberg Media Technologies GmbH, registered in Europe and other countries. Ableton is a registered trademark and Live is a trademark of Ableton AG.
Dorico Maestro is an independent open-source project and is not affiliated with, endorsed, sponsored, or supported by Steinberg Media Technologies GmbH or Ableton AG. For full third-party notices, licenses, and attributions, see [THIRD-PARTY.md](THIRD-PARTY.md).
TDQS
Scored across 40 tools
Most tools target a clearly distinct action (connect, get_status, read_selection, transpose, save, export_pdf, analyze_harmony) and the descriptions actively cross-reference alternatives, which is unusually strong disambiguation. However, render_to_dorico is explicitly described as 'the lower half of write_score', add_notes/add_rest/write_score overlap on note entry, and set_time_signature/set_key_signature are deliberate no-op stubs that duplicate advice given by open_popover and write_score. The read family (get_status, read_selection, read_score, read_open_score, read_project_info) is large but well-differentiated by scope.
Naming is uniformly snake_case and readable, and many tools follow verb_noun (get_status, read_selection, write_score, add_notes, export_pdf, import_musicxml, check_voice_leading). But there are many bare nouns and single words (transpose, save, playback, navigate, project_file, playback_state, playback_setup, plugin_state, score_schema, instrument_range) mixed in, so the verb_noun pattern is not predictable across the set.
40 tools is well past the point where an agent can hold the surface in view, spanning Dorico control, offline music theory, VST/playback configuration, MusicXML conversion and a command-catalog escape hatch. Each tool is individually justified, but several are narrow conveniences (rename_player, activate_playback, plugin_state, set_time_signature stubs) that inflate the set. The scope is genuinely broad, yet the count is heavy enough to slow tool selection.
Coverage is broad and lifecycle-complete for the main workflows: connect, status/selection reads, note entry, score writing, export/import, save/project file, flows, playback and setup, plus offline analysis and a catalog escape hatch for anything missing. Real gaps exist (pitch and caret position unavailable via the API, key/time signatures not settable directly, no player deletion), but each is documented with a concrete workaround rather than left as a dead end.