Final Cut Pro 编辑（通过 FCPXML）

通过 FCPXML 编辑 Final Cut Pro 时间线

刚开始，先别急着改

始终先 inspect，再 diagnose，最后才 edit。时间线中包含的结构信息远不止文件名所示，一旦对结构做出错误假设，后续编辑将代价高昂。

1. 使用 inspect 的动作 analyze_timeline 了解时间线的形状、时长和分辨率。
2. 使用 diagnose 的动作 validate_timeline 查找间隙、闪帧和重复片段。
3. 在真正修改时间线之前，务必读取 preview://<path> 资源，亲眼查看当前时间线，它生成一个独立的 HTML 时间线，包括各自轨道行的连接素材，让你能看到 B-roll 和音频层，而不仅是主故事线。

七大功能组

分组	用途
inspect	只读了解。始终从此开始。
diagnose	发现问题：间隙、闪帧、静音、重复片段、节拍。
edit	修改剪辑：插入、删除、修剪、拆分、重新排序、变速、去除静音。
mark	标记和章节，包括导入 SRT/VTT 和节拍。
generate	构建新结构：粗剪、混剪、A/B 卷、模板，以及通过视频剪辑列表导入 import_edl_json。
transcript	本地转录，然后根据说话内容进行编辑或清理。transcript_pack 将一次拍摄的所有内容放在一页上——在规划对话编辑之前请先阅读。每个动作都可以指定 backend: "elevenlabs" 以获取说话人标签和音频事件；这会将媒体上传到 ElevenLabs，需要 ELEVENLABS_API_KEY；默认的 local 模式永远不出机器。
deliver	导出到其他非编软件、重格式化、重新链接、推入 Final Cut Pro。
preview	查看编辑效果：代理渲染、联系表，以及从源媒体读取的胶片条+波形。
watch	闭环：注意操作者的 Cmd-E 导出，并与上一次结果进行差异对比。
index	分析缓存。index_status 报告其时效；index_build 预热时间线中的所有源；index_clear 清空缓存。没有依赖关系。
scenes	从像素中检测镜头边界。detect_scenes 列出源和时间线时间内的剪辑切换点（如果通过 [scenes] 安装了 PySceneDetect，则使用之；否则使用 ffmpeg 的粗略场景过滤器）；scenes_to_markers 在每个切换点添加标记；scenes_split 在此处剪切剪辑。结果缓存在索引中。
organize	批量库管理及操作日志。organize_auto 根据缓存的标题和转录为每个剪辑建议关键词（apply=true 会写入）。通过 clip_name 通配符、keyword 和/或 role 选择剪辑，然后使用 organize_keywords（添加/删除/替换）、organize_rate（标记/取消标记/清除）或 organize_roles——每个操作都会生成一个 _organized 副本。history 列出该文件文件夹的所有已记录操作；undo 将最近的 n 个输出移动到日志的 undone/ 文件夹（从不删除，如果文件已更改则拒绝执行）。
find	“那段关于……的片段在哪？”作为路由。find_shots 根据说话内容（转录）、日志信息（名称、关键词、备注、标记、音频事件）以及（在安装 [find] 扩展并下载本地模型后）帧内容进行排序——第一行指出哪些层级回答了问题以及为什么某些层级无法回答。find_index 预热场景和标题，并报告哪些剪辑没有转录（从不转录，从不联网）。find_to_timeline 将命中结果组装成一个 _found 精选卷，带有多样性评分。

每次调用都采用 {"action": "...", "args": {...}} 格式。如果你传递的某个动作不属于该分组，错误信息会列出有效动作——仔细阅读而不是乱猜。

FCPXML 中可能让你踩坑的细节

• 时间是分数，不是浮点数。 3600/2400s 表示 1.5 秒。绝不要对时间码进行浮点运算，也永远不要自己四舍五入。
• offset 是时间线上的位置。start 是源素材的入点。 它们是两个不同的数值，混淆会导致无声的偏移。
• 库剪辑和时间线剪辑是不同的元素。 <asset-clip> 位于库中，<clip> 位于时间线上。
• 标记是剪辑的子元素，而非兄弟元素。
• <spine> 是主故事线。 连接素材通过轨道附着在主素材上：正数在上（视频），负数在下（音频）。
• .fcpxmld 捆绑包是目录，包含 Info.fcpxml 以及附带数据。保存时必须保留附带数据，否则物体跟踪和电影模式数据将丢失。
• 重复的剪辑名称很常见。 在工具同时提供这两种方式时，优先使用基于元素的操作，而不是名称查找。

去静音：选择正确的方法

有两组检测-修复配对，不能混用。它们遵循与本服务器中所有其他检测/修复配对相同的模式：检测器位于 diagnose，修复器位于 edit。

• detect_media_silence（diagnose）→ remove_media_silence（edit）：使用 ffmpeg 读取实际源音频，准确但较慢，需要安装 ffmpeg。
• detect_silence_candidates（diagnose）→ remove_silence_candidates（edit）：仅使用时间线启发式，快速、无需 ffmpeg，但结果为猜测。

在对正确性要求高的场景下使用基于媒体的版本。请明确说明你使用的是哪一种。

通常推荐的工作流程

1. inspect → diagnose → 读取 preview:// 资源。
2. 如果编辑以对话为主，则使用 transcript 的 transcript_pack 动作——将全部说话内容集中在一页，以便根据文字而非剪辑名称制定计划。
3. 使用 generate 进行粗剪，edit 进行精修，mark 添加章节。
4. 在告知编辑完成之前，使用 preview 的 preview_check 动作，对你修改过的范围进行检查。这是确保编辑不“盲”的关键。preview:// 资源和 preview_timeline 都从 XML 中提取数据——它们显示的是写入的内容，因此无法区分正确的剪辑和错误的剪辑。而 preview_check 读取的是实际媒体。不要用一个替代另一个，也不要在工具调用成功之后就跳过这一步。
5. 使用 deliver 进行导出或使用 push_to_fcp 推送到正在运行的应用程序。
6. 在会话开始时执行一次 watch_start，然后在操作者导出后再执行 watch_pull。Final Cut Pro 没有程序化导出——苹果从未提供过——所以这个循环只能在用户按下 Cmd-E 时关闭。请直接说明这一点，而不是沉默等待。

不要做

• 不要在未经过 diagnose 的情况下进行编辑。闪帧和间隙问题会累积。
• 不要假设已安装 ffmpeg 或 Whisper。两者都会优雅降级，不报错而直接返回空结果，所以请检查响应。
• 不要将 preview_render 摘要中的 UNVERIFIED 字样视而不见。这表示无法读取渲染文件的时长，因此渲染结果尚未得到确认。
• 不要忽视 Substituted: 这一行。代理渲染会将转场渲染为硬切，所以时间线上的叠化并不等于你在图中看到的效果。
• 除非调用了 push_to_fcp 并报告成功，否则不要声称编辑已进入 Final Cut Pro。写入 .fcpxml 文件并不等于导入它。
• 不要相信工具自身的成功消息能证明时间线看起来正确。请读取 preview:// 并亲眼检查。