dvr 0.1.0__py3-none-any.whl

dvr/__init__.py

@@ -0,0 +1,55 @@
+"""dvr — the missing CLI and Python library for DaVinci Resolve.
+
+This package exposes a small, stable public API. Internal modules are
+prefixed with ``_`` and may change between releases. The two things you
+almost always want are:
+
+    from dvr import Resolve, errors
+
+Open a connection with ``r = Resolve()`` and navigate from there.
+"""
+
+from __future__ import annotations
+
+from . import audio, errors, gallery, interchange, spec
+from .color import ColorGroup, ColorOps, NodeGraph
+from .media import Asset, Bin, MediaPool, MediaPoolItem, MediaStorage
+from .project import Project, ProjectNamespace
+from .render import RenderJob, RenderNamespace
+from .resolve import App, Resolve
+from .timeline import Clip, ClipFusion, ClipQuery, Takes, Timeline, TimelineNamespace, Track
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover - generated at build time
+    __version__ = "0.0.0+local"
+
+__all__ = [
+    "App",
+    "Asset",
+    "Bin",
+    "Clip",
+    "ClipFusion",
+    "ClipQuery",
+    "ColorGroup",
+    "ColorOps",
+    "MediaPool",
+    "MediaPoolItem",
+    "MediaStorage",
+    "NodeGraph",
+    "Project",
+    "ProjectNamespace",
+    "RenderJob",
+    "RenderNamespace",
+    "Resolve",
+    "Takes",
+    "Timeline",
+    "TimelineNamespace",
+    "Track",
+    "__version__",
+    "audio",
+    "errors",
+    "gallery",
+    "interchange",
+    "spec",
+]

dvr/__main__.py

@@ -0,0 +1,8 @@
+"""Make ``python -m dvr`` an alias for the CLI."""
+
+from __future__ import annotations
+
+from .cli.main import main
+
+if __name__ == "__main__":
+    main()

dvr/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

dvr/_wrap.py

@@ -0,0 +1,68 @@
+"""Internal helpers shared by every domain wrapper.
+
+The Resolve API is famously inconsistent: methods can return ``None`` for
+"not found", "wrong page", "no current project", or genuine errors — with
+no way to distinguish. The helpers here let domain wrappers collapse those
+cases into a structured ``DvrError`` with a useful diagnosis.
+
+Nothing here is part of the public API.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from . import errors
+
+T = TypeVar("T")
+
+
+def require(
+    value: T | None,
+    *,
+    error: type[errors.DvrError] = errors.DvrError,
+    message: str,
+    cause: str | None = None,
+    fix: str | None = None,
+    state: dict[str, Any] | None = None,
+) -> T:
+    """Assert ``value is not None`` or raise a structured error.
+
+    Use this around any raw API call that can return ``None`` to signal
+    failure. ``cause``/``fix``/``state`` flow into the resulting exception.
+    """
+    if value is None:
+        raise error(message, cause=cause, fix=fix, state=state)
+    return value
+
+
+def safe_call(
+    fn: Callable[[], T],
+    *,
+    error: type[errors.DvrError] = errors.DvrError,
+    message: str,
+    cause: str | None = None,
+    fix: str | None = None,
+    state: dict[str, Any] | None = None,
+) -> T:
+    """Run a raw API call and translate exceptions into a ``DvrError``.
+
+    The Resolve API occasionally raises bare ``RuntimeError`` from C++.
+    Catch broadly and re-surface with diagnostic context.
+    """
+    try:
+        result = fn()
+    except errors.DvrError:
+        raise
+    except Exception as exc:
+        raise error(
+            message,
+            cause=cause or f"underlying API raised {type(exc).__name__}: {exc}",
+            fix=fix,
+            state=state,
+        ) from exc
+    return require(result, error=error, message=message, cause=cause, fix=fix, state=state)
+
+
+__all__ = ["require", "safe_call"]

dvr/audio.py

@@ -0,0 +1,139 @@
+"""Audio operations: channel mapping, voice isolation, Fairlight presets.
+
+The Fairlight scripting surface is small. Resolve does not expose EQ /
+compression / routing programmatically. What this module covers:
+
+* Reading audio channel mapping (which embedded/linked tracks feed which
+  timeline audio channel) for clips and assets.
+* Voice isolation (Fairlight feature) on timelines.
+* Inserting audio at the playhead.
+* Applying named Fairlight presets to the current timeline.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, List  # noqa: UP035
+
+from . import errors
+
+if TYPE_CHECKING:
+    from .project import Project
+    from .timeline import Clip, Timeline
+
+
+# ---------------------------------------------------------------------------
+# Per-clip / per-asset audio mapping
+# ---------------------------------------------------------------------------
+
+
+def get_clip_audio_mapping(clip: Clip) -> dict[str, Any]:
+    """Return the JSON-decoded audio mapping for a timeline clip."""
+    raw = clip.raw.GetSourceAudioChannelMapping() or "{}"
+    try:
+        return dict(json.loads(raw))
+    except (TypeError, ValueError):
+        return {}
+
+
+def get_asset_audio_mapping(asset: Any) -> dict[str, Any]:
+    """Return the JSON-decoded audio mapping for a media-pool asset."""
+    raw = asset.raw.GetAudioMapping() if hasattr(asset, "raw") else asset.GetAudioMapping()
+    try:
+        return dict(json.loads(raw or "{}"))
+    except (TypeError, ValueError):
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Voice isolation (timeline-level Fairlight feature)
+# ---------------------------------------------------------------------------
+
+
+def voice_isolation_state(timeline: Timeline) -> dict[str, Any]:
+    """Return ``{"enabled": bool, "amount": int}`` for the timeline."""
+    state = timeline.raw.GetVoiceIsolationState() or {}
+    return {
+        "enabled": bool(state.get("Enabled", False)),
+        "amount": int(state.get("Amount", 0)),
+    }
+
+
+def set_voice_isolation(
+    timeline: Timeline,
+    *,
+    enabled: bool,
+    amount: int = 50,
+) -> None:
+    """Toggle voice isolation; ``amount`` is 0-100."""
+    if not 0 <= amount <= 100:
+        raise errors.DvrError(
+            f"Voice isolation amount must be 0-100, got {amount!r}.",
+            state={"amount": amount},
+        )
+    if not timeline.raw.SetVoiceIsolationState({"Enabled": enabled, "Amount": amount}):
+        raise errors.DvrError(
+            "Could not set voice isolation state.",
+            cause="SetVoiceIsolationState returned False.",
+            state={"timeline": timeline.name, "enabled": enabled, "amount": amount},
+        )
+
+
+# ---------------------------------------------------------------------------
+# Project-level Fairlight presets
+# ---------------------------------------------------------------------------
+
+
+def fairlight_presets(project: Project) -> List[str]:  # noqa: UP006
+    return [str(n) for n in (project.raw.GetFairlightPresets() or [])]
+
+
+def apply_fairlight_preset(project: Project, name: str) -> None:
+    """Apply a named Fairlight preset to the current timeline."""
+    if not project.raw.ApplyFairlightPresetToCurrentTimeline(name):
+        raise errors.DvrError(
+            f"Could not apply Fairlight preset {name!r}.",
+            cause="ApplyFairlightPresetToCurrentTimeline returned False.",
+            fix=f"Available presets: {fairlight_presets(project)}",
+            state={"requested": name},
+        )
+
+
+# ---------------------------------------------------------------------------
+# Insert audio at playhead (Fairlight page)
+# ---------------------------------------------------------------------------
+
+
+def insert_audio_at_playhead(
+    project: Project,
+    *,
+    file_path: str,
+    offset_samples: int = 0,
+    duration_samples: int | None = None,
+) -> None:
+    """Insert audio at the current track's playhead on the Fairlight page."""
+    args = [file_path, offset_samples]
+    if duration_samples is not None:
+        args.append(duration_samples)
+    if not project.raw.InsertAudioToCurrentTrackAtPlayhead(*args):
+        raise errors.DvrError(
+            f"Could not insert audio {file_path!r}.",
+            cause="InsertAudioToCurrentTrackAtPlayhead returned False.",
+            fix="Switch to the Fairlight page and select an audio track first.",
+            state={
+                "file_path": file_path,
+                "offset_samples": offset_samples,
+                "duration_samples": duration_samples,
+            },
+        )
+
+
+__all__ = [
+    "apply_fairlight_preset",
+    "fairlight_presets",
+    "get_asset_audio_mapping",
+    "get_clip_audio_mapping",
+    "insert_audio_at_playhead",
+    "set_voice_isolation",
+    "voice_isolation_state",
+]

dvr/cli/__init__.py

@@ -0,0 +1,6 @@
+"""Command-line interface for `dvr`.
+
+The CLI is a thin wrapper around the library: every command is a
+``Resolve()`` call followed by an ``output()`` call. All formatting,
+serialization, and error rendering lives in :mod:`dvr.cli.output`.
+"""

dvr/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI sub-apps, one per top-level domain."""

dvr/cli/commands/apply.py

@@ -0,0 +1,77 @@
+"""``dvr apply`` and ``dvr plan`` — declarative reconciliation."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ... import spec as spec_mod
+from ...resolve import Resolve
+from .. import output
+
+
+def _resolve(ctx: typer.Context) -> Resolve:
+    cfg = ctx.obj or {}
+    return Resolve(auto_launch=cfg.get("auto_launch", True), timeout=cfg.get("timeout", 30.0))
+
+
+def _action_rows(actions: list[spec_mod.Action]) -> list[dict[str, str]]:
+    return [{"op": a.op, "target": a.target, "detail": a.detail} for a in actions]
+
+
+def register(app: typer.Typer) -> None:
+    """Register ``apply`` and ``plan`` as top-level commands."""
+
+    @app.command("plan")
+    def plan_cmd(
+        ctx: typer.Context,
+        spec_file: Annotated[str, typer.Argument(help="Path to a YAML or JSON spec.")],
+    ) -> None:
+        """Show the actions `dvr apply` would take, without executing."""
+        cfg = ctx.obj or {}
+        resolve = _resolve(ctx)
+        spec = spec_mod.load_spec(spec_file)
+        actions = spec_mod.plan(spec, resolve)
+        output.emit(
+            _action_rows(actions),
+            fmt=cfg.get("format"),
+            headline=f"plan: {spec.project}",
+        )
+
+    @app.command("apply")
+    def apply_cmd(
+        ctx: typer.Context,
+        spec_file: Annotated[str, typer.Argument(help="Path to a YAML or JSON spec.")],
+        dry_run: Annotated[
+            bool,
+            typer.Option("--dry-run", "-n", help="Print the plan without applying."),
+        ] = False,
+        yes: Annotated[
+            bool,
+            typer.Option("--yes", "-y", help="Skip the confirmation prompt."),
+        ] = False,
+    ) -> None:
+        """Reconcile a spec against the live DaVinci Resolve state."""
+        cfg = ctx.obj or {}
+        resolve = _resolve(ctx)
+        spec = spec_mod.load_spec(spec_file)
+
+        actions = spec_mod.plan(spec, resolve)
+        output.emit(
+            _action_rows(actions),
+            fmt=cfg.get("format"),
+            headline=f"plan: {spec.project}",
+        )
+
+        if dry_run:
+            return
+
+        if not yes:
+            typer.confirm(f"Apply {len(actions)} action(s) to {spec.project!r}?", abort=True)
+
+        applied = spec_mod.apply(spec, resolve, dry_run=False)
+        output.emit(
+            {"applied": len(applied), "project": spec.project},
+            fmt=cfg.get("format"),
+        )

dvr/cli/commands/mcp.py

@@ -0,0 +1,26 @@
+"""``dvr mcp`` sub-commands — MCP server for LLM agents."""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(name="mcp", help="MCP server: expose dvr to LLM agents.")
+
+
+@app.command("serve")
+def serve(ctx: typer.Context) -> None:
+    """Run the MCP server on stdio (the default MCP transport)."""
+    cfg = ctx.obj or {}
+    try:
+        from ...mcp import run_stdio
+    except ImportError as exc:
+        typer.echo(
+            'MCP support requires the optional extra: pip install "dvr[mcp]"',
+            err=True,
+        )
+        raise typer.Exit(1) from exc
+
+    run_stdio(
+        auto_launch=cfg.get("auto_launch", True),
+        timeout=cfg.get("timeout", 30.0),
+    )

dvr/cli/commands/media.py

@@ -0,0 +1,148 @@
+"""``dvr media`` sub-commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ...resolve import Resolve
+from .. import output
+
+app = typer.Typer(name="media", help="Media pool: bins, assets, import, relink, proxy, audio sync.")
+
+
+def _resolve(ctx: typer.Context) -> Resolve:
+    cfg = ctx.obj or {}
+    return Resolve(auto_launch=cfg.get("auto_launch", True), timeout=cfg.get("timeout", 30.0))
+
+
+@app.command("inspect")
+def inspect_pool(ctx: typer.Context) -> None:
+    """Inspect the current project's media pool."""
+    r = _resolve(ctx)
+    project = r.project.current
+    if project is None:
+        typer.echo("No project is currently loaded.", err=True)
+        raise typer.Exit(1)
+    output.emit(project.media.inspect(), fmt=ctx.obj["format"], headline="media pool")
+
+
+@app.command("bins")
+def bins(ctx: typer.Context) -> None:
+    """List bins in the current project's media pool."""
+    r = _resolve(ctx)
+    project = r.project.current
+    if project is None:
+        typer.echo("No project is currently loaded.", err=True)
+        raise typer.Exit(1)
+    rows = [b.inspect() for b in project.media.root().subbins()]
+    output.emit(rows, fmt=ctx.obj["format"], headline="bins")
+
+
+@app.command("ls")
+def ls_bin(
+    ctx: typer.Context,
+    bin: Annotated[
+        str | None,
+        typer.Argument(help="Bin name to list. Defaults to the root bin."),
+    ] = None,
+) -> None:
+    """List assets in a bin."""
+    r = _resolve(ctx)
+    project = r.project.current
+    if project is None:
+        typer.echo("No project is currently loaded.", err=True)
+        raise typer.Exit(1)
+    target = project.media._find_bin(bin) if bin else project.media.root()
+    rows = [a.inspect() for a in target.assets()]
+    output.emit(rows, fmt=ctx.obj["format"], headline=f"assets in {target.name}")
+
+
+@app.command("mkbin")
+def mkbin(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Bin name.")],
+    parent: Annotated[
+        str | None,
+        typer.Option("--parent", help="Parent bin (default: root)."),
+    ] = None,
+) -> None:
+    """Create (or get-or-create) a bin."""
+    r = _resolve(ctx)
+    project = r.project.current
+    if project is None:
+        typer.echo("No project is currently loaded.", err=True)
+        raise typer.Exit(1)
+    parent_bin = project.media._find_bin(parent) if parent else project.media.root()
+    bin_obj = project.media.ensure_bin(name, parent=parent_bin)
+    output.emit(bin_obj.inspect(), fmt=ctx.obj["format"], headline=f"bin: {bin_obj.name}")
+
+
+@app.command("import")
+def import_files(
+    ctx: typer.Context,
+    paths: Annotated[list[str], typer.Argument(help="One or more file paths to import.")],
+    bin: Annotated[
+        str | None,
+        typer.Option("--bin", "-b", help="Target bin (default: current)."),
+    ] = None,
+) -> None:
+    """Import media files into the pool."""
+    r = _resolve(ctx)
+    project = r.project.current
+    if project is None:
+        typer.echo("No project is currently loaded.", err=True)
+        raise typer.Exit(1)
+    target_bin = project.media._find_bin(bin) if bin else None
+    assets = project.media.import_(paths, bin=target_bin)
+    rows = [a.inspect() for a in assets]
+    output.emit(rows, fmt=ctx.obj["format"], headline=f"imported {len(rows)}")
+
+
+@app.command("relink")
+def relink(
+    ctx: typer.Context,
+    folder: Annotated[
+        str,
+        typer.Argument(help="Folder containing replacement media."),
+    ],
+    bin: Annotated[
+        str | None,
+        typer.Option("--bin", "-b", help="Bin whose assets to relink (default: root)."),
+    ] = None,
+) -> None:
+    """Relink assets in a bin to new files in a folder."""
+    r = _resolve(ctx)
+    project = r.project.current
+    if project is None:
+        typer.echo("No project is currently loaded.", err=True)
+        raise typer.Exit(1)
+    target = project.media._find_bin(bin) if bin else project.media.root()
+    project.media.relink(target.assets(), folder)
+    output.emit(
+        {"relinked": len(target.assets()), "folder": folder, "bin": target.name},
+        fmt=ctx.obj["format"],
+    )
+
+
+@app.command("storage")
+def storage(
+    ctx: typer.Context,
+    path: Annotated[
+        str | None,
+        typer.Argument(help="Path to list (default: mounted volumes)."),
+    ] = None,
+) -> None:
+    """List mounted volumes (no path) or files/folders under a path."""
+    r = _resolve(ctx)
+    if path is None:
+        output.emit(
+            [{"volume": v} for v in r.storage.volumes()],
+            fmt=ctx.obj["format"],
+            headline="volumes",
+        )
+        return
+    rows = [{"name": p, "kind": "folder"} for p in r.storage.subfolders(path)]
+    rows.extend({"name": f, "kind": "file"} for f in r.storage.files(path))
+    output.emit(rows, fmt=ctx.obj["format"], headline=path)

dvr/cli/commands/project.py

@@ -0,0 +1,126 @@
+"""``dvr project`` sub-commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ...resolve import Resolve
+from .. import output
+
+app = typer.Typer(
+    name="project", help="Project operations: list, ensure, load, create, delete, archive."
+)
+
+
+def _resolve(ctx: typer.Context) -> Resolve:
+    cfg = ctx.obj or {}
+    return Resolve(auto_launch=cfg.get("auto_launch", True), timeout=cfg.get("timeout", 30.0))
+
+
+@app.command("list")
+def list_projects(ctx: typer.Context) -> None:
+    """List projects in the current PM folder."""
+    r = _resolve(ctx)
+    rows = [{"name": n} for n in r.project.list()]
+    output.emit(rows, fmt=ctx.obj["format"], headline="projects")
+
+
+@app.command("current")
+def current(ctx: typer.Context) -> None:
+    """Inspect the currently loaded project."""
+    r = _resolve(ctx)
+    proj = r.project.current
+    if proj is None:
+        output.emit({"current": None}, fmt=ctx.obj["format"])
+        return
+    output.emit(proj.inspect(), fmt=ctx.obj["format"], headline=proj.name)
+
+
+@app.command("ensure")
+def ensure(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Project name to load-or-create.")],
+) -> None:
+    """Load the project if it exists, otherwise create it."""
+    r = _resolve(ctx)
+    proj = r.project.ensure(name)
+    output.emit(proj.inspect(), fmt=ctx.obj["format"], headline=f"ensured: {proj.name}")
+
+
+@app.command("create")
+def create(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Project name (must be unique).")],
+) -> None:
+    """Create a new project."""
+    r = _resolve(ctx)
+    proj = r.project.create(name)
+    output.emit(proj.inspect(), fmt=ctx.obj["format"], headline=f"created: {proj.name}")
+
+
+@app.command("load")
+def load(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Project name to load.")],
+) -> None:
+    """Load an existing project."""
+    r = _resolve(ctx)
+    proj = r.project.load(name)
+    output.emit(proj.inspect(), fmt=ctx.obj["format"], headline=f"loaded: {proj.name}")
+
+
+@app.command("delete")
+def delete(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Project name to delete.")],
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Skip the confirmation prompt.")] = False,
+) -> None:
+    """Delete a project (must be closed first)."""
+    if not yes:
+        typer.confirm(f"Really delete project {name!r}?", abort=True)
+    r = _resolve(ctx)
+    r.project.delete(name)
+    output.emit({"deleted": name}, fmt=ctx.obj["format"])
+
+
+@app.command("save")
+def save(ctx: typer.Context) -> None:
+    """Save the currently loaded project."""
+    r = _resolve(ctx)
+    proj = r.project.current
+    if proj is None:
+        typer.echo("No project is currently loaded.", err=True)
+        raise typer.Exit(1)
+    proj.save()
+    output.emit({"saved": proj.name}, fmt=ctx.obj["format"])
+
+
+@app.command("export")
+def export(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Project name to export.")],
+    file: Annotated[str, typer.Argument(help="Output .drp path.")],
+    no_assets: Annotated[
+        bool, typer.Option("--no-assets", help="Exclude stills and LUTs.")
+    ] = False,
+) -> None:
+    """Export a project to a .drp file."""
+    r = _resolve(ctx)
+    r.project.export(name, file, with_stills_and_luts=not no_assets)
+    output.emit({"exported": name, "path": file}, fmt=ctx.obj["format"])
+
+
+@app.command("import")
+def import_(
+    ctx: typer.Context,
+    file: Annotated[str, typer.Argument(help="Input .drp path.")],
+    name: Annotated[
+        str | None, typer.Option("--name", help="Override the imported project name.")
+    ] = None,
+) -> None:
+    """Import a project from a .drp file."""
+    r = _resolve(ctx)
+    proj = r.project.import_(file, name=name)
+    output.emit(proj.inspect(), fmt=ctx.obj["format"], headline=f"imported: {proj.name}")