Cut Review

Cut Review：将 Frame.io 评论和客户备注转为 Final Cut Pro 待办标记

**Cut Review 是一款免费的 Final Cut Pro 开源命令行工具和 MCP 服务。**它会将客户备注和 Frame.io 评论导出内容写入项目的 FCPXML，作为待办标记添加到相关片段上。重新剪辑后，它会对比两份 FCPXML 导出文件，并在一个页面上显示更改内容，以及重新剪辑改动了哪些备注，无论编辑是由你还是 AI Agent 完成的。

演示轮次的状态页面，使用合成测试媒体。网站：daredev256.github.io/cutreview

**已在 Final Cut Pro 12.4 中验证：**待办标记、备注文本和编辑的勾选项在往返过程中均可保留（验证证明）。

这不是什么

• **不是审片平台。**没有服务器、没有账户，也无需上传。每个页面都是磁盘上的一个 HTML 文件，无需加载任何内容。
• 只说“已改动”，绝不说“已处理”。“已改动”表示备注附近的剪辑发生了变化。变化是否符合审阅者的要求由你判断，页面绝不会声称它做出了判断。
• **备注处理流程不使用 AI。**备注由你可以查看的规则读取，见 src/cutreview/notes.py。没有时间码的备注会列为未放置，绝不会被赋予时间。无法读取的行会附上原因列出，绝不会被丢弃。
• **不是剪辑器。**它只写入标记，不做其他操作。它绝不会更改片段，也绝不会打开或控制 Final Cut。

快速开始（60 秒）

你需要 uv（brew install uv）、Python 3.10 或更高版本，以及从 Final Cut Pro 导出的项目 XML（File > Export XML）。

1. 在 notes.txt 中编写备注，每行一条，时间码放在开头：

   00:00:05:00 Too long on B, cut it down
   00:00:13:00 Drone could breathe, slow it down
   

2. 将备注作为待办标记添加到剪辑中：

   uvx cutreview notes cut.fcpxmld notes.txt
   

   这会写入 cut_notes.fcpxmld，并显示每条备注对应的位置。在 Final Cut 中，选择 File > Import > XML，然后打开时间线索引（Shift-Command-2）查看待办事项。
3. 重新剪辑。勾选你已处理的每条待办事项。再次选择 File > Export XML，例如将文件命名为 cut_v2.fcpxmld。
4. 查看重新剪辑改动了哪些备注，以及有哪些变化：

   uvx cutreview status cut_notes.fcpxmld cut_v2.fcpxmld -o status.html
   uvx cutreview diff cut_notes.fcpxmld cut_v2.fcpxmld -o review.html
   

如果路径中有 ffmpeg，则会添加前后帧（可选）。同一台 Mac 上安装 Final Cut Pro 后，每次写入都可以使用 Apple 自己的 FCPXML DTD 进行校验（可选；未安装时，校验结果会说明未运行）。

功能介绍

notes.txt ──► cutreview notes ──► cut_notes.fcpxml  (to-do markers on the clips)
                                       │
                         you, or an agent, recut it in Final Cut
                                       │
              cut_notes.fcpxml + next export ──► cutreview status ──► status.html

1. cutreview notes 会将每条备注写成 Final Cut 待办标记（completed="0"），放在该时刻画面所在的片段上，并使用该片段自身的源时间，因此重新剪辑后，标记仍会随片段移动。备注全文会写入标记的备注字段。
2. 重新剪辑。处理完待办后，在 Final Cut 中勾选它。导出 XML。
3. cutreview status 会读取下一次导出文件。每条备注都有两种状态：已完成或待处理（由你勾选，Final Cut 会将其写入 XML），以及已改动或未改动（该备注前后 1 秒内的剪辑是否发生变化）。页面会优先显示两种状态不一致的项目：已勾选但未改动，以及已改动但未勾选。如果备注所在的片段已被删除，则会显示“随片段一起移除”。

另外两个命令可用于任意两个导出文件，无论其中是否包含备注：

• cutreview diff old.fcpxml new.fcpxml -o review.html：生成变更页面，列出所有新增、移除、修剪、移动、变速或调整的片段，以及新增或移除的转场；页面会显示时间线片段条，并在媒体文件位于本机时显示变更前后的画面。如果片段只是因为前面的内容变短而滑动，则会计入变更，但不会单独列出。
• cutreview blame old.fcpxml new.fcpxml：生成相同的页面，并根据 fcp-mcp-server 的写入日志，将每项变更归因于执行该操作的工具调用。日志无法解释的变更会显示“日志中未记录”。

演示轮次截图（合成媒体）：变更页面、状态页面、手机上的状态页面、手机上的归因页面、浅色模式。

常见问题

如何将 Frame.io 评论导入 Final Cut Pro？

将 Frame.io 评论导出为 CSV（在 Frame.io V4 中：打开“Comments”标签页的三点菜单），然后运行 uvx cutreview notes cut.fcpxmld comments.csv，并通过 File > Import > XML 导入生成的文件。Cut Review 会根据 Commenter 和 Comment 列识别 Frame.io 导出文件，将每条评论写成其下方片段上的待办标记，把回复合并到其所回复的评论中，为画有涂鸦的评论添加标记，并将已标记为完成的评论写成已完成标记。

它支持 Final Cut Pro 12.4 吗？

支持。Final Cut Pro 12.4 导入了 Cut Review 写入的 6 个待办标记，时间点精确，且片段正确；它在时间线索引中显示了标记备注文本，并将编辑者的勾选状态以 completed="1" 写入 XML 导出文件。Cut Review 重新读取该导出文件后，识别出 1 处修剪、2 条已勾选但未改动的备注，以及 1 条已改动但未勾选的备注，与实际情况一致。该测试媒体上的运行过程记录在 docs/final-cut-proof.md 中，并保留为测试。

它支持 Frame.io V4 吗？

Frame.io 文档说明，V4 的评论可导出为 CSV 或纯文本，但没有公布列名列表。Cut Review 按列名读取数据，不依赖列的位置；目前已用根据 V3 时代公布的列名重建的文件进行测试，尚未用真实的 V4 导出文件测试。如果无法读取你的导出文件，请附上表头行提交问题。

如何将 CSV 格式的备注导入为 Final Cut Pro 标记？

任何带标题行的 CSV 都适用：Cut Review 会按名称查找时间列（timecode、time、tc、in、start……），并以同样的方式查找备注列（note、comment、text、feedback……）；如果有作者列，也会一并读取。uvx cutreview notes cut.fcpxmld notes.csv 会将它们写为待办标记。没有时间的行会列为未放置，不会猜测时间。

如何比较两个 FCPXML 文件，查看两次 Final Cut 导出之间有哪些变化？

uvx cutreview diff cut_v1.fcpxmld cut_v2.fcpxmld -o review.html 会生成一个 HTML 页面，列出所有新增、移除、缩短、移动、重新定时或调整过的片段，以及所有转场变化，并附带时间线条和前后帧。片段按源素材而非名称匹配，因此涟漪编辑、片段头部修剪或基于连接片段构建的剪辑都能正确显示。

如何检查 AI Agent 对我的剪辑做了哪些更改？

在 Agent 工作前后的导出文件上运行 cutreview diff。如果 Agent 是通过 fcp-mcp-server 编辑的，uvx cutreview blame before.fcpxml after.fcpxml 会根据该服务的写入日志，指出每项更改背后的工具调用，并将手动完成的操作标记为“日志中没有记录”。如果你在时间线上添加了备注，cutreview status 会显示 Agent 的更改影响了哪些备注。

如何追踪重剪处理了哪些客户备注？

使用 cutreview notes 将备注作为待办标记添加到时间线上，工作时在 Final Cut 中勾选，然后对下一次导出运行 cutreview status。每条备注都会显示为已完成或未完成（根据你的勾选状态），以及已触及或未触及（剪辑是否在其前后 1 秒内发生变化）；页面开头会列出这两种状态不一致的备注。

Cut Review 是 Frame.io 的替代品吗？

不是。它不托管视频，也不收集客户评论。它处理你已有的备注，无论这些备注来自 Frame.io、电子邮件、短信还是通话；也处理 Final Cut 自带的 XML 导出文件。

有适用于 Final Cut Pro 的 MCP 服务吗？

有：fcp-mcp-server 可让 Claude 和其他 MCP 客户端通过 FCPXML 读取和编辑 Final Cut Pro 时间线。Cut Review 是与之配套的审阅步骤，提供一个 MCP 工具 review，包含 diff、blame、notes 和 status 操作（参见作为 MCP 工具）。

对比

	Cut Review	Change List X	Marker Toolbox	Frame.io V4
产品类型	免费、开源的命令行工具和 MCP 服务（MIT）	Mac 应用，US$199.99	Final Cut 工作流扩展，US$19.99	托管式审阅平台，提供免费和付费方案
将备注作为标记导入 Final Cut	支持：纯文本、任意 CSV、Frame.io 评论 CSV；作为片段上的待办标记	不支持	支持：Frame.io FIOJSON（包括 V4 beta）、Vimeo、Wipster、Dropbox Replay、Premiere CSV、Timecode+、电子邮件文本；已解决的评论会标记为已完成	可将评论导出为 CSV 或文本；其 V3“将评论导入 FCP”文章现在会重定向到帮助中心主页
比较剪辑的两个版本	任意两个 FCPXML 导出文件，包含所有轨道，并按源素材匹配	比较两个项目的主故事线，生成 PDF 或 TSV 更改列表，并附带提取和舍弃列表	不支持	并排或叠加播放两个上传的版本：比较的是画面，而非时间线中的片段
哪些备注受到重新剪辑的影响	支持：对照已更改或未更改的内容，显示已完成或未完成的备注	不支持	不支持	不支持
哪次 Agent 工具调用进行了每项更改	支持，来自 fcp-mcp-server 的日志	不支持	不支持	不支持

信息取自各产品自身页面，日期为 2026-11-12：Change List X、Marker Toolbox、Frame.io 评论导出、Frame.io Comparison Viewer。价格为美国 Mac App Store 标价。

如果你需要以英尺和帧为单位，为声音或 VFX 制作整理更改列表，并附带提取和舍弃列表，请使用 Change List X。如果你的备注来自 Vimeo、Wipster、Dropbox Replay 或 Frame.io 的 FIOJSON 下载文件，或者想将绘制的注释一并导入，请使用 Marker Toolbox。Cut Review 适用于备注已经添加到剪辑之后的步骤：了解重新剪辑实际更改了哪些备注。

备注入口

$ cutreview notes music-video.fcpxml music-video.notes.txt
6 notes written as to-do markers into music-video_notes.fcpxml
Times counted from the sequence's start timecode.
  #1   00:00:00:12  on SHOT A 1: Open on something brighter, this feels flat
  #2   00:00:05:00  on SHOT B 1: Too long on B, cut it down
  #3   00:00:02:12  on OVERLAY 1: Overlay 1 is too busy, lose it
  #4   00:00:10:12  on OVERLAY 3: Overlay 3 distracts from the lyric
  #5   00:00:13:00  on DRONE 1: Drone could breathe, slow it down
  #6   00:00:30:00  on TRACK (audio only under it): Hold on the performance here
2 not placed (listed, never guessed):
  music-video.notes.txt line 8: no timecode: Overall the colour is great, no notes on the grade
  music-video.notes.txt line 11: after the end of the cut: Fade out sooner
2 unreadable (listed, never dropped):
  music-video.notes.txt line 9: '00:01:75:00' has minutes or seconds past 59: 00:01:75:00 Check the lyric sync
  music-video.notes.txt line 10: a timecode with no note after it: 00:00:13:00
Checked: Valid against FCPXML 1.13 DTD (FCPXMLv1_13.dtd); 6 markers read back on their clips, each within one frame.
Ledger: music-video_notes.fcpxml.cutreview.json

支持读取三种格式：

• 纯文本：每行一条备注，时间码在前：00:01:23:12 note、1:23 note、[00:01:23:12] note、范围格式 00:01:23:12 - 00:01:25:00 note。缩进行会接续到上一条备注中。
• CSV：包含标题行。根据列名查找时间列（timecode、time、tc、in、start……）、备注列（note、comment、text、feedback……），以及作者列（如果存在）。时间可以是时间码，也可以是纯秒数。
• Frame.io 评论 CSV 导出文件：通过 Commenter 和 Comment 列识别。按列名匹配，因此即使添加或调整列的顺序，也能正常读取。回复会合并到其所回复的评论中；绘制的评论会加以标记；已标记为完成的评论会写入为已完成标记。--source-tc 使用 Timecode Source 列。Frame.io 未发布 V4 的列名列表；列名来源请参见 DECISIONS.md。

时间码从序列的起始时间码开始计数，与 Final Cut 中的显示方式一致。如果序列从零开始、剪辑长度不足一小时，而且所有备注的时间码都晚于 01:00:00:00，cutreview 会将文件识别为起始时间码为一小时的审阅副本，并说明这一点。--start-tc 可手动设置起始时间码。

每次写入都会执行两项检查，任一项失败都不会留下文件：使用已安装的 Final Cut Pro 自带的 Apple FCPXML DTD 运行 xmllint 检查；再通过 fcp-mcp-server 的解析器回读文件，确认每个标记都位于对应片段上，误差不超过一帧。文件写入为 FCPXML 1.13（输入为 1.14 时则保留 1.14）。

剪辑变更记录

cutreview diff 比较的是素材，而不是片段名称。每个片段都是源文件中的一个范围；两个剪辑会按源文件逐一比较：

含义	适用情形
已移除 / 已添加	片段的素材全部消失，或全部为新增
已修剪	片段素材的一部分从开头、结尾或中间移出或移入
已移动	素材现在在主故事线中按不同顺序播放，或连接片段离开了锚点或移至其他轨道
已变速	片段的速度发生变化
已调整	adjust-* 或 filter-* 设置发生变化，或片段已停用
转场	转场已添加、移除或时长发生变化

仅随波纹编辑滑动的片段会计入统计，但不会列出。页面上显示的帧是源帧：不会绘制效果、标题和调色。

cutreview blame 会从 FCP_MCP_JOURNAL、项目文件夹（或其中的 journal/ 或 .fcp-mcp/journal/），或 ~/.fcp-mcp/journal/ 读取 fcp-mcp-server 的日志，并从旧文件开始逐个哈希追溯。每项变更都会归到最后一次更改该素材的日志写入记录。如果最后一次日志写入之后的工作显示为“not in the journal (by hand in Final Cut, or a tool with no journal)”。如果两次写入之间的文件已丢失，则会将这两次写入一并列出。

作为 MCP 工具

uvx cutreview mcp

通过 stdio 提供一个工具 review，包含四种操作：diff、blame、notes、status。它写入的所有文件都会留在传入剪辑所在的文件夹中。

Claude Code：

claude mcp add cutreview -- uvx cutreview mcp

Claude Desktop 和其他接受 JSON 配置的客户端：

{
  "mcpServers": {
    "cutreview": { "command": "uvx", "args": ["cutreview", "mcp"] }
  }
}

它在官方 MCP 注册表中的名称是 io.github.DareDev256/cutreview。它与负责编辑的 fcp-mcp-server 配套使用。

参与开发

git clone https://github.com/DareDev256/cutreview && cd cutreview
uv venv && uv pip install -e ".[dev]"
.venv/bin/python -m pytest

“触及”的确切含义

如果某项变更位于备注在较早剪辑中的帧，或较晚剪辑中的标记附近一秒（--reach）范围内，则该备注视为受到触及。音频轨道上的变更只会触及位于音频上的备注，因此移动音乐底轨不会触及有关画面的备注。仅随波纹编辑滑动的片段不算变更，也不会触及任何内容。就是这样。备注旁的修剪会触及该备注，无论这是否是审阅者希望的修剪。

v0.1 的限制

• 仅支持 Final Cut。Resolve 和 Premiere 项目要等到 v0.2。
• Final Cut 往返流程只运行过一次，使用的是带一次修剪的测试媒体（docs/final-cut-proof.md）。下一轮将使用一个在 Final Cut 中进行了刀片剪辑、添加转场和变速的真实项目。
• 不支持语音备注、不支持未放置时间码的备注，也不能撤销单项变更。
• 变速坡道会按一个平均速度读取。
• 不会检查复合片段中的片段。

致谢

基于 fcp-mcp-server（MIT）构建，该项目提供 FCPXML 解析器、写入器的元素遍历器、写入日志和 DTD 检查。测试文件 fixtures/music-video.fcpxml 和 fixtures/sample.fcpxml 来自其示例；其许可证见 fixtures/LICENSE-fcp-mcp-server。

许可证

MIT。版权所有 (c) 2026 James Olusoga (DareDev256)，jamesdare.com。