juguang/html-ppt-video-skill 本地使用教程

juguang/html-ppt-video-skill 是一个 Claude Code skill，用来把 Markdown、PDF、TXT、URL 或图片内容先整理成 HTML PPT，再生成带中文配音和字幕的讲解视频；典型场景是把文章、技术文档、课程资料做成 10 到 16 页幻灯片，并输出约 3 到 5 分钟的 final-video.mp4。

它解决的不是“怎么写一份 HTML PPT”，而是 PPT 做好以后如何稳妥地变成视频：先让 html-ppt-skill 产出演示页面，再暂停确认视觉效果，随后生成 review.md 给人改解说词和跳过页，确认后用 edge-tts、ffmpeg、字幕文件把整套内容合成视频。

一分钟验证本地环境

先把依赖装齐，再装上配套的 HTML PPT skill：

pip install edge-tts
brew install ffmpeg
brew install font-noto-sans-sc
npx skills add https://github.com/lewislulu/html-ppt-skill -y -g

本仓库默认分支是 master，安装到 Claude Code 时可克隆到指定目录：

git clone https://github.com/juguang/html-ppt-video-skill.git ~/.claude/skills/html-ppt-video

最快的触发方式是在 Claude Code 里直接给文档路径：

/html-ppt-video path/to/your-document.md 把文档转为视频

如果只想先检查本地环境，复制 build_video.py 到项目目录，修改文件顶部常量后运行：

python build_video.py check

这个检查会确认 edge-tts、ffmpeg、ffprobe、Google Chrome、Noto Sans SC 字体、render.sh 和 HTML deck 路径。缺哪一项，脚本会给出相应安装提示。

为什么它需要两个确认点

视频生成比单纯出 HTML PPT 更耗时，也更容易因为前面的小问题返工。仓库把流程拆成四段：文档到 HTML PPT、浏览器里确认视觉效果、生成 review.md、解析确认文档并合成视频。

第一处确认发生在 HTML PPT 之后。此时要打开浏览器看整体风格、页数、主题、排版和内容是否满意，因为一旦进入配音和视频阶段，任何页面调整都会带来更多重跑成本。

第二处确认发生在 review.md。这个文件包含 YAML 配置、每页截图、每页解说词和 checkbox。能改 voice、rate、style，也能把某页标成 - [x] 跳过。确认后的内容才会进入 TTS 和视频合成。

它和 html-ppt-skill 的分工

html-ppt-skill 负责把材料做成 HTML 演示文稿，包含模板、主题、页面结构和浏览器预览。html-ppt-video-skill 站在它后面，负责把已经确定的 HTML deck 渲染成 PNG、生成解说词确认文档、生成音频字幕、拼接视频片段、烧录字幕并输出 MP4。

这种分工很实际：页面设计和视频合成分别处理，出问题也更容易定位。页面不满意，就停在 Phase 1.5 改 HTML PPT；解说词不满意，就改 review.md；字幕漂移或音频问题，则看 build_video.py 的依赖和时长控制。

核心命令怎么用

build_video.py 可以单独运行，README 给了三个主命令：

python build_video.py check
python build_video.py review
python build_video.py build

review 会调用 html-ppt 的 render.sh，把 HTML 幻灯片渲染成 PNG，并写出 video-output/review.md。build 会解析确认文档，按未跳过页面生成解说词 txt、mp3、srt、mp4 片段和最终视频。

只重跑某一步时使用：

python build_video.py build --step 3

脚本顶部有几项需要改：DECK 指向 HTML PPT 的 index.html，RENDER_SH 指向 html-ppt skill 的渲染脚本，N 是幻灯片页数，NARRATIONS 是默认逐页解说词。若这些常量没对齐，后面的 review 或 build 会找不到页面、图片或音频输入。

字幕同步靠精确时长

仓库最值得留意的工程点，是它没有依赖 ffmpeg 的 -shortest 来结束静态图视频片段。SKILL.md 明确写到，静态图循环加 -shortest 可能因为帧对齐让每段多出约两秒，累积后字幕会明显错位。

脚本的做法是用 ffprobe 读取每个 mp3 的真实时长，再给 ffmpeg 传 -t <exact_audio_duration>。合并 SRT 时也按音频时长累计偏移，而不是按上一段字幕结束时间猜测。这个细节对 3 到 5 分钟视频很重要，能避免越到后面字幕越漂。

输出目录里的关键文件

成功运行后，项目会出现 video-output/。里面的 slides/ 放每页 PNG，review.md 是确认文档，narrations/ 放解说词文本，audio/ 放 mp3 和 srt，segments/ 放每页视频片段，subtitles/ 放合并字幕，final-video.mp4 是最终成品。

video-output/
├── slides/
├── review.md
├── narrations/
├── audio/
├── segments/
├── subtitles/
└── final-video.mp4

语音默认是 zh-CN-YunxiNeural，也能换成 zh-CN-XiaoxiaoNeural、zh-CN-YunjianNeural 或 zh-CN-XiaoyiNeural。字幕字体优先用 Noto Sans SC，缺字体时容易出现中文方块。

边界和排错顺序

它面向中文配音和字幕视频，依赖 macOS 命令示例较多，例如 brew install ffmpeg 和 Chrome 应用路径检查。换到其他系统时，需要自己处理 ffmpeg、Chrome、字体和 shell 路径。

排错顺序很简单：先跑 check，再确认 HTML deck 能在浏览器打开，接着跑 review 看 PNG 和解说词是否完整，确认 review.md 后再跑 build。如果换模板后视频没变化，先重新跑渲染或 review，不要只重跑最终合成。

juguang/html-ppt-video-skill 的优势在于把“文档变演示视频”拆成可确认的几个环节。确认 PPT、核对解说词、再产出配音字幕 MP4，这条顺序会比一次性盲目合成更稳。