[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80727":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":14,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":14,"starSnapshotCount":14,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},80727,"davinci-resolve-cli","Poechant\u002Fdavinci-resolve-cli","Poechant","A CLI for DaVinci Resolve 18+ — project \u002F media \u002F render \u002F timeline control for humans and AI agents.",null,"Python",43,8,3,0,2.86,"MIT License",false,"main",true,[21,22,23,24,25,26],"ai-agent","automation","cli","davinci-resolve","python","video-editing","2026-06-12 02:04:06","\u003Cimg width=\"1672\" height=\"941\" alt=\"image\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F86fa31b1-9229-484a-9ce8-6314d4015340\" \u002F>\n\n# davinci-resolve-cli (`dvr`)\n\n[![PyPI version](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fdavinci-resolve-cli.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fdavinci-resolve-cli\u002F)\n[![Python versions](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Fdavinci-resolve-cli.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fdavinci-resolve-cli\u002F)\n[![Downloads](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fdavinci-resolve-cli.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fdavinci-resolve-cli\u002F)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n[![Build](https:\u002F\u002Fgithub.com\u002FPoechant\u002Fdavinci-resolve-cli\u002Factions\u002Fworkflows\u002Fbuild.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FPoechant\u002Fdavinci-resolve-cli\u002Factions\u002Fworkflows\u002Fbuild.yml)\n[![Tests](https:\u002F\u002Fgithub.com\u002FPoechant\u002Fdavinci-resolve-cli\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FPoechant\u002Fdavinci-resolve-cli\u002Factions\u002Fworkflows\u002Ftest.yml)\n\nA CLI for DaVinci Resolve 18+ — project \u002F media \u002F render \u002F timeline control for humans and AI agents.\n\n## Demo\n\n```console\n$ dvr doctor --format json | jq '{version, edition, bridgeStatus}'\n{\n  \"version\": \"19.1.4.11\",\n  \"edition\": \"Studio\",\n  \"bridgeStatus\": \"ok\"\n}\n\n$ dvr project current --format json\n{\n  \"name\": \"Untitled Project\",\n  \"timelineCount\": 1,\n  \"framerate\": 24.0,\n  \"resolution\": { \"width\": 3840, \"height\": 2160 }\n}\n\n$ dvr render presets --format json | head -3\n[\n  \"H.264 Master\",\n  \"ProRes 422 HQ\"\n\n$ dvr timeline marker add --at 00:00:01:00 --note \"review\" --color Green --format json\n{ \"ok\": true, \"frame\": 24, \"timecode\": \"00:00:01:00\" }\n\n$ dvr mcp   # ← then any MCP client (stdio) can call 20 tools\n```\n\n> An animated demo will replace this snapshot once `vhs docs\u002Fdemo.tape` can be run on macOS 15 (the tape script and `docs\u002Fdemo.tape` source are already in the repo).\n\n## Install\n\n```bash\npipx install davinci-resolve-cli\n```\n\nRequires DaVinci Resolve 18+ already installed (Studio recommended). macOS first; Windows\u002FLinux follow.\n\n## Quickstart\n\n```bash\n# Health check\ndvr doctor\n\n# Project ops\ndvr project list\ndvr project current\n\n# Media batch\ndvr media import ~\u002Ffootage --recursive --bin \"Day1\"\n\n# Render (async)\nJOB=$(dvr render submit --preset \"H.264 Master\" --timeline cur --output ~\u002Fout.mp4 --format json | jq -r .jobId)\ndvr render wait \"$JOB\"\n\n# Timeline scripted edits\ndvr timeline marker add --at 01:00:05:00 --note \"review\"\n```\n\n## Capabilities at a glance\n\n| Domain | Subcommands | What it does |\n|--------|-------------|--------------|\n| `doctor` | — | Diagnose the Resolve bridge environment (version, Studio \u002F Free, API path, issues) |\n| `project` | `list \u002F current \u002F open \u002F new \u002F close \u002F save \u002F export \u002F import` | Project library CRUD |\n| `media` | `import \u002F list \u002F tag` | Media-pool batch ops — recursive import, per-bin lookup, 16 named flag colors, partial-failure reporting |\n| `render` | `presets \u002F submit \u002F status \u002F list \u002F wait \u002F cancel` | Async render queue. `submit` returns a `jobId` immediately; `wait` blocks until terminal (`completed` \u002F `failed` \u002F `cancelled`) |\n| `timeline` | `list \u002F current \u002F open \u002F new \u002F delete \u002F clips \u002F cut* \u002F move*`\u003Cbr>`marker add \u002F delete \u002F list` | Timeline CRUD + marker ops. *`cut` and `move` go through the WI bridge but currently emit placeholder behavior because Resolve has no public razor \u002F clip-move API — see [`docs\u002Fwi-research.md`](docs\u002Fwi-research.md). |\n| `mcp` | — | Start a stdio MCP server exposing 20 tools (one per CLI verb), each with a JSON-Schema'd `inputSchema` |\n| `subtitle` | `import \u002F export` | Round-trip `.srt` \u002F `.vtt` between disk and the timeline subtitle track |\n| `config` | `show \u002F init` | TOML-driven defaults; `\u003Ccwd>\u002F.dvr\u002Fconfig.toml` and `~\u002F.dvr\u002Fconfig.toml` merged, CLI flag > project > user > built-in |\n| `install-wi` | `--uninstall \u002F --force` | Deploy \u002F remove the Workflow Integration plugin used by `timeline cut` and `timeline move` |\n\nConventions across every command:\n\n- `--format json|yaml|table` — JSON by default in non-TTY, `table` (rich) in TTY, override via `DVR_OUTPUT`\n- Structured errors on stderr — `{\"errorCode\", \"message\", \"hint\"}`, stable codes (`resolve_not_running`, `validation_error`, `not_found`, `api_call_failed`, `wi_unavailable`, …)\n- `--dry-run` on every mutating command — prints the `planned` actions without touching Resolve\n- Exit codes: `0` ok, `1` user error, `2` Resolve unavailable, `3` API call failed\n\n## Output formats\n\n| context | default |\n|---------|---------|\n| TTY     | `table` (rich) |\n| pipe \u002F non-TTY | `json` |\n\nOverride with `--format json|yaml|table` or `DVR_OUTPUT=yaml`.\n\n## AI Agent\n\n`dvr` ships **two** complementary AI-agent integration paths.\n\n### 1. Skill file (`SKILL.md`)\n\nA SKILL.md packaged with the wheel; auto-discovered by skill systems that scan installed packages. Five worked example prompts:\n\n- \"Render the current timeline as 1080p mp4\"\n- \"List clips imported today and tag them green\"\n- \"Wait for render job X and tell me when it finishes\"\n- \"Check if Resolve is ready\"\n- \"Tag all clips in Day1 bin as Green for review\"\n\n### 2. MCP server (`dvr mcp`)\n\nStandard stdio MCP server exposing 20 tools across `doctor` \u002F `project.*` \u002F `media.*` \u002F `render.*` \u002F `timeline.*` namespaces. Any MCP-aware AI client can wire it up:\n\n```jsonc\n\u002F\u002F .mcp.json or your client's MCP server config\n{\n  \"mcpServers\": {\n    \"davinci-resolve\": {\n      \"command\": \"dvr\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nTool errors are returned as structured JSON `{\"errorCode\", \"message\", \"hint\"}` matching the CLI's stderr contract — same error codes (`resolve_not_running`, `validation_error`, `not_found`, etc.) so an agent can branch on them deterministically.\n\nVerify the server is reachable:\n\n```bash\ndvr mcp   # blocks, reads stdin\u002Fwrites stdout per MCP spec\n```\n\n## Architecture\n\n```mermaid\nflowchart LR\n    Human[\"Human\u003Cbr\u002F>(terminal)\"]\n    Agent[\"AI agent\u003Cbr\u002F>(MCP client)\"]\n    CLI[\"dvr CLI\"]\n    MCP[\"dvr mcp\u003Cbr\u002F>(stdio)\"]\n\n    Boot[\"bootstrap.py\"]\n    DVRScript[\"DaVinciResolveScript\"]\n    Resolve[\"DaVinci Resolve 18+\"]\n\n    WIServer[\"wi_client.py\u003Cbr\u002F>(localhost:50420)\"]\n    WIPlugin[\"WI plugin\u003Cbr\u002F>(JS, inside Resolve)\"]\n\n    Jobs[\"~\u002F.dvr\u002Fjobs.json\"]\n\n    Human -->|argv| CLI\n    Agent -->|tool calls| MCP\n    MCP -->|same helpers| CLI\n    CLI --> Boot --> DVRScript --> Resolve\n    CLI -->|render jobs| Jobs\n    CLI -->|cut\u002Fmove\u003Cbr\u002F>JSON-RPC| WIServer\n    WIPlugin -->|poll \u002Finbox\u003Cbr\u002F>POST \u002Fresult| WIServer\n    WIPlugin --> Resolve\n```\n\nFive command domains, two transports (CLI + MCP), one bridge (`DaVinciResolveScript`), one escape hatch for ops the Python API doesn't cover (Workflow Integration). Full write-up in [`docs\u002Farchitecture.md`](docs\u002Farchitecture.md).\n\n## Compatibility\n\n| OS | Status |\n|----|--------|\n| macOS (Apple Silicon \u002F Intel) | ✅ primary, end-to-end verified |\n| Windows | ✅ unit + CI tested (real-Resolve smoke pending community feedback) |\n| Linux | ✅ unit + CI tested (Resolve Studio Linux only) |\n\n| Resolve | Status |\n|---------|--------|\n| 18.x Studio | ✅ |\n| 18.x Free   | ⚠️ partial (render encoders limited) |\n| 17.x or older | ❌ unsupported |\n\n## Cookbook\n\nFive end-to-end recipes covering the most common workflows. Each is a copy-paste shell snippet that assumes DaVinci Resolve 18+ Studio is running and a project is open.\n\n### 1. Render the current timeline as 1080p H.264 mp4\n\n```bash\n# Preflight: make sure the bridge is healthy\ndvr doctor --format json | jq -e '.bridgeStatus == \"ok\"' >\u002Fdev\u002Fnull || { echo \"Resolve not ready\"; exit 2; }\n\n# Pick the first preset whose name contains \"H.264\"\nPRESET=$(dvr render presets --format json | jq -r '.[] | select(test(\"H\\\\.264\"; \"i\"))' | head -1)\n\n# Submit (async — returns immediately), then block until done\nJOB=$(dvr render submit --preset \"$PRESET\" --timeline cur --output ~\u002FRenders\u002Fout.mp4 --start --format json | jq -r .jobId)\ndvr render wait \"$JOB\"   # progress to stderr, terminal status to stdout\n```\n\n### 2. Import a SD card's footage into per-date bins\n\n```bash\n# Assumes ~\u002Ffootage\u002F\u003CYYYY-MM-DD>\u002F structure\nfor day_dir in ~\u002Ffootage\u002F*\u002F; do\n  day=$(basename \"$day_dir\")\n  dvr media import \"$day_dir\" --bin \"$day\" --recursive --format json | jq '.imported | length' \\\n    | xargs -I{} echo \"imported {} clips into '$day'\"\ndone\n```\n\n### 3. Tag every clip in a bin as \"Green\" for review (skipping ones already tagged)\n\n```bash\nBIN=\"Day1\"\nIDS=$(dvr media list --bin \"$BIN\" --format json \\\n  | jq -r '.[] | select(.flags | index(\"Green\") | not) | .id')\n[ -n \"$IDS\" ] && dvr media tag $IDS --color Green --format json\n```\n\n### 4. Drop chapter markers from a CSV file (timecode, label)\n\n```bash\n# chapters.csv:\n#   00:00:00:00,intro\n#   00:01:30:00,demo\n#   00:04:15:00,outro\nwhile IFS=, read -r tc label; do\n  dvr timeline marker add --at \"$tc\" --name \"$label\" --color Sky --format json >\u002Fdev\u002Fnull\ndone \u003C chapters.csv\n\ndvr timeline marker list --format json | jq '.[] | \"\\(.timecode) → \\(.name)\"'\n```\n\n### 5. AI agent: render via MCP server\n\nWire `dvr mcp` into any MCP-aware client (most desktop AI assistants now support MCP — check your client's docs for the right config file path):\n\n```jsonc\n\u002F\u002F ~\u002F.config\u002F\u003Cclient>\u002Fmcp.json\n{ \"mcpServers\": { \"davinci-resolve\": { \"command\": \"dvr\", \"args\": [\"mcp\"] } } }\n```\n\nThen ask the agent:\n\n> \"Render the currently open timeline as 1080p H.264, save it to ~\u002Fout.mp4, and tell me when it's done.\"\n\nThe agent will call `doctor` → `render.presets` → `render.submit(start=true)` → `render.wait` automatically. Tool errors come back as structured `{errorCode, message, hint}` so the agent can branch on `resolve_not_running` \u002F `validation_error` \u002F etc. deterministically.\n\n## Configuration\n\n`dvr` reads two optional TOML files and merges them with this precedence (highest wins):\n\n1. **CLI flag** — per command, always wins\n2. **`\u003Ccwd>\u002F.dvr\u002Fconfig.toml`** — project-local; commit it to your repo so your team shares the same defaults\n3. **`~\u002F.dvr\u002Fconfig.toml`** — user-global; your personal preferences across all projects\n4. **Built-in defaults**\n\nInitialize a commented sample in the current project:\n\n```bash\ndvr config init\n```\n\nSee exactly which layer every effective value came from:\n\n```bash\ndvr config show --format json | jq '.sources'\n```\n\nInitial supported fields (more can be added incrementally without breaking changes):\n\n```toml\n[defaults]\noutput_format = \"json\"     # default --format for table-capable commands\nbin = \"Master\"             # default --bin for media import \u002F list\npreset = \"H.264 Master\"    # default --preset for render submit\nmarker_color = \"Blue\"      # default --color for timeline marker add\nmarker_duration = 1\n```\n\n## Troubleshooting\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>`dvr doctor` reports `resolve_not_running` but Resolve is open\u003C\u002Fb>\u003C\u002Fsummary>\n\nMake sure:\n1. A project is open inside Resolve (the splash \u002F project picker doesn't count).\n2. Preferences → System → General → **External scripting using** is set to `Local`. The default is `None`; `Local` is required for DaVinciResolveScript to accept connections.\n3. You're on Resolve **18 or newer**. `dvr doctor` will tell you the detected version under `version`.\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Free vs Studio — what works on Free?\u003C\u002Fb>\u003C\u002Fsummary>\n\n`dvr doctor` reports your edition in the `edition` field. On Free:\n\n- ✅ All `project`, `media`, `timeline marker *` commands work\n- ⚠️ `render submit` works but some preset codecs (DNxHR, ProRes 4444, etc.) are Studio-only — the job will queue but fail at encode time\n- ❌ `dvr install-wi` deploys the plugin but **Workflow Integrations require Resolve Studio** at runtime, so `timeline cut \u002F move` will return `wi_unavailable` on Free\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>`pipx install` fails with `No matching distribution found for mcp>=1.0`\u003C\u002Fb>\u003C\u002Fsummary>\n\nYour Python is 3.9 or older. dvr 0.2.1+ requires **Python 3.10+** because the `mcp` SDK does. Check with `python --version`. If your system Python is too old, install a newer one (`pyenv install 3.12`, `brew install python@3.12`, or use Homebrew Cask).\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Windows: `dvr doctor` can't find `DaVinciResolveScript`\u003C\u002Fb>\u003C\u002Fsummary>\n\nResolve's default install path on Windows is `%PROGRAMDATA%\\Blackmagic Design\\DaVinci Resolve\\Support\\Developer\\Scripting\\`. If you installed Resolve to a custom location, set these two env vars before running `dvr`:\n\n```cmd\nset RESOLVE_SCRIPT_API=\u003Cyour-path>\\Support\\Developer\\Scripting\nset RESOLVE_SCRIPT_LIB=\u003Cyour-path>\\fusionscript.dll\n```\n\n`dvr doctor --format json` shows the resolved `apiPath` and `libPath` — useful to confirm what we tried.\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>I ran `dvr install-wi` but the bridge doesn't show up in Resolve's Workspace menu\u003C\u002Fb>\u003C\u002Fsummary>\n\n1. **Restart Resolve.** Workflow Integrations are scanned at launch.\n2. Check you're on **Resolve Studio** — WI is Studio-only.\n3. macOS: the plugin must land at `~\u002FLibrary\u002FApplication Support\u002FBlackmagic Design\u002FDaVinci Resolve\u002FFusion\u002FWorkflow Integration Plugins\u002Fdvr-cli-bridge\u002F`. `dvr install-wi --format json` prints the destination — verify the path exists and contains `manifest.xml \u002F index.html \u002F server.js`.\n4. After enabling under Workspace → Workflow Integrations, a small panel should pop up showing \"Polling localhost:50420…\". If you don't see it, check Resolve's `console.log` (Help → Logs).\n\u003C\u002Fdetails>\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npytest                              # unit only\npytest -m integration               # requires Resolve running\n```\n\n## License\n\nMIT\n","davinci-resolve-cli 是一个为 DaVinci Resolve 18+ 设计的命令行工具，用于项目、媒体、渲染和时间线控制。它通过提供丰富的子命令来实现对 DaVinci Resolve 的自动化操作，支持项目管理、媒体导入与标签、渲染队列提交及监控等功能。该工具使用 Python 编写，并遵循 MIT 许可协议，适合需要批量处理视频编辑任务或希望将 DaVinci Resolve 集成到自动化工作流中的用户。无论是人类还是 AI 代理，都可以利用此 CLI 来提高工作效率。",2,"2026-06-11 04:01:48","CREATED_QUERY"]