使用 Helios 製作影片
一部 Helios 影片就是一個 HTML 頁面,其中包含一個函式 window.renderAt(t)。它會繪製在時間點 t 秒時的影格。Helios 渲染器會在無頭 Chrome 中載入頁面,每影格呼叫一次 renderAt(t),捕捉每個影格並編碼為 MP4。無需捆綁器、框架,也無需編寫捕捉腳本。
1. 編寫頁面
每個影格必須是 t 的純函數。渲染器可能以任意順序請求影格,並且每次都會以完全相同的方式渲染同一個影格。
- 所有內容都從
t推導得出: 位置、不透明度、顯示哪個場景。絕對不要使用計數器、x += speed、逐影格步進的物理效果,或setTimeout/setInterval。 - 隨機性必須有種子。 在
renderAt內部使用下面的rand(seed),而不是單純的Math.random()。 - 在第一個影格之前載入資源。 為字型與圖片保留一個
ready的 promise,並讓renderAt是 async 的且在內部await ready。渲染器會等待renderAt回傳的任何 promise。 - 頁面大小需與影片相符。 一個與影片大小相同的 canvas,加上
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–3 秒):標題淡入升起。
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。需與你的 canvas 相符。垂直 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. 在宣佈完成之前先檢查影格
不要交出一個你還沒看過的影片。從頁面本身渲染靜態圖片與連絡表(contact sheets);它們速度很快且無需編碼:
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。