使用 ffmpeg 进行视频剪辑
你是一位编辑，通过文本和滤镜图而非鼠标和时间线来工作。工作流程是确定性的：所有剪辑都通过文本编辑，并用一条命令重建。
素材 → 带词级时间戳的转录 → 剪辑单 (EDL) → ffmpeg → 完成视频
↑ ↑
faster-whisper 手动编辑 — 这即剪辑
核心原则：从不对视频进行逐像素分析——剪辑由带时间戳的文本驱动。 语音定义结构；画面服务于它。
一卷还是多卷？
首先确定这一点——它会改变后续的一切。
- 一两卷 → 按下面的步骤顺序，以对话方式进行。
- 三卷或更多 → 切换到批量流程：references/batch-pipeline.md。每个阶段在整个项目上运行一次，并按输入哈希缓存。以对话方式处理十卷大约会消耗十倍的上文，且毫无益处。
工作顺序
始终遵循步骤，切勿跳过。每一步都为下一步产生输入。
- 检查环境。 如果缺少 ffmpeg / faster-whisper / Chrome → references/setup.md。在干净的机器上大约需要十分钟。
- 获取源文件。 如果用户提供的是 URL 而非文件，先用
download.py获取。 - 检查源文件 — 使用 ffprobe、场景检测、缩略图合集。通过阅读自行查看帧。 切勿仅凭文本盲目剪辑。
- 转录 生成带词级时间戳并校对结果。即使在干净的音频上，语音识别也可能出错。没有本地模型？
transcribe_cloud.py可通过 Groq/OpenAI 获取相同输出。 - 与用户确认概念（如果用户未指定）：格式、图形内容、目标平台。问一个问题，而非一份问卷。
- 构建 EDL — 剪切停顿，绝不剪切观点。
- 构建
base，然后逐帧验证剪切效果。 - 生成字幕和叠加层，构建
final。 - 执行验收清单并通过 SendUserFile 交付文件。
每个步骤的完整命令请参见 references/pipeline.md。
此流程能做与不能做的事情
能做： 语义剪切、消除停顿、剪切时拉近镜头、调色（包括 .cube LUT）、词级字幕、通过 HTML/CSS 实现任意复杂的图形叠加、稳定、社交媒体响度标准化、批量处理。若安装了 Remotion 插件，还可通过 React 渲染动画图形——参见 references/remotion.md。
完全不能做 — 如果用户要求，应提前说明：物体跟踪（将字幕固定到移动的手上）和遮罩调色。这些仍需要 Premiere / DaVinci / After Effects。
不能单独完成，但安装了 FableCut 后可做： 帧级精确的创意剪切、关键帧动画、转场、速度渐变、色度抠像、按音乐节拍剪切。FableCut 是一个浏览器时间线，通过 MCP 由代理驱动——参见 references/fablecut.md。它没有语音识别，导出需要人工点击，因此语音驱动的结构和无人批处理仍在此流程中完成。
现成工具
assets/tools/ 包含十二个可运行的脚本——将它们复制到项目中，不要从头重写：
| 脚本 | 功能 |
|---|---|
download.py | 从 URL 获取源素材（yt-dlp）——如果已有本地文件则跳过 |
transcribe.py | faster-whisper → 带词级时间戳和 .srt 的 transcript.json |
transcribe_cloud.py | 相同输出，通过 Groq/OpenAI Whisper API——无需模型下载，需要 API 密钥 |
pauses.py | 列出语音中的停顿——作为 EDL 的基础 |
dump_words.py | 每个词及其索引和置信度——用于校对 |
make_ass.py | 词级 ASS 字幕，重新调整为剪辑后的时间线 |
render_overlays.py | HTML/CSS → 无头 Chrome → 带 alpha 通道的 1080×1920 PNG |
build.py | 组装：base（剪切 + 调色），final（叠加层 + 字幕 + 音频） |
build_vo.py | 同上，但针对单独的配音轨道——来自多个源的视频适配到音频 |
batch_vo.py | 一次模型加载转录所有配音 |
mute_subs.py | 当全屏卡片显示时隐藏字幕 |
pipeline.py | 批量驱动程序——每卷每个阶段，带缓存 |
assets/templates/ 包含初始的 edl.json、overlays.json 和 corrections.json。
项目布局如下：
<素材所在的文件夹>/
├── IMG_XXXX.MOV
└── edit/
├── tools/ ← 复制的脚本
├── work/ ← 中间文件，绝不交付
├── overlays/ ← 渲染的 PNG
├── out/ ← 完成的视频
├── edl.json overlays.json corrections.json subs.ass
参考文件
按需加载，不要一次性全部加载：
- references/setup.md — 在干净机器上安装（Windows/macOS），验证 ffmpeg 构建
- references/pipeline.md — 工作流逐步说明、剪切规则、命令
- references/storyboard.md — 视频格式、面板类型、如何为讲话者分镜
- references/design-system.md — 配色、字体比例、安全区、叠加技术
- references/batch-pipeline.md — 将多卷作为阶段运行，以及上下文的实际去向
- references/remotion.md — 动画图形层：何时 React 渲染的叠加值得付出成本
- references/fablecut.md — 时间线层：何时将剪辑交给 FableCut，以及两个流程如何衔接
- references/ffmpeg-cookbook.md — 调色、效果、转场、音频、编码
- references/troubleshooting.md — 在首次运行 ffmpeg 前阅读此文件；十七种失败情况，每种都要花一小时
决定视频成败的规则
来自实际构建经验，而非文档。
- 查看帧。 转录文本不会告诉你讲话者正在起身或整理头发。这正是剪切容易出问题的地方。
- 卡片放在脸部上方，而不是面部上。 第一次尝试总是会将面板放在画面中间，遮住眼睛。讲话者的眼神是视频赢得信任的一半。
- 在短语结束时剪切，而不是按秒表。 每“N 秒”剪切一次会将观点切成两半。
- 每个停顿保留 0.2–0.3 秒。 停顿完全消失听起来会像口吃。
- 绝不触碰戏剧性停顿 ——问题之后、结论之前。此时沉默在起作用。
- 在片段之间交替使用
zoom。 这样剪切看起来像是角度的变化，而非错误。 - 留出一段完全没有图形的片段。 观众需要喘息空间；连续的卡片会让人疲惫。
- 校对字幕。 识别错误一旦嵌入画面就永久存在。
- 通过查看，而非信任来验证。 提取静止帧，用
hstack堆叠，通过 Read 打开结果。 - 不经过 pipeline.md 中的验收清单绝不交付。
- 绝不让工具写回配置文件。 脚本将其自身输出附加到 EDL 会使文件大小翻倍，且每次后续编辑都会将整个文件带入上下文。生成的数据属于
work/。 - 亲自阅读转录文本的第一行和最后一行。 Whisper 会在静音处编造文本——典型的是俄语音频上出现假的字幕制作人员行——且可能带有看起来很正常的置信度分数。两个转录脚本会自动过滤明显情况，但过滤器并非万无一失。参见 troubleshooting.md #17。
编排
任务是多步骤的——使用 TaskCreate 为阶段（转录、EDL、调色、图形、组装）创建任务并保持其状态最新。将长时间运行的操作（模型下载、base 渲染）放在后台，利用这段时间进行不依赖它们的工作：在模型下载时，设计叠加层并在静止帧上测试调色。
通过 SendUserFile 交付完成的视频，并附上简短说明变更内容。