video-edit

Video Edit — 字幕展示视频流水线

基于 HyperFrames 的端到端字幕视频编辑器。用户提供视频后，你负责协调转录 → 审核 → 渲染，并且务必在长时间渲染前暂停，等待用户批准转录稿。

此技能在 YUV.AI 金字塔中的位置

video-edit 位于 YUV.AI 技能金字塔的中间层，与 yuv-design-system、yuv-decks、yuv-viral-video、parallax-landing-page 和 video-to-landing-page 并列。每当用户需要带字幕的展示视频、教程或真人出镜视频剪辑时，顶层编排器 yuv-pilot 都会将任务路由到此处。

这是 yuv-viral-video 的通用视频姊妹技能。二者的区别：

• yuv-viral-video — YUV.AI 的观点鲜明的爆款短视频流水线（MrBeast 式节奏、标志性编辑风格）
• video-edit — 通用字幕编辑器，渲染前先审核转录稿（支持希伯来语、英语以及 Whisper 支持的任何语言）

对于带有 YUV.AI 品牌元素的字幕视频，将此技能与 yuv-design-system 搭配使用（通过 Neon 模式决定字体与配色）。对于通用或第三方字幕视频，此技能可独立使用。

何时调用

• 提供视频文件路径（mp4/mov/mkv），并要求“编辑”“加字幕”“添加字幕”“制作短片/宣传片”或“照着做”
• “修正字幕 / 希伯来语拼写错误”——从现有项目的审核步骤重新开始
• 制作任何带字幕的教程、真人出镜视频或宣传片

保存位置

默认： ~/Documents/yuv-projects/videos/<slug>/ — 始终将带字幕的视频项目保存在此处，方便找到渲染结果。<slug> 是根据主题或源文件名生成的简短名称。

mkdir -p ~/Documents/yuv-projects/videos
cd ~/Documents/yuv-projects/videos
# Initialize the project here.

最终渲染文件位于 ~/Documents/yuv-projects/videos/<slug>/renders/<name>_FINAL.mp4。渲染结束时告知用户视频的保存位置。

---

工作流（12 步）

1. 检查源文件 — 使用 ffprobe 获取尺寸、fps、时长和音频信息。

2. 搭建项目 — 执行 cd ~/Documents/yuv-projects/videos && npx hyperframes init <slug> --video <path> --non-interactive。将复制后的视频重命名为 source.mp4。

3. 提取音频 — 执行 ffmpeg -i source.mp4 -vn -ac 1 -ar 16000 audio.wav。

4. 转录 — 将 references/transcribe.py 复制到项目中。默认模型为 large-v3（最适合希伯来语）。CUDA 在 Windows 上通常会失败（缺少 cuDNN）；脚本会回退到 CPU int8。希伯来语使用 language="he"，英语使用 language="en"；否则自动检测。

5. 应用已知修正 — 将 references/corrections-hebrew.md 的内容复制到项目根目录下的 corrections.json 中（键 = 错误词元，值 = 正确词元）。

6. 🛑 停止——启动审核服务器，让用户在 Web 应用中批准。 先应用已知修正：将 references/make_review.py 复制到项目中并运行 python make_review.py。此脚本会将 corrections.json 应用到 transcript.json。

   然后将审核服务器作为后台任务启动（它会一直阻塞，直到用户在浏览器中点击 “Approve & Render”）：

   python "$HOME/.claude/skills/video-edit/references/serve_review.py" .
   # On Windows: python "C:\Users\<you>\.claude\skills\video-edit\references\serve_review.py" .
   

   服务器会打印类似 REVIEW_URL=http://localhost:PORT/ 的一行内容。从 后台任务输出中提取该 URL（或读取标准输出），然后发送给用户：

   👉 在此处审核你的转录稿：http://localhost:PORT/ 点击 Approve & Render 后，我会自动继续。

   Agent 不需要等待用户发送“continue”消息——用户点击按钮后，服务器会将 transcript_review.txt 写入项目目录，然后以代码 0 退出。Agent 的后台任务通知 会触发，流水线便会从第 8 步继续。

   没有浏览器或服务器时的备用方案：将编辑器作为静态文件打开 （start "" "$HOME/.claude/skills/video-edit/transcript-editor/index.html"）， 请用户选择项目文件夹、进行编辑，并将 transcript_review.txt 保存回项目中， 然后回复“continue”。编辑器支持这两种模式。

7. （可选）移除背景 — 见下方第 7 步；可与用户审核并行进行。

8. 批准后，运行 python references/apply_review.py。它会重新对编辑过的行进行分词，并将词语时间重新分配到 transcript.json，确保字幕仍能同步。

9. （可选）移除背景 — 如果任何真人出镜片段需要在人物身后显示文字，请将该片段提取为 outro.mp4（或 intro.mp4），然后运行 npx hyperframes remove-background <clip>.mp4 -o <name>_subject.webm --quality best。大多数配置下仅使用 CPU（处理约 15 秒的 1440p 片段需约 3–8 分钟）。

10. 使用密集关键帧重新编码源视频 — 多工作进程渲染时，稀疏关键帧会导致定位冻结。务必运行：

    ffmpeg -y -i source.mp4 -c:v libx264 -preset medium -crf 18 -r 30 -g 30 -keyint_min 30 -sc_threshold 0 -pix_fmt yuv420p -movflags +faststart -c:a copy footage.mp4
    

11. 重新加载（编辑后的）转录文本，并通过 references/gen_body.py 生成主体子合成。生成器会输出完整的 compositions/components/caption-body.html，其中编辑内容与矩阵内容交替显示在液态玻璃药丸形元素中，并锚定在中间偏左下方（避开右下角的摄像头画中画）。

12. 根据 references/host-template.html 配置宿主 index.html。图层顺序（按 z-index，而非 track-index）：

    • z0：视频素材 .cam-bg
    • z1：液态斑点背景（compositions/liquid-blobs.html，mix-blend-mode: screen，持续全程）
    • z2：人物身后的视差字幕（使用背景移除时显示片头和／或片尾）
    • z3：人物抠像 .cam-out / .cam-sub（使用匹配的 data-media-start）
    • z6：主体字幕
    • z46：进度条 + 闪光 + 液态变形转场

13. 检查代码 — npx hyperframes lint。错误数必须为 0。常见修复方法：擦除元素上的 GSAP/CSS 变换冲突（使用 xPercent/yPercent 或移除 CSS 变换）；同一属性上的补间动画重叠（添加 overwrite: "auto"）。

14. 渲染 — npx hyperframes render --quality standard --fps 30 --output renders/<name>_FINAL.mp4。standard 是合适的交付目标；high 的渲染时间大约会翻倍。完成前，请从整个时间线上抽取 6–8 帧进行检查。

TikTok / Reels / Shorts 竖屏（9:16）输出

当用户要求将（16:9 源视频）输出为竖屏／纵向／TikTok / Reels / 9:16 格式时：

1. 将项目克隆到同级文件夹：cp -r project/ project-vertical/。
2. 将其 index.html 替换为 references/host-template-vertical.html（1080×1920 画布、带液态斑点的模糊背景、居中横向显示的 16:9 视频素材条带，以及下方的字幕）。
3. 将其 gen_body.py 替换为 references/gen_body_vertical.py（居中药丸形元素、更大的字体、更窄的最大宽度），然后重新运行以生成 compositions/components/caption-body.html。
4. 移除人物抠像和视差子合成（抠像已按 16:9 对齐；v1 版本不值得重新对齐）。竖屏合成改用模糊源视频背景和斑点营造氛围。
5. 将 data-duration 更新为实际视频时长。更新 index.html 中的品牌标签文本（默认为 YUV.AI）。
6. 检查代码并渲染 — 使用相同命令。输出为 1080×1920。可直接上传到 TikTok / IG Reels / YT Shorts。

如需一次性交付 16:9 和 9:16 两种格式，请运行两条渲染命令（在各自的项目中并行执行）。transcript_review.txt 的批准对两者都有效 — 字幕相同，合成不同。

关键规则

• 未经明确的转录稿批准，绝不渲染最终成片。 审核步骤是整个流程的核心。
• 对于希伯来语：使用 large-v3 + language="he" + direction: rtl + Rubik（700 + 900，用于编辑风格的双字重强调）。
• 字幕胶囊始终需要不透明的深色底板——浅色文字直接叠在白色应用界面上会消失。
• 字幕胶囊应水平居中，但如果画面右下角有摄像头画中画（PiP），则将中心 x 坐标向左移（例如 left: 720px）。
• 主体后方的抠像片段必须设置 data-media-start，使其与 data-start 匹配（如果片段是从源素材中提取的，则匹配提取偏移量），否则抠像会从第 0 帧开始播放并失去同步。
• remove-background webm 保留原始 RGB，仅写入 Alpha 蒙版——ffprobe 会报告 yuv420p，看起来像是“没有 Alpha”。请通过 TAG:ALPHA_MODE=1 确认，或将其合成到纯色背景上。
• 已烧录文字的片尾／结束卡片——不要在其上叠加字幕，以免冲突。

文件引用

文件	用途
transcript-editor/index.html	交互式浏览器编辑器——视频预览、RTL 编辑、应用词典、可选的 WebLLM AI 建议，保存为 transcript_review.txt
references/setup.md	Node / Python / FFmpeg / faster-whisper 的先决条件与安装命令
references/transcribe.py	faster-whisper 转录，支持 CPU 回退和单词时间戳
references/serve_review.py	本地审核服务——自动加载编辑器，阻塞等待用户点击 Approve & Render，然后写入 transcript_review.txt 并退出（向 Agent 发出信号）
references/make_review.py	应用修正并生成 transcript_review.txt（文件模式回退方案）
references/apply_review.py	解析编辑后的审核文件，重新分配单词时间，更新 transcript.json
references/gen_body.py	字幕正文生成器（编辑风格 + 液态玻璃胶囊中的矩阵样式）
references/host-template.html	16:9 主体合成模板，带液态效果和转场擦除
references/host-template-vertical.html	9:16 主体模板（1080×1920）——TikTok / Reels / Shorts 布局：模糊背景、居中 16:9 素材条、下方字幕、右上角品牌标识
references/gen_body_vertical.py	为竖屏优化的字幕正文生成器（居中胶囊、更大字体、更窄的最大宽度）
references/liquid-blobs.html	全时长漂移流体形状图层
references/caption-parallax-outro.html	主体后方字幕模板（英文；克隆后用于其他语言）
references/corrections-hebrew.md	Whisper 对希伯来语的已知误听
references/transcript-review-workflow.md	暂停／批准步骤详解