1. 从 hyperframes 这个名字说起它到底想解决什么问题第一次看到 hyperframes 这个词我脑子里蹦出来的第一反应是“超帧”——不是超频是超帧。后来翻了翻相关的讨论和热词发现它跟 HTML、MP4、CLI、AI coding agents 这几个词绑在一起出现基本就能拼出全貌了这是一个把 HTML 页面渲染成 MP4 视频的命令行工具而且它明显是冲着 AI 编程助手的工作流去的。为什么我这么判断你看热词里同时出现了codex cli、codex cli remotion、trae cli、minimax cli、openspec cli、zcode cli、boos cli、gitlab cli这一大串 CLI 工具还有remotion这个关键词。Remotion 是干什么的它是用 React 代码来生成视频的框架。hyperframes 出现在同一批热词里说明它大概率是同一赛道的东西只不过它把入口从 React 换成了更朴素的 HTML。这件事的价值在哪我举个自己踩过的场景。之前我想给一个产品做个 15 秒的演示视频用剪辑软件拖时间轴改一版文案就要重新对齐一次字幕和动画来回折腾了七八遍人都麻了。后来我换成用 HTML CSS 写动画再用工具渲染成 MP4改文案就是改一行文字重新跑一遍命令两分钟出新版本。hyperframes 要解决的就是这类“我不想学剪辑软件我只想写代码出视频”的需求。它适合谁三类人。第一类是前端开发者手里有 HTML/CSS/JS 的底子想快速把网页变成视频第二类是做 AI 编程助手工作流的人想让 agent 自动生成视频内容第三类是做批量视频的运营或技术同学比如批量生成数据播报、批量生成产品卡片视频。如果你属于这三类中的任何一类往下看会有收获。需要提前说明的是hyperframes 目前公开的细节不算多下面涉及具体命令和参数的部分我会基于同类 CLI 工具的通用实践和 Remotion 生态的常见做法来补全并明确标注哪些是推断、哪些是通用做法你实际使用时以官方文档为准。2. hyperframes 的核心工作链路HTML 是怎么变成 MP4 的2.1 渲染管线的四个阶段要把一个 HTML 页面变成 MP4中间至少要经过四个阶段我把它们拆开讲你就能理解为什么这类工具的设计会长成现在这样。第一个阶段是页面加载。工具需要启动一个无头浏览器headless browser把 HTML 文件加载进去同时把 CSS、JS、字体、图片这些依赖都解析完。这一步的关键是“等页面稳定”——如果页面里有异步加载的图片或者字体你不等它加载完就截图出来的就是白屏或者错位。所以成熟的工具都会有一个waitUntil或者delay参数。第二个阶段是逐帧捕获。视频的本质是一秒 24 帧或 30 帧的连续图片。工具需要控制页面里的动画时间轴在第 0 毫秒截一张图第 33 毫秒截一张图以此类推。这里有个技术难点CSS 动画和 JS 动画的时间是跟着真实时钟走的你截图的速度跟不上就会丢帧。所以工具通常会接管时间轴用requestAnimationFrame的虚拟时钟或者直接操作动画的currentTime。第三个阶段是帧序列编码。截出来的一堆 PNG 或 JPEG需要用编码器通常是 FFmpeg压成 H.264 或 H.265 的 MP4。这一步的参数很讲究码率、关键帧间隔、像素格式任何一个设错都会导致视频糊或者体积爆炸。第四个阶段是音频混合可选。如果 HTML 里有音频元素或者你想配背景音乐工具需要把音频轨和视频轨合到一起。这一步经常被忽略但实际做产品视频时没声音的视频基本没法用。2.2 为什么用 HTML 而不是直接用剪辑软件这个问题我被问过很多次。用剪辑软件做视频直观、所见即所得为什么要折腾代码答案在于可编程性和可复用性。我给你算一笔账。假设你要做 100 个结构相同、只是文案和数字不同的视频。用剪辑软件你得手动改 100 次每次 5 分钟就是 500 分钟。用 HTML 模板 hyperframes你写一个模板用一个数据数组循环 100 次跑一条命令可能 20 分钟全部搞定。这就是量变到质变。再往深一层说HTML 天然支持响应式布局、CSS 动画、Web 字体、SVG 矢量图这些能力在视频制作里都是刚需。你想做一个文字逐个淡入的效果CSS 的animation-delay一行就搞定你想做一个数据增长的动画JS 里requestAnimationFrame配合插值函数就能实现。这些在剪辑软件里要么做不了要么得装插件。2.3 CLI 在这个链路里扮演什么角色hyperframes 以 CLI 形式出现这个选择很关键。CLI 意味着它可以被脚本调用、被 CI/CD 集成、被 AI agent 调用。你想想如果一个 AI 编程助手要自动生成视频它最擅长的是什么是写代码、跑命令。它不擅长的是打开一个 GUI 软件拖时间轴。所以 CLI 是 AI agent 唯一能顺畅操作的接口。热词里那一堆codex cli、trae cli、minimax cli本质上都是同一类东西让 AI 通过命令行操作工具。hyperframes 把自己做成 CLI就是在主动接入这个生态。你可以让 agent 写一个 HTML 模板然后调 hyperframes 渲染全程不需要人碰鼠标。3. 环境准备从零到能跑通第一条命令3.1 依赖清单与版本要求在动手之前你得先把环境搭好。这类工具通常依赖三样东西Node.js 运行时、无头浏览器、FFmpeg 编码器。Node.js 建议用 18 LTS 或 20 LTS太老的版本比如 14会因为缺少某些 ES 模块特性而报错。安装方式我推荐用 nvm 管理这样你可以随时切换版本不会污染系统环境。无头浏览器方面如果 hyperframes 基于 Puppeteer 或 Playwright它会在安装时自动下载一个 Chromium。这里有个坑国内网络环境下Chromium 的下载经常超时。我的做法是提前设置好镜像源或者手动下载后放到缓存目录。具体路径取决于工具用的是哪个浏览器引擎Puppeteer 的缓存目录一般在~/.cache/puppeteerPlaywright 在~/.cache/ms-playwright。FFmpeg 是最容易被忽略的。很多工具不会自动装 FFmpeg而是假设你系统里已经有了。你可以用ffmpeg -version检查如果没有macOS 用brew install ffmpegUbuntu 用apt install ffmpegWindows 建议用 winget 或者直接下静态编译版加到 PATH。依赖项推荐版本检查命令常见问题Node.js18 LTS / 20 LTSnode -v版本过低导致 ES 模块报错无头浏览器随工具自动安装看缓存目录下载超时需配镜像FFmpeg5.0 以上ffmpeg -version未安装或不在 PATH字体系统字体或 Web 字体渲染后检查中文乱码缺字体3.2 安装 hyperframes 与首次运行安装命令通常是全局安装或者用 npx 直接跑。我建议先用 npx 试不污染全局环境npx hyperframes --help如果这条命令能打出帮助信息说明工具本身装好了。接下来准备一个最简单的 HTML 文件比如test.html里面就放一个带背景色的 div 和一行文字。然后跑npx hyperframes render test.html -o output.mp4 --duration 5 --fps 30这里的--duration 5表示渲染 5 秒--fps 30表示每秒 30 帧。第一次跑大概率会遇到问题别慌这是正常的。最常见的问题是页面还没加载完就开始截图导致第一帧是白的。解决办法是加一个--delay 1000参数让工具等 1 秒再开始。3.3 一个能跑通的最小 HTML 模板我给你一个我实测能用的最小模板你直接复制就能跑!DOCTYPE html html langzh-cn head meta charsetutf-8 style body { margin: 0; width: 1920px; height: 1080px; display: flex; align-items: center; justify-content: center; background: linear-gradient(135deg, #1a1a2e, #16213e); font-family: sans-serif; } .title { color: #fff; font-size: 96px; opacity: 0; animation: fadeIn 1s ease forwards; } keyframes fadeIn { to { opacity: 1; } } /style /head body div classtitleHello Hyperframes/div /body /html这个模板里body的尺寸我写死了 1920x1080这是 1080P 视频的标准尺寸。为什么要写死因为无头浏览器的默认视口可能不是这个尺寸你不指定渲染出来的视频比例就是错的。animation: fadeIn 1s是让文字淡入这样你渲染出来的视频第一帧是空的后面文字慢慢出现能直观验证动画有没有被正确捕获。4. 把 HTML 动画变成视频帧时间轴控制的那些门道4.1 CSS 动画与虚拟时钟的配合这是整个链路里最容易出问题的地方我单独拎出来讲。CSS 动画的时间是跟着浏览器的真实时钟走的。你写animation: fadeIn 1s浏览器就从页面加载完成那一刻开始计时1 秒后动画结束。但渲染工具需要的是“可控的时间”——它要在第 0 毫秒、第 33 毫秒、第 66 毫秒分别截图而不是等真实时间流逝。成熟的工具会做一件事接管时间轴。它通过 CDPChrome DevTools Protocol的Animation.setPlaybackRate或者直接操作document.timeline把动画的播放速度设成 0然后手动设置currentTime。这样工具就能精确控制每一帧对应的时间点。如果你发现渲染出来的视频动画速度不对比如本该 1 秒的动画变成了 3 秒大概率是工具没有接管时间轴而是用了“实时录制”的方式。实时录制的问题在于截图速度受限于机器性能机器慢就丢帧机器快就重复帧。遇到这种情况你要么换工具要么在 HTML 里用 JS 手动控制动画进度。4.2 用 JS 手动控制动画进度我个人的经验是做复杂动画时与其依赖 CSS 动画不如用 JS 手动控制。这样你对每一帧的状态有完全的控制权。思路是这样的定义一个全局函数renderFrame(progress)progress从 0 到 1。工具在截图前会调用这个函数传入当前时间对应的进度值。你在函数里根据progress计算所有元素的位置、透明度、缩放。function renderFrame(progress) { const title document.querySelector(.title); title.style.opacity Math.min(progress * 2, 1); title.style.transform translateY(${(1 - progress) * 50}px); }这样写的好处是无论工具怎么截图动画状态都是确定的。坏处是你得自己写插值逻辑比 CSS 动画麻烦一点。但对于需要精确控制的场景这点麻烦值得。4.3 帧率、时长与文件体积的三角关系这三个参数是互相牵制的我列个表你感受一下帧率时长分辨率预估体积H.264适用场景24 fps10s1080P5-8 MB电影感动画30 fps10s1080P8-12 MB通用网页演示60 fps10s1080P15-25 MB游戏高流畅30 fps10s4K30-50 MB大屏展示我的建议是除非你有明确的 60 帧需求否则 30 fps 就够了。人眼对 30 帧和 60 帧的感知差异在静态内容为主的视频里几乎可以忽略但文件体积差一倍。分辨率同理1080P 在手机和电脑上看着都很清楚4K 只在超大屏或者需要后期裁剪时才有必要。还有一个隐藏参数是码率。同样 30 fps 1080P码率设 5 Mbps 和 15 Mbps画质和体积差很多。文字为主的视频5 Mbps 足够有渐变、有视频素材的建议 10 Mbps 以上。如果工具没暴露码率参数你可以通过 FFmpeg 二次压制来调整。5. 接入 AI coding agents让 agent 帮你写视频模板5.1 为什么 agent 适合干这件事AI 编程助手最擅长的是什么是写结构化代码、是批量生成、是按模板填充内容。视频模板本质上就是一个结构化的 HTML 文件里面有占位符、有动画逻辑、有样式定义。这正好是 agent 的舒适区。你想想这个工作流你告诉 agent“帮我做一个 10 秒的产品介绍视频标题是 XX副标题是 YY背景用深蓝色渐变文字逐个淡入”。agent 生成 HTML调 hyperframes 渲染输出 MP4。整个过程你只说了一句话。热词里出现的codex cli remotion说明已经有人在做类似的事情了——用 codex 这类 agent 操作 remotion 生成视频。hyperframes 如果定位相同那它的优势就在于 HTML 比 React 更简单agent 生成 HTML 的准确率更高调试也更直观。5.2 给 agent 的提示词该怎么写我试过几种提示词写法效果最好的是“模板 数据”分离的结构。你不要让 agent 直接生成一个完整的 HTML而是让它生成一个模板文件和一个数据文件。模板文件里用{{title}}、{{subtitle}}这样的占位符。数据文件是 JSON里面填具体内容。然后你写一个简单的脚本把数据注入模板再调 hyperframes 渲染。这样做的好处是agent 只需要生成一次模板后面换内容就是改 JSON。而且 JSON 比 HTML 更容易校验agent 生成错了你一眼就能看出来。提示词可以这样写生成一个 HTML 视频模板尺寸 1920x1080背景深色渐变。包含标题和副标题两个元素标题字号 96px副标题 48px。标题在 0-1 秒淡入副标题在 0.5-1.5 秒淡入。用{{title}}和{{subtitle}}作为占位符。同时生成一个 data.json填入示例内容。5.3 agent 工作流里的常见故障用 agent 跑这条链路我遇到过几个高频问题提前告诉你省得踩坑。第一个是路径问题。agent 生成的文件可能放在临时目录而 hyperframes 的工作目录是另一个地方导致找不到文件。解决办法是在提示词里明确指定输出路径或者让 agent 用绝对路径。第二个是字体缺失。agent 生成的 HTML 可能用了系统里没有的字体渲染出来是默认字体跟预期不符。解决办法是在 HTML 里用 Web 字体或者提前把字体文件放到项目目录并用font-face引入。第三个是动画时序错乱。agent 写的 CSS 动画可能用了animation-delay但工具接管时间轴后delay 的计算方式可能不一样。稳妥的做法是让 agent 用 JS 控制动画或者用animation-fill-mode: forwards确保动画结束后状态保持。6. 实测中的坑与排查链路6.1 渲染出来是黑屏或白屏这是最高频的问题我完整走一遍排查链路。第一步先确认 HTML 本身在浏览器里能正常显示。用 Chrome 打开你的 HTML 文件看看有没有内容。如果浏览器里就是白的那问题在 HTML不在工具。第二步如果浏览器里正常但渲染出来是白的检查视口尺寸。无头浏览器的默认视口可能是 800x600你的内容如果定位在 1920x1080 的区域就跑到视口外面去了。解决办法是在 HTML 的body上写死宽高或者在命令里指定--viewport 1920x1080。第三步如果尺寸没问题检查加载时机。页面里的图片、字体如果是异步加载的工具可能在加载完成前就截图了。加--delay参数或者用waitUntil: networkidle这类选项。第四步如果以上都排除了检查背景色。有些工具默认背景是透明的渲染成 MP4 后透明区域变成黑色。在body上显式设置background就能解决。6.2 中文显示成方块这个问题我踩过好几次根因是系统缺少中文字体。无头浏览器用的是系统字体如果你的服务器或容器里没装中文字体中文就渲染不出来。解决办法有两个。一是装字体Ubuntu 上apt install fonts-noto-cjkmacOS 一般自带。二是在 HTML 里用 Web 字体把字体文件woff2 格式放到项目目录用font-face引入。第二种方式更可控推荐。注意用 Web 字体时字体文件要等加载完才能渲染。记得加document.fonts.ready的判断或者给足够的 delay。6.3 视频体积异常大如果你渲染一个 10 秒的视频出来 200 MB那肯定是编码参数有问题。常见原因是码率设太高或者用了无损编码。排查方法是用ffprobe看视频信息ffprobe -v error -show_streams output.mp4看bit_rate字段正常 1080P 30fps 应该在 5-10 Mbps。如果超过 50 Mbps就是码率设错了。解决办法是在渲染命令里指定码率或者用 FFmpeg 二次压制ffmpeg -i output.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac output_compressed.mp4-crf 23是质量参数数字越小质量越高体积越大18-28 是常用范围。6.4 音频不同步如果你的 HTML 里有音频或者你后期合成了音频可能会遇到音画不同步。根因通常是视频帧率和音频采样率不匹配或者渲染时音频轨被截断了。解决办法是先用 FFmpeg 把音频单独抽出来检查时长再和视频时长对比。如果音频比视频长说明视频渲染时丢帧了如果音频比视频短说明音频被截断了。调整--duration参数让两者对齐。7. 进阶玩法批量生成与模板化7.1 用数据驱动批量渲染单次渲染只是入门hyperframes 真正的威力在于批量。我给你一个我实际用过的脚本思路。假设你有一个data.json里面是一个数组每个元素是一条视频的数据[ { title: 产品 A, subtitle: 销量增长 30% }, { title: 产品 B, subtitle: 用户突破 10 万 }, { title: 产品 C, subtitle: 覆盖 20 个国家 } ]你写一个 Node.js 脚本读这个数组循环替换 HTML 模板里的占位符生成临时 HTML调 hyperframes 渲染输出带编号的 MP4。整个过程全自动你只需要维护那个 JSON。这个模式特别适合做数据播报、日报视频、批量产品卡片。我有个朋友做电商的每天用这个方式生成几十条商品视频人工成本几乎为零。7.2 模板的模块化设计当你的视频越来越复杂单个 HTML 文件会变得难以维护。我的做法是把模板拆成几个部分布局模板、动画库、样式表。布局模板只负责结构比如“上面是标题中间是图表下面是落款”。动画库是一个 JS 文件里面封装了fadeIn、slideUp、scaleIn这些常用动画函数。样式表定义颜色、字体、间距这些设计变量。这样拆的好处是换一个视频只需要换布局模板和数据动画和样式可以复用。而且 agent 生成内容时你只需要让它生成布局模板动画和样式用你预设好的输出质量更稳定。7.3 和 CI/CD 结合如果你在团队里做这件事可以把渲染流程接到 CI 里。比如每次产品发版自动生成一条更新视频推到内部频道。具体做法是写一个 CI 任务步骤是拉代码、装依赖、跑渲染脚本、上传产物。GitLab CI 和 GitHub Actions 都支持这种流程。热词里出现的gitlab cli说明有人已经在用命令行工具操作 GitLab 了思路是一样的。需要注意的是CI 环境通常没有图形界面无头浏览器要跑在--no-sandbox模式下。另外 CI 机器的性能可能不如本地渲染时间会变长记得设置合理的超时时间。8. 我对这类工具的一些个人判断用了这段时间我对 hyperframes 这类工具的判断是它不是一个“替代剪辑软件”的东西而是一个“补充”。它擅长的是结构化、批量、可编程的视频不擅长的是创意剪辑、复杂转场、精细调色。你拿它做产品演示、数据播报、模板化内容效率极高你拿它做 Vlog、做宣传片那是用错地方了。另一个判断是这类工具的未来一定和 AI agent 深度绑定。因为 agent 最需要的就是“可编程的接口”而 CLI 就是最直接的接口。当 agent 能自己写 HTML、自己调渲染、自己检查输出质量的时候视频制作的门槛就真正降下来了。你现在花时间学这套工作流等 agent 能力再上一个台阶时你就是那个能指挥 agent 干活的人。最后分享一个小技巧渲染之前先用低分辨率、低帧率跑一遍预览确认动画时序和布局没问题再跑全分辨率。这样能省很多等待时间。我一般用--viewport 640x360 --fps 10做预览确认无误后再上 1080P 30fps。这个习惯帮我省了至少一半的调试时间。