HTML 动画流水线 (9:16 讲解视频,含配音和音效转MP4)
已验证的流程。每个步骤的即用命令位于 assets/pipeline/。
完整参考实现:assets/pipeline/index.fc-reference.html (项目"函数调用"——复制后替换内容,切勿从零编写)。
为什么使用此流水线
- 确定性:GSAP 时间线
paused,按帧搜索 -> MP4 = 预览。 - 用户自己的配音 (来自 ElevenLabs/麦克风的文件),非 TTS;节奏可控。
- 自动布局审核可检测文字超出画布或与其他元素碰撞——必须在完整渲染前通过(可节省1338帧的渲染)。
- 整洁的连接线:锚点在节点边缘,位于底层 (见陷阱 #1)。
主要原则 (核心)
视觉效果服务于脚本与配音,而非相反。
- 屏幕上显示的所有内容必须存在于脚本中并由配音说出。有趣但未被叙述的元素 -> 删除,无论多么好看。
- 相反,脚本中的每个重要想法/句子必须拥有自己的图像,并在该短语被说出时出现。仅作为静态文本出现的句子 = "寂静"场景 -> 添加视觉效果。
- 场景多不是问题——关键是每个场景都要跟随配音和脚本。
- 更多的图像和动画 = 更好 (更生动)。不要吝啬添加视觉效果;视觉丰富度是附加值,而非弱点。
- 视觉的顺序和时机 = 配音中提及的顺序和时机 (根据转录时间戳),而不是自己的逻辑。
- 细节视觉质量也要保持:图标清晰可辨,元素平衡且不漂浮。
流程 (按顺序)
| # | 步骤 | 输出 |
|---|---|---|
| 1 | 获取用户配音 + 按段分割 (呼吸间隙) | meta.json |
| 2 | 通过 ffmpeg atempo 调整配音节奏 + 插入停顿;选择变体 | vo.wav |
| 3 | 逐词转录 (faster-whisper,pip install faster-whisper) | assets/words.json |
| 4 | 构建 index.html (8个场景跟随配音时序) + sfx_score.py | HTML + SFX WAV |
| 5 | 混合配音 + 音效 -> public/full_mix.mp3 | 最终音频 |
| 6 | 布局审核 (audit2.mjs + audit_s2.mjs) — 必须0溢出 | 报告 |
| 7 | 渲染帧 (render_frames.mjs) -> 1338 个 PNG | frames/ |
| 8 | 编码 (encode.sh) -> MP4 | public/*.mp4 |
| 9 | 检查最终 MP4 视觉效果 — 从 MP4 提取帧,通过视觉分析 | 确认无误 |
一次性设置
cd <项目目录>
npm init -y && npm install playwright-core gsap
pip install faster-whisper # 用于逐词转录
# 需要:Google Chrome (/Applications/Google Chrome.app),ffmpeg
流水线脚本
assets/pipeline/:
render_frames.mjs— 逐帧搜索时间线,截取 1080×1920 @30fps 截图。snap.mjs— 拍摄特定时刻 (node snap.mjs 1.0 6.5 17.5) 用于检查视觉效果。audit2.mjs— 检查所有场景:文本是否超出画布 / 进入底部 UI 区域 (>1560px) / 碰撞。audit_s2.mjs— 审核单个场景 (sc2) 的多个时刻 (检测过早揭示、靠近边缘)。audit_overlap.mjs— 检测真正重叠的文本 (文本×文本,文本×图片,文本×按钮)。智能区分真实碰撞与设计性重叠:SVG 容器内的标签、划线/删除线/穿透线、并排的弹性字幕 -> 不会报告。 运行node assets/pipeline/audit_overlap.mjs-> 目标TOTAL 重叠: 0。audit_center.mjs— 检测"悬挂在上方"的内容 (底部 2/3 为空)。测量每个场景内容的边界框,计算与理想中心点 (y≈960,对于 1920px 高度) 的偏差。偏差 > 250px = ⚠ 悬挂。运行node assets/pipeline/audit_center.mjs。typing-prompt.js— "打字提示"动画配方 (编码/AI 主题核心):提示逐字母打字 + 光标闪烁,然后应用响应 (改变颜色 -> 错误 -> 修复 -> 迭代)。 完整示例:仓库视频09-vibe-coding/index.html场景 SK4。encode.sh— ffmpeg -> H.264 yuv420p CRF18 + AAC 192k ++faststart。sfx_score.py— 程序化音效配乐,与词语时间同步。index.fc-reference.html— 完整实现 (复制并替换内容)。
HTML 约定 (在 index.fc-reference.html 中)
#stage1080×1920,点阵背景;#world(摄像机支架,每场景微调缩放); 场景 =.scene(可见性隐藏,通过时间线显示/隐藏)。- 逐词字幕:
assets/words.json-> 分组为每个块 ≤4 个词,一个块 = 一个.line(position:absolute,堆叠以免扩展盒子), 活动词.on,关键词.key(琥珀色)。位置距离底部 390px (安全于覆盖约底部360px 的 Reels/TikTok UI)。 - 连接线: 函数
link(svg,idA,idB)计算节点边缘的锚点 (edge/edgeT) — 线条不从 Logo 中心穿出。SVG.wires放置 作为.scene的第一个子元素 (z-index:0) 以位于卡片之后 (z-index:2)。柔和的曲线 (弯曲度 ≤26px),灰色#7A81888px;活跃线.hot琥珀色 15px。 - Agent Logo:
OPENCLAW_SVG内联 (红龙虾),自动放置到每个包含🤖的.node.dark中。如需更换其他身份,请替换。 - GSAP 确定性:时间线
paused,暴露window.__tl和window.__updateSub。 模式?t=<秒>用于静态快照 (无头),?debug用于手动擦除。
触发条件
用户提及短语 "流水线动态讲解",或要求 "9:16 动态讲解视频",或说 "像上次函数调用那个视频" -> 加载此技能。
不是 motion-format / bang-motion (其他技能)。用户配音总是以文件形式发送每次会话 — 本技能存储工作流程,而非音频/内容资产。
陷阱 (请勿重蹈覆辙)
- 线条穿过 Logo/文本 -> 确保:(a) SVG 电线是场景的第一个子元素,
(b)
z-index:0电线 vsz-index:2卡片,(c) 使用link()锚定在边缘。 - 字幕遮挡卡片 / 进入 UI 区域 -> 每行 1 块 (absolute),最多 4 词/块,底部 ≥390px。
- 渲染时
window.tl未定义 -> 暴露的名称应为window.__tl(使用__),否则 74% 的帧将相同/静态。检查:md5 frames/* | uniq -c。 - 渲染后台重启 -> 在新渲染前确保无旧
render_frames正在运行 (pgrep -fl render_frames);开始前删除frames/。 - DOM 审核不能替代 MP4 视觉检查。 审核检测溢出和边界框碰撞,但不检测线条穿过 Logo 或文本遮挡卡片——这仅在最终像素中可见。编码后,从 MP4 提取关键帧 (
ffmpeg -ss <t> -i out.mp4 -frames:v 1 f.png) 然后通过 vision_analyze 分析。 - 内容"悬挂在上方" (底部 2/3 为空)。 这最常被漏检,因为常规审核只检查溢出,不检查平衡。原因:所有
.hero子元素使用position:absolute->justify-content:center对它们无效。 解决方案:让.hero的子元素成为正常流 (block/flex flow),仅重叠元素 (徽章/划线/标记) 保持 absolute。必须运行audit_center.mjs—— center 偏差 > 250px = 失败。 - 视觉效果不跟随脚本 (最具破坏性)。 不要因为动画在运行就认为场景"已完成"。真实案例:相关性图表和年龄图表显示在屏幕上,但配音从未提及它们。
渲染前的强制脚本审核:(a) 提取配音转录 + 逐词时间戳 (
words.json),(b) 映射"这个短语在屏幕上什么时候出现?",(c) 显示但脚本中没有的元素 -> 删除;脚本中仅作为静态文本存在的短语 -> 添加视觉效果。视觉顺序 = 配音中的提及顺序。 - 渲染内存不足 (Mac 8GB)。 Chromium 在截取数百张截图时积累内存 -> 中途崩溃 ("目标页面已关闭")。 解决方案:每约 400 帧重启浏览器 + 自动恢复 (跳过已存在且 >20KB 的帧)。不要在一个浏览器会话中渲染 2500+ 帧。
- 修订后旧帧混杂。 如果仅修订了部分场景且仅删除了该范围的帧,
frames/将变得混杂 (例如,实际需要 2574 帧却有了 2770 个文件)。 最安全的方法:在完整渲染前删除整个frames/。如果恢复,在编码前验证文件数量 = 总帧数。 - Emoji 逃过 DOM 审核。 用户要求无 emoji —— 如果不自动检查,emojis 可能漏网,因为边界框审核不查看字符类型。渲染前,运行 Python 正则表达式查找 emoji 字符;如果找到 -> 替换为内联 SVG。图标始终是 SVG。
re.findall(r'[\U0001F300-\U0001FAFF\u2600-\u27BF\u2B00-\u2BFF\uFE0F]', html)-> 必须为 0。 - 图标和细节视觉必须在显示大小上清晰可辨 —— DOM 审核和布局审核不捕捉"图标不清楚"。 一个 SVG 可能在代码中有正确形状,但在渲染大小下 (例如,图中 180px 的图标) 看起来像别的东西:轮廓开放的脑图标可能被解读为云/花,而不是大脑。 修复: 在完整渲染前,从 MP4 提取帧,然后放大 (裁剪) 关键图标/图表,通过 vision_analyze 评估——"这能清晰可辨地表示为 X 吗?"。如果模糊,简化形状 (完整剪影 > 开放轮廓) 并增大尺寸。边界框审核只检查位置,不检查形状可读性。
- 比较元素 (A-vs-B 的条形图/柱状图) 必须是一个视觉组。 "浮动"在其父卡片之外的条形 (分离的绝对定位) 违反平衡,并在内容高度变化时容易覆盖其他元素。真实案例:萎缩/强壮肌肉的条形浮动在健身房卡片之外,然后与卡片碰撞。 修复: 将每个条形放入其自己的卡片/列单元格中;不同长度的条形是有意的 (长度 = 大小),但卡片宽度和基线必须相同。每次布局修订后通过 audit_overlap 检查。
- 文本重叠即使看起来"只有一点点"。 不要依赖肉眼;使用
audit_overlap.mjs测量真实边界框。巨大的?,装饰性大数字,或长标题常常不知不觉地覆盖其他文本。 - 编码/AI 主题如果没有打字动画会显得死板。 静态文本无法传达编码氛围的工作方式。使用
typing-prompt.js配方:提示逐字母打字 + 光标闪烁 + 应用响应 (改变颜色 -> 错误 -> 修复 -> 迭代)。 - 来自网络的 Logo/图标: 下载官方 SVG (jsDelivr CDN / 品牌 GitHub 仓库),然后作为文本内联到 HTML 中 —— 不要使用
<img src>链接到外部文件,以确保无头渲染不依赖网络。剥离 SMIL 动画以实现确定性输出。
声音规则 (用户 Hasbi)
- 配音必须是用户自己的声音 (发送的 ElevenLabs 文件),非 TTS。
- 程序化音效通过
procedural-sfx技能 (无需 ElevenLabs 积分)。 - 发送 MP4 后删除原始帧和辅助文件 (
frames/,shots/,*.wav每段) —— MacBook 存储有限。