/reel:面向Claude Code的视频制作
一个基于ffmpeg构建的分层工具。你(Claude)负责审视素材,决定呈现什么并编写计划;代码负责处理构图几何、渲染和检查。输出尺寸可配置(默认为1080x1920的垂直格式)。
命令和文件格式记录在reel仓库的docs/ENGINE.md中。在执行第一条命令之前,请先阅读它:cat "$(reel --root)/docs/ENGINE.md"。reel <command> --help 会列出所有选项。每个命令都会打印一个JSON对象({"ok": true, "result": ...} 或 {"ok": false, "error": {"code": ..., ...}}),并且在失败时以退出码1结束。
工作顺序:方向先行,再行剪辑
对于任何用户之外的人将会观看的视频,请遵循SOP.md:S0素材摄入,S1源打包,S2资产清单,S3-S4 一个 director 代理编写 direction/BRIEF.md 和故事板,然后立即开始剪辑(默认情况下,G1审批步骤不会阻塞流程),最后进入下面的交付关卡。在S7阶段,一个独立的 director 代理会根据BRIEF审查剪辑结果。作为插件安装后,该代理被命名为 reel:director。
- 将原始素材的路径提供给导演,而不是你自己的结论。
- 如果已存在经过审批的BRIEF,并且目的、受众和素材范围没有改变,请遵循它。
- 如果用户说视频很无聊或没有意义,请回到S3阶段重新构思整个作品;不要仅仅重新剪辑。
交付关卡(强制)
每个步骤都由代码强制执行:跳过任何一步,你都无法交付最终剪辑。
- 先写brief(
$P/brief.json,模板见下文)并注册它:reel register brief.json。交付语言、最终版或样片、交付文件夹以及不得更改的内容:如果你无法填写这些,请询问用户。一旦注册,Bash守卫钩子会拒绝向交付文件夹写入cp/mv/ffmpeg等操作。 - 试音。 没有默认语音。选择一个符合brief的语音,渲染一个10-20秒的样片,然后运行
reel voice check sample.mp3 --script sample.txt --brief brief.json。本地的Whisper会转录样片并与文本进行比较(--lang默认为en;对于中文配音,请传递--lang zh,它会通过无声调拼音进行比较,因此同音字拼写不会算作错误);只有当错误率低于或等于10%时,才会将审批写入brief.voice.approved(by: claude,并附上转录文本作为证据)。如果用户听过,请直接记录他们的确切措辞。- 语音转文字(STT)证明单词被正确且清晰地朗读。它不能证明语音适合该作品:在你的回复中说明你选择的语音,并在下一版本中更换语音(如果用户不喜欢)。
- 新的语音需要新的检查。macOS 的
say语音仅用于内部草稿,绝不可用于最终交付的视频。
- 检查渲染结果:
reel check final.mp4 --plan plan.json --brief brief.json [--profile vertical-strict|project-profile.json] [--text caption.txt]。- 退出码1意味着它无法交付。请阅读
result.gate.blockers(技术性失败:即使是样片也无法交付)和result.gate.pending_review(需要审阅者检查的项目)。 - 不要仅仅依赖
ok。result.gate.not_covered列出了未被检查的项目(例如屏幕上的文字,因为没有OCR);永远不要说这些项目已通过检查。
- 退出码1意味着它无法交付。请阅读
- 审查。 查看每一个
needs_review项目(reel scrub,逐帧抓取)并为每个项目编写一条带有时码观察的审查记录。自己观看整个剪辑并签署final_watch(每个镜头至少一帧);从头到尾听一遍并签署final_listen(代理签名需要带有时码的观察记录;如果用户听过,请将他们的确切措辞记录为quote)。当你签署了这两项后,即可将其作为最终版交付:收据上写着approved_by: agent,你的回复会说“最终剪辑,由Claude审查,您尚未观看”。用户的反馈将成为下一个版本的基础。reviews.json的格式在docs/ENGINE.md中。 - 交付:
reel deliver final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json。- 如果最终条件未满足,它会失败并显示
DELIVERY_NOT_FINAL,并列出原因。此时只能使用--sample:文件名会带有sample-pending-review,并且你在告知用户时必须称其为样片。 - 一个版本号只能交付一次;旧版本永远不会被删除或覆盖。只有当用户明确要求移除旧版本时:
reel register brief.json --remove,删除,然后重新注册。
- 如果最终条件未满足,它会失败并显示
- 说“完成” 需要一个状态为
final的收据(reel receipt <receipt.json>会重新验证它)。否则,请说明真实状态:“未完成”、“样片待审”、“语音未试音”。停止钩子(Stop hook)会阻止声称完成但没有匹配收据的情况。 - 由项目自身的渲染脚本(如
build_*.py)制作,或在其他工具中合成并导出的视频,也需经过步骤3-6。
{"version": "reel.brief.v1", "name": "spring-promo", "language": "en", "deliverable": "final",
"delivery_root": "~/Videos/deliveries/spring-promo", "must_not_change": ["end card credit"],
"voice": {"mode": "recorded"}, "profile": "default"}
voice.mode:none(无语音)、recorded(真实录音)、tts或clone(后两者还需要voice_id以及由reel voice check写入的approved块,或者带有quote、sample和sample_sha256的人工审批)。delivery_root必须是一个已存在的绝对路径(或以~开头)。它不能是home文件夹、桌面、文档、下载、iCloud Drive根目录、项目文件夹或其父目录。- 静音版本使用项目配置文件:
{"extends": "default", "audio": "silent"}。 - 配置文件:
default(通用的起始阈值)和vertical-strict(1080x1920 30 fps, -16 LUFS, 严格)。将项目差异放在一个使用extends的项目配置文件中;在allow中注册预期的长停顿并附上原因;将禁用词(旧产品名、占位文本)添加到text.extra_banned中。
在每个Bash调用的开头
每个Bash调用都会启动一个新的shell,因此请在每个调用的开头使用:
REEL_PROJECT=spring-promo # 此项目的名称
command -v reel >/dev/null || { echo "reel is not on PATH (enable the plugin, or run ./install.sh --link)" >&2; return 1 2>/dev/null || exit 1; }
command -v ffmpeg >/dev/null || { echo "ffmpeg not found" >&2; return 1 2>/dev/null || exit 1; }
P="${REEL_PROJECTS_DIR:-$HOME/reel-projects}/$REEL_PROJECT"; mkdir -p "$P/preview" && cd "$P"
所有输出文件都位于 $P 中,绝不要在临时文件夹中;下面的相对路径都是相对于 $P 的。
制作剪辑
你做决策(哪些镜头、哪个主体、摄像机运动、节奏);感知、几何、渲染和检查由代码完成。完整的命令语法在 docs/ENGINE.md 中。
- 素材 放入
$P(资产、observations.json、plan.json、预览、渲染和检查报告都存放在那里;每个计划一个文件夹)。 - 脚本和语音。 撰写配音脚本,选择符合brief的语音并通过试音(交付关卡第2步)。生成
voice.mp3(或.wav),如果需要字幕,则生成voice.vtt。对于出版作品,优先使用真实录音或其许可证覆盖所用场景的语音;对于纯音乐作品,将audio.voice指向音乐轨道(它是时间轴锚点)。 - 查看并选择目标:
reel inspect(列出每个文件)→reel frame(读取带有0-1网格的图像,并读取主体边界框)→reel observe注册它,或reel locate --query ... --check-png ...(OWLv2;在使用检测结果前,先查看检查图像)。 - 编写
plan.json(EditPlan v1):camera: []保持画面静止;zoom_to配合observation_id推近到已注册的主体上;当主体在视频中移动时使用track;transition_out用于转场。不要让一个视频镜头跨越inspect报告的镜头切换点。audio.voice是必需的,并且相对于src_dir解析。 - 验证和预览:
reel validate→reel compile→reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png,然后阅读联系表来评判摄像机运动。 - 渲染:
reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local(仅当用户配置了远程GPU并明确要求时才使用--where remote)。通过渲染检查仅意味着文件未损坏;继续执行交付关卡步骤3-6。
其他入口点,每个在 docs/ENGINE.md 中都有相应章节:
- 检查并更改时间轴:
reel timeline(--format text或--png多轨道图像)、reel scrub(每个剪辑点周围的帧)、reel edit/undo/history、reel preview --range(带声音的低分辨率预览)。 - 跟随节拍剪辑:
reel beats music.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat;然后使用reel timeline --png --beats检查每个剪辑点。需要./install.sh --beats。 - 高亮叙述网页: 使用
kind: "web"的镜头;文本位置来自DOM(无OCR),因此高亮句子必须与页面文本完全匹配;reel words voice.mp3提供逐词计时。需要./install.sh --web。 - Shotcut项目:
reel mlt project.mlt --video-only;--dupes查找使用了两次的源素材。
可用功能:计划组装、主体边界框亚像素推进、跟随移动主体、xfade转场、嵌入字幕、背景音乐、调色和LUT、网页镜头、OWLv2主体搜索、技术检查、关卡式交付。
未内置功能:缓动转场、帧插值、语音克隆。
远程GPU(可选)
--where remote 部分由代码强制执行。
- 仅当用户配置了
REEL_REMOTE(一个ssh目标地址)并明确要求时才使用它;否则使用--where local进行渲染。 - VRAM使用量默认限制在80%。当任务需要更多时,工具返回
NEED_USER_APPROVAL:首先告知用户,并且只有在用户同意的情况下才添加--allow-over-80。GPU利用率达到50%或更高表示有其他人在使用;不要占用。 - 一次只能运行一个reel GPU任务(远程文件锁)。不要更改功率限制。切勿重启或关闭主机。
reel remote probe报告远程主机信息;reel remote setup-vision会在远程主机上安装一个带有torch和OWLv2权重的独立venv。
配套文件
SOP.md:方向先行的工作流程、角色、步骤和退出条件。director代理(存储在仓库中的agents/director.md):brief、故事板和审查。- 仓库中的
docs/ENGINE.md:命令、EditPlan、brief、审查记录、收据和配置文件。