Helios で動画を作成する
Helios 動画は、1 つの関数 window.renderAt(t) を持つ 1 つの HTML ページです。時刻 t 秒のフレームを描画します。Helios レンダラーはヘッドレス Chrome でページを読み込み、フレームごとに 1 回 renderAt(t) を呼び出し、各フレームをキャプチャして MP4 をエンコードします。バンドラー、フレームワーク、または記述するキャプチャスクリプトは必要ありません。
1. ページを記述する
すべてのフレームは t の純粋関数 でなければなりません。レンダラーは任意の順序でフレームを要求する場合があり、毎回同じフレームを同一にレンダリングします。
- すべてを
tから導出する: 位置、不透明度、表示するシーン。カウンター、x += speed、フレームごとにステップ実行する物理演算、setTimeout/setIntervalは絶対に使用しないでください。 - ランダム性はシードする必要があります。
renderAt内で素のMath.random()を使用せず、以下のrand(seed)を使用してください。 - 最初のフレームの前にアセットを読み込みます。 フォントと画像用に
readyプロミスを保持し、renderAtを非同期にしてawait readyとします。レンダラーはrenderAtが返すプロミスを待機します。 - ページのサイズをビデオに合わせます。 ビデオのサイズのキャンバスと、
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); // 0→1 over [start, start+dur]
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 | ページが 1 つの全画面 <canvas> のみの場合に高速化されます。デフォルトの dom は、ページの見た目をそのままキャプチャします。 |
--preset medium | 最終ファイル用。同じ品質で数分の 1 のサイズになり、エンコードに時間がかかります。デフォルトの 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 # ラベル付きグリッド 1 枚
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 を参照してください。
問題が発生した場合
| 症状 | 修正方法 |
|---|---|
| 「ビデオの長さは? --duration を渡してください」 | --duration <秒> を追加します。 |
window.renderAt(2.5) threw: … | その時刻にページでエラーが発生しました。メッセージにスタックトレースが含まれています。 |
| 最初のレンダリングで Chromium のダウンロードが一時停止する | これは予期された動作で、1 回だけ発生します。npx playwright install を自分で実行しないでください。間違った Playwright バージョン用のビルドを取得します。 |
| 「ページに window.helios、window.renderAt(t) … が定義されていません」 | スクリプトで renderAt が定義されていません。構文エラーやインポート失敗など、ページの読み込みエラーを確認してください。 |
2 つのレンダリング間でフレームが異なる、または verify が失敗する | 何かが t の関数になっていません: シードされていない Math.random()、カウンター、タイマーなど。 |
| WebGL フレームが真っ黒 | ロード時に一度だけではなく、renderAt (または rAF ループ) 内で描画します。 |
大規模なプロジェクト (React/Vue コンポーネント、スタジオ編集、分散クラウドレンダリング) では、Helios パッケージを直接使用します: https://github.com/BintzGavin/helios。