framevelo は何をしますか？
FrameVeloは、コードでフレームを描画するページをMP4に変換します。フレームはGPU上（drawElementImageまたはページのキャンバス）に保持され、ハードウェアエンコーダに直接送られるため、スクリーンショットベースのレンダラーに比べてCPUとメモリの使用量が大幅に減少します。HyperFramesプロジェクトは公式のHyperFramesパイプラインでコンパイルされます。FrameVeloはキャプチャとエンコードの部分のみを置き換えます。
呼び出し方
このプラグインのMCPツールが利用可能な場合は、それらを使用してください。初回起動時にプラグインはFrameVeloを~/.cache/frameveloにインストールします（約1分）。プラグインのインストール直後にツールが見つからない場合は、少し待ってから再接続するか（/mcp）、以下のCLIを使用してください。
render: レンダリングを実行します。出力パス、フレーム数、サイズ、タイミング、警告、最後のログ行を返します。doctor: Node、FFmpeg、Chrome、drawElementImage、ハードウェアエンコーダ、HyperFramesのサポート状況を確認します。install_browser: Chrome 151+がインストールされていない場合、chrome-headless-shell（約100 MB）をダウンロードします。
ツールがない場合は、CLIを実行します。--jsonを指定すると、結果（または{"error": ...}）がstdoutに出力されます。
npx -y -p github:gnipbao/framevelo -p @hyperframes/[email protected] -p @hyperframes/[email protected] framevelo render /abs/project -o /abs/out.mp4 --json -q
初回のnpx実行では、約30秒のインストールが行われます。頻繁にレンダリングする場合は、ユーザーに一度だけインストールすることを提案してください：npm install -g github:gnipbao/framevelo @hyperframes/[email protected] @hyperframes/[email protected]。CLIはツールと同じオプションをフラグとして受け取ります（--frames 30 --quality draft）。framevelo render --helpで一覧を表示します。
絶対パスを使用してください。レンダリングは一度に1つずつ実行してください。これは単一のハードウェアエンコーダを共有するためであり、MCPサーバーもキューイングを行うためです。
ワークフロー
- 入力を見つける:
index.htmlを含むプロジェクトディレクトリ、または.htmlファイル。再生時間、fps、サイズはページから取得します（HyperFramesのdata-duration/data-fps/data-width、window.__framevelo.duration、GSAPタイムラインの長さ、window.__comp）。上書きする場合のみ、これらの値を渡します。 - スライスをプレビューする: コンポジションが新しく作成された、または変更されたばかりの場合：
{ input, output: "/tmp/preview.mp4", start: 2, frames: 30, quality: "draft" }。これで数秒で完了します。フレームを確認するには：ffmpeg -v error -ss 0.5 -i /tmp/preview.mp4 -frames:v 1 /tmp/preview.pngを実行し、PNGを表示します。 - デフォルトでフルレンダリングする: デフォルト設定で実行します。1080pレイアウトから4Kにするには
scale: 2を、モーションブラーにはsubframes: 3を追加します。 - 結果を確認する:
framesは期待したフレーム数です。audioはコンポジションに音声がある場合にtrueになります。warningsを読み取ってください。screenshotFrames > 0は、一部の間隔で検証に失敗し、スクリーンショットでキャプチャされたことを意味します（正しい結果ですが、より低速です）。 - レポートする: 出力パス、長さ、サイズ、および所要時間（
wallMs）を報告します。
レンダリング可能なページを作成する
すべてのフレームは時間の純粋関数でなければなりません。FrameVeloは、以下の最初に見つかったものを使用してページをシークします。
window.__framevelo = { seek(t), duration, fps }。seekはPromiseを返すこともできます。window.__seek(t)、オプションでwindow.__duration。- 一時停止されたGSAPタイムライン（
window.__timelines.main、または最初のキー）。
<canvas id="scene" width="1920" height="1080"></canvas>
<script>
const g = document.getElementById("scene").getContext("2d");
function draw(t) {
g.fillStyle = "#05060a";
g.fillRect(0, 0, 1920, 1080);
g.fillStyle = "#6cf";
g.fillRect(200 + 300 * t, 500, 120, 120);
}
window.__framevelo = { duration: 4, seek: draw };
</script>
- フッテージは
<video data-start="1.5" src="clip.mp4">（オプションでdata-media-start、data-duration、data-playback-rate）を使用してタイムラインに配置します。FrameVeloはそれを正確なフレームにシークします。long-GOPソースは、キャッシュされたオールイントラプロキシを取得します。 Math.randomはシードされるため、レンダリングは再現可能です。requestAnimationFrameループ、CSSトランジション、Date.now()、performance.now()のアニメーションはシークできません。これらはseek(t)または一時停止されたGSAPタイムラインに移動してください。- ドライバーを公開する前に、ページ内のアセット（フォント、画像）の読み込みを待つか、
seekからPromiseを返してください。
知っておくと便利なオプション
| ニーズ | 引数 |
|---|---|
| クイックチェック | frames: 30, quality: "draft", start: <s> |
| 1080pレイアウトから4K | scale: 2 |
| サイズが宣言されていない縦長ページ | viewport: "1080x1920" |
| ファイルサイズを小さく | codec: "hevc" |
| モーションブラー | subframes: 3（およびshutter、デフォルト0.5） |
| サウンドトラックを置き換える | audio: "/abs/music.m4a" |
| 1つの要素をキャプチャ | selector: "#stage" |
| 色の上に透明なDOM | background: "#000" |
| code-videoスキルが見つからない | mounts: {"/@skill/": "/abs/path/to/code-video"} |
| HyperFramesプロジェクトをプレーンページとして扱う | hyperframes: false |
エラーが発生した場合
| メッセージ | 対処方法 |
|---|---|
Chrome not found | install_browserを呼び出すか（framevelo browser installを実行）、その後再レンダリングします。 |
FFmpeg / FFprobe failing in doctor | ユーザーにFFmpegのインストールを依頼してください（brew install ffmpeg）。システムソフトウェアを自分でインストールしないでください。 |
The page exposes no way to seek time | ページにタイムドライバーが必要です。「レンダリング可能なページを作成する」を参照してください。 |
Unknown duration | durationまたはframesを渡すか、ページ内で再生時間を宣言してください。 |
The composition failed to set up | コンポジション内のスクリプトエラーです。ページを修正してください。メッセージにページエラーが含まれています。 |
No element matches selector / Nothing to capture / has no size | selectorをサイズのある可視要素に向けるか、レイアウトを修正してください。 |
Rendering a HyperFrames project needs ... @hyperframes/producer | 上記のnpx -p @hyperframes/...コマンドを使用するか、FrameVeloの隣にパッケージをインストールしてください。 |
No paint event within ... | ページの描画が停止しました。通常はスクリプトのハングです。ブラウザで確認してください。 |
レンダリングはアトミックです。失敗またはキャンセルされたレンダリングは出力ファイルを残しません。