run_qml
Executes QML/JavaScript code inside the MuseScore plugin to perform complex score edits in one call and return a JSON-serializable result. Persists state across calls for multi-step work.
Instructions
Execute QML/JavaScript code inside the MuseScore plugin and return its result.
For complex score tasks that would otherwise need many round trips. The code is a function body, run as function(ctx, params, state):
ctx: plugin API facade - ctx.score (current Score), ctx.newCursor(), ctx.processCommand({action, params}), ctx.processElement(element), ctx.getScoreSummary(), ctx.getVoices(params), ctx.log(msg)
params: the params object of this call (yours to shape)
state: object persisting across run_qml calls (for multi-step work; mutate it, do not reassign it) The return value must be JSON-serializable (checked before commit). Undo-aware engraving changes in a run form one undo step; errors roll them back, including nested ctx actions. Playback/mixer actions, undo and recursive eval are rejected inside a run. Raw native writes bypassing MuseScore's undo stack (such as setMetaTag) are outside this guarantee. Call get_score before and after a run when you want your own before/after comparison - the server itself keeps no state. The code runs on MuseScore's GUI thread - an infinite loop freezes MuseScore unrecoverably. See docs/AGENT-COOKBOOK.md for patterns and known pitfalls. Requires the plugin property allowEval: true; otherwise returns an error explaining how to enable it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| params | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |