Communitygithub.com

notque/vexjoy-agent

视频编辑流水线:通过 FFmpeg 和 Remotion 剪辑素材、组装片段。

vexjoy-agent 是什么?

这是一个用于自动化视频编辑的 AI 代理技能,它实现了一个6层流水线,将 AI 的判断任务(如决定保留什么、剪辑什么、选择高光片段)与 FFmpeg 和 Remotion 的确定性机械执行相结合。该技能支持在命令行环境中运行,要求系统预装 ffmpeg 和 node,并可选依赖 Remotion。其工作流程从捕获源素材开始,通过 AI 生成转录和编辑决策列表(EDL),然后由 FFmpeg 根据 EDL 进行批量剪切,接着由 Remotion 进行程序化合成,需要时使用 ElevenLabs 或 fal.ai 生成补充资产,最终移交给人进行精修。此技能特别适合需要批量处理、可重复性强且需要 AI 辅助决策的视频编辑场景。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/notque/vexjoy-agent/tree/HEAD/skills/content/video-editing

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

视频编辑技能

概述

该技能实现了一个6层流水线,其中 AI 负责判断类任务(保留什么、剪辑什么、选择高光片段),而 FFmpeg/Remotion 则负责确定性的机械执行。

层名称机制主要工具
1捕获盘点源素材Bash + Glob
2AI 结构从转录到编辑决策列表LLM 判断
3FFmpeg 剪切编辑决策列表到片段文件FFmpeg (确定性)
4Remotion 合成片段到 TSX 合成Remotion + TypeScript
5AI 生成用生成的资产填补空白ElevenLabs / fal.ai (按需)
6最终精修人为品味层人类 + 非线性编辑

深度参考

信号加载内容
每个阶段的 Shell 命令、门控检查references/phase-commands.md阶段 1-6 的完整命令块
FFmpeg 配方:剪切、拼接、代理、检测references/ffmpeg-commands.md时间戳提取、批量剪切、音频归一化、场景/静音检测
Remotion 合成脚手架references/remotion-scaffold.mdTSX 合成模板、渲染命令、复用模式
图像到视频流水线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>' 并选择一个可用的语言。

相关技能