视频编辑技能
概述
该技能实现了一个6层流水线,其中 AI 负责判断类任务(保留什么、剪辑什么、选择高光片段),而 FFmpeg/Remotion 则负责确定性的机械执行。
| 层 | 名称 | 机制 | 主要工具 |
|---|---|---|---|
| 1 | 捕获 | 盘点源素材 | Bash + Glob |
| 2 | AI 结构 | 从转录到编辑决策列表 | LLM 判断 |
| 3 | FFmpeg 剪切 | 编辑决策列表到片段文件 | FFmpeg (确定性) |
| 4 | Remotion 合成 | 片段到 TSX 合成 | Remotion + TypeScript |
| 5 | AI 生成 | 用生成的资产填补空白 | ElevenLabs / fal.ai (按需) |
| 6 | 最终精修 | 人为品味层 | 人类 + 非线性编辑 |
深度参考
| 信号 | 加载 | 内容 |
|---|---|---|
| 每个阶段的 Shell 命令、门控检查 | references/phase-commands.md | 阶段 1-6 的完整命令块 |
| FFmpeg 配方:剪切、拼接、代理、检测 | references/ffmpeg-commands.md | 时间戳提取、批量剪切、音频归一化、场景/静音检测 |
| Remotion 合成脚手架 | references/remotion-scaffold.md | TSX 合成模板、渲染命令、复用模式 |
| 图像到视频流水线 | references/image-to-video.md | 验证、准备、编码、验证工作流 |
| 用于可视化的 FFmpeg 滤镜图 | references/ffmpeg-filters.md | 缩放/填充、显示波形、显示频谱、叠加、完整滤镜图 |
指令
预检(在阶段 1 之前运行)
硬性要求(缺失则阻止):ffmpeg(所有阶段)、node(Remotion / npx)。
软性要求(缺失则警告):remotion(仅阶段 4 需要)。
which ffmpeg >/dev/null 2>&1 || { echo "错误:未找到 ffmpeg。请安装:brew install ffmpeg (macOS) | apt install ffmpeg (Linux)"; exit 1; }
which node >/dev/null 2>&1 || { echo "错误:未找到 node。请安装:https://nodejs.org 或通过 nvm"; exit 1; }
npx remotion --version >/dev/null 2>&1 || echo "警告:未找到 remotion CLI。阶段 4 不可用。请安装:npm install @remotion/cli"
阶段 1:捕获
目标:盘点所有源素材,并在任何处理之前确认文件存在于磁盘上。
约束:源文件为只读。所有 FFmpeg 命令仅写入新文件。切勿覆盖源素材。
步骤:定位源文件 (find),使用 ffprobe 检查每个文件,为超过 10 分钟的文件生成代理(参见 references/ffmpeg-commands.md -> 代理生成),创建工作目录(segments/、assembled/)。完整命令块:references/phase-commands.md -> 阶段 1。
门控:源文件已在磁盘上确认。文件列表已写入 source-inventory.txt。仅当门控通过时继续。
阶段 2:AI 结构
目标:分析内容并生成一个书面的编辑决策列表 (cuts.txt),该列表驱动所有下游的剪切操作。
约束:cuts.txt 是契约。编辑决策列表文件是下游阶段的唯一事实来源。不要手动编辑 FFmpeg 命令——从编辑决策列表生成它们。
约束:在手动编写编辑决策列表之前,先运行 FFmpeg 场景/静音检测。检测输出用于辅助判断,而非替代判断。
步骤:使用 whisper/AssemblyAI 转录,运行场景/静音检测,应用判断(哪些推进叙事,哪些是填充内容,目标时长),以 EDL 格式(START_TIME,END_TIME,LABEL)编写 cuts.txt,检查重叠和总时长。完整命令块和编辑决策列表格式示例:references/phase-commands.md -> 阶段 2。
门控:transcript.txt 存在。cuts.txt 已写入磁盘。仅当两个文件都存在时继续。
阶段 3:FFmpeg 剪切
目标:确定性地执行编辑决策列表——cuts.txt 中每个片段执行一次 FFmpeg 剪切。
约束:使用循环从编辑决策列表批量剪切。不要为每个剪切创建单独的 FFmpeg 命令。这确保了可复现性和作为列表进行审查的能力。
约束:始终从 cuts.txt 的顺序生成 concat-list.txt,而不是从 shell 通配符。Shell 通配符 (segments/*.mp4) 按字母顺序排序,而非编辑决策列表顺序。
步骤:使用 while 循环从编辑决策列表批量剪切(libx264/aac,-avoid_negative_ts make_zero),验证片段,按编辑决策列表顺序生成 concat-list.txt,使用 -f concat -safe 0 -c copy 拼接。完整命令块:references/phase-commands.md -> 阶段 3。另请参阅 references/ffmpeg-commands.md -> 批量剪切。
门控:所有片段文件都存在。assembled/rough-cut.mp4 已写入磁盘。仅当门控通过时继续。
阶段 4:Remotion 合成
目标:将片段封装到 Remotion TSX 合成中,以实现程序化的叠加、标题或转场。
何时使用:仅当 rough-cut.mp4 需要程序化元素(动画标题、下三分之一、字幕轨道、品牌叠加)时。如果 rough-cut.mp4 就足够了,则跳到阶段 6。
约束:第 4 层需要 TypeScript/React。将 TSX 工作移交给 typescript-frontend-engineer;从阶段 5 开始返回给 python-general-engineer。
步骤:初始化 Remotion(首次使用 npm create video@latest;否则 npm install @remotion/cli @remotion/player remotion),构建合成骨架(参见 references/remotion-scaffold.md),使用 npx remotion render 渲染。完整命令块:references/phase-commands.md -> 阶段 4。
门控:assembled/remotion-output.mp4 存在。仅当门控通过时继续。
阶段 5:AI 生成
目标:仅在需要时,使用生成的资产填补源素材中的真实空白。
约束:在生成任何内容之前,检查现有素材是否已覆盖该空白。仅生成不存在的部分。
决策树:围绕空白进行剪切 → 更新 cuts.txt 并重新运行阶段 3;画外音 → ElevenLabs(需要授权);音乐 → fal.ai(移交给 fal-ai-media);B-roll → fal.ai(移交给 fal-ai-media)。ElevenLabs Python 辅助工具、授权模式和保存到磁盘的流程:references/phase-commands.md -> 阶段 5。
门控:所有必需的生成资产在继续前均已保存到 assets/ 目录。
阶段 6:最终精修
目标:交付组装好的输出,并将品味层面的工作移交给人类。
约束:第 6 层属于人类领域。该技能进行组装;人类完成最终工作。以下工作需人工判断,不应通过程序尝试:
- 调色和片段间的色彩匹配
- 音乐时机和音量闪避
- 字幕样式、字体和位置
- 转场时机和样式
- 最终音频混音电平
交接模板(handoff-notes.txt,包含源列表、编辑决策列表、粗剪路径、需人工处理的剩余项清单):references/phase-commands.md -> 阶段 6。
门控:assembled/rough-cut.mp4(或 assembled/remotion-output.mp4)存在。handoff-notes.txt 已写入磁盘。
视频转录提取
以可读段落的形式提取视频的转录。优先使用上传者字幕;否则使用自动生成的字幕。
# 路径 1:上传者字幕(准确)
yt-dlp --skip-download --write-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# 路径 2:自动生成(当路径 1 未写入文件时的回退)
yt-dlp --skip-download --write-auto-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# 将 VTT 清理为段落
python3 skills/research/video-transcript/scripts/vtt_to_paragraph.py <work-dir>/<id>.en.vtt
选项:--timestamps 用于 [mm:ss] 标记,--keep-brackets 用于提示标签,-o FILE 用于文件输出。其他语言:更改 --sub-langs。列出可用字幕:yt-dlp --list-subs '<URL>'。
错误处理
| 错误 | 原因 | 解决方案 |
|---|---|---|
| 源文件“没有那个文件或目录” | cuts.txt 中的路径与文件名不匹配 | 运行 cat source-inventory.txt。对含空格的路径使用引号。 |
| FFmpeg“无效选项”或编解码器错误 | 编解码器不可用或标志语法错误 | `ffmpeg -codecs |
| Remotion“找不到合成” | 合成 ID 不匹配 | 检查 src/index.ts 中注册的 ID。确保与渲染命令完全匹配。 |
| 片段拼接顺序错误 | Shell 通配符按字母顺序排序,而非编辑决策列表顺序 | 从 cuts.txt 的顺序生成 concat-list.txt,而非通配符。 |
| ElevenLabs 401 | 未设置 ELEVENLABS_API_KEY | 在阶段 5 之前执行 export ELEVENLABS_API_KEY=your_key。 |
| 转录提取未生成 .vtt 文件 | 视频没有请求语言的字幕 | 执行 yt-dlp --list-subs '<URL>' 并选择一个可用的语言。 |