Skip to main content
Glama
Dorico Maestro

Dorico Maestro

README.md
# 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: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE) [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/) [![Dorico 4+](https://img.shields.io/badge/Dorico-4%20%7C%205%20%7C%206-orange.svg)](https://www.steinberg.net/dorico/) [![No telemetry](https://img.shields.io/badge/telemetry-none-brightgreen.svg)](#your-music-stays-yours) [![Glama](https://glama.ai/mcp/servers/romanstark/dorico-maestro/badges/score.svg)](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

A3.9/5.0

Scored across 40 tools

Disambiguation4/5

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 Consistency3/5

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.

Tool Count2/5

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.

Completeness4/5

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.

Maintenance

ActivityNo data
ResponsivenessOutdated data