1. 从 hyperframes 说起一个被低估的 HTML 转 MP4 思路第一次看到 hyperframes 这个词是在一个做自动化内容生产的小圈子里。有人丢了一句“用 hyperframes 把 HTML 直接渲染成 MP4比录屏稳多了”底下立刻有人追问是不是又一个套壳工具。我当时也没太在意直到自己接了一个批量生成数据播报视频的活儿才真正把它捡起来研究了一遍。hyperframes 本质上不是一个具体的软件包而是一类技术方案的统称把 HTML 页面当作视频的一帧帧画面来源通过浏览器渲染引擎逐帧截图再交给编码器合成 MP4。它解决的核心问题很直接——当你已经能用 HTML、CSS、JS 画出漂亮的动态画面时为什么还要去学 AE、PR 或者写复杂的视频合成代码直接让浏览器把页面“演”一遍录下来不就完了。这套思路特别适合几类人做数据可视化视频的开发者、需要批量产出营销素材的运营、想用 AI coding agents 自动生成视频的工程师以及那些手里已经有一堆 HTML 模板、想快速转成 MP4 的普通用户。它不要求你懂 FFmpeg 的复杂滤镜也不要求你会写 Remotion 那种 React 式的视频代码只要你会写网页就能做视频。但这里有个关键点很多人一开始会搞混hyperframes 不是“录屏”。录屏是实时捕获帧率不稳、画质受限于屏幕分辨率、还容易掉帧。hyperframes 是“逐帧渲染”每一帧都精确控制时间点画面清晰度由浏览器视口决定理论上可以做到 4K 甚至更高。这个区别决定了它在批量生产场景下的稳定性远超录屏方案。我后来把这个思路用在了三个项目里一个是每日数据播报视频一个是产品介绍动画还有一个是给 AI coding agents 生成的 HTML 报告自动配视频。踩了不少坑也总结了一些能直接抄作业的配置。下面就把这套东西拆开讲清楚。2. 核心原理拆解HTML 是怎么变成 MP4 的2.1 浏览器渲染管线与逐帧捕获要让 HTML 变成视频第一步得理解浏览器是怎么画出一帧的。现代浏览器渲染一帧大致经过这几个阶段解析 HTML 构建 DOM 树、计算样式、布局、绘制、合成。对于视频生成来说最关键的是“合成”之后的画面——也就是最终呈现在屏幕上的像素。hyperframes 类方案通常走两条路。第一条是使用无头浏览器比如 Puppeteer、Playwright打开页面然后通过 CDP 协议调用Page.captureScreenshot或者Page.startScreencast来抓取画面。第二条是使用浏览器自带的MediaRecorderAPI直接录制 canvas 或者整个页面的视频流。两条路各有优劣后面会详细对比。逐帧捕获的核心在于“时间控制”。你不能让页面自己随便跑否则每一帧对应的时间点就不确定了。常见做法是在页面里注入一个全局的时间控制函数比如window.setFrameTime(t)页面里所有的动画、过渡、定时器都基于这个t来计算状态。然后外部渲染器循环调用setFrameTime(0)、setFrameTime(1/30)、setFrameTime(2/30)……每设置一次就截一张图。这样出来的帧序列时间轴是完全线性的不会因为机器性能波动而丢帧或重复帧。这里有个细节CSS 动画和requestAnimationFrame默认是跟真实时间走的必须把它们“冻结”掉。我通常会在页面加载完成后先执行一段脚本把Date.now、performance.now、requestAnimationFrame全部替换成受控版本。这样页面里所有基于时间的逻辑都会乖乖听渲染器的指挥。2.2 帧率、分辨率与编码参数的三角关系帧率、分辨率、码率这三个参数是互相拉扯的。帧率越高画面越流畅但需要编码的帧数也越多分辨率越高画面越清晰但每帧的像素量呈平方增长码率决定了压缩后保留多少细节码率太低会出现块效应太高则文件体积爆炸。以 1080p、30fps、时长 60 秒的视频为例总帧数是 1800 帧。如果每帧截图是 PNG一张 1920×1080 的 PNG 大约 2MB 到 5MB1800 帧就是 3.6GB 到 9GB 的中间文件。这个体积在批量生产时非常要命。所以实际项目中我通常会把截图格式换成 JPEG质量设到 90 到 95单帧能压到 200KB 到 500KB中间文件降到 360MB 到 900MB可接受得多。编码阶段用 FFmpeg 的话H.264 的crf参数是关键。crf越低画质越好18 到 23 是常用区间。对于文字较多的 HTML 画面我建议用 18 到 20因为文字边缘的压缩伪影特别明显。如果追求更小体积可以上 H.265但兼容性会差一些网页端播放需要额外处理。还有一个容易被忽略的参数是-preset。FFmpeg 的-preset从ultrafast到veryslow有多个档位影响的是编码速度和压缩效率。批量生产时我一般用medium单机一天能处理几百条视频如果只是偶尔跑一条用slow换更小体积也划算。2.3 为什么不用录屏稳定性与可复现性对比录屏方案最大的问题是“不可复现”。同一段动画今天录和明天录因为机器负载不同可能一个掉了几帧一个颜色偏了一点。对于需要批量产出、风格统一的场景这是致命的。逐帧渲染则完全 deterministic。只要输入相同、代码相同、浏览器版本相同输出的帧序列就是一模一样的。这意味着你可以把整个流程放进 CI/CD 流水线每天定时跑出来的视频质量稳定得像工厂流水线。另一个区别是分辨率自由度。录屏受限于显示器分辨率你想录 4K 就得有 4K 屏幕。逐帧渲染只需要在启动无头浏览器时设置viewport为 3840×2160哪怕你的笔记本只有 1080p 屏幕也能渲染出 4K 视频。当然逐帧渲染的代价是速度。录屏是实时的60 秒视频就录 60 秒。逐帧渲染 1800 帧每帧截图加编码可能要跑几分钟到十几分钟。所以它适合“离线批量生产”不适合“实时直播”。3. 工具链选型从 CLI 到 AI coding agents 的完整拼图3.1 无头浏览器Puppeteer 还是 PlaywrightPuppeteer 和 Playwright 都能做无头浏览器控制选哪个主要看你的技术栈和部署环境。Puppeteer 是 Chrome 团队维护的对 Chrome 的支持最及时API 也最简洁。Playwright 是微软出的支持 Chromium、Firefox、WebKit 三套引擎跨浏览器测试更方便。对于 hyperframes 场景我通常选 Puppeteer因为它的page.screenshot在大量调用时性能更稳而且和 Chrome 的 CDP 协议贴合更紧。但如果你需要在 Linux 服务器上跑Playwright 的依赖安装脚本更省心它会自动帮你装好系统库。安装命令很简单npm install puppeteer # 或者 npm install playwright npx playwright install chromium注意 Puppeteer 从 v19 开始默认不下载 Chromium需要手动指定或者用puppeteer-core配合已有的 Chrome。这个坑我踩过CI 环境里跑半天报“找不到浏览器”最后发现是版本问题。3.2 编码器FFmpeg 的 CLI 用法与参数模板FFmpeg 是视频编码的瑞士军刀但参数多到让人头大。我整理了一个适合 HTML 转 MP4 的模板ffmpeg -framerate 30 -i frame_%05d.jpg \ -c:v libx264 -crf 20 -preset medium \ -pix_fmt yuv420p -movflags faststart \ output.mp4逐项解释一下。-framerate 30告诉 FFmpeg 输入帧序列的帧率是 30。-i frame_%05d.jpg是输入模式%05d表示五位数字序号从 00000 开始。-c:v libx264指定 H.264 编码器。-crf 20是画质控制。-preset medium是编码速度档位。-pix_fmt yuv420p是像素格式这个必须加否则很多播放器不认。-movflags faststart把元数据移到文件头部方便网页端边下边播。如果要做 H.265把libx264换成libx265再加一个-tag:v hvc1保证苹果设备兼容。但 H.265 编码速度慢很多批量生产要权衡。3.3 AI coding agents 在流程中的角色AI coding agents 在这套流程里可以干两件事。第一件是生成 HTML 模板。你给它一段数据或者一个需求描述它直接输出一个带 CSS 动画的 HTML 文件。第二件是写渲染脚本。你告诉它“用 Puppeteer 逐帧截图帧率 30时长 10 秒”它能生成完整的 Node.js 脚本。我实测下来Codex CLI 和 Claude 在这类任务上表现不错。Codex CLI 的优势是能直接在终端里跑和文件系统交互方便。你可以这样用codex 生成一个 1920x1080 的 HTML 页面包含一个从左侧滑入的标题和淡入的柱状图动画时长 5 秒用 CSS keyframes 实现它会直接在当前目录生成 HTML 文件。然后你再让它写渲染脚本codex 写一个 Puppeteer 脚本打开这个 HTML逐帧截图 150 帧保存为 frame_00000.jpg 到 frame_00149.jpg这里有个技巧让 AI 生成的 HTML 里所有动画都基于一个全局变量window.frameProgress而不是直接用 CSS 动画。这样渲染脚本只需要在每帧设置window.frameProgress i / totalFrames然后调用截图。AI 一开始可能不理解这个需求你需要在 prompt 里明确说“不要用 CSS animation用 JS 根据 frameProgress 计算样式”。3.4 辅助工具HTML 转 Markdown、打包多个 HTML有时候输入不是单个 HTML而是一堆 HTML 文件需要合并成一个长页面再渲染。这时候可以用html-to-md或者turndown先把 HTML 转成 Markdown再用marked重新渲染成统一风格的 HTML。这个链路听起来绕但在处理用户上传的富文本内容时特别有用。打包多个 HTML 可以用html-bundler-webpack-plugin或者简单的 Node.js 脚本拼接。我一般写个几十行的脚本按文件名排序把每个 HTML 的body内容抽出来塞进一个统一的模板里。这样出来的页面风格一致渲染出来的视频也不会忽明忽暗。4. 完整实操从零跑通一条 HTML 转 MP4 流水线4.1 环境准备与依赖安装先确保机器上有 Node.js 18 以上和 FFmpeg。Ubuntu 上装 FFmpegsudo apt update sudo apt install ffmpegmacOS 上用 Homebrewbrew install ffmpeg然后建项目目录初始化 npmmkdir hyperframes-demo cd hyperframes-demo npm init -y npm install puppeteer如果 Puppeteer 下载 Chromium 太慢可以设置环境变量指向国内镜像或者直接用系统已装的 Chromenpm install puppeteer-core然后用executablePath指向/usr/bin/google-chrome或/Applications/Google Chrome.app/Contents/MacOS/Google Chrome。4.2 编写受控动画的 HTML 模板下面是一个最小可用的 HTML 模板所有动画都基于window.frameProgress!DOCTYPE html html langzh-cn head meta charsetutf-8 titleHyperframes Demo/title style body { margin: 0; width: 1920px; height: 1080px; background: #0f172a; color: #e2e8f0; font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; overflow: hidden; } .title { font-size: 96px; font-weight: 700; opacity: 0; transform: translateY(40px); } .bar { width: 80px; background: #38bdf8; margin: 0 12px; border-radius: 8px 8px 0 0; height: 0; } .chart { display: flex; align-items: flex-end; height: 400px; margin-top: 60px; } /style /head body div styletext-align:center div classtitle idtitle数据播报/div div classchart idchart/div /div script const data [120, 200, 150, 280, 180, 240]; const chart document.getElementById(chart); data.forEach(v { const bar document.createElement(div); bar.className bar; bar.dataset.value v; chart.appendChild(bar); }); window.frameProgress 0; window.renderFrame function() { const p window.frameProgress; const title document.getElementById(title); const titleP Math.min(1, p / 0.3); title.style.opacity titleP; title.style.transform translateY(${40 * (1 - titleP)}px); const bars document.querySelectorAll(.bar); bars.forEach((bar, i) { const start 0.3 i * 0.08; const bp Math.max(0, Math.min(1, (p - start) / 0.3)); const target parseInt(bar.dataset.value); bar.style.height (target * bp) px; }); }; /script /body /html关键点页面里没有任何setTimeout、setInterval、requestAnimationFrame或者 CSSanimation。所有视觉状态都由renderFrame根据frameProgress计算。这样渲染器就能精确控制每一帧。4.3 逐帧截图脚本的编写与参数计算Node.js 渲染脚本const puppeteer require(puppeteer); const path require(path); const fs require(fs); const FPS 30; const DURATION 5; // 秒 const TOTAL_FRAMES FPS * DURATION; const OUTPUT_DIR path.join(__dirname, frames); (async () { if (!fs.existsSync(OUTPUT_DIR)) fs.mkdirSync(OUTPUT_DIR); const browser await puppeteer.launch({ headless: new, args: [--no-sandbox, --disable-setuid-sandbox] }); const page await browser.newPage(); await page.setViewport({ width: 1920, height: 1080, deviceScaleFactor: 1 }); await page.goto(file:// path.join(__dirname, template.html)); await page.waitForSelector(#chart); for (let i 0; i TOTAL_FRAMES; i) { const progress i / (TOTAL_FRAMES - 1); await page.evaluate((p) { window.frameProgress p; window.renderFrame(); }, progress); const filename frame_${String(i).padStart(5, 0)}.jpg; await page.screenshot({ path: path.join(OUTPUT_DIR, filename), type: jpeg, quality: 92 }); if (i % 30 0) console.log(已渲染 ${i}/${TOTAL_FRAMES} 帧); } await browser.close(); console.log(截图完成); })();参数计算说明TOTAL_FRAMES FPS * DURATION5 秒 30fps 就是 150 帧。progress i / (TOTAL_FRAMES - 1)保证第一帧是 0最后一帧是 1闭区间。padStart(5, 0)生成frame_00000.jpg到frame_00149.jpg和 FFmpeg 的%05d对应。4.4 合成 MP4 与质量校验截图完成后用 FFmpeg 合成ffmpeg -framerate 30 -i frames/frame_%05d.jpg \ -c:v libx264 -crf 20 -preset medium \ -pix_fmt yuv420p -movflags faststart \ output.mp4跑完后用ffprobe检查一下ffprobe -v error -show_entries streamwidth,height,r_frame_rate,duration \ -of defaultnoprint_wrappers1 output.mp4应该看到width1920、height1080、r_frame_rate30/1、duration5.000000。如果帧率显示30/1但时长不对多半是截图数量不对检查TOTAL_FRAMES和实际文件数是否一致。我一般还会抽几帧出来肉眼看一下特别是第一帧、中间帧、最后一帧。用ffmpeg -i output.mp4 -vf selecteq(n\,0) -vframes 1 check_0.png抽第一帧把n换成75抽中间帧。确认文字没有模糊、颜色没有偏移、动画位置正确。5. 常见问题与排查技巧实录5.1 截图模糊、文字发虚的三种原因第一种是deviceScaleFactor没设对。默认是 1如果你在 Retina 屏幕上开发可能觉得清晰但渲染出来是 1 倍像素。解决方法是显式设置deviceScaleFactor: 2这样 1920×1080 的视口实际渲染 3840×2160 像素再缩放到 1080p 输出文字边缘会锐利很多。第二种是 JPEG 质量太低。quality: 92是我实测的甜点值低于 85 文字边缘会出现明显振铃效应高于 95 文件体积增长很快但画质提升有限。第三种是字体渲染问题。无头浏览器在某些 Linux 环境下缺少中文字体会 fallback 到默认字体导致文字变细或者间距异常。解决方法是安装fonts-noto-cjksudo apt install fonts-noto-cjk然后在 CSS 里显式指定font-family: Noto Sans CJK SC, sans-serif。5.2 帧率不稳、动画卡顿的排查思路如果合成出来的视频动画一卡一卡的先检查截图数量对不对。ls frames | wc -l应该等于TOTAL_FRAMES。如果少了说明截图循环里有帧被跳过可能是page.screenshot抛异常被吞了。再检查progress的计算。如果你写的是i / TOTAL_FRAMES最后一帧是149/150 0.993永远到不了 1动画最后一帧会缺一点。正确写法是i / (TOTAL_FRAMES - 1)。还有一种情况是页面里有异步加载的资源比如图片或者字体截图时还没加载完。解决方法是在page.goto之后加await page.waitForNetworkIdle()或者显式等待某个元素出现。5.3 内存溢出与批量渲染的优化渲染 4K 视频时150 帧 JPEG 可能占几百 MB 内存如果同时开多个页面并行渲染很容易 OOM。我的做法是限制并发数为 2 到 4并且每渲染完一条视频就关掉页面重新开一个。Puppeteer 的page.close()不会立即释放内存最好用browser.newPage()重新创建。如果批量跑几百条建议每 50 条重启一次浏览器实例。另外截图目录要及时清理。我写了个cleanup函数合成 MP4 成功后自动删除frames目录避免磁盘被撑满。5.4 常见问题速查表问题现象可能原因解决方法视频时长不对截图数量与 FPS 不匹配检查TOTAL_FRAMES和实际文件数文字模糊deviceScaleFactor为 1设为 2 或更高动画卡顿progress计算错误用i / (TOTAL_FRAMES - 1)中文字体异常缺少 CJK 字体安装fonts-noto-cjk内存溢出并发过高限制并发数定期重启浏览器颜色偏暗像素格式不对加-pix_fmt yuv420p网页端不能边下边播元数据在文件尾部加-movflags faststart截图全黑页面未加载完成加waitForNetworkIdle或等待选择器6. 进阶玩法把 hyperframes 接入自动化内容生产6.1 用 CLI 串联整个流程把截图脚本和 FFmpeg 命令包成一个 CLI 工具用commander或者yargs解析参数#!/usr/bin/env node const { program } require(commander); program .option(-i, --input path, HTML 文件路径) .option(-o, --output path, 输出 MP4 路径) .option(-f, --fps number, 帧率, 30) .option(-d, --duration number, 时长秒, 5) .parse(); const opts program.opts(); // 调用渲染逻辑这样就能在终端里直接跑hyperframes -i template.html -o output.mp4 -f 30 -d 5配合cron或者 GitHub Actions每天定时从数据源生成 HTML再转成 MP4自动上传到内容平台。整个链路不需要人工干预。6.2 与 AI coding agents 配合的 prompt 模板让 AI 生成 HTML 时prompt 里要明确约束生成一个 1920×1080 的 HTML 页面所有动画必须基于window.frameProgress0 到 1 的浮点数不要使用 CSS animation、setTimeout、requestAnimationFrame。页面加载后调用window.renderFrame()根据frameProgress更新所有视觉状态。包含一个标题和一组柱状图动画总时长对应 5 秒 30fps。这个模板我用了很多次Codex CLI 和 Claude 都能稳定输出符合要求的代码。如果 AI 第一次没理解把renderFrame的示例代码贴给它让它照着改。6.3 批量生产的目录结构与命名规范批量跑的时候目录结构要清晰projects/ daily-report-2024-01-01/ template.html frames/ output.mp4 daily-report-2024-01-02/ template.html frames/ output.mp4命名规范用日期或者业务 ID方便追溯。渲染脚本接受一个项目目录列表逐个处理处理完一个删一个frames目录。日志输出到render.log记录每条视频的耗时和文件大小。6.4 从 MP4 到多平台分发的注意事项生成的 MP4 如果要发到不同平台可能需要不同规格。横屏 1920×1080 适合视频网站竖屏 1080×1920 适合短视频平台。我的做法是在 HTML 模板里用 CSS 变量控制画布尺寸渲染时通过page.setViewport切换同一套内容生成横竖两个版本。文件大小也要注意。短视频平台通常限制单文件 500MB 以内如果超了用 FFmpeg 二次压缩ffmpeg -i output.mp4 -c:v libx264 -crf 24 -preset fast -vf scale1080:1920 output_mobile.mp4crf从 20 提到 24画质略降但体积能减一半左右移动端观看完全够用。7. 我踩过的坑与实测经验第一个坑是 Puppeteer 的headless: true和headless: new的区别。老版本true用的是旧的无头模式对某些 CSS 特性支持不好比如backdrop-filter会失效。换成new之后正常。如果你发现渲染出来的画面和浏览器里看到的不一样先检查这个。第二个坑是page.screenshot的clip参数。如果你只想截取页面的一部分用clip: {x, y, width, height}。但注意clip的坐标是相对于视口的如果页面有滚动需要先page.evaluate(() window.scrollTo(0, 0))回到顶部。第三个坑是 FFmpeg 的-framerate和-r的区别。-framerate是输入帧率-r是输出帧率。如果你只写-r 30不写-framerate 30FFmpeg 可能按默认的 25fps 读入导致视频速度不对。两个都写上最保险。第四个坑是 JPEG 的quality参数在 Puppeteer 里是 0 到 100但实际有效范围大概是 60 到 100。低于 60 画质惨不忍睹高于 95 体积增长不成比例。我一般用 90 到 93。第五个坑是批量渲染时的文件句柄泄漏。Puppeteer 每开一个页面都会占用文件句柄如果忘记page.close()跑几百条之后会报EMFILE: too many open files。解决方法是每条视频渲染完显式关闭页面并且用try/finally保证异常时也能关闭。最后分享一个小技巧如果你需要渲染的 HTML 里有外部图片或者字体尽量把它们内联成 base64 或者用本地文件路径。无头浏览器加载外部资源受网络影响很大有时候快有时候慢批量生产时不可控。把资源本地化之后渲染速度稳定很多也不会因为网络问题导致某几帧图片没加载出来。这套 hyperframes 的思路我从去年开始用到现在跑了大概几千条视频稳定性比录屏方案高一个数量级。如果你也在做类似的事情建议先从 5 秒 30fps 的小 demo 跑通再逐步加时长和分辨率。不要一上来就搞 4K 60fps中间文件能把磁盘撑爆。