Make a video with Helios
Helios 视频就是一张 HTML 页面加一个函数 window.renderAt(t)。该函数负责绘制 t 秒时刻的画面。Helios 渲染器在无头 Chrome 中加载页面，逐帧调用 renderAt(t)，捕获每一帧并编码为 MP4。无需打包器、框架，也无需编写捕获脚本。
一、用途 适合用代码绘制视频：动态图形、产品发布与讲解视频、动画短片、动态图表与数据可视化、Logo 揭示、社交媒体短片、配乐视频等。
二、编写页面
- 每一帧都必须是 t 的纯函数。渲染器可能以任意顺序请求帧，且每次渲染同一帧结果必须一致。
- 一切从 t 推导：位置、透明度、当前显示哪个场景。不要使用计数器、x += speed、逐帧步进的物理模拟或 setTimeout/setInterval。
- 随机性必须有种子。使用文档中的 rand(seed)，而不是在 renderAt 内直接调用 Math.random()。
- 在第一帧之前加载资源。为字体和图片保留 ready promise，让 renderAt 为 async 并 await ready。渲染器会等待 renderAt 返回的任何 promise。
- 页面尺寸与视频一致。画布大小等于视频尺寸，并设置 html,body{margin:0;overflow:hidden}。
文档给出了完整的示例页面骨架，包括画布、clamp/ease/span/rand 辅助函数、ready promise 以及 renderAt 中按 t 绘制标题与粒子的逻辑。DOM、CSS、SVG 和 WebGL 页面同样可用：可在 renderAt 中根据 t 设置样式，或让 CSS 动画与 GSAP/motion 时间线运行，渲染器会将其定位到每一帧的时间。
三、渲染 使用命令：
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 再转换。
四、完成前查看帧 不要交付未看过的视频。可从页面本身快速渲染静帧和联系表，无需编码：
npx -y @helios-project/cli@latest still video.html --at 0.5,3,7.25 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 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 npx -y @helios-project/cli@latest verify video.html --duration 12 --cues lyrics.srt
联系表的取样点应根据视频结构选取：每个场景的首、中、末帧，每个大节拍或击打点，每次入场，每个转场的中点。查看 PNG 时检查：文字清晰且在画面内、转场确实发生、没有空白或黑帧、节奏符合需求。修改后再次检查并重新渲染。随后检查成片文件：
npx -y @helios-project/cli@latest check video.mp4
该命令检查闪烁是否超过 WCAG 2.3.1 限制、颜色标记和帧数。
五、音乐与声音 --audio 混入音频文件。要让画面与音乐同步，先分析音频：
npx -y @helios-project/cli@latest analyze track.mp3
它会写出 track.beats.json，包含节拍、强拍、鼓点、重大时刻、逐帧响度。在页面中加载该文件并在 t 处读取：在强拍处切换、在底鼓上做冲击、在大动作落在击打点。真实歌曲速度会漂移，应使用其节拍列表而非 k * 60 / bpm。歌词和字幕按演唱时间上屏，不要对齐到节拍。
六、常见问题
- 提示需要 --duration：添加 --duration <秒数>。
- window.renderAt(2.5) threw：页面在该时刻报错，信息含堆栈。
- 首次渲染暂停下载 Chromium：属正常，仅一次；不要自行运行 npx playwright install，会拉取错误 Playwright 版本的构建。
- 提示页面未定义 window.helios、window.renderAt(t)：脚本未定义 renderAt，检查加载错误如语法错误或导入失败。
- 两次渲染帧不一致或 verify 失败：有非 t 函数的内容，如未设种子的 Math.random()、计数器或定时器；canvas 上还可能是未设 willReadFrequently 的像素读取，或上一帧残留的上下文状态。
- verify --cues 提示某字幕未上屏：字幕需在其整个时间内显示；画布上绘制文字需声明 window.heliosDrawnText?.add(text)。
- check 报告闪烁：一秒内超过三次闪光可能诱发癫痫，需放慢频闪、缩小闪烁面积或降低对比度。
- WebGL 空白帧：在 renderAt（或 rAF 循环）内绘制，而不是仅在加载时绘制一次。
七、更大项目 需要 React/Vue 组件、工作室编辑、分布式云渲染时，直接使用 Helios 相关包：https://github.com/BintzGavin/helios。