trackwright 0.3.0__py3-none-any.whl

trackwright/core/reading.py

@@ -0,0 +1,229 @@
+"""Read-only tools (epic E05). None of them modifies the project."""
+
+from __future__ import annotations
+
+from trackwright.core.base import MIXER, JsonObject, ServiceBase, operation
+from trackwright.core.models import (
+    ChangeEvent,
+    ChangesOut,
+    InsertsOut,
+    ParameterInfo,
+    ParameterOut,
+    ParametersOut,
+    PluginCatalogOut,
+    PluginEntry,
+    PluginInSlot,
+    Section,
+    SelectedChannelOut,
+    SlotInfo,
+    StatusOut,
+    TimePosition,
+    TrackListOut,
+    TransportOut,
+)
+from trackwright.core.refs import TrackSelector
+from trackwright.errors import NotFoundError, TrackwrightError
+
+MAX_FILTER_SCAN = 500
+MAX_EVENT_LOOKUPS = 20
+
+
+class ReadingMixin(ServiceBase):
+    @operation
+    def status(self) -> StatusOut:
+        hello = self.call("hello")
+        caps = self.call("capabilities")
+        capabilities: JsonObject = caps.get("capabilities") or {}
+        host: JsonObject = caps.get("host") or hello.get("host") or {}
+        return StatusOut(
+            connected=True,
+            simulated=bool(self.host.simulated or capabilities.get("simulated")),
+            session=self.host.session_id or hello.get("sessionId"),
+            script_version=hello.get("scriptVersion"),
+            host_app=host.get("appName"),
+            host_version=host.get("appVersion"),
+            insert_slots=host.get("insertSlots"),
+            mixer_access=bool(
+                capabilities.get("mixerDirectAccessActive", capabilities.get("mixerDirectAccessCreated"))
+            ),
+            transport_access=bool(capabilities.get("transportTimeDisplay")),
+            commands_bound=capabilities.get("commandsBound"),
+            writes_enabled=self.policy.enabled,
+            allowed_tracks=list(self.policy.allowed_tracks),
+        )
+
+    @operation
+    def list_tracks(self, offset: int = 0, limit: int = 32) -> TrackListOut:
+        channels = self.channels()
+        page = channels[offset : offset + limit]
+        return TrackListOut(total=len(channels), tracks=[self.track_info(c) for c in page])
+
+    @operation
+    def get_selected_channel(self) -> SelectedChannelOut:
+        base = self.call("da.base")
+        if int(base.get("base", -1)) < 0:
+            return SelectedChannelOut(track=None, sections=[])
+        track = self.resolve_track(TrackSelector("selected"))
+        sections = [
+            Section(kind=str(c.get("type")), title=str(c.get("title")), ref=self.ref_for(c))
+            for c in self.children(int(track["id"]))
+        ]
+        return SelectedChannelOut(track=self.track_info(track), sections=sections)
+
+    @operation
+    def list_inserts(self, track: str) -> InsertsOut:
+        item = self.resolve_track(TrackSelector.parse(track))
+        slots: list[SlotInfo] = []
+        for index, slot in enumerate(self.children(int(self.section(item, "Inserts")["id"])), start=1):
+            plugin = None
+            if slot.get("children"):
+                child = self.children(int(slot["id"]))[0]
+                plugin = PluginInSlot(
+                    name=str(child.get("title")),
+                    plugin_uid=self.plugin_uid(str(child.get("uniqueName"))),
+                    ref=self.ref_for(child),
+                )
+            slots.append(SlotInfo(index=index, empty=plugin is None, ref=self.ref_for(slot), plugin=plugin))
+        return InsertsOut(track=self.track_info(item), slots=slots)
+
+    @operation
+    def list_available_plugins(
+        self, track: str, slot: int = 1, filter_text: str | None = None, offset: int = 0, limit: int = 20
+    ) -> PluginCatalogOut:
+        slot_obj = self.insert_slot(self.resolve_track(TrackSelector.parse(track)), slot)
+        collections = self.call("pm.collections", {"slot": slot_obj["id"], **MIXER})
+        index = int(collections.get("activeIndex", -1))
+        if int(collections.get("total", 0)) == 0 or index < 0:
+            raise NotFoundError("this slot offers no plugin collection", code="NO_COLLECTION")
+        entries = self.call(
+            "pm.entries",
+            {
+                "slot": slot_obj["id"],
+                "collection": index,
+                "offset": offset,
+                "limit": min(limit, 40),
+                "filter": filter_text or "",
+                **MIXER,
+            },
+        )
+        items = [
+            PluginEntry(
+                name=str(e["name"]),
+                vendor=str(e["vendor"]),
+                version=str(e["version"]),
+                uid=str(e["uid"]),
+                sub_categories=str(e["subCategories"]),
+            )
+            for e in entries.get("items", [])
+        ]
+        return PluginCatalogOut(
+            collection=entries.get("collectionName"),
+            total=int(entries.get("total", 0)),
+            matched=int(entries.get("matched", 0)),
+            offset=offset,
+            items=items,
+        )
+
+    @operation
+    def list_parameters(
+        self, track: str, target: str, offset: int = 0, limit: int = 25, filter_text: str | None = None
+    ) -> ParametersOut:
+        obj = self.resolve_target(self.resolve_track(TrackSelector.parse(track)), target)
+        needle = (filter_text or "").lower()
+        items: list[ParameterInfo] = []
+        next_offset, scanned, total = offset, 0, 0
+        while len(items) < limit and scanned < MAX_FILTER_SCAN:
+            page_size = 25 if needle else min(25, limit - len(items))
+            page = self.call("da.params", {"id": obj["id"], "offset": next_offset, "limit": page_size, **MIXER})
+            total = int(page.get("total", 0))
+            batch = page.get("items", [])
+            if not batch:
+                break
+            for raw in batch:
+                # Consume parameter by parameter so that no match is skipped when the limit is reached.
+                next_offset = int(raw.get("index", next_offset)) + 1
+                scanned += 1
+                if needle in str(raw.get("title", "")).lower():
+                    items.append(self.parameter_info(raw))
+                    if len(items) >= limit:
+                        break
+            if next_offset >= total:
+                break
+        return ParametersOut(
+            target=target,
+            target_ref=self.ref_for(obj),
+            target_name=str(obj.get("title", "")),
+            total=total,
+            offset=offset,
+            scanned=scanned,
+            items=items,
+            next_offset=next_offset,
+            truncated=next_offset < total,
+        )
+
+    @operation
+    def get_parameter(self, track: str, target: str, tag: int) -> ParameterOut:
+        obj = self.resolve_target(self.resolve_track(TrackSelector.parse(track)), target)
+        raw = self.read_parameter(int(obj["id"]), tag)
+        return ParameterOut(
+            target=target,
+            target_ref=self.ref_for(obj),
+            target_name=str(obj.get("title", "")),
+            parameter=self.parameter_info(raw),
+        )
+
+    @operation
+    def get_transport(self) -> TransportOut:
+        data = self.call("transport.get")
+        primary: JsonObject = data.get("primary") or {}
+        if not data.get("available") or not primary.get("locator"):
+            raise TrackwrightError(
+                "transport values have not arrived yet; move the cursor once in Cubase and retry", code="UNAVAILABLE"
+            )
+
+        def position(key: str) -> TimePosition | None:
+            raw = primary.get(key)
+            return TimePosition(time=str(raw["time"]), format=raw.get("format")) if isinstance(raw, dict) else None
+
+        cursor = position("locator")
+        assert cursor is not None
+        return TransportOut(
+            cursor=cursor,
+            cycle_left=position("cycleLeft"),
+            cycle_right=position("cycleRight"),
+            tempo_bpm=data.get("tempoBPM"),
+        )
+
+    @operation
+    def poll_changes(self) -> ChangesOut:
+        data = self.call("events")
+        events: list[ChangeEvent] = []
+        described: dict[int, JsonObject | None] = {}
+        unchecked = 0
+        for raw in data.get("events", []):
+            oid = int(raw.get("id", -1))
+            if oid not in described and len(described) < MAX_EVENT_LOOKUPS:
+                try:
+                    described[oid] = self.call("da.object", {"id": oid, **MIXER})
+                except TrackwrightError:
+                    described[oid] = None
+            checked = oid in described
+            obj = described.get(oid)
+            unchecked += not checked
+            tag = int(raw.get("t", -1))
+            events.append(
+                ChangeEvent(
+                    kind=str(raw.get("k")),
+                    tag=tag if tag >= 0 else None,
+                    ref=self.ref_for(obj) if obj else None,
+                    title=obj.get("title") if obj else None,
+                    still_valid=(obj is not None) if checked else None,
+                )
+            )
+        dropped = int(data.get("dropped", 0))
+        advice = (
+            "events were dropped: re-list tracks and objects"
+            if dropped
+            else "a 'removed' event is a hint to re-validate, not proof of removal (it also fires on selection changes)"
+        )
+        return ChangesOut(events=events, dropped=dropped, unchecked=unchecked, advice=advice)

trackwright/core/refs.py

@@ -0,0 +1,88 @@
+"""Track selectors and opaque object references.
+
+Runtime object ids are only valid inside one script session and are **reused** for different
+objects after a reload (verified: id 550 went from Compressor to Input Filter). They are therefore
+never exposed alone: tools return an opaque ``ref`` that embeds the session and a fingerprint of
+the object, and validate both before every use.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from trackwright.errors import ProtocolError, StaleReferenceError
+
+REF_PREFIX = "tw1."
+SELECTED = "selected"
+
+
+@dataclass(frozen=True, slots=True)
+class TrackSelector:
+    """How a tool input designates a track.
+
+    Accepted forms: ``"selected"``; ``"uid:<UID>"`` (stable across Cubase restarts); ``"name:<exact name>"``;
+    or any other text, taken as an exact track name.
+    """
+
+    kind: Literal["selected", "uid", "name"]
+    value: str = ""
+
+    @classmethod
+    def parse(cls, text: str | None) -> TrackSelector:
+        raw = (text or SELECTED).strip()
+        if not raw or raw == SELECTED:
+            return cls("selected")
+        if raw.startswith("uid:") and raw[4:].strip():
+            return cls("uid", raw[4:].strip())
+        if raw.startswith("name:") and raw[5:]:
+            return cls("name", raw[5:])
+        return cls("name", raw)
+
+    def __str__(self) -> str:
+        return SELECTED if self.kind == "selected" else f"{self.kind}:{self.value}"
+
+
+@dataclass(frozen=True, slots=True)
+class ObjectRef:
+    """Opaque handle on a Cubase object: session + runtime id + fingerprint."""
+
+    session: str
+    object_id: int
+    type_name: str
+    unique_name: str
+
+    def encode(self) -> str:
+        payload = {"s": self.session, "i": self.object_id, "t": self.type_name, "u": self.unique_name}
+        raw = json.dumps(payload, separators=(",", ":"), ensure_ascii=True).encode()
+        return REF_PREFIX + base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+    @classmethod
+    def decode(cls, text: str) -> ObjectRef:
+        if not text.startswith(REF_PREFIX):
+            raise ProtocolError("not a Trackwright object reference", details={"ref": text[:40]})
+        body = text[len(REF_PREFIX) :]
+        try:
+            data: Any = json.loads(base64.urlsafe_b64decode(body + "=" * (-len(body) % 4)))
+            return cls(str(data["s"]), int(data["i"]), str(data["t"]), str(data["u"]))
+        except (ValueError, KeyError, TypeError) as exc:
+            raise ProtocolError("malformed object reference", details={"ref": text[:40]}) from exc
+
+    def check_session(self, current: str | None) -> None:
+        if current is None or current != self.session:
+            raise StaleReferenceError(
+                "the reference belongs to a previous Cubase script session; list the objects again",
+                details={"ref_session": self.session, "current_session": current},
+            )
+
+    def check_fingerprint(self, described: dict[str, Any]) -> None:
+        if described.get("type") != self.type_name or described.get("uniqueName") != self.unique_name:
+            raise StaleReferenceError(
+                "the reference now points at a different object; list the objects again",
+                details={
+                    "expected": {"type": self.type_name, "uniqueName": self.unique_name},
+                    "found": {"type": described.get("type"), "uniqueName": described.get("uniqueName")},
+                },
+            )

trackwright/core/saving.py

@@ -0,0 +1,72 @@
+"""Saving the project (TW-1202). Only on an explicit request: separate policy switch, dry run by default.
+
+Verified in Cubase Elements 15.0.30 (experiments/tw1202): ``File / Save`` rewrites the project's .cpr and
+``File / Save New Version`` writes ``<name>-01.cpr`` (and Cubase then works on it), both without a dialog
+in a project that was saved before. The result is checked by the .cpr files' dates; nothing is opened.
+Close, Revert and Quit are not offered.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Literal
+
+from trackwright.core.base import ServiceBase, operation
+from trackwright.core.models import ProjectFileOut, SaveOut
+from trackwright.exports import PROJECT_SUFFIXES, ExportedFile
+
+SAVE_KEYS = {"save": "file.save", "new_version": "file.save_new_version"}
+SAVE_WAIT_SECONDS = 10.0
+EFFECTS = {
+    "save": "overwrites the project file Cubase has open with the current state",
+    "new_version": "writes a new numbered project file (<name>-NN.cpr); Cubase then works on that file",
+}
+
+
+def _file(found: ExportedFile) -> ProjectFileOut:
+    return ProjectFileOut(name=Path(found.path).name, size_bytes=found.size_bytes,
+                          modified=time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(found.modified)))  # fmt: skip
+
+
+class SavingMixin(ServiceBase):
+    def _project_folder(self) -> Path | None:
+        folders = self.launcher.project_folders() if self.launcher is not None else []
+        return Path(folders[0]) if folders else None
+
+    def _project_files(self, folder: Path | None, since: float = 0.0) -> list[ExportedFile]:
+        return self.exports.find(folder, since, PROJECT_SUFFIXES) if folder else []
+
+    @operation
+    def save_project(self, mode: Literal["save", "new_version"] = "save", *, dry_run: bool = True) -> SaveOut:
+        folder = self._project_folder()
+        before = self._project_files(folder)
+        out = SaveOut(mode=mode, dry_run=dry_run, status="planned", folder=str(folder) if folder else None,
+                      files_before=[_file(f) for f in before], notes=[EFFECTS[mode]])  # fmt: skip
+        if folder is None:
+            out.notes.append("the project folder is unknown (no audio file open): the save cannot be verified")
+        if dry_run:
+            return out
+        self.policy.check_save()
+        started = time.time()
+        self.call("cmd.run", {"key": SAVE_KEYS[mode]})
+        if folder is None:
+            out.status = "saved"
+            return out
+        names_before = {Path(f.path).name for f in before}
+        deadline = time.monotonic() + SAVE_WAIT_SECONDS
+        while True:
+            written = [f for f in self._project_files(folder, started)
+                       if mode == "save" or Path(f.path).name not in names_before]  # fmt: skip
+            if written or time.monotonic() >= deadline:
+                break
+            self._sleep(0.5)
+        if written:
+            out.status, out.saved, out.verified = "saved", _file(written[0]), True
+        else:
+            out.status, out.verified = "awaiting_user", False
+            out.instructions = (
+                "no project file was written: Cubase may be showing a dialog (for example 'Save As' for a "
+                "project that was never saved). Answer it in Cubase."
+            )
+        return out

trackwright/core/service.py

@@ -0,0 +1,27 @@
+"""The Cubase service: every tool's logic, independent of MCP so it can be tested directly."""
+
+from __future__ import annotations
+
+from trackwright.core.automation import AutomationMixin
+from trackwright.core.commanding import CommandingMixin
+from trackwright.core.importing import ImportMixin
+from trackwright.core.lifecycle import LifecycleMixin
+from trackwright.core.presets import PresetMixin
+from trackwright.core.reading import ReadingMixin
+from trackwright.core.saving import SavingMixin
+from trackwright.core.settings import SettingsMixin
+from trackwright.core.writing import WritingMixin
+
+
+class CubaseService(
+    PresetMixin,
+    SettingsMixin,
+    SavingMixin,
+    ImportMixin,
+    LifecycleMixin,
+    AutomationMixin,
+    CommandingMixin,
+    WritingMixin,
+    ReadingMixin,
+):
+    """Every tool: read, write, commands, automation, launch, project, ranges, export, import and save (E05-E12)."""

trackwright/core/settings.py

@@ -0,0 +1,80 @@
+"""Change project and transport settings (TW-1210) through Cubase's Transport and Metronome objects.
+
+Verified in Cubase Elements 15.0.30 (experiments/tw1210): every switch below and the click level accept a
+DirectAccess write and read back; the time signature does not (its value is outside [0, 1]).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from trackwright.core.base import MIXER, operation
+from trackwright.core.models import ProjectSettingsOut, SettingChange
+from trackwright.core.project import ProjectMixin
+from trackwright.errors import NotFoundError, PreconditionFailedError
+
+JsonObject = dict[str, Any]
+SWITCHES: dict[str, tuple[str, str]] = {  # setting -> (object type, parameter title)
+    "cycle": ("Transport", "cycle"),
+    "metronome": ("Transport", "metronomeOn"),
+    "precount": ("Transport", "precountOn"),
+    "punch_in": ("Transport", "punchIn"),
+    "punch_out": ("Transport", "punchOut"),
+    "pre_roll": ("Transport", "usePreRoll"),
+    "post_roll": ("Transport", "usePostRoll"),
+    "click_in_playback": ("Metronome", "tickInPlayback"),
+    "click_in_record": ("Metronome", "tickInRecord"),
+}
+CLICK_LEVEL = ("Metronome", "clickLevel")
+
+
+class SettingsMixin(ProjectMixin):
+    @operation
+    def set_project(self, settings: dict[str, bool | int], *, dry_run: bool = True) -> ProjectSettingsOut:
+        if not settings:
+            raise PreconditionFailedError("give at least one setting to change", code="BAD_REQUEST")
+        unknown = sorted(set(settings) - set(SWITCHES) - {"click_level"})
+        if unknown:
+            raise PreconditionFailedError(f"unknown settings {unknown}", code="BAD_REQUEST",
+                                          details={"known": [*SWITCHES, "click_level"]})  # fmt: skip
+        level = settings.get("click_level")
+        if level is not None and (isinstance(level, bool) or not 0 <= int(level) <= 127):
+            raise PreconditionFailedError("click_level must be 0..127", code="OUT_OF_RANGE")
+        objects = self._studio_objects()
+        params = {kind: self._params_by_title(objects.get(kind)) for kind in ("Transport", "Metronome")}
+        plan: list[tuple[str, int, int, float, bool | int | None]] = []  # name, object, tag, value, before
+        for name, requested in settings.items():
+            kind, title = SWITCHES.get(name, CLICK_LEVEL)
+            param = params[kind].get(title)
+            if param is None or objects.get(kind) is None:
+                raise NotFoundError(f"Cubase does not expose {kind}/{title}", code="UNAVAILABLE")
+            value = int(requested) / 127 if name == "click_level" else (1.0 if requested else 0.0)
+            plan.append((name, int(objects[kind]), int(param["tag"]), value, self._setting_value(name, param)))
+        out = ProjectSettingsOut(
+            dry_run=dry_run,
+            changes=[
+                SettingChange(setting=n, before=b, requested=settings[n], after=None, verified=None)
+                for n, _o, _t, _v, b in plan
+            ],
+            verified=None,
+        )
+        if dry_run:
+            return out
+        self.policy.check_project_write()
+        for change, (name, oid, tag, value, _before) in zip(out.changes, plan, strict=True):
+            self.call("da.param.set", {"id": oid, "tag": tag, "value": value, **MIXER})
+            change.after = self._read_setting(name, oid, tag, change.requested)
+            change.verified = change.after == change.requested
+        out.verified = all(c.verified for c in out.changes)
+        return out
+
+    def _read_setting(self, name: str, oid: int, tag: int, wanted: bool | int) -> bool | int:
+        def read() -> bool | int:
+            return self._setting_value(name, self.call("da.param.get", {"id": oid, "tag": tag, **MIXER}))
+
+        return self.wait_until(read, wanted.__eq__)
+
+    @staticmethod
+    def _setting_value(name: str, param: JsonObject) -> bool | int:
+        process = float(param.get("process") or 0)
+        return round(process * 127) if name == "click_level" else process >= 0.5