FilmCraft — 由 Claude 驱动的视频编辑
本机安装
| 组件 | 位置 |
|---|---|
| 应用 + CLI（便携版 0.13.0） | %LOCALAPPDATA%\Programs\FilmCraft\（filmcraft.exe、filmcraft-cli.exe，数据在 data\ 中） |
| 启动器（控制通道 127.0.0.1:9876 + 令牌） | {{DEPOT}}\filmcraft-mcp\launcher\FilmCraftClaude.exe（桌面快捷方式“FilmCraft”） |
| 控制通道令牌 | %LOCALAPPDATA%\FilmCraft-Claude\control.token（绝不显示或复制到别处） |
| 配套 MCP（Python，uv） | {{DEPOT}}\filmcraft-mcp\server\ |
| FilmCraft 源代码（文档） | {{DEPOT}}\filmcraft\docs\（agents.md、control-protocol.md、captions.md、graphics.md） |
启动（始终按此顺序）
filmcraft_status（MCP filmcraft-assist）。如果running=false→filmcraft_launch（可附带files即项目.fcproj或媒体文件）。- 如果 MCP 工具延迟加载则加载它们：ToolSearch
+filmcraft（两个服务器）。 - 绝不将用户的工作装入演示项目：使用
command_run file.newProject {name}然后file.saveAs {path}到项目文件夹，或使用file.open {path}。
两个 MCP
| 需求 | 工具 |
|---|---|
| 状态 / 启动应用 | filmcraft_status、filmcraft_launch（assist） |
| 读取项目、ID | doc_inspect、project_inspect、sequence_inspect（filmcraft） |
| 执行操作 | command_run {id, params}、command_batch {steps, stop_on_error}、media_import（filmcraft） |
| 查找命令 | command_list {filter} 或在 references/commands.md 中 grep |
| 查看结果 | render_frame {seconds}、ui_screenshot {panel?}（filmcraft）；contact_sheet（assist）然后读取图片 |
| 编辑前分析片段 | media_probe → 若 VFR 则 media_conform（assist） |
| 逐字转录（法语） | transcribe_media（assist）— 绝不使用 transcript.generate（whisper-base，法语弱） |
| 对齐音乐 | music_beats {add_markers, every, offset_seconds}（assist） |
| 最终质量控制 | export_qc {path, platform}（assist） |
除 MCP 外，CLI 也可在 Bash 中运行（无头模式，无窗口）：filmcraft-cli --project p.fcproj --save exec <id> key=value、filmcraft-cli --project p.fcproj export out.mp4 --preset "YouTube 1080p Full HD"。
工作循环
- 检查（
sequence_inspect）→ 获取剪辑/元素的 ID。使用 razor 后 ID 会变：重新检查。 - 使用显式目标执行操作（
clips: [id]、item: id），而非使用选区。 - 通过查看验证：在关键点使用
render_frame、调色使用scopes.read、节奏使用contact_sheet。 - 如果出错：
command_run edit.undo。经常保存：file.save。
避免错误的关键规则
- 时间：ticks（254 016 000 000 / 秒）。大多数命令接受
seconds、frame或timecode→ 优先使用seconds。markers.add和sequence.addEdit需要time为 ticks。 - 序列 = 输出格式：
file.newSequence {name, width, height, fps, sampleRate: 48000}设置为广播标准（16:9 1920×1080、9:16 1080×1920、1:1 1080×1080），帧率 = 已转码片段的帧率。 - 法语语言标记：
transcript.removeFillers默认使用英语列表 → 始终传递fillers（由transcribe_media返回）。 - 长时间导出：
file.exportMedia {…, wait: true}。始终以export_qc然后对导出的文件使用contact_sheet结束。 - PATH 中的 ffmpeg 是 2013 年的版本：使用 assist 工具（ffmpeg 8 WinGet）或
%LOCALAPPDATA%\Microsoft\WinGet\Links\ffmpeg.exe。 - 命令被拒绝 "not available right now"：缺少条件（序列未打开、剪辑类型不正确、目标不正确）。读取
command_list {filter: "<id>"}→enabled字段。
菜谱
详细菜谱及精确参数：references/recipes.md。
- A. 教程 / 镜头前发言：probe → conform → 转录 → 剪掉“嗯”和空白 → 纯净人声 → 字幕 → 调色 → 导出 -14 LUFS → QC。
- B. 竖屏短视频 9:16：序列 1080×1920、裁剪、大字短字幕、预设“Social Vertical 1080×1920”。
- C. 音乐剪辑：
music_beats→ 节拍标记 → 在标记处切割 → 闪避。 - D. 调色：Lumetri（实际参数见
references/effects.md，效果lumetri）、镜头匹配lumetri.applyMatch、通过scopes.read控制。 - E. 混音：Essential Sound（对话/音乐）、闪避、Mix 上的限幅器 true peak。
- F. 导出 + QC：预设见
references/export-presets.md、loudnessLufs、captionSidecar、burnCaptions。
参考资料
references/recipes.md— 菜谱 A–F 的逐步指南及 JSON 参数。references/commands.md— 按类别划分的 710 条命令（grep：`timeline.`、`captions.`、`lumetri.`、`essentialSound.`、`export.`、`transcript.`）。references/effects.md— 303 个效果/转场及其参数 ID、边界和选项（grep：`lumetri`、`hard_limiter`、`cross_dissolve`）。references/export-presets.md— 39 个导出预设。scripts/gen_reference.py— 更新 FilmCraft 后重新生成三个参考文件：python -I scripts/gen_reference.py。
更新 FilmCraft
从 github.com/storytold/filmcraft/releases 下载 filmcraft-<ver>-windows-x64-portable.zip（验证 SHA256SUMS.txt），关闭 FilmCraft，替换 %LOCALAPPDATA%\Programs\FilmCraft\ 中的 filmcraft.exe 和 filmcraft-cli.exe（保留 data\ 和 portable.txt），然后重新运行 scripts/gen_reference.py。