trackwright 0.3.0__py3-none-any.whl

trackwright/core/base.py

@@ -0,0 +1,313 @@
+"""Shared machinery of the Cubase service: session, references, track and target resolution."""
+
+from __future__ import annotations
+
+import functools
+import re
+import threading
+import time
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Concatenate, Protocol, TypeVar
+
+from trackwright.core.models import ParameterInfo, TrackInfo, Value
+from trackwright.core.policy import WritePolicy
+from trackwright.core.refs import ObjectRef, TrackSelector
+from trackwright.errors import (
+    HostError,
+    NotFoundError,
+    PreconditionFailedError,
+    StaleSessionError,
+    TrackwrightError,
+)
+from trackwright.exports import ExportedFile, ExportInspector
+from trackwright.hostport import HostPort
+from trackwright.ops import WRITE_OPS
+
+JsonObject = dict[str, Any]
+T = TypeVar("T")
+
+
+class ExportFinder(Protocol):
+    def find(self, folder: Path, since: float, suffixes: frozenset[str] = ...) -> list[ExportedFile]: ...
+
+    def duration(self, path: Path) -> float | None: ...
+
+
+class AppLauncher(Protocol):
+    """Opens Cubase (:class:`trackwright.launcher.CubaseLauncher`, or a fake in tests)."""
+
+    @property
+    def app(self) -> str: ...
+
+    @property
+    def launch_timeout(self) -> float: ...
+
+    def is_running(self) -> bool: ...
+
+    def launch(self, project: Path | None = None) -> None: ...
+
+    def project_folders(self) -> list[str]: ...
+
+
+MIXER: JsonObject = {"scope": "mixer"}
+CHANNEL_TAGS = (1024, 4000, 1025, 1027, 1028, 4101, 4102)
+TAG_NAME, TAG_SELECTED, TAG_VOLUME, TAG_MUTE, TAG_SOLO, TAG_RECORD, TAG_INPUT, TAG_OUTPUT = (
+    1024,
+    4000,
+    1025,
+    1027,
+    1028,
+    4002,
+    4101,
+    4102,
+)
+_SLOT_SUFFIX = re.compile(r"-\d+$")
+
+
+_INACTIVE = object()
+
+
+def operation[S: "ServiceBase", **P, R](fn: Callable[Concatenate[S, P], R]) -> Callable[Concatenate[S, P], R]:
+    """Mark a public tool method: the script session is pinned for its whole duration.
+
+    Object ids are only meaningful inside one script session. A tool gathers ids over several
+    calls; if Cubase reloads the script in between, the bridge renegotiates transparently and a
+    later write could carry an id that now names another object. Pinning makes the tool stop with
+    ``STALE_SESSION`` before any further write.
+    """
+
+    def wrapper(self: S, /, *args: P.args, **kwargs: P.kwargs) -> R:
+        with self.pinned_session():
+            return fn(self, *args, **kwargs)
+
+    functools.update_wrapper(wrapper, fn)
+    return wrapper
+
+
+class ServiceBase:
+    """Base of :class:`trackwright.core.service.CubaseService`; tool groups are mixins on top of it."""
+
+    def __init__(
+        self,
+        host: HostPort,
+        policy: WritePolicy,
+        *,
+        sleep: Callable[[float], None] = time.sleep,
+        settle_timeout: float = 1.0,
+        launcher: AppLauncher | None = None,
+        exports: ExportFinder | None = None,
+    ) -> None:
+        self.host = host
+        self.launcher = launcher
+        self.exports: ExportFinder = exports if exports is not None else ExportInspector()
+        self.policy = policy
+        self._sleep = sleep
+        self._settle_timeout = settle_timeout
+        self._local = threading.local()
+
+    # ------------------------------------------------------------------ host access
+    @contextmanager
+    def pinned_session(self) -> Iterator[None]:
+        """Pin the session for the current thread (nested uses keep the outer pin)."""
+        if getattr(self._local, "session", _INACTIVE) is not _INACTIVE:
+            yield
+            return
+        self._local.session = None
+        try:
+            yield
+        finally:
+            self._local.session = _INACTIVE
+
+    def call(self, op: str, params: JsonObject | None = None) -> JsonObject:
+        pinned = getattr(self._local, "session", _INACTIVE)
+        if op in WRITE_OPS and pinned not in (_INACTIVE, None) and self.host.session_id != pinned:
+            raise self._session_changed(op)
+        result = self.host.call(op, params)
+        if pinned is not _INACTIVE:
+            current = self.host.session_id
+            if pinned is None:
+                self._local.session = current
+            elif current != pinned:
+                raise self._session_changed(op)
+        return result
+
+    @staticmethod
+    def _session_changed(op: str) -> StaleSessionError:
+        return StaleSessionError(
+            "Cubase reloaded the script during this operation; it was stopped before any further write. "
+            "Run the tool again.",
+            details={"op": op},
+        )
+
+    def session(self) -> str:
+        if self.host.session_id is None:
+            self.call("hello")
+        session = self.host.session_id
+        if session is None:
+            raise TrackwrightError("the Cubase script did not report a session", code="NO_SESSION")
+        return session
+
+    def wait_until(self, read: Callable[[], T], done: Callable[[T], bool]) -> T:
+        """Re-read until ``done`` or the settle timeout (values that arrive through callbacks lag a little)."""
+        deadline = time.monotonic() + self._settle_timeout
+        value = read()
+        while not done(value) and time.monotonic() < deadline:
+            self._sleep(0.1)
+            value = read()
+        return value
+
+    # ------------------------------------------------------------------ references
+    def ref_for(self, described: JsonObject) -> str:
+        return ObjectRef(
+            self.session(), int(described["id"]), str(described["type"]), str(described["uniqueName"])
+        ).encode()
+
+    # ------------------------------------------------------------------ tracks
+    def channels(self) -> list[JsonObject]:
+        """Every mixer channel, deduplicated by id (the mixer's last child is a duplicate)."""
+        items: list[JsonObject] = []
+        offset = 0
+        while True:
+            page = self.call("da.channels", {"offset": offset, "limit": 32, "tags": list(CHANNEL_TAGS), **MIXER})
+            items.extend(page.get("items", []))
+            indexes = [i["index"] for i in page.get("items", [])] + [d["index"] for d in page.get("duplicates", [])]
+            if not indexes:
+                break
+            offset = max(indexes) + 1
+            if offset >= int(page.get("total", 0)):
+                break
+        unique: dict[int, JsonObject] = {}
+        for item in items:
+            unique.setdefault(int(item["id"]), item)
+        return list(unique.values())
+
+    def track_info(self, item: JsonObject) -> TrackInfo:
+        values: JsonObject = item.get("values") or {}
+
+        def value(tag: int) -> JsonObject | None:
+            v = values.get(str(tag))
+            return v if isinstance(v, dict) else None
+
+        def flag(tag: int) -> bool | None:
+            v = value(tag)
+            return None if v is None else float(v.get("process") or 0) >= 0.5
+
+        def text(tag: int) -> str | None:
+            v = value(tag)
+            return None if v is None else str(v.get("display"))
+
+        volume = value(TAG_VOLUME)
+        return TrackInfo(
+            track=f"uid:{item['uid']}",
+            uid=str(item["uid"]),
+            name=text(TAG_NAME) or str(item.get("title", "")),
+            type=str(item.get("type", "")),
+            ref=self.ref_for(item),
+            mixer_index=item.get("mixerIndex"),
+            selected=bool(flag(TAG_SELECTED)),
+            volume=Value(process=volume.get("process"), display=volume.get("display")) if volume else None,
+            mute=flag(TAG_MUTE),
+            solo=flag(TAG_SOLO),
+            input=text(TAG_INPUT),
+            output=text(TAG_OUTPUT),
+        )
+
+    def resolve_track(self, selector: TrackSelector) -> JsonObject:
+        """Return the mixer item of the designated track (with ``values``)."""
+        channels = self.channels()
+        if selector.kind == "selected":
+            base = int(self.call("da.base").get("base", -1))
+            if base < 0:
+                raise NotFoundError(
+                    "no track with a mixer channel is selected (marker and folder tracks have none)",
+                    code="NO_SELECTION",
+                )
+            matches = [c for c in channels if c["id"] == base]
+        elif selector.kind == "uid":
+            matches = [c for c in channels if c.get("uid") == selector.value]
+        else:
+            matches = [c for c in channels if self.track_info(c).name == selector.value]
+        if not matches:
+            raise NotFoundError(
+                f"track {selector} not found",
+                code="TRACK_NOT_FOUND",
+                details={"available": [self.track_info(c).name for c in channels]},
+            )
+        if len(matches) > 1:
+            raise PreconditionFailedError(
+                f"{len(matches)} tracks are called {selector.value!r}; use the uid selector",
+                code="TRACK_AMBIGUOUS",
+                details={"candidates": [f"uid:{m['uid']}" for m in matches]},
+            )
+        return matches[0]
+
+    # ------------------------------------------------------------------ targets inside a track
+    def children(self, object_id: int) -> list[JsonObject]:
+        items: list[JsonObject] = []
+        while True:
+            page = self.call("da.children", {"id": object_id, "offset": len(items), "limit": 50, **MIXER})
+            items.extend(page.get("items", []))
+            if not page.get("items") or len(items) >= int(page.get("total", 0)):
+                return items
+
+    def section(self, track: JsonObject, kind: str) -> JsonObject:
+        for child in self.children(int(track["id"])):
+            if child.get("type") == kind:
+                return child
+        raise NotFoundError(f"the track has no {kind} section", details={"track": track.get("title")})
+
+    def insert_slot(self, track: JsonObject, slot: int) -> JsonObject:
+        slots = self.children(int(self.section(track, "Inserts")["id"]))
+        if not 1 <= slot <= len(slots):
+            raise NotFoundError(f"insert slot {slot} does not exist (1..{len(slots)})", code="SLOT_NOT_FOUND")
+        return slots[slot - 1]
+
+    def resolve_target(self, track: JsonObject, target: str) -> JsonObject:
+        """``channel`` | ``insert:N`` (the plugin in slot N) | ``strip:eq``."""
+        spec = target.strip().lower()
+        if spec == "channel":
+            return track
+        if spec.startswith("insert:") and spec[7:].isdigit():
+            slot = self.insert_slot(track, int(spec[7:]))
+            if not slot.get("children"):
+                raise PreconditionFailedError(f"insert slot {spec[7:]} is empty", code="EMPTY_SLOT")
+            return self.children(int(slot["id"]))[0]
+        if spec == "strip:eq":
+            for strip_slot in self.children(int(self.section(track, "Strips")["id"])):
+                for child in self.children(int(strip_slot["id"])) if strip_slot.get("children") else []:
+                    if child.get("type") == "EQ":
+                        return child
+            raise NotFoundError("the channel strip has no EQ module", code="EQ_NOT_FOUND")
+        raise NotFoundError(f"unknown target {target!r}: use 'channel', 'insert:N' or 'strip:eq'", code="BAD_TARGET")
+
+    # ------------------------------------------------------------------ parameters
+    @staticmethod
+    def parameter_info(raw: JsonObject) -> ParameterInfo:
+        return ParameterInfo(
+            tag=int(raw["tag"]),
+            title=str(raw.get("title", "")),
+            process=raw.get("process"),
+            display=raw.get("display"),
+            units=raw.get("units"),
+            plain=raw.get("plain"),
+            value_type=raw.get("valueType"),
+            automatable=raw.get("automatable"),
+            edit_locked=raw.get("editLock"),
+        )
+
+    def read_parameter(self, object_id: int, tag: int) -> JsonObject:
+        raw = self.call("da.param.get", {"id": object_id, "tag": tag, **MIXER})
+        if not raw.get("title") and raw.get("process") == -1:
+            raise NotFoundError(f"parameter {tag} does not exist on this object", code="PARAM_NOT_FOUND")
+        return raw
+
+    @staticmethod
+    def plugin_uid(unique_name: str) -> str:
+        """The plugin's type UID: its unique name without the ``-N`` instance suffix."""
+        return _SLOT_SUFFIX.sub("", unique_name)
+
+    @staticmethod
+    def is_host_code(exc: TrackwrightError, code: str) -> bool:
+        return isinstance(exc, HostError) and exc.code == code

trackwright/core/commanding.py

@@ -0,0 +1,300 @@
+"""Tools built on Cubase commands (epic E07).
+
+Commands give no result back. The tools therefore:
+- check ``canPerform`` first (it depends on context);
+- report the observed class of the command (``direct``, ``dialog``, ``confirm``, ``ui_selection``,
+  ``unknown``) and never report a ``dialog`` command as done;
+- verify the effect by reading state when it is observable, or say ``not_observable``.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from trackwright.commands import COMMANDS, CommandSpec
+from trackwright.core.base import JsonObject, ServiceBase, operation
+from trackwright.core.models import CommandOut, CommandStatus
+from trackwright.core.refs import TrackSelector
+from trackwright.core.writing import bars_tuple, format_bars
+from trackwright.errors import NotFoundError, PreconditionFailedError
+
+TRACK_KINDS = {"audio": "addtrack.audio", "group": "addtrack.group", "folder": "addtrack.folder"}
+MARKER_ACTIONS = {
+    "add_marker_track": "addtrack.marker",
+    "insert_at_cursor": "marker.insert",
+    "locate_prev": "transport.locate_prev_marker",
+    "locate_next": "transport.locate_next_marker",
+}
+NAVIGATION_COMMANDS = frozenset(
+    {
+        "transport.locate_prev_marker",
+        "transport.locate_next_marker",
+        "project.select_track_next",
+        "project.select_track_prev",
+    }
+)
+
+
+class CommandingMixin(ServiceBase):
+    # ------------------------------------------------------------------ core
+    def _spec(self, key: str) -> CommandSpec:
+        spec = COMMANDS.get(key)
+        if spec is None:
+            raise NotFoundError(
+                f"unknown command {key!r}", code="COMMAND_NOT_FOUND", details={"known": sorted(COMMANDS)}
+            )
+        return spec
+
+    def _can_perform(self, key: str) -> bool | None:
+        value = self.call("cmd.canPerform", {"key": key}).get("canPerform", {}).get(key)
+        return value if isinstance(value, bool) else None
+
+    def _out(
+        self,
+        spec: CommandSpec,
+        *,
+        dry_run: bool,
+        can: bool | None,
+        status: CommandStatus,
+        verified: bool | Literal["not_observable"] | None,
+        instructions: str | None = None,
+        details: dict[str, str | int | float | bool | None] | None = None,
+    ) -> CommandOut:
+        return CommandOut(
+            dry_run=dry_run,
+            key=spec.key,
+            category=spec.category,
+            name=spec.name,
+            command_class=spec.command_class,
+            can_perform=can,
+            status=status,
+            verified=verified,
+            instructions=instructions,
+            details=details or {},
+        )
+
+    def _fire(self, spec: CommandSpec, *, force: bool = False) -> None:
+        params: JsonObject = {"key": spec.key}
+        if force:
+            params["force"] = True
+        self.call("cmd.run", params)
+
+    def _status_for(self, spec: CommandSpec) -> tuple[CommandStatus, str | None]:
+        if spec.command_class == "dialog":
+            return "awaiting_user", f"Cubase opened a dialog for '{spec.name}': ask the user to complete or cancel it"
+        if spec.command_class == "confirm":
+            return "fired", "Cubase may ask the user to confirm"
+        if spec.command_class == "ui_selection":
+            return "fired", "acts on the selection in the Cubase window, which Trackwright cannot see: ask the user"
+        return "fired", None
+
+    @operation
+    def run_command(self, key: str, *, dry_run: bool = True, force: bool = False) -> CommandOut:
+        spec = self._spec(key)
+        can = self._can_perform(key)
+        if can is False and not force:
+            raise PreconditionFailedError(
+                f"Cubase reports that '{spec.name}' cannot be performed now", code="CANNOT_PERFORM"
+            )
+        if dry_run:
+            return self._out(spec, dry_run=True, can=can, status="planned", verified=None)
+        if key not in NAVIGATION_COMMANDS:
+            self.policy.check_project_write()
+        self._fire(spec, force=force)
+        status, instructions = self._status_for(spec)
+        return self._out(
+            spec, dry_run=False, can=can, status=status, verified="not_observable", instructions=instructions
+        )
+
+    # ------------------------------------------------------------------ markers
+    @operation
+    def markers(self, action: str, *, dry_run: bool = True) -> CommandOut:
+        key = MARKER_ACTIONS.get(action)
+        if key is None:
+            raise PreconditionFailedError(f"action must be one of {sorted(MARKER_ACTIONS)}", code="BAD_REQUEST")
+        spec = self._spec(key)
+        can = self._can_perform(key)
+        if can is False:
+            raise PreconditionFailedError(
+                f"Cubase reports that '{spec.name}' cannot be performed now", code="CANNOT_PERFORM"
+            )
+        if dry_run:
+            return self._out(spec, dry_run=True, can=can, status="planned", verified=None)
+        if key not in NAVIGATION_COMMANDS:
+            self.policy.check_project_write()
+        before = self._cursor()
+        self._fire(spec)
+        if key in NAVIGATION_COMMANDS:
+            after = self._cursor()
+            return self._out(
+                spec,
+                dry_run=False,
+                can=can,
+                status="done",
+                verified=after is not None,
+                details={"cursor_before": before, "cursor_after": after},
+            )
+        return self._out(
+            spec,
+            dry_run=False,
+            can=can,
+            status="done",
+            verified="not_observable",
+            instructions="marker tracks are not visible through the API: check in Cubase",
+            details={"cursor": before},
+        )
+
+    def _cursor(self) -> str | None:
+        raw = (self.call("transport.get").get("primary") or {}).get("locator")
+        return str(raw["time"]) if isinstance(raw, dict) else None
+
+    # ------------------------------------------------------------------ removing tracks
+    @operation
+    def remove_selected_tracks(self, expect_selected: str, *, dry_run: bool = True) -> CommandOut:
+        spec = self._spec("project.remove_selected_tracks")
+        expected = self.resolve_track(TrackSelector.parse(expect_selected))
+        base = int(self.call("da.base").get("base", -1))
+        # "Remove Selected Tracks" removes *every* selected track: require exactly one, the expected one.
+        selected = [self.track_info(c).name for c in self.channels() if self.track_info(c).selected]
+        if base != expected["id"] or selected != [self.track_info(expected).name]:
+            raise PreconditionFailedError(
+                "the selection must be exactly the expected track; select it alone first (cubase_select_track)",
+                code="SELECTION_MISMATCH",
+                details={"expected": self.track_info(expected).name, "selected": selected},
+            )
+        name = self.track_info(expected).name
+        can = self._can_perform(spec.key)
+        if dry_run:
+            return self._out(spec, dry_run=True, can=can, status="planned", verified=None, details={"track": name})
+        self.policy.check_track(name)
+        self._fire(spec)
+        listing = self.wait_until(
+            lambda: {"ids": [c["id"] for c in self.channels()]}, lambda d: expected["id"] not in d["ids"]
+        )
+        if expected["id"] in listing["ids"]:
+            return self._out(
+                spec,
+                dry_run=False,
+                can=can,
+                status="pending_confirmation",
+                verified=False,
+                instructions="Cubase is asking for confirmation (the track has events): ask the user",
+                details={"track": name},
+            )
+        return self._out(spec, dry_run=False, can=can, status="done", verified=True, details={"track": name})
+
+    # ------------------------------------------------------------------ split at locators
+    @operation
+    def split_at_locators(self, left: str, right: str, *, dry_run: bool = True) -> CommandOut:
+        spec = self._spec("edit.split_loop")
+        left_pos, right_pos = bars_tuple(left), bars_tuple(right)
+        if left_pos is None or right_pos is None:
+            raise PreconditionFailedError("locators look like '2. 1. 1. 0'", code="BAD_TIME")
+        if left_pos >= right_pos:
+            raise PreconditionFailedError("the left locator must be before the right one", code="BAD_TIME")
+        previous = dict(self.call("transport.get").get("primary") or {})
+        details: dict[str, str | int | float | bool | None] = {
+            "left": format_bars(left_pos),
+            "right": format_bars(right_pos),
+            # The locators are left at the split points: restoring them right away could race with the
+            # command, which Cubase runs in its own idle tick. Report them so they can be restored.
+            "previous_left": (previous.get("cycleLeft") or {}).get("time"),
+            "previous_right": (previous.get("cycleRight") or {}).get("time"),
+            "warning": "splits every track with events crossing the locators; the locators stay at the split points",
+        }
+        if dry_run:
+            return self._out(
+                spec, dry_run=True, can=self._can_perform(spec.key), status="planned", verified=None, details=details
+            )
+        self.policy.check_project_write()
+        for which, text in (("cycleLeft", format_bars(left_pos)), ("cycleRight", format_bars(right_pos))):
+            self.call("transport.setTime", {"which": which, "display": "primary", "time": text})
+        locators = self.wait_until(
+            lambda: dict(self.call("transport.get").get("primary") or {}),
+            lambda p: (
+                bars_tuple(str((p.get("cycleLeft") or {}).get("time", ""))) == left_pos
+                and bars_tuple(str((p.get("cycleRight") or {}).get("time", ""))) == right_pos
+            ),
+        )
+        if (
+            bars_tuple(str((locators.get("cycleLeft") or {}).get("time", ""))) != left_pos
+            or bars_tuple(str((locators.get("cycleRight") or {}).get("time", ""))) != right_pos
+        ):
+            raise PreconditionFailedError("the locators could not be set; nothing was split", code="VERIFY_FAILED")
+        can = self._can_perform(spec.key)
+        if can is False:
+            raise PreconditionFailedError(
+                "Cubase reports that 'Split Loop' cannot be performed now", code="CANNOT_PERFORM"
+            )
+        self._fire(spec)
+        return self._out(
+            spec,
+            dry_run=False,
+            can=can,
+            status="done",
+            verified="not_observable",
+            instructions="events are not visible through the API: check the result in Cubase",
+            details=details,
+        )
+
+    # ------------------------------------------------------------------ add a track with the user's help
+    @operation
+    def add_track_interactive(self, phase: Literal["start", "confirm"], kind: str, suggested_name: str) -> CommandOut:
+        key = TRACK_KINDS.get(kind)
+        if key is None:
+            raise PreconditionFailedError(f"kind must be one of {sorted(TRACK_KINDS)}", code="BAD_REQUEST")
+        spec = self._spec(key)
+        if phase == "start":
+            self.policy.check_project_write()
+            if any(self.track_info(c).name == suggested_name for c in self.channels()):
+                # Otherwise 'confirm' could report an old track as the new one.
+                raise PreconditionFailedError(
+                    f"a track called {suggested_name!r} already exists; suggest another name", code="NAME_CONFLICT"
+                )
+            can = self._can_perform(key)
+            if can is False:
+                raise PreconditionFailedError(
+                    f"Cubase reports that '{spec.name}' cannot be performed now", code="CANNOT_PERFORM"
+                )
+            self._fire(spec)
+            return self._out(
+                spec,
+                dry_run=False,
+                can=can,
+                status="awaiting_user",
+                verified=None,
+                instructions=f"In Cubase's Add Track dialog, name the track '{suggested_name}' and accept it "
+                f"(or cancel). Then call this tool again with phase='confirm'.",
+                details={"suggested_name": suggested_name},
+            )
+        if phase != "confirm":
+            raise PreconditionFailedError("phase must be 'start' or 'confirm'", code="BAD_REQUEST")
+        if kind == "folder":
+            return self._out(
+                spec,
+                dry_run=False,
+                can=None,
+                status="done",
+                verified="not_observable",
+                instructions="folder tracks have no mixer channel: confirm visually in Cubase",
+                details={"suggested_name": suggested_name},
+            )
+        found = [c for c in self.channels() if self.track_info(c).name == suggested_name]
+        if not found:
+            return self._out(
+                spec,
+                dry_run=False,
+                can=None,
+                status="not_found",
+                verified=False,
+                instructions="no new track with that name: the dialog may have been cancelled or the name changed",
+                details={"suggested_name": suggested_name},
+            )
+        return self._out(
+            spec,
+            dry_run=False,
+            can=None,
+            status="done",
+            verified=True,
+            details={"suggested_name": suggested_name, "track": f"uid:{found[0]['uid']}"},
+        )