内容
<div align="center">
<img src="docs/images/logo.png" alt="Wasserman's Unofficial DaVinci MCP" width="360">
# Wasserman's Unofficial DaVinci MCP
**让任何 AI 代理为您运行 DaVinci Resolve** — Claude Code, Codex, Cursor, Hermes 或任何 MCP 客户端。按照节拍剪辑，匹配参考外观，紧凑对话，达到响度规格，并构建时间线 — 直接驱动 Resolve Studio，或生成干净的导入文件用于免费版。
[](LICENSE)
<sub>一种扁平的 log-ish 等级（BEFORE）匹配到温暖的参考帧（REFERENCE）→ MATCHED 结果，烘焙到 33 点 `.cube` LUT。实际输出来自 `color_match` 引擎在一个单一的沙漠舞蹈帧上。</sub>
</div>
---
您用日常语言描述编辑；您的代理调用工具。服务器执行确定性的、数值的工作，而 LLM 不应该猜测 — 节拍网格、LUT 数学、EBU R128 响度、FCPXML — 并返回您可以信任的文件和计划。没有云渲染，没有黑盒：每个引擎都是 stdlib + numpy + ffmpeg，每个变异工具在触摸任何内容之前都会预览。
## 两个层级，自动检测
服务器在启动时检测它是否可以驱动正在运行的 **DaVinci Resolve Studio（验证 Studio 21）** 或应该回落到 **interchange** 文件。`resolve_capabilities` 告诉您您处于哪个层级以及原因。
| 能力 | Resolve **Studio** — *实时* | **免费** Resolve / 未运行 — *交换* |
|---|---|---|
| 工作方式 | 通过脚本 API 驱动正在运行的应用程序 | 编写您导入的 **一个操作** 文件 |
| 构建和编辑时间线 | 直接在应用程序中 | FCPXML 1.9 / EDL → `文件 ▸ 导入 ▸ 时间线` |
| 标记 | 实时插入 | 标记 CSV，或嵌入在 FCPXML 中 |
| 色彩分级和 LUT | 通过 API 应用每个剪辑 | 烘焙 `.cube` LUT 并将其放在节点上 |
| 渲染 | 排队和启动作业 | 使用 Resolve 自身的导出 |
| 探测，节拍网格，音乐剪辑，对话紧凑，响度和混音 | ✅ 引擎无论哪种方式都运行 | ✅ 引擎无论哪种方式都运行 |
| **外部脚本** | ✅ **仅限 Studio** | ❌ 免费 Resolve 中不可用 |
诚实地说：**外部脚本是 DaVinci Resolve Studio 功能。** 在免费版中，实时工具无法访问应用程序 — 但每个创意引擎仍然运行，交换写入器为您提供时间线、LUT、标记和预混音，您可以导入一步骤。免费路径没有任何内容是存根。
## 快速入门
直接从 GitHub 安装：
```bash
pip install "git+https://github.com/wassermanproductions/unofficial-davinci-mcp.git"
```
可选的额外功能 — 节拍跟踪 (`librosa`) 和语音桥：
```bash
pip install "unofficial-davinci-mcp[beats] @ git+https://github.com/wassermanproductions/unofficial-davinci-mcp.git"
pip install "unofficial-davinci-mcp[voice] @ git+https://github.com/wassermanproductions/unofficial-davinci-mcp.git"
```
或克隆并安装可编辑：
```bash
git clone https://github.com/wassermanproductions/unofficial-davinci-mcp.git
cd unofficial-davinci-mcp
pip install -e .
```
您还需要 **ffmpeg** 在您的 PATH 上 (`brew install ffmpeg`，或您的发行版的包管理器)。这是唯一的非 Python 依赖项。
### 将其连接到您的代理
**Claude Code** — 一行：
```bash
claude mcp add davinci -- unofficial-davinci-mcp
```
**任何 MCP 客户端** （通用 `mcpServers` JSON）：
```json
{
"mcpServers": {
"davinci": {
"command": "unofficial-davinci-mcp"
}
}
}
```
**Hermes** — `~/.hermes/config.yaml`：
```yaml
mcpServers:
davinci:
command: unofficial-davinci-mcp
```
如果控制台脚本不在您的 PATH 上，请使用 `python -m davinci_mcp` 作为命令。 然后要求您的代理首先调用 `resolve_capabilities` — 它报告您的层级，Resolve 版本，ffmpeg 和可选依赖项。
---
## 它能做什么
### 参考色彩匹配
指向 `color_match` 参考静止图像（或分级帧）和您要匹配的镜头。它在 CIE Lab 中采样两者，计算每个镜头的变换（Reinhard 平均值/标准差，或更牢固的 Lab 直方图匹配），并烘焙一个 Resolve 可加载的 **33 点 `.cube` LUT** — 以及一个前后预览条带和数值 ΔE 收敛。上面的英雄条带是一个真正的运行：一个扁平的色级被拉到一个温暖的参考，ΔE **43.9 → 3.2**。在 Studio 上，它可以为您应用 LUT；在免费 Resolve 上，您可以获取要放在节点上的文件。
### 一个完整的示例，从头到尾
> *"将这些剪辑剪辑到音乐中，给它一个温暖的外观，并将对话设置为 −16 LUFS。"*
一个请求，七个工具调用：读取层级，探测媒体，找到节奏，组装一个节拍快照编辑，编写 FCPXML，烘焙一个温暖的 LUT，并计划混音 — 上面的每个数字都是运行服务器的实际输出。
### 节拍感知的音乐剪辑
`beat_grid` 找到节奏，节拍，下拍和起始强度（安装时使用 librosa，否则使用能量包络备用）。`cut_music` 使用该网格将轨道修剪到目标长度 **在音乐边界上**，然后在指数衰减下削减尾部 — 或落在打击乐上带有“按钮”结尾。没有中途剪辑。
### 对话，响度和混音
- **`tighten_dialogue`** 检测对话剪辑中的死区并返回一个保持范围的剪辑计划（带有头/尾句柄）— 实时应用或导出紧凑的编辑为 FCPXML。
- **`measure_loudness`** 报告 EBU R128 综合 LUFS，响度范围和每个文件的真实峰值。
- **`mix_plan`** 将对话标准化为您的交付规格，设置音乐床并在其下，使用语音派生鸭子窗口，并渲染一个 **重新测量的** 预混音，以便您可以信任数字。
### 构建时间线
`assemble_edit` 验证编辑计划与探测的媒体并将剪辑快照到节拍网格。然后 `generate_fcpxml` 编写一个 **FCPXML 1.9** 时间线，干净地导入 Resolve 19/20，`generate_edl` 编写一个 CM3600 剪辑列表，`generate_marker_csv` 编写一个标记清单。在 Studio 上，`resolve_create_timeline` / `resolve_append_to_timeline` 直接在应用程序中构建。
---
## 37 个工具
每个变异工具默认为 `dry_run=true` 并返回一个计划；重新运行 `dry_run=false` 和 `confirm=true` 以应用它。层级 **两者** = 在免费或 Studio 中工作；**实时** = 需要 DaVinci Resolve Studio。
| 工具 | 层级 | 它做什么 |
|---|---|---|
| `resolve_capabilities` | 两者 | 报告活动层级，Resolve 版本，ffmpeg 和可选依赖项。 **先调用。** |
| `get_editing_knowledge` | 两者 | 提供编辑知识（色彩，节拍，对话，音乐，混音）并附上具体数字。 |
| `probe_media` | 两者 | ffprobe 文件：时长，帧率，分辨率，编解码器，音频通道/速率，时间码。 |
| `scan_media_folder` | 两者 | 扫描文件夹并探测每个媒体文件，按稳定排序顺序。 |
| `beat_grid` | 两者 | 估计节奏（BPM），节拍时间，下拍猜测和起始强度。 |
| `cut_music` | 两者 | 将歌曲剪辑到音乐边界上的长度，带有平滑的串出。 |
| `color_match` | 两者 | 将剪辑/静止图像匹配到参考；烘焙 33 点 `.cube` LUT 和预览。 |
| `measure_loudness` | 两者 | 测量 EBU R128 综合 LUFS，响度范围和每个文件的真实峰值。 |
| `mix_plan` | 两者 | 计划对话标准化 + 音乐床 + 鸭子；渲染重新测量的预混音。 |
| `tighten_dialogue` | 两者 | 检测对话剪辑中的死区；返回保持范围的剪辑计划。 |
| `assemble_edit` | 两者 | 验证编辑计划与探测的媒体；将剪辑快照到节拍网格。 |
| `generate_fcpxml` | 两者 | 编写导入 Resolve 的 FCPXML 1.9 时间线。 |
| `generate_edl` | 两者 | 编写 CM3600 EDL 剪辑列表以进行往返。 |
| `generate_marker_csv` | 两者 | 编写标记清单 CSV（帧，时间码，名称，颜色，注释）。 |
| `resolve_project_summary` | 实时 | 读取当前项目，时间线，活动时间线 fps 和标记。 |
| `resolve_render_status` | 实时 | 检查渲染进度和渲染队列。 |
| `resolve_import_media` | 实时 | 将媒体导入项目媒体池。 |
| `resolve_create_timeline` | 实时 | 从剪辑计划，音乐和标记中创建时间线。 |
| `resolve_append_to_timeline` | 实时 | 将剪辑（带有源/记录范围）附加到活动时间线。 |
| `resolve_add_markers` | 实时 | 将标记添加到活动时间线。 |
| `resolve_apply_lut` | 实时 | 将 `.cube` LUT 应用于时间线视频轨道上的剪辑。 |
| `resolve_set_grade` | 实时 | 在剪辑上设置 ASC CDL 斜率/偏移/功率/饱和度。 |
| `resolve_render` | 实时 | 配置并启动当前时间线的渲染作业。 |
---
## 它了解编辑，而不是按钮
操作应用程序是工作的一半；了解一个好的编辑 **是什么** 是另一半。`get_editing_knowledge` 提供与工具一起构建的相同编辑手册 — 写成一个经验丰富的编辑人员给助手简报的样子，并附上数字，您的代理可以采取：
- **按目的地进行响度。** 对话以 **−16 LUFS** 为网络 / **−23 LUFS** 为广播；音乐床骑在 **4–8 dB 下**；鸭子是 **−6 到 −8 dB**，带有 **0.3 秒攻击 / 0.5 秒释放**；主限幅器上限 **−1 dBTP**。`mix_plan` 将这些作为参数。
- **剪辑到能量，而不是节拍器。** 在 120 BPM 下，一个节拍是 **12 帧** — 所以剪辑一个 *移动* 镜头 **1–2 帧提前**，运动在感知上落在节拍上；保持 **8–16 个镜头每 8 个小节** 在合唱中，只有 **1–3** 在介绍中。`assemble_edit` 的节拍快照公差在 **±2 帧** 下降到 **下降**。
- **匹配，不要发明。** 对于青绿色，使用温暖的皮肤/凉爽的阴影帧，`method="lab_histogram"` 强度 **0.5–0.65**，并始终重新检查皮肤。永远不要将曝光或白平衡烘焙到外观 LUT 中。
主题：`color-looks`，`beat-cutting`，`dialogue-editing`，`music-editing`，`mixing`。
---
## 一键工作流
四个主要工具将上述引擎链接到单个调用中。每个工具首先计划（`dry_run=true`）并返回一个计划，您可以在写入任何内容之前检查。
### 自动编辑音乐
扫描一个素材文件夹，节拍网格歌曲，将其剪辑到长度，并创建一个节拍同步编辑，其剪辑密度跟踪歌曲的能量 — 长保持在介绍中，合唱中 1-2 个节拍剪辑 — 并附带一个理由。每个剪辑都带有理由，计划以 FCPXML 导出或实时馈送 `resolve_create_timeline`。
```text
auto_edit(music="track.wav", media_dir="./footage", target_seconds=30, style="music_video")
```
### 按内容搜索素材
一次性转录每个剪辑（缓存），然后按短语，所有单词或正则表达式搜索口语单词。命中返回带有时间戳和上下文的内容；`build_selects=true` 将它们剪辑成一个选择时间线，带有 0.5 秒的句柄。
```text
find_in_footage(query="let's go", media="./interviews", mode="phrase", build_selects=true)
```
### 字幕和章节
将转录内容转换为广播安全的 SRT/VTT 字幕（行长度，持续时间和孤词规则，语音快照定时，可选卡拉 OK），并从语音的主题转换中导出 YouTube 章节。
```text
generate_captions(media="talk.mp4", format="srt") # youtube_chapters(media="talk.mp4")
```
### 将时间线分级为参考
将每个剪辑匹配到参考帧，使用一个自动调谐的 LUT：循环读取质量报告并降低强度（低至 0.5 底线）直到分级通过其关卡，标记任何无法剪辑的剪辑为 `needs_human`。返回每个剪辑的 LUT 以及实时/交换应用清单。
```text
grade_timeline(reference_image="look.png", clips=[{"path": "a.mov", "in": 0, "out": 4}])
```
---
## 与编辑人员交谈
一个可选的 macOS **语音桥** 让您按住按键，说话，并将转录内容直接放入您的代理终端 — 手持素材，不用键盘。
它 **完全在您的 Mac 上运行**：`faster-whisper` 在本地转录，内容不会发送到云端，编辑术语（LUFS，J-cut，sting，FCPXML）被偏向模型以便清晰转录。设置，权限和配置在 **[voice/README.md](voice/README.md)** 中。
```bash
pip install "unofficial-davinci-mcp[voice] @ git+https://github.com/wassermanproductions/unofficial-davinci-mcp.git"
python -m voice
```
---
## 要求和故障排除
- **Python ≥ 3.10**，**numpy** 和 **ffmpeg** 在您的 PATH 上（在 `/opt/homebrew/bin`，`/usr/local/bin`，`/usr/bin` 作为回落）。在 macOS 上使用 `brew install ffmpeg` 或 Linux 上的发行版包管理器安装 ffmpeg。
- **`librosa`** 是可选的额外功能 (`[beats]`) 用于节奏跟踪的节拍网格；如果没有，它使用能量包络备用，仍然有效。
- **Studio vs 免费。** 实时工具需要 **DaVinci Resolve Studio**，正在运行，并启用外部脚本（**首选项 ▸ 系统 ▸ 通用 ▸ 外部脚本：本地**）。如果您使用的是免费版或 Resolve 未运行，服务器会自动降级为交换 — `resolve_capabilities` 解释原因。
- **“Studio required” / 握手失败。** 脚本模块加载但无法访问应用程序：确认 Resolve 已打开，您处于 Studio，并且启用了脚本。交换层面的所有内容仍然有效。
---
## 免责声明
**非官方。** 本项目与 Blackmagic Design 无关联，未授权或未获得 Blackmagic Design 授权。“DaVinci Resolve” 是 Blackmagic Design Pty Ltd 的商标。这是独立的社区工具，通过其公共脚本 API 和标准交换格式与 Resolve 通信。
---
## 许可证和致谢
**Apache License 2.0** — 请参阅 [LICENSE](LICENSE)。免费使用，修改，分支和构建，商业或其他用途均可。
**需要注明出处：** 根据 [NOTICE](NOTICE) 文件（Apache 2.0 §4(d)），任何使用，分支或重新分发必须保留 NOTICE 文件，并在其文档和关于/信用界面中提及 **Sam Wasserman ([wassermanproductions.com](https://wassermanproductions.com))**。
由 **Sam Wasserman** 创建 — [wassermanproductions.com](https://wassermanproductions.com) · [wasserman.ai](https://wasserman.ai)。
