video-use：用 Claude Code 对话式编辑视频的开源工作流

一句话结论：video-use 不让模型"看"视频，而是把剪辑问题压缩成模型擅长的结构化文本推理，只在关键决策点补充少量视觉证据。 事实边界：本文基于公开的 README 与 SKILL.md 解读它的设计和使用方式；未展开核验的内部实现细节，不作为确定事实描述。 目标读者：想把 Claude Code、FFmpeg 与转录系统组合成实际生产力工具的开发者、内容创作者、AI 工作流设计者。 前置知识：命令行基础、视频容器与编码的基本概念、对 FFmpeg 的粗略认知。

一、学习目标

读完这篇文章，你应该能回答 4 个问题：

1. 为什么 video-use 让 LLM “读"视频，而不是"看"视频？
2. 这个项目里哪些是艺术风格选择，哪些是必须遵守的生产正确性规则？
3. 一次从原始素材到 final.mp4 的完整工作流是怎样的？
4. 把类似思路迁移到别的多媒体任务时，最值得复用的方法是什么？

二、目录

• 一、学习目标
• 二、目录
• 三、先看结论
• 四、它到底在解决什么问题
• 五、核心创新：让 LLM “读"视频
• 六、从素材到成片：完整工作流
• 七、不是所有规则都能改：12 条生产正确性约束
• 八、它能做什么，以及这些能力意味着什么
• 九、怎么开始：安装、准备素材、发出第一条指令
• 十、一次理想的编辑会话，应该怎么推进
• 十一、这套方案的风险、限制与排错思路
• 十二、从 video-use 可以迁移出的 3 个方法论
• 十三、进阶路径
• 十四、资料口径说明
• 十五、练习与自测
• 十六、常见问题
• 相关资源
• 文档信息

三、先看结论

如果你只想快速判断 video-use 值不值得研究，先记住这 5 点：

1. 它是剪辑工具，和 Runway、Pika、Sora 那类生成式视频模型不是一类产品。
2. 它的创新点不在新模型，而在输入界面设计：把视频压缩为转录文本，把图像检查延迟到必要时。
3. 它把 Claude Code 放在"剪辑决策协调者"的位置，FFmpeg、字幕、动画、转录都是它编排的工具链。
4. 它坚持先提策略、等确认、再执行、再自检，拿到指令不会直接动刀。
5. 最值得学的不是"怎么剪视频”，而是怎么把高成本的多模态问题改写成低成本的文本推理问题。

四、它到底在解决什么问题

4.1 传统视频剪辑，难点不只是"会不会用软件”

很多人以为视频剪辑的门槛在软件操作，其实更大的门槛在三件事：

1. 反复定位语气词、卡壳、重录片段和无效停顿。
2. 在音画都不穿帮的前提下决定切点。
3. 在字幕、调色、动画叠加和导出规范之间保持一致性。

对开发者或内容创作者来说，真正想要的往往不是"再学一门剪辑软件"，而是"给出一句自然语言指令后，系统能提出合理方案并执行"。

4.2 它和生成式视频工具不是一类产品

video-use 的公开定位很明确：把已有素材剪成成片，而不是凭空生成新视频。README 对适用场景的描述是口播（talking heads）、混剪（montages）、教程、旅行、访谈，不需要预设和菜单。

它更适合这些场景：

• 口播视频去掉 umm、uh 和空白停顿
• 多段素材拼成产品发布视频
• 教程、访谈、旅行片段的结构化重组
• 在现有视频上添加字幕、调色与动画层

它不擅长的方向同样明确：

• 从零生成镜头内容
• 复杂多轨道非线性剪辑
• 需要大型图形界面精修的后期项目
• 不允许云端语音转录的严格离线环境

4.3 为什么这类工具值得关注

它展示了一个有代表性的 AI agent 设计方向：不追求把所有事情交给一个"万能多模态模型"，而是把问题拆成模型擅长的推理层与传统工具擅长的执行层，最终让自然语言变成可审阅、可确认、可迭代的生产流程。

五、核心创新：让 LLM “读"视频

5.1 为什么不能直接把视频帧丢给模型

项目 README 用一组对比概括了这个问题：

Naive approach: 30,000 frames × 1,500 tokens = 45M tokens of noise. Video Use: 12KB text + a handful of PNGs.

这背后不是简单的"省钱”，而是三个工程判断：

1. 大多数剪辑决策首先来自语音而不是画面。 去掉填充词、删掉死空间、保留笑点、避免切断句子，本质上都依赖语音边界和停顿。
2. 大多数视频帧对剪辑决策是噪声。 在决定"这里该不该剪"之前，模型不需要看完整分钟级画面，只需要在关键点看到足够证据。
3. 文本是最便宜、最稳定、最可搜索的推理界面。 一旦视频被转换成带时间戳的文本，LLM 就能像读日志、读 DOM、读结构化数据那样去推理。

5.2 Layer 1：始终加载的转录层

video-use 的第一层输入来自 ElevenLabs Scribe。每个源文件调用一次，获得：

• 词级时间戳
• 说话人分离（speaker diarization）
• 音频事件标记，例如 (laughter)、(applause)、(sigh)

所有素材的转录结果会打包成一个约 12KB 的 takes_packed.md，作为 LLM 的主阅读面。README 给出的示例：

## C0103  (duration: 43.0s, 8 phrases)
  [002.52-005.36] S0 Ninety percent of what a web agent does is completely wasted.
  [006.08-006.74] S0 We fixed this.

这一步的意义在于：

• 模型能直接看到每句内容对应的时间范围
• 切点可以对齐到单词边界，而不是粗略的句子边界
• 多段素材先统一压缩为一个文本阅读面

按 SKILL.md 的说法，短语在静音 ≥ 0.5s 或说话人切换处断开；相比原始 JSON，这份打包文本只消耗约十分之一的 token，却保留了词级精度。

5.3 Layer 2：按需触发的可视化层

只有当文本不足以做决定时，video-use 才调用 timeline_view 生成复合图：胶片条（filmstrip）、波形、单词标签，外加指定时间窗口的上下文。SKILL.md 特别提醒它不是扫描工具——只在决策点使用，比如：

• 某个停顿到底是语义停顿还是尴尬空白
• 两段重录素材该选哪一条
• 切点附近音画是否真的干净

模型不会"全程看视频"，只在这些时刻查看图像。

5.4 这个设计和 browser-use 同源

browser-use 给 LLM 的不是整页截图，而是结构化 DOM；video-use 给 LLM 的不是完整视频帧，而是结构化转录文本。README 自己点明了这层继承关系——“Same idea as browser-use giving an LLM a structured DOM instead of a screenshot — but for video”。

换句话说，创新点不在"把视频交给大模型"，而在为大模型设计一种更便宜、更稳定、更适合决策的观察界面。

六、从素材到成片：完整工作流

6.1 管线总览

README 给出的管线是一条单向流，自检不过就修复重渲，最多 3 轮：

Transcribe ──> Pack ──> LLM Reasons ──> EDL ──> Render ──> Self-Eval
                                                          │
                                                          └─ issue? fix + re-render (max 3)

对应到数据流：转录打包成 takes_packed.md，模型基于它推理出 edl.json（剪辑决策），render.py 据此渲染，自检用 timeline_view 复查渲染结果。

6.2 它最重要的流程约束，不是技术而是交互

SKILL.md 里最值得注意的一条不是某个滤镜参数，而是这条流程原则：

Ask → confirm → execute → iterate → persist

翻成更工程化的话：

1. 先盘点素材，不急着动刀。
2. 用自然语言提出剪辑策略，不直接执行。
3. 用户确认后，再生成剪辑结果。
4. 渲染后先自检，不满意就重试。
5. 把会话状态持久化，下一次接着做。

这套顺序让"自然语言剪辑"不至于退化成黑盒自动化——策略未经确认，模型永远不许碰素材。

6.3 剪辑决策的载体：edl.json

模型推理的产物是一份 EDL（Edit Decision List，剪辑决策列表）。SKILL.md 给出了真实格式：

{
  "version": 1,
  "sources": {"C0103": "/abs/path/C0103.MP4"},
  "ranges": [
    {"source": "C0103", "start": 2.42, "end": 6.85,
     "beat": "HOOK", "quote": "...", "reason": "Cleanest delivery, stops before slip at 38.46."}
  ],
  "grade": "warm_cinematic",
  "overlays": [
    {"file": "edit/animations/slot_1/render.mp4", "start_in_output": 0.0, "duration": 5.0}
  ],
  "subtitles": "edit/master.srt",
  "total_duration_s": 87.4
}

每一段取舍都带 beat（叙事节拍）、quote（原话）和 reason（理由），所以剪辑决策是可审阅的，不是一个黑盒时间线。

6.4 一次会话的输出物

根据 SKILL.md，所有会话产物都写在 <videos_dir>/edit/，源素材目录保持不动：

这也解释了它为什么更像一个"工程化工作流"，而不是单一脚本。

七、不是所有规则都能改：12 条生产正确性约束

video-use 设计里非常成熟的一点，是它明确区分了两类东西：

• 可以自由发挥的艺术选择：风格、节奏、字体、色彩、动画语言。SKILL.md 原话是"Artistic freedom is the default"——文档里出现的每个具体参数都只是"来自一支真实成片的示例"，不是规定。
• 不能违反的正确性规则：违反后输出会悄悄坏掉，甚至看起来"差不多"，实际已经不可靠。

下面这 12 条是 SKILL.md 公开写出的硬规则（Hard Rules），值得逐条理解：

为什么这一节比"功能清单"更重要

很多 AI 工具文章喜欢强调"能做什么"，却不解释"为什么这样做才不会出错"。如果你想把这套思路迁移到别的多媒体项目，这 12 条硬规则比"支持哪几种调色预设"更值得学习——前者是方法论，后者只是产品表层。

八、它能做什么，以及这些能力意味着什么

8.1 删除填充词和死空间

README 列的第一项能力，就是去掉 umm、uh、口误开头（false starts）和素材间空白。

这件事看似简单，其实考验三点：

1. 转录是否足够细，能定位到单词边界
2. 系统是否知道某个停顿是"强调"还是"失误"
3. 渲染时是否处理了音频边界，避免出现爆音

所以它的价值不在"能删停顿"，而在把"删停顿"变成一条可重复执行、可自检的工程流程。SKILL.md 还给了一条剪辑手艺：保留笑点、金句这些"峰值"，并把切点延长到反应结束后——“the laugh IS the beat”。

8.2 自动调色

公开说明中提到三个内置预设加自定义通道：

• warm_cinematic：复古技术感，轻微橙青分离、降饱和，来自一支真实发布视频
• neutral_punch：最小校正，提对比 + 温和 S 曲线，不动色相
• none：直拷，用户没提调色时的默认值
• 任意自定义 ffmpeg 滤镜链（grade.py --filter '<raw>'）

调色的心智模型是 ASC CDL（美国电影摄影师协会色彩决策列表）：每个通道做 out = (in * slope + offset) ** power，再做全局饱和度。硬规则只有一条——调色必须按片段在抽取时执行，不能拼接后补救（那会二次编码）；大胆调色前先检查肤色。

8.3 字幕烧录

README 给出的默认风格是 2-word 大写分块（bold-overlay），完全可定制。SKILL.md 给出了这套默认的完整参数：Helvetica 18 Bold、白字黑边、MarginV=35，在标点和 ≥ 0.3s 停顿处断行，短于 0.35s 的字幕提示宁可延长到 3 个词也不闪现。

它同时提醒了字幕系统真正容易翻车的两处：

• 字幕必须最后叠加（硬规则 1）
• 字幕时间不能沿用原片时间，要映射到输出时间轴（硬规则 5）

还有一种适合纪录片、教学的 natural-sentence 思路（4-7 词分块、句子大小写、MarginV=60-80）——但文档把它标为"由你发明"的示例。字幕在这里不是附属功能，而是和剪辑决策、片段拼接紧耦合的输出系统。

8.4 动画叠加层

公开资料列了 4 类动画引擎，按动画槽位逐个选用：

两点工程约束值得注意：HyperFrames 目前要求 Node.js 22+；多个动画必须用并行子代理生成——SKILL.md 明确禁止"因为动画和 web 沾边就默认选 Remotion"，也禁止串行生成。

8.5 音乐与音效

SKILL.md 有一节常被忽略的混音指导，结论都来自真实发布剪辑：

• 音效宁少勿多：18 秒里塞 20 个素材音效显得廉价，8 个左右才显得"设计过"；每个音效都要对应可见事件
• 音效起点按攻击帧对齐：测量文件的 attack（峰值前首个高于约 -30 dBFS 的采样），让它在可见接触帧之前开始
• 音乐在语音下压低约 -12 到 -15 dB，并在尾卡前淡出
• 母带只做一次：混成 PCM 后两遍 loudnorm（-14 LUFS，true peak ≤ -1 dBTP）
• 模型不能"听"，只能测：它被明确要求报告响度数字，而不是声称"听起来不错"

8.6 自我评估

这套工作流里最不像传统剪辑软件、最像 AI agent 的能力，是"渲染后、交付前"的自检。SKILL.md 规定：

• 对渲染结果（不是源素材）的每个切点跑 timeline_view，检查 ±1.5s 窗口内的视觉跳变、波形尖峰、字幕遮挡、叠加层错位
• 用 ffmpeg -i out.mp4 -af ebur128=peak=true 实测整体响度与峰值——文案区比尾卡高 15 dB 以上才算正常，“你听不到，所以要报数字”
• 抽查首尾 2 秒和中段 2-3 个点，核对调色一致性与字幕可读性，ffprobe 校验时长与 EDL 预期一致
• 发布级素材（发布会、广告）额外派一个挑剔子代理（critic sub-agent），指令是"roast, not to praise"：给出裁决、按时间码排列的问题清单和最优先的 5 个修复
• 自检最多 3 轮，仍有问题就显式上报用户，而不是无限循环

这一步让系统不是"生成结果然后交付"，而是"生成结果后先审自己一遍，通过才给你看预览"。

九、怎么开始：安装、准备素材、发出第一条指令

9.1 安装：两种方式

方式一：让 agent 自己装（README 首推）。 把下面这段话贴给 Claude Code、Codex、Hermes、Openclaw 或任何有 shell 权限的 agent：

Set up https://github.com/browser-use/video-use for me.

Read install.md first to install this repo, wire up ffmpeg, register the skill with whichever agent you're running under, and set up the ElevenLabs API key — ask me to paste it when you need it. Then read SKILL.md for daily usage, and always read helpers/ because that's where the editing scripts live. After install, don't transcribe anything on your own — just tell me it's ready and wait for me to drop footage into a folder.

agent 会完成克隆、依赖安装、技能注册，并只在你粘贴 ElevenLabs API Key 时打扰你一次。

方式二：手动安装。 以下命令照抄自 README 的 Manual install 一节：

# 1. Clone and symlink into your agent's skills directory
git clone https://github.com/browser-use/video-use ~/Developer/video-use
ln -sfn ~/Developer/video-use ~/.claude/skills/video-use        # Claude Code
# ln -sfn ~/Developer/video-use ~/.codex/skills/video-use       # Codex

# 2. Install deps
cd ~/Developer/video-use
uv sync                         # or: pip install -e .
brew install ffmpeg             # required
brew install yt-dlp             # optional, for downloading online sources

# 3. Add your ElevenLabs API key
cp .env.example .env
$EDITOR .env                    # ELEVENLABS_API_KEY=...

一个值得注意的事实：虽然项目常被归为"Claude Code 技能"，但 README 明确写着它面向"any agent with shell access"——Codex、Hermes、Openclaw 都在列，symlink 到对应技能目录即可。

9.2 准备素材并进入会话

cd /path/to/your/videos
claude

然后在会话里输入一条自然语言指令，例如：

edit these into a launch video

产出会出现在素材旁边的 edit/final.mp4。

9.3 第一次使用时，你需要提前想清楚什么

为了让策略阶段更高质量，最好先明确这几个信息——这也是 SKILL.md 要求 agent 在对话中收集的项：

• 目标时长与画幅（横屏、竖屏还是方形）
• 风格方向：发布会、教程还是访谈
• 哪些瞬间必须保留，哪些表达必须删掉
• 是否要字幕、动画、统一调色

这些问题没想清楚，系统仍然可以工作，但结果更可能停在"能看"，而不是"贴近你的表达目标"。

十、一次理想的编辑会话，应该怎么推进

SKILL.md 的 The process 一节把会话定义为 8 个阶段：

1. 盘点素材：ffprobe 每个源文件，批量转录，生成 takes_packed.md，抽看一两张 timeline_view 建立第一印象。
2. 预扫描问题：通读一遍转录文本，列出口误、明显说错的表述，作为剪辑简报的输入。
3. 对话澄清：用素材 shaping 出的问题向用户收集信息——内容类型、目标时长、审美方向、必留必删的瞬间，而不是套固定清单。
4. 提出策略：4-8 句话讲清形态、选段方向、动画与调色计划、字幕风格、时长估计，然后停下等确认。
5. 执行：生成 edl.json，歧义处下钻 timeline_view，动画并行开工，按片段调色，render.py 合成。
6. 出预览：render.py --preview 渲染 720p 快速版。
7. 自检：按 8.6 节的流程审自己，最多 3 轮，通过才展示。
8. 迭代与持久化：自然语言反馈、重规划、重渲染（绝不重新转录），确认后出 final.mp4，把本次会话追加进 project.md。

下次会话冷启动时，agent 会先读 project.md，用一句话复述上次进度再问你是否继续——这是它"跨周记忆"的来源。

十一、这套方案的风险、限制与排错思路

11.1 最常见的风险点

11.2 它当前不解决什么问题

基于公开文档，下面这些方向不应被理解为其核心能力：

• 复杂多轨道编辑台
• 完整替代专业 GUI 剪辑软件
• 完全离线的端到端工作流（转录依赖云端 Scribe）
• 针对所有素材类型的现成模板

11.3 一个很实用的判断标准

如果你的素材主要问题是"删废话、缩空白、加字幕、统一风格、补一点动画"，它很值得试。如果你的项目核心是精细 keyframe、复杂遮罩、多轨合成、逐帧修补，那它更像前处理或粗剪工具，而不是终局工具。

SKILL.md 还附了一份反模式清单（Anti-patterns），每一条都是反复翻车后的结论：手调的时刻评分函数不如让 LLM 直接选、本地 CPU 跑 Whisper 又慢又归一化填充词、线性缓动的动画像机器人、逐转场堆库存音效显得廉价。自己搭类似系统时，这份清单比功能列表更省学费。

十二、从 video-use 可以迁移出的 3 个方法论

12.1 用结构化文本替代原始多模态洪流

不要默认"多模态任务就应该把原始模态全喂给模型"。先问自己：有没有一种更稀疏、更便宜、更可索引的中间表示？

对视频，这个中间表示是词级转录；对浏览器，是 DOM；对日志分析，可能是事件流和聚合摘要。

12.2 把"模型推理"与"传统工具执行"拆开

Claude Code 负责理解需求、制定策略、判断哪里该剪、自检是否达标；FFmpeg、转录服务、字幕系统和动画引擎负责精确执行。各自待在自己概率分布最窄、正确率最高的位置上。

这比"让模型直接做一切"更稳，也更容易排错——出问题时你能分清是推理错了还是执行错了。

12.3 让系统先验证自己，再把结果给人

很多 AI workflow 的问题不是"生成不了"，而是"生成了但没人复查"。video-use 的做法可以抄：把自检写成硬规则（检查什么、用什么工具、几轮上限、失败怎么办），而不是指望模型"自觉一点"。

十三、进阶路径

想在 video-use 基础上继续深入，可以按下面的顺序走，每一步都有明确的产出物：

1. 跑通最小闭环：找一段 3-5 分钟的口播素材，只做"去填充词 + 字幕"，走完从转录到 final.mp4 的全流程。这一步会暴露环境问题（ffmpeg、API key、技能注册）。
2. 读 SKILL.md 全文：重点看 Hard Rules、The process 和 Anti-patterns 三节。它是这个项目真正的"源代码"——所有行为约束都在里面。
3. 读 helpers/ 脚本：transcribe.py、pack_transcripts.py、timeline_view.py、render.py、grade.py，对照正文理解分段抽取、PTS 偏移和字幕时间轴换算的实现。
4. 四种动画引擎各做一个槽位：PIL 卡片最简单，先做它；再试 Manim 图示和 Remotion 合成；HyperFrames 需要先装 Node.js 22+。体会"每槽位一子代理"的并行结构。
5. 造一次失败，再修一次：故意把字幕放到滤镜链前面、或把切点落在单词中间，观察静默失败的样子，再按排错表修回来。对"为什么有这 12 条硬规则"的理解，此刻才会落地。
6. 跟仓库迭代：仓库 2026 年 10 月仍在活跃推送，Issue 和 PR 区能看到真实使用中的问题与修复方向。

十四、资料口径说明

本文基于以下来源和假设：

1. 信息来源：video-use 官方 GitHub 仓库的公开 README.md 与 SKILL.md，关键命令与参数照抄原文。所有技术描述均可回溯到这两个文件。
2. 版本口径：文章初版基于 2026-04-16 的仓库状态；2026-10-04 对照 main 分支最新版本逐节复核，安装命令、硬规则、动画引擎等均以复核时点为准。项目活跃开发中，使用前请核对官方文档。
3. 技术细节边界：转录层工作原理、自检触发条件、12 条硬规则等均来自公开文档描述，本文未在真实素材上独立复现每条规则的行为。
4. 性能数据未验证：45M tokens、12KB 等数字引自 README 的说明性对比；转录精度、渲染速度、成本数据需读者在自己的环境中实测。
5. 安全与合规边界：ElevenLabs 转录是云端服务，会把音频上传到第三方。对素材保密性有严格要求的场景，请先评估这一依赖。

十五、练习与自测

15.1 建议你亲手做的 3 个练习

1. 找一段 3-5 分钟口播视频，只做"去填充词 + 去空白 + 字幕"，观察文本驱动剪辑是否已经足够。
2. 在同一段素材上分别尝试"无调色"和 warm_cinematic，比较按片段调色与整片后处理的差异。
3. 用 PIL 做一个带打字机效果的动画槽位，故意先线性缓动再换 cubic 缓动，体会为什么文档说线性缓动"看起来像机器人"。

15.2 发布前自测清单

• 你能解释为什么它先读转录文本，而不是先看完整视频吗？
• 你能区分"风格建议"和"硬规则"吗？
• 你知道字幕为什么必须最后叠加吗？
• 你知道为什么切点不能落在单词中间吗？
• 你知道什么情况下它更适合作为粗剪工具，而不是最终后期工具吗？

这 5 个问题都能回答清楚，说明你已经越过"会用"，开始理解它的系统设计了。

十六、常见问题

Q1：支持哪些视频格式？

上限取决于底层 FFmpeg 能处理什么，常见的 mp4、mov、avi、mkv、webm 都在常规讨论范围内。

Q2：为什么依赖 ElevenLabs Scribe？

因为大量剪辑决策依赖词级时间戳、说话人分离与音频事件，这些正是第一层阅读面的原料。SKILL.md 的反模式清单还特别点名了替代方案的问题：本地 CPU 跑 Whisper 又慢，又会把填充词归一化，丢掉编辑信号——所以它选择了托管 Scribe。

Q3：能不能完全离线？

不能。转录环节必须配置 ElevenLabs API Key，音频会上传到云端处理。严格离线环境暂时不适合这套工作流。

Q4：它和生成式视频模型最大的区别是什么？

它处理的是"已有素材怎么剪"，不是"没有素材怎么生成镜头"。

Q5：只能配合 Claude Code 使用吗？

不是。README 的安装说明覆盖 Claude Code、Codex、Hermes、Openclaw，本质要求只有一个：能执行 shell 命令、能读技能文件的 agent。把仓库 symlink 到对应 agent 的技能目录即可。

Q6：我应该把它当成什么？

一个由 Claude Code 协调的对话式视频编辑工作流：模型负责推理与自检，FFmpeg 与各类动画引擎负责执行。它不是单一模型，不是单一脚本，也不是 GUI 剪辑软件的完整替代品。

相关资源

• GitHub 仓库：browser-use/video-use
• 技能说明：SKILL.md
• 转录能力说明：ElevenLabs Speech to Text
• 动画引擎：HyperFrames / Remotion / Manim
• 视频处理基础工具：FFmpeg

文档信息

• 类型：技术笔记 / 架构解读 / 工作流教程
• 难度：进阶
• 发布日期：2026-04-16
• 阅读建议：先看第 4、5、9 节决定是否上手，再按第 13 节的顺序深入实践