视频编辑——带字幕展示流水线
基于 HyperFrames 的端到端带字幕视频编辑器。用户提供视频,你编排转写→审核→渲染,并在长时间渲染前始终暂停等待用户批准转写文本。
该技能在 YUV.AI 技能体系中的位置
video-edit 位于 YUV.AI 技能金字塔的中间层,与 yuv-design-system、yuv-decks、yuv-viral-video、parallax-landing-page 和 video-to-landing-page 并列。顶层编排器 yuv-pilot 会在用户需要带字幕的展示视频、教程或带字幕的 talking-head 视频时路由至此。
这是 yuv-viral-video 的更通用的视频编辑兄弟技能。两者的分工:
yuv-viral-video—— 强观点 YUV.AI 病毒式短视频流水线(MrBeast 节奏、标志性编辑风格)video-edit—— 通用带字幕编辑器,支持转写审核后再渲染(希伯来语 + 英语 + 任何 Whisper 支持的语言)
对于 YUV.AI 品牌的带字幕视频,将此技能与 yuv-design-system(Neon 模式用于字体/配色决策)搭配使用。对于通用/第三方带字幕视频,该技能可独立运行。
何时调用
- 提供视频文件路径(mp4/mov/mkv)+ 要求“编辑”、“加字幕”、“添加字幕”、“制作 Reel/宣传片”或“做同样的处理”
- “修复字幕 / 希伯来语拼写错误”——在现有项目的审核步骤重新进入
- 任何带字幕的教程 / talking-head / 宣传片构建
保存位置
默认: ~/Documents/yuv-projects/videos/<slug>/ —— 始终将带字幕视频项目保存于此,以便渲染结果可寻。<slug> 简短,由主题或源文件名派生。
mkdir -p ~/Documents/yuv-projects/videos
cd ~/Documents/yuv-projects/videos
# 在此初始化项目。
最终渲染输出位于 ~/Documents/yuv-projects/videos/<slug>/renders/<name>_FINAL.mp4。渲染结束时告知用户视频位置。
工作流(12 步)
-
探测源文件 —— 使用
ffprobe获取尺寸、帧率、时长、音频信息。 -
搭建脚手架 —— 执行
cd ~/Documents/yuv-projects/videos && npx hyperframes init <slug> --video <path> --non-interactive。将复制的视频重命名为source.mp4。 -
提取音频 —— 执行
ffmpeg -i source.mp4 -vn -ac 1 -ar 16000 audio.wav。 -
转写 —— 将
references/transcribe.py复制到项目中。默认模型large-v3(希伯来语最佳)。CUDA 通常在 Windows 上失败(缺少 cuDNN);脚本回退到 CPU int8。对于希伯来语强制使用language="he",英语使用language="en";否则自动检测。 -
应用已知修正 —— 将
references/corrections-hebrew.md的内容复制到项目根目录下的corrections.json中(键 = 错误 token,值 = 正确 token)。 -
🛑 停止——启动审核服务器并让用户在 Web 应用中批准。 首先应用已知修正:将
references/make_review.py复制到项目中并运行python make_review.py。它会将corrections.json应用于transcript.json。然后将审核服务器作为后台任务启动(它会阻塞直到用户在浏览器中点击“批准并渲染”):
python "$HOME/.claude/skills/video-edit/references/serve_review.py" . # Windows 上:python "C:\Users\<你>\.claude\skills\video-edit\references\serve_review.py" .服务器会打印一行类似
REVIEW_URL=http://localhost:PORT/的内容。从后台任务输出(或读取 stdout)获取该 URL,然后发送给用户:👉 在此处审核您的转写文本:http://localhost:PORT/ 点击 批准并渲染 后,我将自动继续。
代理无需等待“继续”消息——当用户点击按钮时,服务器会将
transcript_review.txt写入项目目录并以退出码 0 退出。代理的后台任务通知触发,流水线从步骤 8 继续执行。无浏览器/无服务器时的回退方案:以静态文件方式打开编辑器(
start "" "$HOME/.claude/skills/video-edit/transcript-editor/index.html"),要求用户选择项目文件夹,编辑,保存transcript_review.txt回项目目录,然后回复“继续”。编辑器支持两种模式。 -
(可选)背景移除 —— 见下方步骤 7;可与用户的审核并行运行。
-
批准后,运行
python references/apply_review.py。它会重新标记化编辑过的行并重新分配单词时间戳回transcript.json,以便字幕同步仍然有效。 -
(可选)背景移除 —— 如果任何 talking-head 片段需要主体后文本,将该片段提取为
outro.mp4(或intro.mp4),然后运行npx hyperframes remove-background <clip>.mp4 -o <name>_subject.webm --quality best。大多数设置下仅支持 CPU(~3–8 分钟处理一个 ~15s 的 1440p 片段)。 -
使用密集关键帧重新编码源文件 —— 多工作者渲染在稀疏关键帧上会冻结。始终运行:
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 -
重新加载(已编辑的)转写文本并通过
references/gen_body.py生成主体子合成。生成器输出完整的compositions/components/caption-body.html,其中 editorial 和 matrix 交替显示在液态玻璃胶囊中,锚定在左下角偏中心位置(为右下角网络摄像头 PiP 留出空间)。 -
从
references/host-template.html接入宿主index.html。图层顺序(z-index,非轨道索引):- z0:视频源
.cam-bg - z1:液态 blob 背景(
compositions/liquid-blobs.html,mix-blend-mode: screen,全时长) - z2:视差主体后字幕(intro 和/或 outro,当使用背景移除时)
- z3:主体抠像
.cam-out/.cam-sub(带有匹配的data-media-start) - z6:主体字幕
- z46:进度条 + 闪光 + 液态变形转场
- z0:视频源
-
检查 —— 运行
npx hyperframes lint。必须为 0 错误。常见修复:转场元素上的 GSAP/CSS transform 冲突(使用xPercent/yPercent或移除 CSS transform);同一属性上的重叠 tween(添加overwrite: "auto")。 -
渲染 —— 运行
npx hyperframes render --quality standard --fps 30 --output renders/<name>_FINAL.mp4。Standard 是正确的交付目标——high会使渲染时间大约翻倍。在报告完成前,通过时间轴上的 6–8 个抽查帧进行验证。
竖屏(9:16)输出用于 TikTok / Reels / Shorts
当用户要求竖屏/肖像/TikTok/Reels/9:16 输出(来自 16:9 源文件)时:
- 将项目克隆到兄弟文件夹:
cp -r project/ project-vertical/。 - 将其
index.html替换为references/host-template-vertical.html(1080×1920 画布,带液态 blob 的模糊背景,16:9 视频源作为居中水平条,字幕在下方)。 - 将其
gen_body.py替换为references/gen_body_vertical.py(居中胶囊,更大字体,更窄最大宽度),然后重新运行以生成compositions/components/caption-body.html。 - 删除主体后抠像 + 视差子合成(抠像针对 16:9 对齐;v1 版本不值得重新对齐)。竖屏合成使用模糊源背景 + blob 来营造氛围。
- 更新
data-duration为实际视频时长。更新index.html中的品牌芯片文本(默认为YUV.AI)。 - 检查 + 渲染——命令相同。输出为
1080×1920。可直接上传到 TikTok / IG Reels / YT Shorts。
要一次性交付同时16:9 和 9:16,运行两个渲染命令(在并行项目中)。transcript_review.txt 的批准适用于两者——相同字幕,两种合成。
关键规则
- 未经明确转写文本批准,切勿渲染最终视频。 审核步骤是整个流程的核心。
- 对于希伯来语:
large-v3+language="he"+direction: rtl+ Rubik(700 + 900 用于 editorial 双权重强调)。 - 字幕胶囊始终需要不透明的深色背景——裸色浅文本在白色应用 UI 上会消失。
- 水平居中字幕胶囊,但当视频源有右下角网络摄像头 PiP 时,将中心 x 坐标向左移动(例如
left: 720px)。 - 主体后抠像片段必须携带与其
data-start匹配的data-media-start(如果片段是从源文件中提取的,则匹配与源的偏移量),否则抠像将从第 0 帧开始播放并导致不同步。 remove-background输出的 webm 保留原始 RGB 并仅写入 alpha 蒙版——ffprobe报告yuv420p,看起来像“无 alpha”。通过TAG:ALPHA_MODE=1确认,或叠加在纯色上进行验证。- Outro/结束卡片带有烧录文本——不要在其上添加字幕;它们会冲突。
文件引用
| 文件 | 用途 |
|---|---|
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 | 本地审核服务器——自动加载编辑器,阻塞直到用户点击批准并渲染,然后写入 transcript_review.txt 并退出(通知代理) |
references/make_review.py | 应用修正 + 输出 transcript_review.txt(文件模式回退) |
references/apply_review.py | 解析已编辑的审核文件,重新分配单词时间戳,更新 transcript.json |
references/gen_body.py | 字幕主体生成器(editorial + matrix 交替显示在液态玻璃胶囊中) |
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 | 全时长的流动 blob 图层 |
references/caption-parallax-outro.html | 主体后字幕模板(英语;其他语言请克隆) |
references/corrections-hebrew.md | 已知的希伯来语 Whisper 误听修正 |
references/transcript-review-workflow.md | 暂停/批准步骤的详细说明 |