trackwright 0.3.0__py3-none-any.whl

trackwright/core/models.py

@@ -0,0 +1,467 @@
+"""Structured outputs of the MCP tools (their JSON schemas are published to MCP clients)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from trackwright.commands import CommandClass
+
+
+class _Out(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+# ---------------------------------------------------------------------------- shared pieces
+class Value(_Out):
+    process: float | None = Field(description="normalized value as stored by Cubase")
+    display: str | None = Field(description="value as Cubase shows it (localized)")
+
+
+class TrackInfo(_Out):
+    track: str = Field(description='selector to reuse in other tools: "uid:<UID>" (stable across restarts)')
+    uid: str
+    name: str
+    type: str = Field(description="AudioChannel, Synth, GroupChannel, OutputChannel...")
+    ref: str = Field(description="opaque reference, valid only in the current script session")
+    mixer_index: int | None
+    selected: bool
+    volume: Value | None
+    mute: bool | None
+    solo: bool | None
+    input: str | None
+    output: str | None
+
+
+class ParameterInfo(_Out):
+    tag: int = Field(description="stable identifier of the parameter for a given plugin/channel")
+    title: str = Field(description="localized title")
+    process: float | None
+    display: str | None
+    units: str | None
+    plain: float | None = Field(description="value in real units (dB, Hz...) when the plugin provides it")
+    value_type: str | None
+    automatable: bool | None
+    edit_locked: bool | None
+
+
+class Change(_Out):
+    tag: int
+    title: str
+    before: Value
+    requested: float | str
+    after: Value | None
+    verified: bool | None
+
+
+# ---------------------------------------------------------------------------- read tools
+class StatusOut(_Out):
+    connected: bool
+    simulated: bool = Field(description="true when answering from the built-in simulator, not Cubase")
+    session: str | None
+    script_version: str | None
+    host_app: str | None
+    host_version: str | None
+    insert_slots: int | None
+    mixer_access: bool
+    transport_access: bool
+    commands_bound: int | None
+    writes_enabled: bool
+    allowed_tracks: list[str]
+
+
+class TrackListOut(_Out):
+    total: int
+    tracks: list[TrackInfo]
+    note: str = "tracks without a mixer channel (marker, folder) are not listed"
+
+
+class Section(_Out):
+    kind: str = Field(description="Inserts, Strips, Sends, Panner...")
+    title: str
+    ref: str
+
+
+class SelectedChannelOut(_Out):
+    track: TrackInfo | None = Field(description="null when the selected track has no mixer channel or none is selected")
+    sections: list[Section]
+
+
+class PluginInSlot(_Out):
+    name: str
+    plugin_uid: str
+    ref: str
+
+
+class SlotInfo(_Out):
+    index: int
+    empty: bool
+    ref: str
+    plugin: PluginInSlot | None
+
+
+class InsertsOut(_Out):
+    track: TrackInfo
+    slots: list[SlotInfo]
+
+
+class PluginEntry(_Out):
+    name: str
+    vendor: str
+    version: str
+    uid: str
+    sub_categories: str
+
+
+class PluginCatalogOut(_Out):
+    collection: str | None
+    total: int
+    matched: int
+    offset: int
+    items: list[PluginEntry]
+
+
+class ParametersOut(_Out):
+    target: str
+    target_ref: str
+    target_name: str
+    total: int
+    offset: int
+    scanned: int
+    items: list[ParameterInfo]
+    next_offset: int = Field(description="offset to pass to get the following parameters")
+    truncated: bool = Field(description="true when more parameters remain after next_offset")
+
+
+class ParameterOut(_Out):
+    target: str
+    target_ref: str
+    target_name: str
+    parameter: ParameterInfo
+
+
+class TimePosition(_Out):
+    time: str
+    format: str | None
+
+
+class TransportOut(_Out):
+    cursor: TimePosition
+    cycle_left: TimePosition | None
+    cycle_right: TimePosition | None
+    tempo_bpm: float | None
+
+
+class ChangeEvent(_Out):
+    kind: str
+    tag: int | None
+    ref: str | None
+    title: str | None
+    still_valid: bool | None = Field(description="null when the object was not checked (see unchecked)")
+
+
+class ChangesOut(_Out):
+    events: list[ChangeEvent]
+    dropped: int
+    unchecked: int = Field(description="events whose object was not looked up (only the first 20 objects are)")
+    advice: str
+
+
+# ---------------------------------------------------------------------------- write tools
+class WriteOut(_Out):
+    dry_run: bool
+    target: str
+    changes: list[Change]
+    verified: bool | None = Field(description="all changes read back as requested (null in dry runs)")
+    note: str | None = None
+
+
+class InsertPluginOut(_Out):
+    dry_run: bool
+    track: str
+    slot: int
+    plugin_uid: str
+    plugin_name: str
+    inserted: bool | None
+    verified: bool | None
+    plugin_ref: str | None
+
+
+class SelectOut(_Out):
+    selected_before: str | None
+    selected_after: str | None
+    verified: bool
+
+
+class PositionOut(_Out):
+    dry_run: bool
+    which: str
+    requested: str
+    before: TimePosition | None
+    after: TimePosition | None
+    verified: bool | None
+    note: str | None = None
+
+
+class TempoOut(_Out):
+    dry_run: bool
+    before: float | None
+    requested: float
+    after: float | None
+    verified: bool | None
+
+
+CommandStatus = Literal["planned", "fired", "awaiting_user", "pending_confirmation", "done", "not_found"]
+
+
+class CommandOut(_Out):
+    dry_run: bool
+    key: str
+    category: str
+    name: str
+    command_class: CommandClass
+    can_perform: bool | None
+    status: CommandStatus
+    verified: bool | Literal["not_observable"] | None
+    instructions: str | None = None
+    details: dict[str, str | int | float | bool | None] = Field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------- automation (TW-1207)
+class AutomationPoint(BaseModel):
+    """One point of an automation curve (input): give ``plain`` (real units) or ``value`` (normalized)."""
+
+    model_config = ConfigDict(extra="forbid")
+    position: str = Field(description="bar position, e.g. '9. 1. 1. 0' (bar. beat. 16th. tick); 4/4 assumed")
+    plain: float | None = Field(
+        default=None, description="value in real units (dB, Hz...), converted exactly by Cubase. Preferred."
+    )
+    value: float | None = Field(default=None, ge=0, le=1, description="normalized value 0..1 (use plain instead)")
+
+    @model_validator(mode="after")
+    def _one_value(self) -> AutomationPoint:
+        if (self.plain is None) == (self.value is None):
+            raise ValueError("give exactly one of plain or value")
+        return self
+
+
+class AutomationTarget(_Out):
+    parameter: str = Field(description="key to pass to cubase_record_automation, e.g. 'volume' or 'insert1.p1'")
+    title: str | None = Field(description="the Cubase parameter bound to it, e.g. 'Compressor / Threshold'")
+    value: float | None
+    display: str | None = Field(description="current value as Cubase shows it, in real units (dB, Hz, L/R...)")
+    available: bool = Field(description="false when nothing is bound (empty insert slot, unassigned quick control)")
+    converts_units: bool = Field(description="plain values (real units) are accepted for this parameter")
+
+
+class AutomationTargetsOut(_Out):
+    track: str
+    targets: list[AutomationTarget]
+    note: str = "the track was selected: automation controls follow the selected track"
+
+
+class ResolvedPoint(_Out):
+    position: str
+    value: float = Field(description="normalized value written")
+    plain: float | None = Field(description="the value in real units, when given or converted")
+
+
+class ConvertOut(_Out):
+    track: str
+    parameter: str
+    title: str | None
+    plain: float
+    value: float = Field(description="normalized value 0..1")
+    note: str = "exact conversion by Cubase (convertParameterPlainToProcessValue / ProcessValueToPlain)"
+
+
+class WrittenPoint(_Out):
+    position: str
+    value: float
+    display: str | None
+
+
+class AutomationRecordOut(_Out):
+    dry_run: bool
+    track: str
+    parameter: str
+    title: str | None
+    value_before: float | None
+    display_before: str | None
+    start: str = Field(description="where playback starts (pre-roll before the first point)")
+    points: list[ResolvedPoint] = Field(description="the curve, with the normalized value used for each point")
+    written: list[WrittenPoint]
+    verified: bool | None = Field(description="a read-back pass followed the curve (null when not verified)")
+    mismatches: list[str] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------- lifecycle (TW-1201)
+class LaunchOut(_Out):
+    status: Literal["planned", "already_running", "running_without_script", "ready", "awaiting_user"]
+    app: str
+    dry_run: bool
+    process_running: bool
+    script_version: str | None
+    project: str | None
+    instructions: str | None = None
+
+
+# ---------------------------------------------------------------------------- project properties (TW-1209)
+class Signature(_Out):
+    text: str = Field(description="as Cubase shows it, e.g. '3/4'")
+    numerator: int | None
+    denominator: int | None
+
+
+class Span(_Out):
+    active: bool | None
+    start: str | None
+    end: str | None
+
+
+class Roll(_Out):
+    active: bool | None
+    length: str | None
+
+
+class Metronome(_Out):
+    active: bool | None
+    click_level: str | None
+    in_record: bool | None
+    in_playback: bool | None
+
+
+class ProjectOut(_Out):
+    tempo_bpm: float | None
+    signature: Signature | None = Field(description="time signature at the cursor (verified with 4/4 and 3/4)")
+    cycle: Span
+    punch_in: bool | None
+    punch_out: bool | None
+    punch_range: Span
+    pre_roll: Roll
+    post_roll: Roll
+    metronome: Metronome
+    precount: bool | None
+    transport: Literal["stopped", "playing", "recording", "unknown"]
+    time_formats: list[str | None] = Field(description="primary and secondary time displays")
+    modes: dict[str, str | None] = Field(description="record and playback modes, as Cubase shows them")
+    project_folders: list[str] | None = Field(
+        description="folders of the open project(s), deduced from the audio files Cubase has open; "
+        "null when not requested, empty when Cubase has no audio file open"
+    )
+    unavailable: dict[str, str] = Field(description="properties the Cubase API does not expose, and why")
+
+
+# ---------------------------------------------------------------------------- range editing (TW-1211)
+class RangeEditOut(_Out):
+    dry_run: bool
+    action: str
+    start: str = Field(description="h:mm:ss.mmm")
+    end: str
+    length_seconds: float
+    effect: str
+    scope: str
+    track: str | None = Field(default=None, description="the only track edited (single-track delete)")
+    verify_track: str | None = Field(description="track whose event edges were probed to verify")
+    applied: bool = False
+    locators: list[str] = Field(default_factory=list, description="the range as bars, while editing")
+    edges_before: list[str] = Field(default_factory=list, description="event edges (starts and ends) probed")
+    edges_after: list[str] = Field(default_factory=list)
+    undo_steps: int = Field(default=0, description="Undo steps that revert the edit in Cubase")
+    verified: bool | None = None
+    mismatches: list[str] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------- export (TW-1204)
+class ExportedFileOut(_Out):
+    path: str
+    size_bytes: int
+    duration_seconds: float | None
+    difference_seconds: float | None = Field(default=None, description="duration minus the expected one")
+    duration_matches: bool | None = Field(
+        description="the duration equals the range: ±0.15 s, or ±(0.5 s + 0.2 %) for MP3/AAC/OGG (estimated)"
+    )
+
+
+class ExportOut(_Out):
+    phase: Literal["start", "confirm"]
+    status: Literal["planned", "awaiting_user", "done", "not_found"]
+    dry_run: bool
+    start: str | None = Field(description="range start (h:mm:ss.mmm)")
+    end: str | None
+    expected_seconds: float | None
+    folder: str | None = Field(description="where Cubase proposes to export (<project folder>/Mixdown)")
+    since: float | None = Field(description="pass it back to the confirm phase")
+    files: list[ExportedFileOut] = Field(default_factory=list)
+    verified: bool | None = None
+    instructions: str | None = None
+    notes: list[str] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------- save (TW-1202)
+class ProjectFileOut(_Out):
+    name: str
+    size_bytes: int
+    modified: str = Field(description="local time, YYYY-MM-DD HH:MM:SS")
+
+
+class SaveOut(_Out):
+    mode: Literal["save", "new_version"]
+    dry_run: bool
+    status: Literal["planned", "saved", "awaiting_user"]
+    folder: str | None = Field(description="project folder (deduced from the audio files Cubase has open)")
+    files_before: list[ProjectFileOut] = Field(default_factory=list, description=".cpr files, newest first")
+    saved: ProjectFileOut | None = Field(default=None, description="the .cpr written by this save")
+    verified: bool | None = None
+    instructions: str | None = None
+    notes: list[str] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------- import (TW-1203)
+class ImportOut(_Out):
+    phase: Literal["start", "confirm"]
+    status: Literal["planned", "awaiting_user", "done", "not_found"]
+    dry_run: bool
+    track: str
+    position: str = Field(description="where the audio goes (h:mm:ss.mmm)")
+    file: str | None = Field(description="the file to pick in the dialog, when given")
+    expected_seconds: float | None = Field(description="duration of that file (afinfo)")
+    since: float | None = Field(description="pass it back to the confirm phase")
+    edges_found: list[str] = Field(default_factory=list, description="event edges at the start and end")
+    copied_to_project: list[str] = Field(default_factory=list, description="new files in <project>/Audio")
+    verified: bool | None = None
+    instructions: str | None = None
+    notes: list[str] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------- project settings (TW-1210)
+class SettingChange(_Out):
+    setting: str
+    before: bool | int | None
+    requested: bool | int
+    after: bool | int | None
+    verified: bool | None
+
+
+class ProjectSettingsOut(_Out):
+    dry_run: bool
+    changes: list[SettingChange]
+    verified: bool | None
+    notes: list[str] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------- plugin presets (TW-1205)
+class PresetStepOut(_Out):
+    dry_run: bool
+    track: str
+    slot: int
+    plugin: str
+    direction: Literal["next", "previous"]
+    status: Literal["planned", "done", "awaiting_user"] = "planned"
+    changed: dict[str, str] = Field(default_factory=dict, description="parameter: 'before -> after'")
+    instructions: str | None = None
+    verified: bool | None = Field(description="some parameter changed (the preset was applied)")
+    notes: list[str] = Field(default_factory=list)

trackwright/core/policy.py

@@ -0,0 +1,58 @@
+"""Write policy: what the MCP server may change, configured by the user.
+
+- ``[writes] enabled = false`` (default): every project modification fails with ``WRITES_DISABLED``.
+  Dry runs always work, and so does *navigation* (selecting a track, moving the cursor), which
+  does not modify the project.
+- ``allowed_tracks``: when not empty, only those track names may be modified (``NOT_ALLOWED``).
+- ``save``: saving the project file needs its own switch (``SAVE_DISABLED``), on top of ``enabled``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from trackwright.config import WritesConfig
+from trackwright.errors import PolicyError
+
+
+@dataclass(frozen=True, slots=True)
+class WritePolicy:
+    enabled: bool = False
+    allowed_tracks: tuple[str, ...] = ()
+    save: bool = False
+
+    @classmethod
+    def from_config(cls, config: WritesConfig) -> WritePolicy:
+        return cls(enabled=config.enabled, allowed_tracks=config.allowed_tracks, save=config.save)
+
+    def check_save(self) -> None:
+        """Raise unless saving the project file is allowed."""
+        self.check_project_write()
+        if not self.save:
+            raise PolicyError(
+                "saving is disabled; set [writes] save = true in the Trackwright configuration "
+                "(dry runs work without it)",
+                code="SAVE_DISABLED",
+            )
+
+    def check_project_write(self) -> None:
+        """Raise unless project modifications are enabled."""
+        if not self.enabled:
+            raise PolicyError(
+                "writes are disabled; set [writes] enabled = true in the Trackwright configuration "
+                "(dry runs work without it)",
+                code="WRITES_DISABLED",
+            )
+
+    def check_track(self, track_name: str | None) -> None:
+        """Raise unless writes are enabled and ``track_name`` may be modified."""
+        self.check_project_write()
+        if self.allowed_tracks and track_name not in self.allowed_tracks:
+            raise PolicyError(
+                f"track {track_name!r} is not in [writes] allowed_tracks",
+                code="NOT_ALLOWED",
+                details={"track": track_name, "allowed_tracks": list(self.allowed_tracks)},
+            )
+
+    def describe(self) -> dict[str, object]:
+        return {"writes_enabled": self.enabled, "allowed_tracks": list(self.allowed_tracks), "save": self.save}

trackwright/core/presets.py

@@ -0,0 +1,88 @@
+"""Step through a plugin's presets (TW-1205).
+
+Verified in Cubase Elements 15.0.30 (experiments/tw1205): the slot's "Edición" parameter opens the plugin
+editor; ``Preset / Next`` and ``Previous`` act on that editor only once the user has clicked on its window
+(keyboard focus), and from then on also after closing and reopening it through the API; they do nothing
+when the editor is closed or no preset is loaded. The result is checked by comparing the plugin's
+parameters. Presets cannot be chosen or read by name.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from trackwright.core.base import MIXER, ServiceBase, operation
+from trackwright.core.models import PresetStepOut
+from trackwright.core.refs import TrackSelector
+from trackwright.errors import PreconditionFailedError
+
+JsonObject = dict[str, Any]
+TAG_EDIT = 4101
+METERS = ("Vu", "Gain Red", "Max", "Gain Reduction", " PH", "Meter")
+KEYS = {"next": "preset.next", "previous": "preset.previous"}
+EDITOR_SETTLE_SECONDS = 1.0
+
+
+class PresetMixin(ServiceBase):
+    def _plugin_values(self, plugin: int) -> dict[str, tuple[float, str]]:
+        values: dict[str, tuple[float, str]] = {}
+        offset = 0
+        while True:
+            page = self.call("da.params", {"id": plugin, "offset": offset, "limit": 25, **MIXER})
+            for param in page.get("items", []):
+                title = str(param.get("title"))
+                if title and not any(m in title for m in METERS):
+                    values[title] = (float(param.get("process") or 0), str(param.get("display")))
+            offset += len(page.get("items", []))
+            if not page.get("items") or offset >= int(page.get("total", 0)):
+                return values
+
+    def _editor_open(self, slot: int) -> bool:
+        return float(self.call("da.param.get", {"id": slot, "tag": TAG_EDIT, **MIXER}).get("process") or 0) >= 0.5
+
+    def _set_editor(self, slot: int, open_: bool) -> None:
+        self.call("da.param.set", {"id": slot, "tag": TAG_EDIT, "value": 1.0 if open_ else 0.0, **MIXER})
+        self.wait_until(lambda: self._editor_open(slot), open_.__eq__)
+
+    @operation
+    def plugin_preset(
+        self, track: str, slot: int, direction: Literal["next", "previous"], *, dry_run: bool = True
+    ) -> PresetStepOut:
+        if direction not in KEYS:
+            raise PreconditionFailedError("direction must be 'next' or 'previous'", code="BAD_REQUEST")
+        item = self.resolve_track(TrackSelector.parse(track))
+        name = self.track_info(item).name
+        slot_obj = self.insert_slot(item, slot)
+        plugin = self.resolve_target(item, f"insert:{slot}")
+        out = PresetStepOut(dry_run=dry_run, track=name, slot=slot, plugin=str(plugin.get("title")),
+                            direction=direction, verified=None)  # fmt: skip
+        out.notes.append("the plugin's editor is opened for the command and closed again if it was closed")
+        if dry_run:
+            return out
+        self.policy.check_track(name)
+        slot_id, plugin_id = int(slot_obj["id"]), int(plugin["id"])
+        before = self._plugin_values(plugin_id)
+        was_open = self._editor_open(slot_id)
+        if not was_open:
+            self._set_editor(slot_id, True)
+            self._sleep(EDITOR_SETTLE_SECONDS)
+        self.call("cmd.run", {"key": KEYS[direction]})
+        after = self.wait_until(lambda: self._plugin_values(plugin_id), lambda now: now != before)
+        out.changed = {
+            t: f"{before[t][1]} -> {after[t][1]}" for t in before if t in after and after[t][0] != before[t][0]
+        }
+        out.verified = bool(out.changed)
+        if not out.changed:
+            out.status = "awaiting_user"  # the editor stays open so that the user can click on it
+            out.instructions = (
+                f"The {out.plugin} window is open in Cubase. Click once on an empty area of it (Cubase needs it to "
+                "have the keyboard focus; only the first time), make sure a preset is loaded in its preset bar, "
+                "then call this tool again."
+            )
+            return out
+        out.status = "done"
+        if not was_open:
+            self._set_editor(slot_id, False)
+        other = "previous" if direction == "next" else "next"
+        out.notes.append(f"the opposite step ('{other}') returns to the previous values")
+        return out