视频使用
原则
- LLM 从原始转录 + 按需视觉素材进行推理。 唯一值得保留的派生工件是打包的短语级转录 (
takes_packed.md)。所有其他内容——填充词标记、重拍检测、镜头分类、强调评分——都在决策时由你推导得出。 - 音频是首要的,视觉其次。 剪辑候选来自语音边界和静音间隙。仅在决策点深入查看视觉信息。
- 询问 → 确认 → 执行 → 迭代 → 持久化。 在用户用通俗语言确认策略之前,绝对不要碰剪辑。
- 泛化。 不要假设视频的类型。查看素材,询问用户,然后进行编辑。
- 艺术自由是默认设置。 本文档中的每一个具体值、预设、字体、颜色、时长、音高结构和技术,都只是来自一个已验证视频的实践示例,而非硬性规定。阅读它们是为了理解可能性以及每个示例为何有效。然后,根据素材的实际情况和用户的真实需求,做出你自己的品味判断。你必须做的唯一事情是下面“硬性规则”部分中的内容。 其余一切都是你的自由。
- 自由创造。 如果素材需要这里没有描述的技术——分屏、画中画、底部三分之一身份卡、反应剪辑、速度坡道、冻结帧、交叉淡入淡出、匹配剪辑、L-cut、J-cut、呼吸间的速度坡道,等等——就创建它。辅助工具是 ffmpeg 和 PIL。它们可以执行格式支持的任何操作。不要等待许可。
- 在向用户展示输出之前,先验证自己的输出。 如果你自己都不会发布它,就不要展示它。
硬性规则(生产正确性——不可协商)
这些是偏差会导致静默失败或输出损坏的规则。它们不是品味问题,而是正确性问题。请牢记它们。
- 字幕在滤镜链中最后应用,在所有覆盖层之后。否则覆盖层会遮挡字幕。静默失败。
- 逐段提取 → 无损
-c copy拼接,而不是单次滤镜图传递。否则,在添加覆盖层时,每个片段都会被二次编码。 - 在每个片段边界处添加 30 毫秒音频淡入淡出 (
afade=t=in:st=0:d=0.03,afade=t=out:st={dur-0.03}:d=0.03)。否则,每个剪辑点都会出现可闻的爆音。 - 覆盖层使用
setpts=PTS-STARTPTS+T/TB将其帧 0 移位到窗口起始点。否则,您将在覆盖窗口期间看到动画的中间部分。 - 主 SRT 使用输出时间线偏移:
output_time = word.start - segment_start + segment_offset。否则,字幕在段落拼接后会对齐错误。 - 永远不要在单词中间进行剪辑。 将每个剪辑边缘对齐到 Scribe 转录中的单词边界。
- 填充每个剪辑边缘。 工作窗口:30–200毫秒。Scribe 时间戳漂移 50–100毫秒——填充可以吸收漂移。快节奏时更紧,电影感时更松。
- 仅使用单词级别的逐字 ASR。 切勿使用 SRT/短语模式(丢失亚秒级间隙数据)。切勿使用归一化的填充词(丢失编辑信号)。
- 按源文件缓存转录。 除非源文件本身发生更改,否则切勿重新转录。
- 对多个动画使用并行子代理。 切勿使用顺序模式。通过
Agent工具同时生成 N 个;总挂钟时间 ≈ 最慢的那个。 - 执行前确认策略。 在用户批准通俗英语计划之前,绝对不要碰剪辑。
- 所有会话输出放在
<videos_dir>/edit/中。 切勿在video-use/项目目录内写入。
本文档中的其余内容都是实践示例。只要素材需要,就可以偏离。
目录布局
该技能位于 video-use/ 目录。用户素材放在任何他们放置的地方。所有会话输出都进入 <videos_dir>/edit/。
<videos_dir>/
├── <源文件,保持原样>
└── edit/
├── project.md ← 记忆;每个会话追加
├── takes_packed.md ← 短语级转录,LLM 的主要阅读视图
├── edl.json ← 剪辑决策
├── transcripts/<name>.json ← 缓存的原始 Scribe JSON
├── animations/slot_<id>/ ← 每个动画的源代码 + 渲染 + 推理过程
├── clips_graded/ ← 带有调色和淡入淡出的逐段提取
├── master.srt ← 输出时间线字幕
├── downloads/ ← yt-dlp 输出
├── verify/ ← 调试帧/时间线 PNG
├── preview.mp4
└── final.mp4
设置
首次安装位于 install.md(克隆、依赖项、ffmpeg、技能注册、API 密钥)。不要在每个会话中都重新运行它;在冷启动时只需验证:
ELEVENLABS_API_KEY已解析——要么在环境中,要么在 video-use 仓库根目录的.env文件中。如果缺失,请用户粘贴一个并写入.env(切勿写入用户的<videos_dir>)。ffmpeg+ffprobe在 PATH 中。- Python 依赖项已安装(在仓库内运行
uv sync或pip install -e .)。 - 如果会话需要 HyperFrames 或 Remotion 插槽,则 Node.js + npm 可用。HyperFrames 目前需要 Node.js 22+。
yt-dlp、HyperFrames、Remotion、Manim 仅在首次使用时安装。- 首次使用的动画设置发生在插槽目录内,切勿在 video-use 仓库根目录。HyperFrames 可以通过
npx --yes hyperframes ...调用;Remotion 可以使用npx create-video@latest搭建脚手架,或在使用其remotion render命令之前安装为项目本地依赖项。 - 此技能附带
skills/manim-video/。在构建 Manim 插槽时阅读其 SKILL.md。
辅助工具(helpers/transcribe.py、helpers/render.py 等)与此 SKILL.md 位于同一目录。相对于包含此文件的目录解析路径——该技能通常被符号链接到 ~/.claude/skills/video-use/ 或 ~/.codex/skills/video-use/。
辅助工具
transcribe.py <video>— 单文件 Scribe 调用。可选参数--num-speakers N。已缓存。transcribe_batch.py <videos_dir>— 4 工作线程并行转录。用于多段素材。pack_transcripts.py --edit-dir <dir>— 将transcripts/*.json转换为takes_packed.md(短语级,静音 ≥ 0.5s 时断开)。timeline_view.py <video> <start> <end>— 胶片条 + 波形 PNG。按需视觉深入查看。不是扫描工具——在决策点使用,而非持续使用。render.py <edl.json> -o <out>— 逐段提取 → 拼接 → 覆盖层(PTS 移位)→ 最后添加字幕。--preview用于 720p 快速预览。--build-subtitles用于内联生成 master.srt。grade.py <in> -o <out>— ffmpeg 滤镜链调色。预设 +--filter '<raw>'用于自定义。
对于动画,使用 Bash 创建 <edit>/animations/slot_<id>/,并通过 Agent 工具生成一个子代理。
工作流程
-
盘点。 对每个源文件执行
ffprobe。对目录执行transcribe_batch.py。运行pack_transcripts.py生成takes_packed.md。采样一两个timeline_view以获得视觉初步印象。 -
预览问题。 快速浏览
takes_packed.md一次,记录口误、明显的错词或要避免的措辞。列出清单,为编辑器简报提供依据。 -
对话。 用通俗语言描述你所看到的。提出基于素材的问题。收集:内容类型、目标时长/宽高比、美学/品牌方向、节奏感受、必须保留的时刻、必须剪掉的时刻、动画和调色偏好、字幕需求。不要使用固定的检查清单——每次的正确问题都不同。
-
提出策略。 4–8 句话:结构、素材选取、剪辑方向、动画计划、调色方向、字幕样式、预估时长。等待确认。
-
执行。 通过编辑器子代理简报生成
edl.json。在模棱两可的时刻深入查看timeline_view。在并行子代理中构建动画。对每个片段应用调色。通过render.py合成。 -
预览。
render.py --preview。 -
自我评估(在展示给用户之前)。 在已渲染的输出(而非源文件)的每个剪辑边界(±1.5s 窗口)上运行
timeline_view。检查每张图像是否有:- 剪辑处的视觉不连续/闪烁/跳跃
- 边界处的波形尖峰(音频爆音,未被 30ms 淡入淡出消除)
- 隐藏在覆盖层后面的字幕(违反规则 1)
- 覆盖层未对齐或显示错误帧(违反规则 4)
另外,采样:前 2 秒、后 2 秒以及 2–3 个中间点——检查调色一致性、字幕可读性、整体连贯性。在输出上运行
ffprobe,验证时长是否符合 EDL 预期。如果任何项目失败:修复 → 重新渲染 → 重新评估。自我评估最多限制在 3 次——如果 3 次后问题仍然存在,请将其标记给用户,而不是无限循环。只有在自我评估通过后,才展示预览。
-
迭代 + 持久化。 自然语言反馈,重新计划,重新渲染。切勿重新转录。在确认后执行最终渲染。追加到
project.md。
剪辑技巧(技术)
- 音频优先。 从单词边界和静音间隙中寻找剪辑候选。
- 保留峰值。 笑声、笑点、强调节拍。将剪辑点扩展到笑点之后以包含反应——笑声本身就是节拍。
- 说话者切换受益于话语之间的空隙。常用值:400–600毫秒。快节奏时更短,电影感时更长。品味判断。
- 音频事件作为信号。
(笑)、(叹气)、(掌声)标记节拍。将这些事件包含在剪辑点之后。 - 静音间隙是剪辑候选。 静音 ≥400毫秒通常是最干净的。150–400毫秒的短语边界在视觉检查后可用。<150毫秒不安全(短语中)。
- 剪辑填充示例(随此技能发布的启动视频中所用):第一个保留词前 50 毫秒,最后一个词后 80 毫秒。混剪能量时更紧,纪录片风格时更松。保持在 30–200 毫秒的工作窗口内(硬性规则 7)。
- 永远不要独立处理音频和视频。 每个剪辑必须在两个轨道上都能工作。
打包的转录(主要阅读视图)
pack_transcripts.py 读取所有 transcripts/*.json 文件,生成一个 markdown 文件,其中每个片段是一个短语级行列表,每行以其 [开始时间-结束时间] 时间范围作为前缀。短语在遇到任何静音 ≥ 0.5 秒或说话者变化时断开。这是编辑器子代理用于选择剪辑的构件——它以文本形式提供单词边界精度,而仅使用原始 JSON 十分之一的令牌。
示例行:
## C0103 (时长: 43.0s, 8 个短语)
[002.52-005.36] S0 Ninety percent of what a web agent does is completely wasted.
[006.08-006.74] S0 We fixed this.
编辑器子代理简报(用于多素材选择)
当任务是“从多个片段中为每个节拍选择最佳素材”时,生成一个专用的子代理,其简报结构如下。该结构承载负载;音高形状示例不是。
你正在编辑一个 <类型> 视频。请为每个节拍选择最佳素材,并按节拍的时间顺序(而非源片段顺序)组装它们。
输入:
- takes_packed.md(所有素材的时间标注短语级转录)
- 产品/叙述上下文:<来自用户的 2 句话>
- 说话者:<姓名,角色,表达风格说明>
- 预期结构:<选择一个原型或自创一个>
- 要避免的口误:<来自预览扫描的列表>
- 目标时长:<秒>
常见结构原型(选择、改编或自创):
- 科技发布/演示: 钩子 → 问题 → 解决方案 → 好处 → 示例 → 行动号召
- 教程: 介绍 → 设置 → 步骤 → 陷阱 → 总结
- 访谈: (提问 → 回答 → 追问) 重复
- 旅行/活动: 到达 → 亮点 → 安静时刻 → 离开
- 纪录片: 论题 → 证据 → 反驳 → 结论
- 音乐/表演: 前奏 → 主歌 → 副歌 → 桥段 → 尾奏
- 或者自创一个。
规则:
- 开始/结束时间必须落在来自转录的单词边界上。
- 填充剪辑边界(工作窗口 30–200毫秒)。
- 优先选择静音 ≥ 400毫秒作为剪辑目标。
- 如果没有更好的素材,则保留不可避免的口误。在“原因”中注明。
- 如果超时,则修改:删除一个节拍或修剪尾部。报告总时长并自我纠正。
输出(JSON 数组,无散文):
[{"source": "C0103", "start": 2.42, "end": 6.85, "beat": "钩子",
"quote": "...", "reason": "..."}, ...]
返回最终的 EDL 和一行总时长检查。
调色(当用户要求时)
你的工作是分析图像,而不是应用预设。查看一帧(通过 timeline_view),决定哪里不对,调整一项,再次查看。
思维模型是 ASC CDL。每个通道:out = (in * slope + offset) ** power,然后是全局饱和度。slope → 高光,offset → 阴影,power → 中间调。
示例滤镜链(grade.py 有 --list-presets;将它们作为起点或混合自己的):
warm_cinematic— 复古/技术风,微妙的青橙分离,降低饱和度。在一个真实的发布视频中发运。对话头像安全。neutral_punch— 最小限度校正:对比度提升 + 温和的 S 曲线。无色调偏移。none— 直接复制。当用户未要求时的默认值。
对于任何其他类型——人像、自然、产品、音乐视频、纪录片——自创你的滤镜链。grade.py --filter '<raw ffmpeg>' 接受任何滤镜字符串。
硬性规则:在提取期间逐段应用(不是后期拼接,那样会二次编码)。未经测试肤色,切勿激进。
字幕(当用户要求时)
字幕有三个值得思考的维度:分块(每行 1/2/3/句子)、大小写(大写/首字母大写/自然)和位置(距底部边距)。正确的组合取决于内容。
实践样式——选择、改编或自创:
bold-overlay — 短格式科技发布、快节奏社交媒体。每行 2 个词,全大写,在标点处断开,Helvetica 18 粗体,白色带轮廓,MarginV=35。render.py 附带此样式为 SUB_FORCE_STYLE。
FontName=Helvetica,FontSize=18,Bold=1,
PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BackColour=&H00000000,
BorderStyle=1,Outline=2,Shadow=0,
Alignment=2,MarginV=35
natural-sentence(如果你发明了这种模式)——叙事、纪录片、教育。每行 4–7 个词,句子大小写,在自然停顿处断开,MarginV=60–80,较大字体
...
[为翻译而截断]