trackwright 0.3.0__py3-none-any.whl

trackwright/commands.py

@@ -0,0 +1,397 @@
+"""Cubase commands bound by the script, with the behaviour observed for each one.
+
+Commands give no result back: only ``canPerform`` (which depends on context) and whatever state
+can be read afterwards. Each command is classified by what was **observed** in the POC
+(phases 4 and 2b, Cubase Elements 15.0.30):
+
+- ``direct``: acts immediately without UI (verified).
+- ``dialog``: opens a Cubase dialog; the user must complete it (verified). Never report as done.
+- ``confirm``: may ask the user to confirm (verified when a removed track has events).
+- ``ui_selection``: acts on the GUI selection/focus, which the API cannot see; results are not
+  controllable from the script (verified: Paste went to another track than the one selected).
+- ``unknown``: bound and accepted by Cubase but its effect was not observed.
+
+The keys must match ``COMMANDS`` in ``cubase/Trackwright_Bridge.js`` (checked by a test).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+CommandClass = Literal["direct", "dialog", "confirm", "ui_selection", "unknown"]
+
+
+@dataclass(frozen=True, slots=True)
+class CommandSpec:
+    key: str
+    category: str
+    name: str
+    command_class: CommandClass
+    description: str
+    evidence: str
+
+
+_SPECS = [
+    CommandSpec(
+        "zoom.in",
+        "Zoom",
+        "Zoom In",
+        "unknown",
+        "Zoom in the focused window",
+        "fired, no visible effect (focus-dependent)",
+    ),
+    CommandSpec("zoom.out", "Zoom", "Zoom Out", "unknown", "Zoom out the focused window", "not observed"),
+    CommandSpec(
+        "edit.undo",
+        "Edit",
+        "Undo",
+        "ui_selection",
+        "Undo the last step",
+        "verified: one step per call; a paste may create two steps",
+    ),
+    CommandSpec("edit.redo", "Edit", "Redo", "ui_selection", "Redo the last undone step", "not observed"),
+    CommandSpec(
+        "addtrack.audio", "AddTrack", "Audio", "dialog", "Add an audio track", "verified: opens the Add Track dialog"
+    ),
+    CommandSpec(
+        "addtrack.marker",
+        "AddTrack",
+        "Marker",
+        "direct",
+        "Add a marker track",
+        "verified: created and selected directly",
+    ),
+    CommandSpec(
+        "addtrack.group",
+        "AddTrack",
+        "Group Channel",
+        "dialog",
+        "Add a group channel",
+        "verified: opens the Add Track dialog",
+    ),
+    CommandSpec(
+        "addtrack.folder", "AddTrack", "Folder", "dialog", "Add a folder track", "verified: opens the Add Track dialog"
+    ),
+    CommandSpec(
+        "project.remove_selected_tracks",
+        "Project",
+        "Remove Selected Tracks",
+        "confirm",
+        "Remove the selected tracks",
+        "verified: may ask for confirmation when the track has events, unless the user disabled that prompt",
+    ),
+    CommandSpec(
+        "project.selected_to_new_folder",
+        "Project",
+        "Folding: Tracks To Folder",
+        "unknown",
+        "Move the selected tracks into a new folder",
+        "not observed",
+    ),
+    CommandSpec(
+        "project.select_track_next", "Project", "Select Track: Next", "direct", "Select the next track", "verified"
+    ),
+    CommandSpec(
+        "project.select_track_prev", "Project", "Select Track: Prev", "direct", "Select the previous track", "verified"
+    ),
+    CommandSpec(
+        "transport.return_to_zero",
+        "Transport",
+        "Return to Zero",
+        "unknown",
+        "Move the cursor to the project start",
+        "not observed",
+    ),
+    CommandSpec(
+        "transport.locate_next_marker",
+        "Transport",
+        "Locate Next Marker",
+        "direct",
+        "Move the cursor to the next marker",
+        "verified; without a next marker it goes to the end of the last event (Cubase 15)",
+    ),
+    CommandSpec(
+        "transport.locate_prev_marker",
+        "Transport",
+        "Locate Previous Marker",
+        "direct",
+        "Move the cursor to the previous marker",
+        "verified; ignores the locators; goes to the project start without markers",
+    ),
+    CommandSpec(
+        "transport.set_left_locator",
+        "Transport",
+        "Set Left Locator",
+        "direct",
+        "Set the left locator at the cursor",
+        "verified: left locator at the cursor (TW-1211)",
+    ),
+    CommandSpec(
+        "transport.set_right_locator",
+        "Transport",
+        "Set Right Locator",
+        "direct",
+        "Set the right locator at the cursor",
+        "verified: right locator at the cursor (TW-1211)",
+    ),
+    CommandSpec(
+        "transport.locators_to_selection",
+        "Transport",
+        "Locators to Selection",
+        "unknown",
+        "Set the locators to the selection range",
+        "not observed",
+    ),
+    CommandSpec(
+        "marker.insert",
+        "Marker",
+        "Insert Marker",
+        "direct",
+        "Insert a marker at the cursor",
+        "verified (needs a marker track)",
+    ),
+    CommandSpec("edit.cut", "Edit", "Cut", "ui_selection", "Cut the selection", "not observed"),
+    CommandSpec(
+        "edit.copy", "Edit", "Copy", "ui_selection", "Copy the selection", "verified: acts on the GUI selection"
+    ),
+    CommandSpec(
+        "edit.paste",
+        "Edit",
+        "Paste",
+        "ui_selection",
+        "Paste at the cursor",
+        "verified: pasted into another track than the one selected through the API",
+    ),
+    CommandSpec("edit.delete", "Edit", "Delete", "ui_selection", "Delete the selection", "not observed"),
+    CommandSpec(
+        "edit.split_at_cursor",
+        "Edit",
+        "Split at Cursor",
+        "ui_selection",
+        "Split the selected events at the cursor",
+        "verified: split a MIDI part at the cursor",
+    ),
+    CommandSpec(
+        "edit.split_loop",
+        "Edit",
+        "Split Loop",
+        "direct",
+        "Split every event crossing the locators",
+        "verified: all tracks with events in the range",
+    ),
+    CommandSpec(
+        "edit.split_range", "Edit", "Split Range", "ui_selection", "Split at the range selection", "not observed"
+    ),
+    CommandSpec("edit.select_all", "Edit", "Select All", "ui_selection", "Select all events", "not observed"),
+    CommandSpec("edit.select_none", "Edit", "Select None", "ui_selection", "Clear the selection", "not observed"),
+    CommandSpec(
+        "edit.select_in_loop",
+        "Edit",
+        "Select in Loop",
+        "ui_selection",
+        "Select the range between the locators",
+        "verified: with the Range tool, a range between the locators on all tracks (TW-1211)",
+    ),
+    # TW-1211: range editing and event probing (experiments/tw1211)
+    CommandSpec("tool.range", "Tool", "Range Tool", "direct", "Activate the Range Selection tool", "not observed"),
+    CommandSpec("tool.select", "Tool", "Select Tool", "direct", "Activate the Object Selection tool", "not observed"),
+    CommandSpec(
+        "file.export_audio_mixdown",
+        "File",
+        "Export Audio Mixdown",
+        "dialog",
+        "Open the Export Audio Mixdown dialog",
+        "not observed (TW-1204)",
+    ),
+    CommandSpec("file.save", "File", "Save", "direct", "Save the project", "verified: rewrites the .cpr (TW-1202)"),
+    CommandSpec(
+        "file.save_new_version",
+        "File",
+        "Save New Version",
+        "unknown",
+        "Save the project as a new numbered version",
+        "not observed (TW-1202)",
+    ),
+    CommandSpec(
+        "file.import_audio",
+        "File",
+        "Import Audio File",
+        "dialog",
+        "Open the Import Audio File dialog",
+        "not observed (TW-1203)",
+    ),
+    CommandSpec(
+        "preset.next", "Preset", "Next", "unknown", "Next preset of the focused plugin", "not observed (TW-1205)"
+    ),
+    CommandSpec(
+        "preset.previous",
+        "Preset",
+        "Previous",
+        "unknown",
+        "Previous preset of the focused plugin",
+        "not observed (TW-1205)",
+    ),
+    CommandSpec(
+        "edit.delete_time",
+        "Edit",
+        "Delete Time",
+        "ui_selection",
+        "Delete the range and close the gap",
+        "verified: removes the range selection and closes the gap on every track in it (TW-1211)",
+    ),
+    CommandSpec(
+        "edit.cut_time",
+        "Edit",
+        "Cut Time",
+        "ui_selection",
+        "Cut the range and close the gap",
+        "verified: like Delete Time, also copies (TW-1211)",
+    ),
+    CommandSpec(
+        "edit.insert_silence",
+        "Edit",
+        "Insert Silence",
+        "ui_selection",
+        "Insert silence over the range",
+        "verified: inserts silence over the range, shifting later events (TW-1211)",
+    ),
+    CommandSpec(
+        "edit.crop_range",
+        "Edit",
+        "Crop Range",
+        "ui_selection",
+        "Keep only the range",
+        "verified: keeps only the range selection (TW-1211)",
+    ),
+    CommandSpec(
+        "process.silence",
+        "Process",
+        "Silence",
+        "dialog",
+        "Silence the selected audio",
+        "verified: asks about audio files shared by several events (TW-1211)",
+    ),
+    CommandSpec(
+        "edit.select_all_on_tracks",
+        "Edit",
+        "Select All on Tracks",
+        "ui_selection",
+        "Select all events of the selected tracks",
+        "verified: all events of the selected tracks (TW-1211)",
+    ),
+    CommandSpec(
+        "edit.select_events_under_cursor",
+        "Edit",
+        "Select Events under Cursor",
+        "unknown",
+        "Select the events under the cursor",
+        "not observed",
+    ),
+    CommandSpec(
+        "transport.locate_next_event",
+        "Transport",
+        "Locate Next Event",
+        "direct",
+        "Move the cursor to the next event edge",
+        "verified: next event edge (start or end) on the selected tracks (TW-1211)",
+    ),
+    CommandSpec(
+        "transport.locate_prev_event",
+        "Transport",
+        "Locate Previous Event",
+        "direct",
+        "Move the cursor to the previous event edge",
+        "not observed; mirror of Locate Next Event",
+    ),
+    CommandSpec(
+        "transport.locate_selection",
+        "Transport",
+        "Locate Selection",
+        "direct",
+        "Move the cursor to the selection start",
+        "verified: cursor to the selection start (TW-1211)",
+    ),
+    CommandSpec(
+        "transport.locate_selection_end",
+        "Transport",
+        "Locate Selection End",
+        "direct",
+        "Move the cursor to the selection end",
+        "verified: cursor to the selection end (TW-1211)",
+    ),
+    CommandSpec(
+        "transport.to_left_locator",
+        "Transport",
+        "To Left Locator",
+        "unknown",
+        "Move the cursor to the left locator",
+        "not observed",
+    ),
+    CommandSpec(
+        "audio.detect_silence",
+        "Audio",
+        "Detect Silence",
+        "dialog",
+        "Open Detect Silence for the selected audio event",
+        "verified: opens its dialog; needs a selected audio event",
+    ),
+    CommandSpec(
+        "automation.mode_touch",
+        "Automation",
+        "Automation Mode - Touch",
+        "unknown",
+        "Automation mode Touch: writes only while a control is touched",
+        "not observed (TW-1206)",
+    ),
+    CommandSpec(
+        "automation.mode_auto_latch",
+        "Automation",
+        "Automation Mode - Auto-Latch",
+        "unknown",
+        "Automation mode Auto-Latch: writing starts on any change and lasts until stop",
+        "not observed (TW-1206)",
+    ),
+    CommandSpec(
+        "automation.mode_cross_over",
+        "Automation",
+        "Automation Mode - Cross-Over",
+        "unknown",
+        "Automation mode Cross-Over: like Auto-Latch, stops when crossing existing automation",
+        "not observed (TW-1206)",
+    ),
+    CommandSpec(
+        "automation.next_mode",
+        "Automation",
+        "Next Automation Mode",
+        "unknown",
+        "Switch to the next automation mode",
+        "not observed (TW-1206)",
+    ),
+    CommandSpec(
+        "automation.toggle_write_selected",
+        "Automation",
+        "Toggle Write Enable Selected Tracks",
+        "unknown",
+        "Toggle automation write on the selected tracks",
+        "used by factory scripts; not observed",
+    ),
+    CommandSpec(
+        "transport.start",
+        "Transport",
+        "Start",
+        "direct",
+        "Start playback (never records)",
+        "verified: the cursor advances (2026-11-13)",
+    ),
+    CommandSpec(
+        "transport.stop",
+        "Transport",
+        "Stop",
+        "direct",
+        "Stop playback",
+        "verified: the cursor stops at once (2026-11-13)",
+    ),
+]
+
+COMMANDS: dict[str, CommandSpec] = {spec.key: spec for spec in _SPECS}

trackwright/config.py

@@ -0,0 +1,149 @@
+"""Configuration: TOML file + environment, validated with pydantic.
+
+Lookup order for the file:
+1. the path in ``TRACKWRIGHT_CONFIG`` (must exist);
+2. ``~/.config/trackwright/config.toml`` (optional).
+
+Defaults are safe: **writes are disabled** until ``[writes] enabled = true``.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import tomllib
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+from trackwright.errors import ConfigError
+
+CONFIG_ENV = "TRACKWRIGHT_CONFIG"
+DEFAULT_CONFIG_PATH = Path("~/.config/trackwright/config.toml")
+DEFAULT_SCRIPT_DIR = Path("~/Documents/Steinberg/Cubase/MIDI Remote/Driver Scripts/Local/trackwright/bridge")
+
+
+def default_socket_dir() -> Path:
+    """Private per-user directory under ``$TMPDIR`` (never inside the project: the data volume may be ``noowners``)."""
+    base = Path(os.environ.get("TMPDIR") or tempfile.gettempdir())
+    return base / f"trackwright-{os.getuid()}"
+
+
+class _Section(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class BridgeConfig(_Section):
+    to_cubase_port: str = Field(default="Trackwright To Cubase", min_length=1)
+    """Virtual port Python writes to; Cubase sees it as the script's MIDI input."""
+    from_cubase_port: str = Field(default="Trackwright From Cubase", min_length=1)
+    """Virtual port Python reads from; Cubase sees it as the script's MIDI output."""
+    socket_dir: Path = Field(default_factory=default_socket_dir, validate_default=True)
+    """Directory of the IPC Unix socket (created with mode 0700)."""
+    request_timeout: float = Field(default=3.0, ge=0.05, le=30.0)
+    """Default timeout in seconds for one request to Cubase."""
+    write_timeout: float = Field(default=5.0, ge=0.05, le=30.0)
+    """Timeout for write operations (they run in an idle tick and read back)."""
+    backend: Literal["auto", "coremidi", "rtmidi"] = "auto"
+    """MIDI transport: ``coremidi`` (ctypes, nothing to compile; macOS), ``rtmidi`` (mido + python-rtmidi,
+    which must be installed: see pyproject.toml) or ``auto`` (coremidi on macOS, rtmidi elsewhere)."""
+    autostart: bool = True
+    """``trackwright serve`` starts the bridge when it is not running (TW-1201)."""
+    autostart_timeout: float = Field(default=10.0, ge=0.5, le=60.0)
+    """Seconds to wait for an auto-started bridge to accept connections."""
+
+    @field_validator("socket_dir", mode="after")
+    @classmethod
+    def _expand(cls, value: Path) -> Path:
+        return value.expanduser()
+
+    @property
+    def socket_path(self) -> Path:
+        return self.socket_dir / "bridge.sock"
+
+
+class WritesConfig(_Section):
+    enabled: bool = False
+    """Master switch. While false every write tool fails with ``WRITES_DISABLED`` (dry runs still work)."""
+    allowed_tracks: tuple[str, ...] = ()
+    """Track names that may be modified. Empty means every track (when ``enabled``)."""
+    save: bool = False
+    """Allow cubase_save_project to save the project file on disk (TW-1202). Separate from ``enabled``."""
+
+
+class LoggingConfig(_Section):
+    level: Literal["TRACE", "DEBUG", "INFO", "SUCCESS", "WARNING", "ERROR", "CRITICAL"] = "INFO"
+    file: Path | None = None
+    """Optional log file (rotated at 10 MB, 5 files kept)."""
+
+    @field_validator("level", mode="before")
+    @classmethod
+    def _upper(cls, value: Any) -> Any:
+        return value.upper() if isinstance(value, str) else value
+
+    @field_validator("file", mode="after")
+    @classmethod
+    def _expand(cls, value: Path | None) -> Path | None:
+        return value.expanduser() if value is not None else None
+
+
+class ScriptConfig(_Section):
+    # validate_default: pydantic does not run validators on defaults otherwise, and "~" would stay literal.
+    install_dir: Path = Field(default=DEFAULT_SCRIPT_DIR, validate_default=True)
+    """Where ``trackwright script install`` copies the MIDI Remote script."""
+
+    @field_validator("install_dir", mode="after")
+    @classmethod
+    def _expand(cls, value: Path) -> Path:
+        return value.expanduser()
+
+
+class CubaseConfig(_Section):
+    app: str = Field(default="Cubase 15", min_length=1)
+    """Application name for ``open -a`` and process name for ``pgrep -x``."""
+    launch_timeout: float = Field(default=120.0, ge=5.0, le=600.0)
+    """Seconds cubase_launch waits for the script to answer after opening Cubase."""
+
+
+class Settings(_Section):
+    bridge: BridgeConfig = Field(default_factory=BridgeConfig)
+    writes: WritesConfig = Field(default_factory=WritesConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    script: ScriptConfig = Field(default_factory=ScriptConfig)
+    cubase: CubaseConfig = Field(default_factory=CubaseConfig)
+    source: Path | None = None
+    """File the settings were loaded from (``None`` = built-in defaults)."""
+
+
+def config_path(path: Path | None = None, *, environ: dict[str, str] | None = None) -> tuple[Path, bool]:
+    """The configuration file to use and whether it was given explicitly (argument or ``$TRACKWRIGHT_CONFIG``)."""
+    env = os.environ if environ is None else environ
+    explicit = path or (Path(env[CONFIG_ENV]) if env.get(CONFIG_ENV) else None)
+    return (explicit or DEFAULT_CONFIG_PATH).expanduser(), explicit is not None
+
+
+def load_settings(
+    path: Path | None = None, *, environ: dict[str, str] | None = None, missing_ok: bool = False
+) -> Settings:
+    """Load settings from ``path``, ``$TRACKWRIGHT_CONFIG`` or the default location.
+
+    A missing default file means built-in defaults; a missing explicit file is an error unless ``missing_ok``
+    (``trackwright setup`` is about to create it).
+    """
+    candidate, explicit = config_path(path, environ=environ)
+    if not candidate.exists():
+        if explicit and not missing_ok:
+            raise ConfigError(f"configuration file not found: {candidate}", details={"path": str(candidate)})
+        return Settings()
+    try:
+        raw = tomllib.loads(candidate.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"cannot read {candidate}: {exc}", details={"path": str(candidate)}) from exc
+    if "source" in raw:
+        raise ConfigError("'source' is not a configurable key", details={"path": str(candidate)})
+    try:
+        return Settings(**raw, source=candidate)
+    except ValidationError as exc:
+        errors = [{"loc": ".".join(str(p) for p in e["loc"]), "msg": e["msg"]} for e in exc.errors()]
+        raise ConfigError(f"invalid configuration in {candidate}", details={"errors": errors}) from exc

trackwright/core/__init__.py

@@ -0,0 +1 @@
+"""Domain layer of the MCP server: references, policy, models and the Cubase service."""