Communitygithub.com

HTML动态动画流水线 (9:16讲解视频,含配音和音效转MP4)

一个将HTML转换为9:16竖屏动态讲解视频的流水线,支持用户自录音频、逐词字幕和节点动画,最终输出MP4文件。

HTML动态动画流水线 (9:16讲解视频,含配音和音效转MP4) 是什么?

这个技能提供了一套完整的流水线,用于生成9:16竖屏的动画讲解视频 (类似抖音/Reels上的教育科技类账号风格)。它首先接收用户提供的配音音频文件(非TTS),然后通过`faster-whisper`进行逐词转录,并利用GSAP创建精确到帧的动画时间线。流水线的核心是视觉必须服务于脚本和配音:每个出现在画面中的元素都必须有对应的旁白,反之亦然。它包含一系列自动化检查工具,如布局审核 (`audit2.mjs`)、重叠检测 (`audit_overlap.mjs`) 和居中审核 (`audit_center.mjs`),以确保视觉质量,并为已适配的环境(如Claude Code、Cursor、GitHub Copilot)提供了详细的参考实现 (`index.fc-reference.html`)。最终,通过Playwright无头浏览器渲染每一帧,再使用ffmpeg编码为带有同步音效的H.264 MP4视频。该技能特别强调避免常见的陷阱,如线条穿透logo、字幕被UI遮挡、渲染时内存溢出,以及因未遵循脚本而导致视觉与配音脱节。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hasbiridwan57-creator/hermes-video-motion-skills/tree/main/html-motion-pipeline

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HTML 动画流水线 (9:16 讲解视频,含配音和音效转MP4)

已验证的流程。每个步骤的即用命令位于 assets/pipeline/。 完整参考实现:assets/pipeline/index.fc-reference.html (项目"函数调用"——复制后替换内容,切勿从零编写)。

为什么使用此流水线

  • 确定性:GSAP 时间线 paused,按帧搜索 -> MP4 = 预览。
  • 用户自己的配音 (来自 ElevenLabs/麦克风的文件),非 TTS;节奏可控。
  • 自动布局审核可检测文字超出画布或与其他元素碰撞——必须在完整渲染前通过(可节省1338帧的渲染)。
  • 整洁的连接线:锚点在节点边缘,位于底层 (见陷阱 #1)。

主要原则 (核心)

视觉效果服务于脚本与配音,而非相反。

  1. 屏幕上显示的所有内容必须存在于脚本中并由配音说出。有趣但未被叙述的元素 -> 删除,无论多么好看。
  2. 相反,脚本中的每个重要想法/句子必须拥有自己的图像,并在该短语被说出时出现。仅作为静态文本出现的句子 = "寂静"场景 -> 添加视觉效果。
  3. 场景多不是问题——关键是每个场景都要跟随配音和脚本。
  4. 更多的图像和动画 = 更好 (更生动)。不要吝啬添加视觉效果;视觉丰富度是附加值,而非弱点。
  5. 视觉的顺序和时机 = 配音中提及的顺序和时机 (根据转录时间戳),而不是自己的逻辑。
  6. 细节视觉质量也要保持:图标清晰可辨,元素平衡且不漂浮。

流程 (按顺序)

#步骤输出
1获取用户配音 + 按段分割 (呼吸间隙)meta.json
2通过 ffmpeg atempo 调整配音节奏 + 插入停顿;选择变体vo.wav
3逐词转录 (faster-whisper,pip install faster-whisper)assets/words.json
4构建 index.html (8个场景跟随配音时序) + sfx_score.pyHTML + SFX WAV
5混合配音 + 音效 -> public/full_mix.mp3最终音频
6布局审核 (audit2.mjs + audit_s2.mjs) — 必须0溢出报告
7渲染帧 (render_frames.mjs) -> 1338 个 PNGframes/
8编码 (encode.sh) -> MP4public/*.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 中)

  • #stage 1080×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),灰色 #7A8188 8px;活跃线 .hot 琥珀色 15px。
  • Agent Logo: OPENCLAW_SVG 内联 (红龙虾),自动放置到每个包含 🤖 的 .node.dark 中。如需更换其他身份,请替换。
  • GSAP 确定性:时间线 paused,暴露 window.__tl 和 window.__updateSub。 模式 ?t=<秒> 用于静态快照 (无头),?debug 用于手动擦除。

触发条件

用户提及短语 "流水线动态讲解",或要求 "9:16 动态讲解视频",或说 "像上次函数调用那个视频" -> 加载此技能。 不是 motion-format / bang-motion (其他技能)。用户配音总是以文件形式发送每次会话 — 本技能存储工作流程,而非音频/内容资产。

陷阱 (请勿重蹈覆辙)

  1. 线条穿过 Logo/文本 -> 确保:(a) SVG 电线是场景的第一个子元素, (b) z-index:0 电线 vs z-index:2 卡片,(c) 使用 link() 锚定在边缘。
  2. 字幕遮挡卡片 / 进入 UI 区域 -> 每行 1 块 (absolute),最多 4 词/块,底部 ≥390px。
  3. 渲染时 window.tl 未定义 -> 暴露的名称应为 window.__tl (使用 __),否则 74% 的帧将相同/静态。检查:md5 frames/* | uniq -c。
  4. 渲染后台重启 -> 在新渲染前确保无旧 render_frames 正在运行 (pgrep -fl render_frames);开始前删除 frames/。
  5. DOM 审核不能替代 MP4 视觉检查。 审核检测溢出和边界框碰撞,但不检测线条穿过 Logo 或文本遮挡卡片——这仅在最终像素中可见。编码后,从 MP4 提取关键帧 (ffmpeg -ss <t> -i out.mp4 -frames:v 1 f.png) 然后通过 vision_analyze 分析。
  6. 内容"悬挂在上方" (底部 2/3 为空)。 这最常被漏检,因为常规审核只检查溢出,不检查平衡。原因:所有 .hero 子元素使用 position:absolute -> justify-content:center 对它们无效。 解决方案:让 .hero 的子元素成为正常流 (block/flex flow),仅重叠元素 (徽章/划线/标记) 保持 absolute。必须运行 audit_center.mjs —— center 偏差 > 250px = 失败。
  7. 视觉效果不跟随脚本 (最具破坏性)。 不要因为动画在运行就认为场景"已完成"。真实案例:相关性图表和年龄图表显示在屏幕上,但配音从未提及它们。 渲染前的强制脚本审核:(a) 提取配音转录 + 逐词时间戳 (words.json),(b) 映射"这个短语在屏幕上什么时候出现?",(c) 显示但脚本中没有的元素 -> 删除;脚本中仅作为静态文本存在的短语 -> 添加视觉效果。视觉顺序 = 配音中的提及顺序。
  8. 渲染内存不足 (Mac 8GB)。 Chromium 在截取数百张截图时积累内存 -> 中途崩溃 ("目标页面已关闭")。 解决方案:每约 400 帧重启浏览器 + 自动恢复 (跳过已存在且 >20KB 的帧)。不要在一个浏览器会话中渲染 2500+ 帧。
  9. 修订后旧帧混杂。 如果仅修订了部分场景且仅删除了该范围的帧,frames/ 将变得混杂 (例如,实际需要 2574 帧却有了 2770 个文件)。 最安全的方法:在完整渲染前删除整个 frames/。如果恢复,在编码前验证文件数量 = 总帧数。
  10. Emoji 逃过 DOM 审核。 用户要求无 emoji —— 如果不自动检查,emojis 可能漏网,因为边界框审核不查看字符类型。渲染前,运行 Python 正则表达式查找 emoji 字符;如果找到 -> 替换为内联 SVG。图标始终是 SVG。 re.findall(r'[\U0001F300-\U0001FAFF\u2600-\u27BF\u2B00-\u2BFF\uFE0F]', html) -> 必须为 0。
  11. 图标和细节视觉必须在显示大小上清晰可辨 —— DOM 审核和布局审核不捕捉"图标不清楚"。 一个 SVG 可能在代码中有正确形状,但在渲染大小下 (例如,图中 180px 的图标) 看起来像别的东西:轮廓开放的脑图标可能被解读为云/花,而不是大脑。 修复: 在完整渲染前,从 MP4 提取帧,然后放大 (裁剪) 关键图标/图表,通过 vision_analyze 评估——"这能清晰可辨地表示为 X 吗?"。如果模糊,简化形状 (完整剪影 > 开放轮廓) 并增大尺寸。边界框审核只检查位置,不检查形状可读性。
  12. 比较元素 (A-vs-B 的条形图/柱状图) 必须是一个视觉组。 "浮动"在其父卡片之外的条形 (分离的绝对定位) 违反平衡,并在内容高度变化时容易覆盖其他元素。真实案例:萎缩/强壮肌肉的条形浮动在健身房卡片之外,然后与卡片碰撞。 修复: 将每个条形放入其自己的卡片/列单元格中;不同长度的条形是有意的 (长度 = 大小),但卡片宽度和基线必须相同。每次布局修订后通过 audit_overlap 检查。
  13. 文本重叠即使看起来"只有一点点"。 不要依赖肉眼;使用 audit_overlap.mjs 测量真实边界框。巨大的 ?,装饰性大数字,或长标题常常不知不觉地覆盖其他文本。
  14. 编码/AI 主题如果没有打字动画会显得死板。 静态文本无法传达编码氛围的工作方式。使用 typing-prompt.js 配方:提示逐字母打字 + 光标闪烁 + 应用响应 (改变颜色 -> 错误 -> 修复 -> 迭代)。
  15. 来自网络的 Logo/图标: 下载官方 SVG (jsDelivr CDN / 品牌 GitHub 仓库),然后作为文本内联到 HTML 中 —— 不要使用 <img src> 链接到外部文件,以确保无头渲染不依赖网络。剥离 SMIL 动画以实现确定性输出。

声音规则 (用户 Hasbi)

  • 配音必须是用户自己的声音 (发送的 ElevenLabs 文件),非 TTS。
  • 程序化音效通过 procedural-sfx 技能 (无需 ElevenLabs 积分)。
  • 发送 MP4 后删除原始帧和辅助文件 (frames/,shots/,*.wav 每段) —— MacBook 存储有限。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

motion-format

Bikin video motion graphic lewat chat dengan alur kerja Motion Format — Reels/TikTok/Shorts 9:16, YouTube 16:9, atau feed 1:1 — dari brief sampai MP4 bersuara (voiceover + efek suara ElevenLabs, subtitle per kata). Punya resep gaya siap pakai dari seri konten Motion Format: Isometrik Dibongkar (cara kerja mesin, 3D), Sejarah 3D Sinematik (bangunan & peristiwa bersejarah), Tubuh Manusia Anime (organ tubuh), Dunia 2D Bertekstur (noir, cat air, ukiran, lanskap anime), Kartun Cel Cerah (tokoh menjelaskan), Peta Relief Sinematik (geografi, jalur, wilayah), dan Promo Produk & Iklan (UMKM, aplikasi, flash sale) — plus cara meracik gaya sendiri. Gunakan setiap kali user meminta "video", "konten Reels/TikTok/Shorts", "explainer", "video edukasi", "video penjelasan", "promo", "iklan", "intro", "animasi", "motion graphic", menyebut salah satu gaya di atas atau "Resep Gaya", ingin menambah voiceover/efek suara/subtitle, ingin merevisi video yang sudah ada, atau ingin merender jadi MP4 — walau tida

video-motion

SOP induk untuk bikin video motion/explainer bersuara via chat (9:16 Reels/TikTok, 16:9 YouTube, 1:1 feed) — menggabungkan alur kerja Motion Format (brief→gaya→naskah→ suara→adegan→render), hukum sinematik Bang Motion (video bukan slide, deterministik, gaya dari tema), dan pipeline HTML→MP4 teruji (html-motion-pipeline: faster-whisper, SFX prosedural, CDP render, audit layout, subtitle aman Reels). Gunakan bila user minta video motion/explainer/animasi/promo, atau "kayak video sebelumnya" — walau tidak menyebut "motion graphic".

相关技能