dvr 0.1.0__tar.gz

dvr-0.1.0/.gitignore

@@ -0,0 +1,70 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Hatch / generated version file
+dvr/_version.py
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project-local
+*.log
+.env
+.env.local
+scratch/
+local/
+
+# Docs
+site/

dvr-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `dvr` are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Media domain: `MediaPool`, `Asset` / `MediaPoolItem`, `Bin`, `MediaStorage` with bins, import, relink, proxy linking, auto-sync
+- Color domain: `ColorOps` (CDL, LUT export, magic mask, stabilization, smart reframe, versions), `NodeGraph`, `ColorGroup`
+- Audio domain: voice isolation, channel mapping introspection, Fairlight presets, audio insertion
+- Gallery domain: still albums, PowerGrade albums, import/export
+- Fusion (per-clip): `ClipFusion` for add / load / import / export / rename / delete comps
+- Takes: `Takes` for take/variant management on a clip
+- Interchange: unified import/export covering 21 formats — AAF, EDL (+ CDL/SDL/missing), FCP7 XML, FCPXML 1.8/1.9/1.10, DRT, OTIO, CSV, TAB, ALE, ALE-CDL, Dolby Vision 2.9/4.0/5.1, HDR10 A/B
+- Daemon: `dvr serve start/stop/status/methods` with newline-delimited JSON over a Unix socket
+- MCP server: `dvr mcp serve` exposes the library as typed tools for LLM agents
+- Declarative specs: `dvr plan` and `dvr apply` reconcile YAML/JSON specs against live state, with built-in HDR color presets
+- CLI sub-apps for every domain: `dvr media`, `dvr serve`, `dvr mcp`, `dvr plan`, `dvr apply`
+- Docs site: mkdocs-material with concept guides, CLI reference, library tour, daemon and MCP guides, declarative-spec walkthrough, auto-generated API reference
+
+## [0.1.0] - 2026-04-24
+
+### Added
+- Initial scaffold: connection layer, error system, Resolve / Project / Timeline / Render core classes
+- CLI entry point with structured output (JSON / table / YAML)
+- Inspection-first object model

dvr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M Hadi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dvr-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: dvr
+Version: 0.1.0
+Summary: The missing CLI and Python library for DaVinci Resolve. Declarative, scriptable, LLM-friendly.
+Project-URL: Homepage, https://github.com/mhadifilms/dvr
+Project-URL: Documentation, https://mhadifilms.github.io/dvr
+Project-URL: Repository, https://github.com/mhadifilms/dvr
+Project-URL: Issues, https://github.com/mhadifilms/dvr/issues
+Project-URL: Changelog, https://github.com/mhadifilms/dvr/blob/main/CHANGELOG.md
+Author-email: M Hadi <mhadifilms@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: automation,cli,color-grading,davinci-resolve,edl,fcpxml,post-production,vfx,video-editing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# dvr
+
+**The missing CLI and Python library for DaVinci Resolve.**
+
+Declarative. Scriptable. LLM-friendly. No more silent `None` returns.
+
+```bash
+pip install dvr
+```
+
+```bash
+$ dvr timeline inspect
+{
+  "name": "MyShow_207_R2",
+  "fps": 24.0,
+  "duration_frames": 86400,
+  "tracks": {
+    "video": [{"index": 1, "name": "V1", "clips": 1, "enabled": true}, ...],
+    "audio": [{"index": 1, "name": "A1", "clips": 4, "subtype": "stereo"}, ...]
+  },
+  "markers": [...],
+  "color": {"science": "DaVinci YRGB Color Managed v2", "input": "Rec.2020", ...}
+}
+```
+
+---
+
+## Why this exists
+
+DaVinci Resolve has a powerful Python scripting API. It's also painful:
+
+- **Silent failures everywhere.** `AddRenderJob()` returns `None` on success or failure — good luck.
+- **String-keyed settings** with undocumented valid values.
+- **No batch operators.** You loop everything.
+- **macOS connection footguns.** Resolve binds to LAN IP; vanilla `scriptapp('Resolve')` returns `None`.
+- **Chain navigation.** Every `.Get*()` can return `None`. One typo and you're traversing nothing.
+- **20+ export formats** behind magic enum constants.
+
+`dvr` wraps the API with a clean object model, idempotent operations, decoded errors, structured I/O, and a CLI that's pleasant for humans *and* parseable by LLM agents.
+
+## Three ways to use it
+
+### 1. Python library
+
+```python
+from dvr import Resolve
+
+r = Resolve()  # auto-connects, handles macOS LAN-IP quirk
+
+with r.project.use("MyShow_207"):
+    tl = r.timeline.current
+    print(tl.inspect())                      # one call, full state
+
+    # Query language operates on inspected state
+    bad = tl.clips.where(lambda c: c.duration < 12)
+    for clip in bad:
+        clip.add_marker(color="red", note="too short")
+
+    job = r.render.submit(preset="delivery")
+    job.wait()                               # blocks with progress
+    print(job.output_path)
+```
+
+### 2. CLI
+
+```bash
+$ dvr project ensure MyShow_207 --color rec2020_pq_4000 --fps 24
+$ dvr timeline inspect | jq '.tracks.video[].clips'
+$ dvr render submit --preset delivery --wait --stream
+{"job_id": "abc", "status": "rendering", "pct": 12, "eta_s": 240}
+{"job_id": "abc", "status": "rendering", "pct": 24, "eta_s": 210}
+{"job_id": "abc", "status": "complete", "output": "/path/out.mov"}
+```
+
+### 3. MCP server (for LLM agents)
+
+```bash
+$ dvr mcp serve              # exposes the library as MCP tools
+```
+
+LLM agents call typed tools directly — no shell parsing, no silent failures.
+
+## Five things that make it fundamentally better than the raw API
+
+1. **One `inspect()` call replaces ten API calls.** Full structured state in a single round-trip.
+2. **Idempotent operations.** `project.ensure()`, `timeline.ensure()`, `bin.ensure()` — re-run anything safely.
+3. **Decoded errors.** Every failure carries `cause`, `fix`, and `state`. No more `None`.
+4. **Declarative specs.** `dvr apply project.dvr.yaml` reconciles state. `kubectl apply` for DaVinci.
+5. **Persistent connection.** `dvr serve` keeps Resolve warm — sequential commands run in <100ms.
+
+## Install
+
+```bash
+# stable
+pip install dvr
+
+# with MCP server for LLM agents
+pip install "dvr[mcp]"
+
+# from source
+git clone https://github.com/mhadifilms/dvr
+cd dvr
+pip install -e ".[dev]"
+```
+
+### Requirements
+
+- **Python 3.10+** (matches Resolve's embedded Python on current versions)
+- **DaVinci Resolve 18.5+** (Studio or Free)
+- **macOS, Windows, or Linux**
+
+`dvr` auto-discovers Resolve's scripting library on each platform. No environment variables needed for typical installs.
+
+## Status
+
+Pre-1.0. The public API may change. See [CHANGELOG.md](CHANGELOG.md) for breaking changes.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+Issues and pull requests welcome. The project's API surface is large; contributions covering edge cases on Windows / Linux are especially valuable. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and conventions.
+
+---
+
+> `dvr` is an independent open-source project. It is **not affiliated with, endorsed by, or sponsored by Blackmagic Design**. "DaVinci" and "DaVinci Resolve" are trademarks of Blackmagic Design Pty Ltd.

dvr-0.1.0/README.md

@@ -0,0 +1,128 @@
+# dvr
+
+**The missing CLI and Python library for DaVinci Resolve.**
+
+Declarative. Scriptable. LLM-friendly. No more silent `None` returns.
+
+```bash
+pip install dvr
+```
+
+```bash
+$ dvr timeline inspect
+{
+  "name": "MyShow_207_R2",
+  "fps": 24.0,
+  "duration_frames": 86400,
+  "tracks": {
+    "video": [{"index": 1, "name": "V1", "clips": 1, "enabled": true}, ...],
+    "audio": [{"index": 1, "name": "A1", "clips": 4, "subtype": "stereo"}, ...]
+  },
+  "markers": [...],
+  "color": {"science": "DaVinci YRGB Color Managed v2", "input": "Rec.2020", ...}
+}
+```
+
+---
+
+## Why this exists
+
+DaVinci Resolve has a powerful Python scripting API. It's also painful:
+
+- **Silent failures everywhere.** `AddRenderJob()` returns `None` on success or failure — good luck.
+- **String-keyed settings** with undocumented valid values.
+- **No batch operators.** You loop everything.
+- **macOS connection footguns.** Resolve binds to LAN IP; vanilla `scriptapp('Resolve')` returns `None`.
+- **Chain navigation.** Every `.Get*()` can return `None`. One typo and you're traversing nothing.
+- **20+ export formats** behind magic enum constants.
+
+`dvr` wraps the API with a clean object model, idempotent operations, decoded errors, structured I/O, and a CLI that's pleasant for humans *and* parseable by LLM agents.
+
+## Three ways to use it
+
+### 1. Python library
+
+```python
+from dvr import Resolve
+
+r = Resolve()  # auto-connects, handles macOS LAN-IP quirk
+
+with r.project.use("MyShow_207"):
+    tl = r.timeline.current
+    print(tl.inspect())                      # one call, full state
+
+    # Query language operates on inspected state
+    bad = tl.clips.where(lambda c: c.duration < 12)
+    for clip in bad:
+        clip.add_marker(color="red", note="too short")
+
+    job = r.render.submit(preset="delivery")
+    job.wait()                               # blocks with progress
+    print(job.output_path)
+```
+
+### 2. CLI
+
+```bash
+$ dvr project ensure MyShow_207 --color rec2020_pq_4000 --fps 24
+$ dvr timeline inspect | jq '.tracks.video[].clips'
+$ dvr render submit --preset delivery --wait --stream
+{"job_id": "abc", "status": "rendering", "pct": 12, "eta_s": 240}
+{"job_id": "abc", "status": "rendering", "pct": 24, "eta_s": 210}
+{"job_id": "abc", "status": "complete", "output": "/path/out.mov"}
+```
+
+### 3. MCP server (for LLM agents)
+
+```bash
+$ dvr mcp serve              # exposes the library as MCP tools
+```
+
+LLM agents call typed tools directly — no shell parsing, no silent failures.
+
+## Five things that make it fundamentally better than the raw API
+
+1. **One `inspect()` call replaces ten API calls.** Full structured state in a single round-trip.
+2. **Idempotent operations.** `project.ensure()`, `timeline.ensure()`, `bin.ensure()` — re-run anything safely.
+3. **Decoded errors.** Every failure carries `cause`, `fix`, and `state`. No more `None`.
+4. **Declarative specs.** `dvr apply project.dvr.yaml` reconciles state. `kubectl apply` for DaVinci.
+5. **Persistent connection.** `dvr serve` keeps Resolve warm — sequential commands run in <100ms.
+
+## Install
+
+```bash
+# stable
+pip install dvr
+
+# with MCP server for LLM agents
+pip install "dvr[mcp]"
+
+# from source
+git clone https://github.com/mhadifilms/dvr
+cd dvr
+pip install -e ".[dev]"
+```
+
+### Requirements
+
+- **Python 3.10+** (matches Resolve's embedded Python on current versions)
+- **DaVinci Resolve 18.5+** (Studio or Free)
+- **macOS, Windows, or Linux**
+
+`dvr` auto-discovers Resolve's scripting library on each platform. No environment variables needed for typical installs.
+
+## Status
+
+Pre-1.0. The public API may change. See [CHANGELOG.md](CHANGELOG.md) for breaking changes.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+Issues and pull requests welcome. The project's API surface is large; contributions covering edge cases on Windows / Linux are especially valuable. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and conventions.
+
+---
+
+> `dvr` is an independent open-source project. It is **not affiliated with, endorsed by, or sponsored by Blackmagic Design**. "DaVinci" and "DaVinci Resolve" are trademarks of Blackmagic Design Pty Ltd.

dvr-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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"]