playback_setup
Change VST plugin slots, instrument routing, or expression maps and apply playback templates in Dorico, confirming destructive edits before they run.
Instructions
Change VST slots, an instrument's routing, or an expression map.
Returns:
Result dictionary with the command sent, whether Dorico finished it, and
whether a playback change was signalled; ``route`` also reports the
endpoint and, where Dorico logs it, a verified MIDI thru change.
Note:
Measured in Dorico Elements 6.2.40 on a test project. The project must be
activated for playback, or a load is refused with ``kCommandNotAllowed``.
Endpoint = 1024 × (slot − 1) + channel − 1, so slot 2 channel 1 is 1024; a slot
that was replaced can leave instruments elsewhere, which read_playback_setup shows.
Loading into a slot that holds a plugin replaces it, and the instruments
routed to it lose their routing silently: route them again. Dorico logs
"slot is already occupied by the same plugin" even for a load that worked,
so that line is no failure signal. Removing a slot needs ``confirm=True``.
``apply_template`` rebuilds the whole setup from a playback template: it
reloads the template's sounds and resets routing and expression maps, so it
needs ``confirm=True``.
An instrument id that does not exist is answered with kOK and changes
nothing; read_playback_setup lists the ids of a saved project. ``verified`` is
True only when Dorico's log shows the MIDI thru endpoint moving, which happens
for the instrument Dorico monitors; otherwise it is None, not False.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"action": "<action>"
},
"name": "playback_setup"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slot | No | VST instrument slot as Dorico's window numbers it; slot 1 is Dorico's click, so the first usable slot is 2. Ignored by apply_template. | |
| action | Yes | What to change in the playback setup. | |
| plugin | No | load_plugin: plugin name or 32-digit class id, see list_plugins. | |
| channel | No | route and set_expression_map: MIDI channel. | |
| confirm | No | True authorises a change that discards work or cannot be undone. | |
| template | No | apply_template: playback template id; the default is Dorico's automatic one. | playbacktemplate.auto |
| instrument | No | route: Dorico's instrument id, see read_playback_setup. | |
| expression_map | No | set_expression_map: map id (xmap.…) or name, see playback_state. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||