trackwright 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. trackwright/__init__.py +13 -0
  2. trackwright/__main__.py +7 -0
  3. trackwright/bridge.py +323 -0
  4. trackwright/cli.py +203 -0
  5. trackwright/commands.py +397 -0
  6. trackwright/config.py +149 -0
  7. trackwright/core/__init__.py +1 -0
  8. trackwright/core/automation.py +410 -0
  9. trackwright/core/base.py +313 -0
  10. trackwright/core/commanding.py +300 -0
  11. trackwright/core/exporting.py +143 -0
  12. trackwright/core/importing.py +127 -0
  13. trackwright/core/lifecycle.py +74 -0
  14. trackwright/core/models.py +467 -0
  15. trackwright/core/policy.py +58 -0
  16. trackwright/core/presets.py +88 -0
  17. trackwright/core/project.py +221 -0
  18. trackwright/core/ranges.py +355 -0
  19. trackwright/core/reading.py +229 -0
  20. trackwright/core/refs.py +88 -0
  21. trackwright/core/saving.py +72 -0
  22. trackwright/core/service.py +27 -0
  23. trackwright/core/settings.py +80 -0
  24. trackwright/core/writing.py +390 -0
  25. trackwright/coremidi.py +307 -0
  26. trackwright/cubase/Trackwright_Bridge.js +1130 -0
  27. trackwright/cubase/__init__.py +83 -0
  28. trackwright/doctor.py +69 -0
  29. trackwright/errors.py +120 -0
  30. trackwright/exports.py +54 -0
  31. trackwright/fake.py +1112 -0
  32. trackwright/host.py +238 -0
  33. trackwright/hostport.py +74 -0
  34. trackwright/installer.py +305 -0
  35. trackwright/launcher.py +150 -0
  36. trackwright/logs.py +50 -0
  37. trackwright/ops.py +46 -0
  38. trackwright/protocol.py +182 -0
  39. trackwright/py.typed +0 -0
  40. trackwright/server.py +472 -0
  41. trackwright/transport.py +130 -0
  42. trackwright-0.3.0.dist-info/METADATA +190 -0
  43. trackwright-0.3.0.dist-info/RECORD +46 -0
  44. trackwright-0.3.0.dist-info/WHEEL +4 -0
  45. trackwright-0.3.0.dist-info/entry_points.txt +3 -0
  46. trackwright-0.3.0.dist-info/licenses/LICENSE +661 -0
@@ -0,0 +1,190 @@
1
+ Metadata-Version: 2.4
2
+ Name: trackwright
3
+ Version: 0.3.0
4
+ Summary: Independent MCP server for controlling digital audio workstations (DAWs). First implementation: Cubase, through a MIDI Remote script
5
+ Keywords: mcp,daw,cubase,midi-remote,audio,podcast,claude,copilot
6
+ Author: impalah
7
+ Author-email: impalah <impalah@gmail.com>
8
+ License-Expression: AGPL-3.0-or-later
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: End Users/Desktop
13
+ Classifier: Operating System :: MacOS :: MacOS X
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Topic :: Multimedia :: Sound/Audio
17
+ Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
18
+ Classifier: Typing :: Typed
19
+ Requires-Dist: loguru>=0.8.0
20
+ Requires-Dist: mcp>=2.3.0
21
+ Requires-Dist: pydantic>=2.14.3
22
+ Requires-Python: >=3.14
23
+ Project-URL: Author, https://pressanykey.tech
24
+ Description-Content-Type: text/markdown
25
+
26
+ # Trackwright
27
+
28
+ **English** · Español: `README.es.md` in the source repository
29
+
30
+ [![PyPI version](https://badge.fury.io/py/trackwright.svg)](https://pypi.org/project/trackwright/)
31
+ [![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
32
+ [![License: AGPL v3+](https://img.shields.io/badge/License-AGPL%20v3%2B-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
33
+ ![Coverage 98%](https://img.shields.io/badge/coverage-98%25-brightgreen.svg)
34
+ ![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)
35
+ ![DAW: Cubase 15.0.20+](https://img.shields.io/badge/DAW-Cubase%2015.0.20+-red.svg)
36
+ [![MCP](https://img.shields.io/badge/MCP-server-8A2BE2.svg)](https://modelcontextprotocol.io)
37
+
38
+ **Trackwright** is an independent [MCP](https://modelcontextprotocol.io) server for controlling digital audio workstations (DAWs).
39
+
40
+ It lets an AI assistant (Claude, GitHub Copilot or any other MCP client) **inspect and control your DAW**: tracks, mixing, plugins and their parameters, transport, markers, automation and time-range editing designed for podcasts.
41
+
42
+ The first implementation supports **Cubase**. It works through a MIDI Remote script that runs inside Cubase and needs no hardware controllers or IAC ports. Other DAWs may follow: much of the core (MIDI transport, bridge, write policy, verification by reading back) does not depend on Cubase.
43
+
44
+ | | |
45
+ |---|---|
46
+ | Package | `trackwright` |
47
+ | Executable | `trackwright` |
48
+ | MCP server | `trackwright` (stdio) |
49
+ | MCP clients | Any client that supports stdio servers. Tested with Claude Code |
50
+ | Platform | macOS. Verified on macOS 27.2 (Apple Silicon) |
51
+ | DAW | Cubase 15.0.20 or later (MIDI Remote API 1.3). Verified on Cubase Elements 15.0.30 |
52
+ | License | AGPL-3.0-or-later |
53
+
54
+ > Trackwright is an independent project. It is not affiliated with or endorsed by Steinberg; Cubase is a trademark of Steinberg Media Technologies GmbH.
55
+
56
+ ## Requirements
57
+
58
+ - **[uv](https://docs.astral.sh/uv/)** 0.13 or later (`brew install uv`). You don't need to install Python: uv downloads the right one. There is nothing to compile.
59
+ - **Cubase** 15.0.20 or later.
60
+ - An MCP client: **Claude Code** (tested), Claude Desktop, **GitHub Copilot** in VS Code or any other client that supports stdio servers.
61
+
62
+ ## Installation
63
+
64
+ ```sh
65
+ uv tool install trackwright
66
+ trackwright setup
67
+ ```
68
+
69
+ If the terminal can't find `trackwright`, run `uv tool update-shell` and open a new terminal.
70
+
71
+ `trackwright setup` is a guided installation. At each step it **shows what it is going to do and asks** before applying it (the default answer is "no"):
72
+
73
+ 1. copies the `Trackwright_Bridge.js` script into the Cubase MIDI Remote folder (`~/Documents/Steinberg/Cubase/MIDI Remote/Driver Scripts/Local/trackwright/bridge/`);
74
+ 2. creates `~/.config/trackwright/config.toml` if it doesn't exist, asking whether writes and project saving are allowed (default: no);
75
+ 3. registers the server in Claude Code (`claude mcp add --scope user trackwright …`) or, if it can't find `claude`, shows you the command;
76
+ 4. checks everything with `trackwright doctor`.
77
+
78
+ It never uses `sudo` and never changes Cubase or system settings. To skip the question for a step: `--yes script`, `--yes config` or `--yes claude`.
79
+
80
+ ### Activate the script in Cubase
81
+
82
+ 1. **Restart Cubase** (it doesn't reload scripts on its own) and open a project. For the first tests, a throwaway one is best.
83
+ 2. The **Trackwright – Bridge** surface should appear in the **MIDI Remote** tab of the lower zone. Trackwright creates the virtual ports when it starts, and your MCP client starts the MCP server. If the surface doesn't appear, click **+ Add MIDI Controller Surface** and choose `Trackwright` / `Bridge`, with input `Trackwright To Cubase` and output `Trackwright From Cubase`.
84
+ 3. **Recommended:** in *Studio > Studio Setup > MIDI Port Setup*, uncheck **"In 'All MIDI Inputs'"** for `Trackwright To Cubase`.
85
+
86
+ ### Check
87
+
88
+ ```sh
89
+ trackwright doctor # checks every link and tells you what to do if something fails
90
+ ```
91
+
92
+ Then, in your MCP client (for example, Claude Code): "Check the Cubase status with Trackwright".
93
+
94
+ ### Try it without Cubase
95
+
96
+ Trackwright includes a simulated Cubase. To try it from Claude Code without installing anything else:
97
+
98
+ ```sh
99
+ claude mcp add trackwright-sim -- uvx trackwright serve --simulate
100
+ ```
101
+
102
+ ### Other MCP clients
103
+
104
+ `trackwright setup` registers the server in Claude Code. Any other MCP client needs the same command: `trackwright serve` over stdio. Desktop apps don't inherit your terminal's `PATH`, so use the absolute path shown by `which trackwright`.
105
+
106
+ **GitHub Copilot in VS Code** (not tested yet): run **MCP: Open User Configuration** and add:
107
+
108
+ ```json
109
+ {
110
+ "servers": {
111
+ "trackwright": {
112
+ "type": "stdio",
113
+ "command": "/Users/<you>/.local/bin/trackwright",
114
+ "args": ["serve"]
115
+ }
116
+ }
117
+ }
118
+ ```
119
+
120
+ Then use Copilot Chat in agent mode. The Trackwright tools appear in its tool list.
121
+
122
+ ## Update and uninstall
123
+
124
+ - **Update:** `uv tool upgrade trackwright` and then `trackwright setup`, which updates the script if it changed. Restart Cubase.
125
+ - **Uninstall:**
126
+ 1. `claude mcp remove trackwright -s user`;
127
+ 2. `pkill -f "trackwright bridge"`;
128
+ 3. `uv tool uninstall trackwright`;
129
+ 4. delete `~/Documents/Steinberg/Cubase/MIDI Remote/Driver Scripts/Local/trackwright/` and `~/.config/trackwright/`, and remove the surface in the Cubase MIDI Remote tab.
130
+
131
+ ## What it can do (Cubase)
132
+
133
+ 32 tools, all with structured output:
134
+
135
+ - **Reading:** status, mixer tracks, selected channel, inserts, plugin catalog, parameters, transport and recent changes.
136
+ - **Writing**, always with a dry run (`dry_run`) and verification by reading back: parameters (as normalized values or in real units), plugin insertion, volume, mute, solo, record arm, track name and tempo.
137
+ - **Navigation:** select tracks and move the cursor and the locators.
138
+ - **Automation:** records volume, pan, send, channel EQ, pre-filter and plugin parameter curves by playing the project, with values in real units (dB, Hz) converted by Cubase. Verified on Cubase Elements.
139
+ - **Podcast editing:** delete, cut or insert silence over a range in seconds, on all tracks or on one, with verification of the result.
140
+ - **Project settings:** read time signature, cycle, metronome, count-in, punch…; change cycle, metronome, count-in, punch, pre-roll and post-roll, and click level.
141
+ - **Plugin presets:** next or previous, verified by the change in parameters. The preset name is not available through the API.
142
+ - **Save the project:** only on request, with its own permission (`[writes] save`), dry run and verification by the file's timestamp.
143
+ - **Import audio:** on the given track and position, with the Cubase file picker, and verification by the edges of the new event.
144
+ - **Export the mix:** of a range or of the whole project, with the Cubase dialog, and confirmation of the created file.
145
+ - **Cubase commands:** markers, track deletion, splitting at the locators, track creation with the user's help, and a list of allowed commands. Each command states how it behaves: whether it acts directly, opens a dialog or asks for confirmation.
146
+
147
+ By default it **only reads**. Writes are enabled in the configuration and can be limited to specific tracks.
148
+
149
+ ## Security
150
+
151
+ - **Read-only by default.** Writes are enabled in `~/.config/trackwright/config.toml` (`[writes] enabled = true`) and can be limited to specific tracks (`allowed_tracks`). Saving the project has its own permission (`[writes] save`).
152
+ - Every write supports a **dry run** (`dry_run`) and is **verified by reading back** the state. A write whose result is uncertain is not retried.
153
+ - **It opens no network ports:** the server talks to the MCP client over stdio and to the bridge over a private Unix socket.
154
+ - It doesn't close Cubase, doesn't record audio and doesn't save anything unless asked.
155
+
156
+ ## Configuration
157
+
158
+ ```toml
159
+ # ~/.config/trackwright/config.toml
160
+ [writes]
161
+ enabled = true # allow changes to the open project
162
+ save = false # allow saving the project on request
163
+ # allowed_tracks = ["Voice"] # limit writes to these tracks
164
+
165
+ [cubase]
166
+ app = "Cubase 15" # application name for cubase_launch
167
+ ```
168
+
169
+ `trackwright config` shows the effective configuration.
170
+
171
+ ## Known limitations
172
+
173
+ - **Not possible through the API:** changing routing (inputs, outputs or sends), reading track contents (events, audio or automation) or completing Cubase dialogs.
174
+ - **Only tracks with a mixer channel are visible.**
175
+ - Importing audio, exporting the mix and changing presets use Cubase dialogs or windows: Trackwright opens and prepares them, and you complete the dialog.
176
+ - For now, **macOS only** and **Cubase only**.
177
+
178
+ ## Status
179
+
180
+ Alpha version. Every tool has been run against Cubase Elements 15.0.30 on macOS 27.2, with visual confirmation where the API cannot observe the result. It also has unit tests, MCP contract tests, script tests with Node.js and end-to-end tests, with 98 % coverage.
181
+
182
+ ## Documentation
183
+
184
+ Manuals and tutorials, in English with Spanish translations in `*.es.md` files, are in the `docs/` folder of the source code (index in `docs/README.md`; Spanish in `docs/README.es.md`).
185
+
186
+ ## License
187
+
188
+ Copyright (C) 2026 impalah.
189
+
190
+ This program is free software: you can redistribute it and/or modify it under the terms of the **GNU Affero General Public License** as published by the Free Software Foundation, either version 3 or, at your option, any later version (`AGPL-3.0-or-later`). It is distributed without any warranty. See the `LICENSE` file.
@@ -0,0 +1,46 @@
1
+ trackwright/__init__.py,sha256=txxZh23-qTvV3oHa0253mj2LAjGzwEdBCSsjXM4eoVk,431
2
+ trackwright/__main__.py,sha256=4bif22fLmux72Oy_X8H1B-zfL-3YPIlJmQthassP8Kg,143
3
+ trackwright/bridge.py,sha256=NZSkAMSG1c6wwQ2XSRCiMSd5UQO-RpL0ugnWPfOHOXc,13459
4
+ trackwright/cli.py,sha256=Xe5xywwKvqXNO6Euv2dbOGQMp1Z4iSgPI-xo8vlWXeY,8839
5
+ trackwright/commands.py,sha256=CuKjWjbdVlv9OTKFEL_6ZHo8Cb8NkA701V9Iyvilaw0,12708
6
+ trackwright/config.py,sha256=rj8qMBIOC_ZlTHKrnDDdyJCZhQnWYAtrNJeEYp_4x90,6638
7
+ trackwright/core/__init__.py,sha256=yXNUDZQxEg1Kn9s7vF_TB3tQT3OlWegO0FoL2ciGCG4,89
8
+ trackwright/core/automation.py,sha256=_CxbrtkFTqswetPZXHkoyj9jDlYD-MP3MqA5aSRoJ44,19463
9
+ trackwright/core/base.py,sha256=vK6RXyFBoPeFLuv7sBt17RBRNLX2RaknfnYnpY714y8,12444
10
+ trackwright/core/commanding.py,sha256=dv8Y8xOwKV8YLHVJq1qc0Li5GKuqkJ1sGa35HfGAKE0,13592
11
+ trackwright/core/exporting.py,sha256=hy571GcOrdWxIBEImJ4PVm3gL38LsfHa9jQ4CDPAMH0,7432
12
+ trackwright/core/importing.py,sha256=m0UIAqNGUcKG4Flqn9-NHkLArCO4mQAqbwi9ETNkB4s,6302
13
+ trackwright/core/lifecycle.py,sha256=Hl8JgXLfrfGE2N4wA-Ag86Nhj4T17xnFper6E4JyyJk,3429
14
+ trackwright/core/models.py,sha256=gmuwjSMhAkeltz9XBf5Vu-TXoZt2ab1_DsVKZuBxKFc,15290
15
+ trackwright/core/policy.py,sha256=U55xP_mTX6KZDgyG_Q8ngQgCwnylyt60bYBmbVkhCs4,2397
16
+ trackwright/core/presets.py,sha256=VhGXQqfv5BIR79neup436E-v8AhYdIL5ztKjB9ba7qA,4367
17
+ trackwright/core/project.py,sha256=8IOYzZWfTUklY1NpXKTW9o7qXuy0kUBbsL-iFVccrEY,10132
18
+ trackwright/core/ranges.py,sha256=NSle3E7zejMO8lTKDNXfD0yjn8lCUNAw-iUFE13uWp0,17267
19
+ trackwright/core/reading.py,sha256=lCqKClJESE8XVLY1i1omtqTa6Ca2iBCTIZJ5yRfZpjg,9229
20
+ trackwright/core/refs.py,sha256=keASk949epsWFuCxp3DG6WiP0H4uJ_Pta0sNXZL4UME,3503
21
+ trackwright/core/saving.py,sha256=h6WS16K6f1KAAkXy5oNJiAEAn1uNjniNcHUuK7VH7pw,3332
22
+ trackwright/core/service.py,sha256=2j360zG83FchF5dBhYwxE1uPOP9ibWaUnRzK1G8glpo,909
23
+ trackwright/core/settings.py,sha256=csd2dErVTNEc197SJULqq7WJwETJfxSVUZ3MQxr4DFw,4037
24
+ trackwright/core/writing.py,sha256=qlM9XedEZ-TEJJb6Kvx1f8Lp6bJLdR-OEb_e9O-25Fg,18346
25
+ trackwright/coremidi.py,sha256=x6mJWlowAOaufqdHSIo6y2l1Nl0LGodcAZ2gKJ3cpr8,13376
26
+ trackwright/cubase/Trackwright_Bridge.js,sha256=UCQHqyPs_hARpCufBbd0kSlqTCYme5a0oTNALBR2Kmk,47783
27
+ trackwright/cubase/__init__.py,sha256=ovMhBVVcNzUuysVZ5A_5anrVtqy113MrL5SNeJO4juk,3225
28
+ trackwright/doctor.py,sha256=pTeDps25QMn_w9kuXdEAoda4yItWn_T5QPbYoBpWHZE,2724
29
+ trackwright/errors.py,sha256=-ofQeIPkeAplV2lXrMxG_jZGzRE3GG6wmhWEx2TOeXg,3865
30
+ trackwright/exports.py,sha256=_VQq-fojCwvCtMFZIBvgTNqNM4_gzbH5QWxD9D8h8Og,2102
31
+ trackwright/fake.py,sha256=-mSa6mIjcjgCckwn73oggyBz3rvefabv0Fylbt7OedM,51356
32
+ trackwright/host.py,sha256=l4KSBQIcEl77PC8Ot2-hrSmmQLDstXi6mDlnMMfwHIo,9735
33
+ trackwright/hostport.py,sha256=fxSBcDrDdOaBWG3bCsT6CsqyzdGFZyyCqUlgURqJwfQ,2587
34
+ trackwright/installer.py,sha256=VamRsl2Koh0Eprc7vGOcaCTEKw9XzrvJNWCPSfKlndY,14167
35
+ trackwright/launcher.py,sha256=R0ZY13lvsuE9Gpv2ytl_6uC9n6KfGN3bKlJE9DEwr9o,5717
36
+ trackwright/logs.py,sha256=gl1oBFxp6imNt-YunyTzwfEkr8__kMOOvP8OGMUlgok,2080
37
+ trackwright/ops.py,sha256=T2KGHvHUIT_X-hFqFeX5bmmMoWzPEttekxgZD5Kx96E,1218
38
+ trackwright/protocol.py,sha256=Ie_HCe5KV0zVSbG9Rap17XMiG77H7TLYexOXYISrT0s,6711
39
+ trackwright/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
40
+ trackwright/server.py,sha256=JE8IyECDYlQPP7QOwnFw6Bn-a3Whv2hm5NmcB6X8fYI,25064
41
+ trackwright/transport.py,sha256=uU1mU2tD20UohIR-jP0wm5vbLG1_SYA8tC2vzsEnYBw,4565
42
+ trackwright-0.3.0.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
43
+ trackwright-0.3.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
44
+ trackwright-0.3.0.dist-info/entry_points.txt,sha256=8ZNBQzbsIBqp5G_n6qJA1TuAMyLEXcTRUGsCTxf38T0,54
45
+ trackwright-0.3.0.dist-info/METADATA,sha256=Iv_--0t1Sv0tPIp3skeppraPRMDFezGFLpsglT52CdA,10553
46
+ trackwright-0.3.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.13.7
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ trackwright = trackwright.cli:main
3
+