使用 Helios 制作视频
Helios 视频是一个包含单一函数 window.renderAt(t) 的 HTML 页面。该函数在 t 秒时绘制相应帧。Helios 渲染器会在无头 Chrome 中加载页面,每帧调用一次 renderAt(t),捕获每一帧并编码为 MP4。无需打包工具、框架或编写捕获脚本。
1. 编写页面
每一帧必须是 t 的纯函数。渲染器可能以任意顺序请求帧,并且每次渲染同一帧的结果必须完全相同。
- 一切从
t派生: 位置、透明度、显示哪个场景。绝不要使用计数器、x += speed、逐帧步进的物理模拟或setTimeout/setInterval。 - 随机性必须接入种子。 在
renderAt内部使用下面的rand(seed),而不是裸Math.random()。 - 在第一帧之前加载资源。 为字体和图片维护一个
readypromise,使renderAt为 async 并await ready。渲染器会等待renderAt返回的任何 promise。 - 页面尺寸与视频一致。 画布尺寸等于视频尺寸,并设置
html,body{margin:0;overflow:hidden}。
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>html,body{margin:0;background:#0b0b10;overflow:hidden}</style>
</head>
<body>
<canvas id="c" width="1920" height="1080"></canvas>
<script>
const W = 1920, H = 1080;
const ctx = document.getElementById('c').getContext('2d');
const clamp = (x, a = 0, b = 1) => Math.min(b, Math.max(a, x));
const ease = (x) => 1 - Math.pow(1 - clamp(x), 3); // easeOutCubic
const span = (t, start, dur) => clamp((t - start) / dur); // 在 [start, start+dur] 区间内从 0 → 1
const rand = (seed) => { const x = Math.sin(seed * 12.9898) * 43758.5453; return x - Math.floor(x); };
const ready = document.fonts.ready; // 加上你加载的任何图片
window.renderAt = async (t) => {
await ready;
ctx.fillStyle = '#0b0b10';
ctx.fillRect(0, 0, W, H);
// 场景 1 (0–3s):标题淡入升起。
const p = ease(span(t, 0.2, 1.2));
ctx.globalAlpha = p;
ctx.fillStyle = '#f5b700';
ctx.font = '800 140px system-ui, sans-serif';
ctx.textAlign = 'center';
ctx.fillText('Hello, video', W / 2, H / 2 + 60 * (1 - p));
ctx.globalAlpha = 1;
// 粒子:每个粒子使用种子化的位置,由 t 驱动。
for (let i = 0; i < 80; i++) {
const x = (rand(i) * W + t * 60 * (0.5 + rand(i + 99))) % W;
const y = rand(i + 7) * H;
ctx.fillStyle = `rgba(255,255,255,${0.15 + 0.35 * rand(i + 3)})`;
ctx.fillRect(x, y, 3, 3);
}
};
</script>
</body>
</html>
DOM、CSS、SVG 和 WebGL 页面同样适用。在 renderAt 内部通过 t 设置样式,或者让 CSS 动画和 GSAP/motion 时间线运行。渲染器会将它们定位到每一帧对应的时间。参见 references/pages.md。
2. 渲染
npx -y @helios-project/cli@latest render video.html -o video.mp4 --duration 12
| 标志 | 用途 |
|---|---|
--duration <s> | 视频长度(秒)。支持小数。对于 renderAt 页面是必需的。 |
--width 1080 --height 1920 | 帧尺寸;默认为 1920×1080。需与你的画布匹配。竖屏 9:16 为 1080x1920。 |
--fps <n> | 帧率;默认为 30。 |
--audio song.mp3 | 配乐,会自动裁剪至视频长度。 |
--mode canvas | 对于仅包含一个全帧 <canvas> 的页面更快速。默认值 dom 会捕获页面实际显示。 |
--preset medium | 用于最终文件。相同质量下文件体积小几倍,但编码时间更长。默认值 ultrafast 适合快速草稿。 |
渲染是逐帧精确的。第 n 帧正好是 renderAt(n / fps),不会丢帧、重复帧,也不依赖于机器速度。
如需生成 GIF,请先渲染 MP4 再转换。参见 references/pages.md。
3. 在说完成之前先检查帧
不要交付一个你从未看过的视频。直接从页面渲染静态帧和联系表;它们速度很快且无需编码:
npx -y @helios-project/cli@latest still video.html --at 0.5,3,7.25 # 全尺寸 PNG
npx -y @helios-project/cli@latest sheet video.html --every 1 --duration 12 # 带标签的网格
npx -y @helios-project/cli@latest sheet video.html --strip 2:3 --fps 30 # 2–3 秒内的每一帧
npx -y @helios-project/cli@latest sheet video.html --at 4 --crop 600,300,720,480 # 放大到某个区域
在长时间渲染之前,检查页面是否真的是 t 的函数:
npx -y @helios-project/cli@latest verify video.html --duration 12 # 如果存在依赖历史的帧,则退出代码为 1 并列出它们
使用图片查看工具打开 PNG 并检查:
- 文字清晰可读且在画面内
- 过渡确实发生
- 没有空白或黑色帧
- 节奏符合要求
修复页面,再次检查,然后重新渲染。
4. 音乐和音效
--audio 会混入一个音频文件。要使画面与音乐同步,可使用以下方法之一:
- 已知 BPM: 第
k个节拍落在k * 60 / bpm秒。根据t以此网格驱动脉冲。 - 未知节奏: 在页面中分析音频。解码一次,预先计算响度包络,然后在
renderAt中根据t读取该包络。参见 references/music.md。
出现问题时的对策
| 症状 | 解决方法 |
|---|---|
| "How long should the video be? Pass --duration" | 添加 --duration <seconds>。 |
window.renderAt(2.5) threw: … | 你的页面在此时出错。消息中包含你的堆栈跟踪。 |
| 首次渲染时暂停下载 Chromium | 这是预期的,且只会发生一次。不要自行运行 npx playwright install:它会获取错误的 Playwright 版本的构建。 |
| "The page defines no window.helios, window.renderAt(t) …" | 你的脚本从未定义 renderAt。检查页面是否有加载错误,例如语法错误或导入失败。 |
两次渲染之间帧不同,或 verify 失败 | 某些内容不是 t 的函数:可能是未种子化的 Math.random()、计数器或定时器。 |
| WebGL 帧空白 | 在 renderAt(或 rAF 循环)内部绘制,不要在加载时只绘制一次。 |
更大的项目(React/Vue 组件、工作室编辑、分布式云端渲染)可以直接使用 Helios 包:https://github.com/BintzGavin/helios。