HyperFrames上手指南：原文实测三行命令本地导出无水印MP4，日语配音是坑

原文要点

日本作者2026年10月7日在M4 Pro Mac上实测HeyGen开源工具HyperFrames（v0.8.140）：需Node.js 22以上和FFmpeg，不需要HeyGen账号；init生成模板、preview预览、render导出mp4，本地导出无水印，作者称10秒日语字幕视频18.3秒导出。许可证为Apache 2.0，云端渲染收费且4K按1.5倍计。两个坑：日文字体需@font-face声明否则lint报错；免费语音Kokoro把汉字逐字读成“Chinese letter”，日语配音不可用。作者还指出Claude对HyperFrames的描述与官方文档有出入。

这次做成什么

在本机用HyperFrames把HTML页面渲染成无水印mp4短视频，并绕开日语/中文字体和内置免费语音的两个坑。本站设计一个10秒三条字幕的练习，全程用作者文中提到的三条命令完成。

准备什么

• 已安装Node.js 22或更高版本（用 node -v 确认）
• 已安装FFmpeg（Mac可用 brew install ffmpeg）
• 本机装有Chrome浏览器（渲染过程会调用）
• 不需要HeyGen账号；如用Claude Code辅助生成需另行订阅该工具

具体怎么做

1. 检查环境

   在终端运行 npx hyperframes doctor，逐行确认Node.js、FFmpeg、Chrome三项是否就位。缺的先装好再继续。如不想被收集匿名使用统计，可运行 npx hyperframes telemetry disable。

2. 生成模板

   运行 npx hyperframes init my-video，会生成index.html（画面内容）、hyperframes.json（配置）以及CLAUDE.md/AGENTS.md（给AI代理读的规则文件）。

3. 写入三条字幕的画面

   编辑index.html，参考下方示例：三条文本分别设置data-start为0、3.3、6.6秒，动画按官方约定注册到window.__timelines。中文或日文字体务必加@font-face声明，例如src: local('Hiragino Sans')，否则lint会报字体未声明错误，换台电脑渲染可能变成替代字体。

4. 检查并预览

   运行 npm run check 把写法错误和字体问题提前暴露，错误清零后运行 npx hyperframes preview 在浏览器里看三条字幕是否按时序出现。

5. 导出mp4

   运行 npx hyperframes render 得到mp4。用ffprobe查看文件元数据，应只见hyperframes版本等标记，画面无水印。作者称10秒视频在其M4 Pro Mac上18.3秒导出，仅供参考不保证你的耗时。

6. （可选）处理配音

   内置免费语音Kokoro需先 pip install kokoro-onnx soundfile，但作者实测它把汉字逐字读成英文“Chinese letter”，中文/日语解说都不要用它。现实做法是自己录音或用其他对中文友好的TTS生成音频文件，再用<audio>标签引入。

可直接复制的材料

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<style>
@font-face {
  font-family: 'Hiragino Sans';
  src: local('Hiragino Sans');
}
body { background: #000; margin: 0; }
.caption {
  position: absolute; bottom: 80px; width: 1920px;
  text-align: center; color: #fff;
  font-family: 'Hiragino Sans', sans-serif;
  font-size: 64px; font-weight: bold;
  opacity: 0;
}
</style>
</head>
<body>
<div class="caption" id="c1" data-start="0" data-duration="3.3">写HTML就能生成视频</div>
<div class="caption" id="c2" data-start="3.3" data-duration="3.3">本地导出不加水印</div>
<div class="caption" id="c3" data-start="6.6" data-duration="3.4">中文字幕也能直接显示</div>
<script>
// 动画按官方约定注册到 window.__timelines；
// 具体注册写法请以 init 生成模板里的示例和官方文档为准核对
window.__timelines = window.__timelines || [];
</script>
</body>
</html>

请用 /hyperframes 制作一个10秒视频：画面1920×1080，黑色背景，三条白色粗体字幕依次出现在画面底部，文案分别是“写HTML就能生成视频”“本地导出不加水印”“中文字幕也能直接显示”。中文字体请用 @font-face 声明 src: local('Hiragino Sans')。完成后先运行 npm run check，错误为0再用 npm run render 导出mp4。

npx hyperframes doctor        # 检查Node.js/FFmpeg/Chrome
npx hyperframes init my-video # 生成模板目录
npx hyperframes preview       # 浏览器预览
npm run check                 # lint检查字体与写法
npx hyperframes render        # 导出mp4
npx hyperframes telemetry disable  # 关闭匿名使用统计

输入与输出示例

本站虚构示意流程，非实际运行结果；耗时与文件大小因机器而异，作者在其Mac上称18.3秒、335.7KB，仅供量级参考

输入

按步骤执行init后写入三条字幕骨架，运行 npm run check 再 npx hyperframes render

对应输出

示意：check首次报1个错误“使用了Hiragino Sans但未用@font-face声明”；补上声明后错误为0；render完成后得到约10秒的mp4，ffprobe显示含hyperframes_version等元数据标记，画面无HeyGen水印，三条字幕按0/3.3/6.6秒依次出现

做完检查这些

• npx hyperframes doctor输出的Node.js、FFmpeg、Chrome三项均显示已安装
• npm run check最终错误数为0，特别是没有@font-face字体未声明的报错
• 导出的mp4画面中没有HeyGen名称或Logo水印
• 三条字幕按设定的data-start顺序出现且中文没有乱码或变成方块字
• ffprobe读到的元数据只有hyperframes相关标记，无其他水印信息

容易卡住的地方

• 只有本地渲染免费；用HeyGen云端渲染会计费且4K按1.5倍计，单条价格原文称官方文档未写明，导出前先在HeyGen页面确认
• Kokoro免费语音需Python环境额外安装kokoro-onnx和soundfile，且作者实测读不了汉字；中日文配音请自录音频或换TTS
• 字体错误在作者Mac上即使不修复也能导出且显示正常，但换Windows或云端渲染不保证有同款字体；跨机导出建议把Noto Sans JP等字体文件放进项目目录
• 官方Studio图形界面应用只有Mac和Linux版；Windows用户需通过WSL使用命令行
• Claude等AI对HyperFrames的问答可能过时或出错（作者实测Claude否认存在的Studio应用其实存在），操作以官方文档为准