DonutStudio API: JSON-RPC & Lua scripting

Two ways to drive DonutStudio programmatically

DonutStudio exposes its full editing surface in two interchangeable ways: a JSON-RPC command server on port 9900 (used by the MCP server and any HTTP client), and the `arbit` Lua scripting API (used by .lua scripts dropped into the install directory). Both speak the same namespace, with the same method names and the same argument shapes, so a tool that works in one works in the other. Bring your own MCP-compatible client (Claude Code, Cursor, Codex, any Model Context Protocol host), or write a Lua script and call it from the in-app menu.

MCP server (port 9900)

JSON-RPC over HTTP. Use this from any agent.

Connect

POST JSON-RPC requests to http://localhost:9900. The MCP server fronting it exposes the same surface. Register it as a Model Context Protocol server and your client sees a tool per method.

Notes

create_note, delete_note, move_note, resize_note, set_note_velocity, set_note_muted, set_note_root, set_cents_offset, get_notes. Batch entry point: create_notes (one undo step).

Harmonic links

create_link, delete_link, set_link_ratio, get_links. A link retunes a slave note relative to a master via a rational (slaveHarmonic / masterHarmonic) ratio. 3/2 = perfect fifth, 7/4 = natural seventh, any prime ratio up to the harmonic graph ceiling.

Pitch bends and expression

set_pitch_bend, get_pitch_bend, clear_pitch_bend, set_note_expression. Vibrato (OpenUtau model), portamento, and DiffSinger gender/velocity overrides are all per-note state.

Transports and playback

play, stop, set_playhead, set_bpm, get_transport, preview_note (audition a single note with the correct tuning), stop_previews.

Tracks and instruments

set_track_instrument (soundfont / dx7 / diffsinger / va / external MIDI), set_track_volume, set_track_pan, set_track_adsr, set_track_reverb, set_track_muted, set_track_soloed, set_track_name.

Batch transforms

batch_transform with named transforms: quantize, double_length, halve_length, reverse, legato, staccato, transpose, set_velocity, scale_velocity, humanize, mute, set_track, join, bow_split, root_path_tune.

File I/O and checkpoints

import_midi, export_midi, import_arbit, export_arbit, save_checkpoint, restore_checkpoint, list_checkpoints, delete_checkpoint.

Visual state and window

screenshot (window='main'|'video'), get_audio_meters, reset_audio_meters, get_loudness, reset_loudness, get_spectrum, get_debug_log.

Lua scripting API (`arbit.*`)

Same surface, callable from .lua scripts.

Setup

Drop a .lua file into the install directory (per-platform paths in docs/lua-scripting.md). It shows up in the in-app menu and can also be invoked from the MCP server.

Namespace

Same method names as the JSON-RPC surface: arbit.create_note, arbit.create_link, arbit.batch_transform, arbit.export_arbit, etc. Return values are tables.

Examples

Ready-to-edit scripts in github.com/DonutsDelivery/donutstudio/tree/main/examples — Analysis/, Generators/, Skins/, Transforms/. Copy, modify, drop in.

Public documentation

Everything below lives in the public GitHub repo.

README.md

Overview, downloads, the Lua example, and the "For developers & AI agents" section. Start here. — https://github.com/DonutsDelivery/donutstudio

docs/api-reference.md

Full `arbit` API reference — method signatures, argument shapes, return values. Same surface as the MCP server. — https://github.com/DonutsDelivery/donutstudio/blob/main/docs/api-reference.md

docs/lua-scripting.md

Lua setup, install locations per platform, and complete example scripts. — https://github.com/DonutsDelivery/donutstudio/blob/main/docs/lua-scripting.md

docs/skinning.md

Skin format overview. See also examples/Skins/ for working packs. — https://github.com/DonutsDelivery/donutstudio/blob/main/docs/skinning.md

docs/downloads.md

Download mirror and integrity notes. — https://github.com/DonutsDelivery/donutstudio/blob/main/docs/downloads.md

Examples in the public repo

Copy a script and modify it for your task.

examples/Analysis/

Read-only scripts that walk a project and report properties (note distribution, tuning spread, harmonic-chain depth). — https://github.com/DonutsDelivery/donutstudio/tree/main/examples/Analysis

examples/Generators/

Scripts that lay down a pattern from a rule or a parameter — chord progressions, arpeggios, drum patterns, generative melodies. — https://github.com/DonutsDelivery/donutstudio/tree/main/examples/Generators

examples/Transforms/

Note transforms that don't fit the built-in batch_transform vocabulary — adaptive humanize, microtonal swing, ratio-aware quantize. — https://github.com/DonutsDelivery/donutstudio/tree/main/examples/Transforms

examples/Skins/

Working .skin packs to use as starting points. — https://github.com/DonutsDelivery/donutstudio/tree/main/examples/Skins

Run the README's Lua example

Boosts every quiet note's velocity. The same shape works from the MCP server; see the agents page.

For AI agents Download DonutStudio

Inline links to every page an AI agent or non-JS client might need. The page top nav (Features … Download) is JS-rendered from data/projects.json:donutstudio.subnav.

Features: /donutstudio/features — every major feature in one place.
API & scripting: /donutstudio/api — the public arbit scripting surface, MCP server reference, and links to docs/, examples/, skills/.
For AI agents: /donutstudio/agents — how to start, what you can do, example tasks, do/don't.
About: /donutstudio/about — one-person project in Denmark.
Download: /donutstudio/download — installers for Windows, macOS, Linux.
DonutStudio overview: /donutstudio — the home page.
MCP server port: localhost:9900 (JSON-RPC; the same surface the arbit Lua API exposes).
Public docs on GitHub: https://github.com/DonutsDelivery/donutstudio/tree/main/docs
Agent skills on GitHub: https://github.com/DonutsDelivery/donutstudio/tree/main/skills