HTML To Explainer Video — Development skill for Claude Code

html-to-explainer-video

[English](README.en.md) · 简体中文

一个 Agent Skill：把一个主题做成**带配音、词级字幕和动效画面的讲解视频**（MP4），并配好封面。

你给题目和时长，智能体按固定流水线推进：调研 → 解说词 → 配音 → 字幕与节拍 → HTML/GSAP 画面 → 逐帧渲染 → 质检 → 封面。 画面里每个元素的出场时刻都锚在解说词的吐字时刻上，改一句词、重跑配音，画面自动重新对位。

---

特性

配音	默认 阿里云百炼 qwen-audio-3.1-tts-flash（字级时间戳，18 个实测音色）；也可切 edge-tts（免密钥）或火山引擎语音合成 2.0。三种引擎产出同一种 manifest，下游零改动
字幕	按词/字级时间戳切块、硬字幕烧录，同时输出 SRT / VTT；数字展开读法（「2026」→「二零二六」）会映射回原文，不会错位
画面	HTML + CSS + GSAP，1920×1080 或竖版；23 个风格模板（8 类）+ 40 多个动效词汇；style_director.py 读解说词给每场挑风格与动效强度
音画同步	场景里写 B('块文本') 取该字幕块的起播秒排动画；时长取 MP3 容器时长，拼音轨时每段按同一时长补齐到采样（长片不漂移），字幕收尾取语音真实结束
渲染	确定性逐帧 seek 截图（不是实时录屏）；1080p / 2K / 4K，30 / 60 fps；可选快门运动模糊；多浏览器进程并行、断点续渲
质检	渲染前：节拍引用校验、契约 lint、几何体检（遮挡 / 越界 / 侵入字幕带）；渲染后：流、时长、音量、抽帧速览、逐帧连续性（单帧跳动、场间硬切）
封面	16:9 + 3:4（投竖版再加 9:16），每张独立排版，出图后做几何实测
确认闸门	配色、风格、形态、配音、时长、封面、渲染通道七项由用户拍板，gate_check.py 在构建和渲染前各挡一次

---

工作原理

narration.json ──tts_build──▶ audio/*.mp3 + manifest（词/字级时间戳）
                  │
                  ├─timeline_build─▶ layout.json（全局时间轴）+ narration-full.mp3
                  │
                  └─subs──────────▶ subs.json + frames/.beats.js（B() 节拍器）+ SRT/VTT
                                              │
frames/.html（GSAP 时间轴，B() 取节拍）◀─┘
        │
        └─render_video──▶ 逐帧 tl.pause(t) → 截图 → ffmpeg 合成 → out/.mp4
                              │
                              └─qc_check / cover_build / check_cover

• 一句话一个场景。每个场景是一个自包含的 HTML 文件，注册一条暂停的 GSAP 时间轴 window.__tl。
• 渲染器逐帧 seek：把时间轴停在第 t 秒，同步 CSS 动画，截图，再交给 ffmpeg。没有墙钟，不受机器快慢影响， 同一份输入每次渲出的画面一致。
• 段间静默算在上一场里：场景帧一直播到 duration + gap，出场过渡就写在这段静默里（__SEG__.gap）。
• 字幕层与进度条由渲染器注入并逐帧驱动，场景作者不用管。

---

安装

**依赖**：Python ≥ 3.9、Node ≥ 18、Chrome 或 Edge（都没有时自动下载 playwright chromium）、ffmpeg （PATH 上没有就用 imageio-ffmpeg 自带的静态二进制）。

git clone https://github.com/amliuyong/html-to-explainer-video.git ~/.cl