trackwright 0.3.0__py3-none-any.whl

trackwright/core/exporting.py

@@ -0,0 +1,143 @@
+"""Export the mix (TW-1204), with the user: Trackwright sets the range and opens Cubase's dialog, the user
+chooses the format and exports, and the confirm phase finds the file and checks its duration.
+
+Verified in Cubase Elements 15.0.30 (experiments/tw1204): the dialog has no range field and exports between
+the locators; Select All + Locators to Selection put them around all the audio; it proposes
+``<project folder>/Mixdown`` and the project name.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Literal
+
+from trackwright.core.base import operation
+from trackwright.core.models import ExportedFileOut, ExportOut
+from trackwright.core.project import format_seconds
+from trackwright.core.ranges import TAG_RECORD, TAG_START, RangeMixin
+from trackwright.errors import PreconditionFailedError, TrackwrightError
+
+DURATION_TOLERANCE = 0.15
+LOSSY_SUFFIXES = frozenset({".mp3", ".m4a", ".ogg"})
+
+
+def duration_tolerance(path: str, expected: float) -> float:
+    """Lossy files report an *estimated* duration and lose or gain a few frames at the end: an MP3 of a
+    139.976 s range measured 139.721 s (verified, TW-1204), a 28 s one 27.991 s."""
+    if Path(path).suffix.lower() in LOSSY_SUFFIXES:
+        return 0.5 + expected * 0.002
+    return DURATION_TOLERANCE
+
+
+INSTRUCTIONS = (
+    "Cubase shows 'Export Audio Mixdown'. Check the channel (Stereo Out), the name, the folder and the format "
+    "(WAV for archiving, MP3 for publishing), then click 'Export Audio'. Afterwards call this tool with "
+    "phase 'confirm' and the same 'since' and 'expected_seconds'."
+)
+
+
+class ExportMixin(RangeMixin):
+    def _locators_around_all_audio(self, transport: int) -> tuple[float, float]:
+        """Select All + Locators to Selection (verified), then read both locators in seconds."""
+        self._range_cmd("tool.select")
+        self._range_cmd("edit.select_all")
+        self._range_cmd("transport.locators_to_selection")
+        self._clear_selection()
+        cursor = self._cursor_seconds(transport)
+        primary = self.call("transport.get").get("primary") or {}
+        bounds = []
+        for field in ("cycleLeft", "cycleRight"):
+            bars = str((primary.get(field) or {}).get("time", ""))
+            self.call("transport.setTime", {"which": "locator", "display": "primary", "time": bars})
+            self.wait_until(self._cursor_bars, bars.__eq__)
+            bounds.append(self._cursor_seconds(transport))
+        self._move_cursor_seconds(transport, cursor)
+        return bounds[0], bounds[1]
+
+    def _export_folder(self) -> Path | None:
+        folders = self.launcher.project_folders() if self.launcher is not None else []
+        return Path(folders[0]) / "Mixdown" if folders else None
+
+    @operation
+    def export_mix(
+        self,
+        phase: Literal["start", "confirm"],
+        *,
+        start: str | None = None,
+        end: str | None = None,
+        unit: str = "seconds",
+        since: float | None = None,
+        expected_seconds: float | None = None,
+        folder: str | None = None,
+        dry_run: bool = True,
+    ) -> ExportOut:
+        if phase == "confirm":
+            return self._confirm_export(since, expected_seconds, folder)
+        if (start is None) != (end is None):
+            raise PreconditionFailedError("give both start and end, or neither for the whole project",
+                                          code="BAD_REQUEST")  # fmt: skip
+        transport = self._transport_id()
+        guess = self._export_folder()
+        out = ExportOut(phase="start", status="planned", dry_run=dry_run, start=None, end=None,
+                        expected_seconds=None, folder=str(guess) if guess else None, since=None)  # fmt: skip
+        if start is not None and end is not None:
+            cursor = self._cursor_seconds(transport)
+            span = (self._seconds_of(transport, start, unit), self._seconds_of(transport, end, unit))
+            self._move_cursor_seconds(transport, cursor)
+            if not 0 <= span[0] < span[1]:
+                raise PreconditionFailedError("the range must have 0 <= start < end", code="BAD_TIME")
+            out.start, out.end = format_seconds(span[0]), format_seconds(span[1])
+            out.expected_seconds = round(span[1] - span[0], 3)
+        else:
+            out.notes.append("whole project: the locators will go around all the audio")
+        if dry_run:
+            return out
+        self.policy.check_project_write()
+        if self._transport_flag(transport, TAG_START) or self._transport_flag(transport, TAG_RECORD):
+            raise PreconditionFailedError("stop the transport before exporting", code="TRANSPORT_RUNNING")
+        if out.expected_seconds is None:
+            span = self._locators_around_all_audio(transport)
+            out.start, out.end = format_seconds(span[0]), format_seconds(span[1])
+            out.expected_seconds = round(span[1] - span[0], 3)
+        else:
+            cursor = self._cursor_seconds(transport)
+            self._set_locator_seconds(transport, "left", self._seconds_of(transport, str(start), unit))
+            self._set_locator_seconds(transport, "right", self._seconds_of(transport, str(end), unit))
+            self._move_cursor_seconds(transport, cursor)
+        if not self._performable("file.export_audio_mixdown"):
+            raise TrackwrightError("Cubase cannot open the export dialog now (is another dialog open?)",
+                                   code="CANNOT_PERFORM")  # fmt: skip
+        out.since = time.time()
+        self._range_cmd("file.export_audio_mixdown")
+        out.status = "awaiting_user"
+        out.instructions = INSTRUCTIONS
+        out.notes.append("the locators stay on the exported range")
+        return out
+
+    def _confirm_export(self, since: float | None, expected: float | None, folder: str | None) -> ExportOut:
+        if since is None:
+            raise PreconditionFailedError("give 'since' from the start phase", code="BAD_REQUEST")
+        where = Path(folder).expanduser() if folder else self._export_folder()
+        out = ExportOut(phase="confirm", status="not_found", dry_run=False, start=None, end=None,
+                        expected_seconds=expected, folder=str(where) if where else None, since=since)  # fmt: skip
+        if where is None:
+            out.instructions = "the export folder is unknown: give 'folder' (the path shown in Cubase's dialog)"
+            return out
+        for found in self.exports.find(where, since):
+            matches, difference = None, None
+            if expected is not None and found.duration_seconds is not None:
+                difference = round(found.duration_seconds - expected, 3)
+                matches = abs(difference) <= duration_tolerance(found.path, expected)
+            out.files.append(ExportedFileOut(path=found.path, size_bytes=found.size_bytes,
+                                             duration_seconds=found.duration_seconds,
+                                             difference_seconds=difference, duration_matches=matches))  # fmt: skip
+        if out.files:
+            out.status = "done"
+            out.verified = out.files[0].duration_matches
+        else:
+            out.instructions = (
+                "no audio file newer than the start phase in that folder: finish the export in Cubase, or give "
+                "'folder' if you chose another one"
+            )
+        return out

trackwright/core/importing.py

@@ -0,0 +1,127 @@
+"""Import an audio file, with the user (TW-1203).
+
+Verified in Cubase Elements 15.0.30 (experiments/tw1203): ``File / Import Audio File`` opens the macOS file
+selector, the file goes to the **selected track at the cursor**, and Cubase copies it to
+``<project>/Audio``. While the selector is open **Cubase does not answer the script**, so the start phase
+makes no call after opening it. The confirm phase probes the track's event edges.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Literal
+
+from trackwright.core.base import operation
+from trackwright.core.exporting import ExportMixin
+from trackwright.core.models import ImportOut
+from trackwright.core.project import SECONDS_TOLERANCE, format_seconds
+from trackwright.core.ranges import TAG_RECORD, TAG_START
+from trackwright.core.refs import TrackSelector
+from trackwright.errors import PreconditionFailedError, RequestTimeoutError, TrackwrightError
+from trackwright.exports import AUDIO_SUFFIXES
+
+EDGE_TOLERANCE = 0.01
+
+
+class ImportMixin(ExportMixin):
+    @operation
+    def import_audio(
+        self,
+        phase: Literal["start", "confirm"],
+        track: str,
+        position: str,
+        *,
+        unit: str = "seconds",
+        file: str | None = None,
+        since: float | None = None,
+        dry_run: bool = True,
+    ) -> ImportOut:
+        path = Path(file).expanduser() if file else None
+        expected = None
+        if path is not None:
+            if not path.is_file() or path.suffix.lower() not in AUDIO_SUFFIXES:
+                raise PreconditionFailedError(f"not an audio file: {path}", code="NOT_FOUND")
+            expected = self.exports.duration(path)
+        if phase == "confirm":
+            return self._confirm_import(track, position, unit, path=path, expected=expected, since=since)
+        item = self.resolve_track(TrackSelector.parse(track))
+        transport = self._transport_id()
+        cursor = self._cursor_seconds(transport)
+        at = self._seconds_of(transport, position, unit)
+        self._move_cursor_seconds(transport, cursor)
+        out = ImportOut(phase="start", status="planned", dry_run=dry_run, track=self.track_info(item).name,
+                        position=format_seconds(at), file=str(path) if path else None, expected_seconds=expected,
+                        since=None)  # fmt: skip
+        out.notes.append("the audio goes to this track at this position; Cubase copies the file into the project")
+        if dry_run:
+            return out
+        self.policy.check_track(out.track)
+        if self._transport_flag(transport, TAG_START) or self._transport_flag(transport, TAG_RECORD):
+            raise PreconditionFailedError("stop the transport before importing", code="TRANSPORT_RUNNING")
+        if not self._performable("file.import_audio"):
+            raise TrackwrightError("Cubase cannot open the import dialog now (is another dialog open?)",
+                                   code="CANNOT_PERFORM")  # fmt: skip
+        self._select_channel(int(item["id"]))
+        self._move_cursor_seconds(transport, at)
+        out.since = time.time()
+        self._range_cmd("file.import_audio")  # from here Cubase is blocked until the user closes the selector
+        out.status = "awaiting_user"
+        pick = f"press Cmd+Shift+G, paste {path} and open it" if path else "choose the audio file and open it"
+        out.instructions = (
+            f"Cubase shows the file selector: {pick}. Accept the import options (Cubase copies the file into "
+            "the project). Cubase does not answer until the selector is closed. Then call this tool with phase "
+            "'confirm', the same track, position and file, and 'since'."
+        )
+        return out
+
+    def _confirm_import(
+        self,
+        track: str,
+        position: str,
+        unit: str,
+        *,
+        path: Path | None,
+        expected: float | None,
+        since: float | None,
+    ) -> ImportOut:
+        if since is None:
+            raise PreconditionFailedError("give 'since' from the start phase", code="BAD_REQUEST")
+        out = ImportOut(phase="confirm", status="not_found", dry_run=False, track=track, position=position,
+                        file=str(path) if path else None, expected_seconds=expected, since=since)  # fmt: skip
+        try:
+            item = self.resolve_track(TrackSelector.parse(track))
+            transport = self._transport_id()
+        except RequestTimeoutError:
+            out.status = "awaiting_user"
+            out.instructions = "Cubase does not answer yet: the file selector is probably still open"
+            return out
+        cursor = self._cursor_seconds(transport)
+        at = self._seconds_of(transport, position, unit)
+        out.track, out.position = self.track_info(item).name, format_seconds(at)
+        selected = self.call("da.base").get("base")
+        self._select_channel(int(item["id"]))
+        edges, _ = self.probe_edges(transport, max(at - 1.0, 0.0), until=at + (expected or 0.0) + 1.0)
+        self._restore(transport, {}, cursor, selected)
+        wanted = [at] + ([at + expected] if expected is not None else [])
+        found = [e for e in edges if any(abs(e - w) <= EDGE_TOLERANCE + SECONDS_TOLERANCE for w in wanted)]
+        out.edges_found = [format_seconds(e) for e in found]
+        project = self._project_folder_for_import()
+        if project is not None:
+            out.copied_to_project = [Path(f.path).name for f in self.exports.find(project / "Audio", since)]
+        if len(found) == len(wanted):
+            out.status, out.verified = "done", True
+        else:
+            out.instructions = (
+                "the expected event edges are not on that track: the import was cancelled, went elsewhere, or "
+                "the file has another duration"
+            )
+            out.verified = False
+        if expected is None:
+            out.notes.append("only the start was checked: give 'file' to check the end too")
+        out.notes.append("Undo in Cubase removes the event, not the copy in the project's Audio folder")
+        return out
+
+    def _project_folder_for_import(self) -> Path | None:
+        folders = self.launcher.project_folders() if self.launcher is not None else []
+        return Path(folders[0]) if folders else None

trackwright/core/lifecycle.py

@@ -0,0 +1,74 @@
+"""Opening Cubase (TW-1201). Trackwright never closes Cubase, forces it to quit or saves projects."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from trackwright.core.base import ServiceBase, operation
+from trackwright.core.models import LaunchOut
+from trackwright.errors import PreconditionFailedError, TrackwrightError
+
+POLL_SECONDS = 1.0
+
+
+class LifecycleMixin(ServiceBase):
+    def _script_version(self) -> str | None:
+        """The script's version when it answers, else ``None`` (Cubase closed, loading or showing a dialog)."""
+        try:
+            return str(self.call("hello").get("scriptVersion") or "?")
+        except TrackwrightError:
+            return None
+
+    @operation
+    def launch_cubase(
+        self, project: str | None = None, *, dry_run: bool = True, timeout: float | None = None
+    ) -> LaunchOut:
+        if self.launcher is None:
+            raise TrackwrightError("this server cannot open applications", code="UNSUPPORTED")
+        app = self.launcher.app
+        project_path = self._project_path(project)
+        version = self._script_version()
+        running = self.launcher.is_running()
+        if version is not None:
+            return LaunchOut(status="already_running", app=app, dry_run=dry_run, process_running=True,
+                             script_version=version, project=None)  # fmt: skip
+        if running:
+            return LaunchOut(
+                status="running_without_script", app=app, dry_run=dry_run, process_running=True,
+                script_version=None, project=None,
+                instructions="Cubase is open but the Trackwright script does not answer. Open or create a project, "
+                "close any dialog, and check Studio > MIDI Remote Manager (run 'trackwright doctor'). "
+                "A second instance is not opened.",
+            )  # fmt: skip
+        plan = LaunchOut(status="planned", app=app, dry_run=dry_run, process_running=False, script_version=None,
+                         project=str(project_path) if project_path else None)  # fmt: skip
+        if dry_run:
+            return plan
+        self.policy.check_project_write()
+        self.launcher.launch(project_path)
+        deadline = time.monotonic() + (timeout if timeout is not None else self.launcher.launch_timeout)
+        while time.monotonic() < deadline:
+            self._sleep(POLL_SECONDS)
+            version = self._script_version()
+            if version is not None:
+                plan.status, plan.script_version, plan.process_running = "ready", version, True
+                return plan
+        plan.process_running = self.launcher.is_running()
+        plan.status = "awaiting_user"
+        plan.instructions = (
+            "Cubase is starting but the script has not answered yet. Look at Cubase: answer any dialog "
+            "(Steinberg Hub, project choice, audio device) and open a project; then call cubase_status."
+        )
+        return plan
+
+    @staticmethod
+    def _project_path(project: str | None) -> Path | None:
+        if project is None:
+            return None
+        path = Path(project).expanduser()
+        if path.suffix.lower() != ".cpr":
+            raise PreconditionFailedError("project must be a Cubase .cpr file", code="BAD_REQUEST")
+        if not path.is_file():
+            raise PreconditionFailedError(f"project not found: {path}", code="NOT_FOUND")
+        return path.resolve()