hyperframes

HyperFrames

動画の信頼できる唯一の情報源は HTML です。コンポジションは、タイミング用の data-* 属性、アニメーション用の GSAP タイムライン、見た目を定義する CSS を備えた HTML ファイルです。HyperFrames エンジンはページをフレームごとにキャプチャし、FFmpeg で MP4/WebM にエンコードします。

manim-video の補完: 数学や幾何学の解説（数式、3B1B スタイル）には manim-video を使用します。モーショングラフィックス、字幕付きトークヘッド、製品紹介、ソーシャルメディア向けオーバーレイ、シェーダートランジション、実際の動画・音声メディアを使用するコンテンツには hyperframes を使用します。

使用する場面

• テキスト、スクリプト、またはウェブサイトから動画をレンダリングするようユーザーから依頼された場合
• アニメーション付きタイトルカード、ローワーサード、タイポグラフィを使ったイントロ
• 字幕付きナレーション動画（TTS ＋ 波形に同期した字幕）
• 音声に反応するビジュアル（ビート同期、スペクトラムバー、脈動するグロー）
• シーン間のトランジション（クロスフェード、ワイプ、シェーダーワープ、白を通過するフラッシュ）
• ソーシャルメディア向けオーバーレイ（Instagram/TikTok/YouTube スタイル）
• ウェブサイトから動画を作成するパイプライン（URL をキャプチャしてプロモーション動画を作成）
• 動画ファイルに決定論的にレンダリングする必要がある HTML/CSS/JS アニメーション全般

次の用途には、このスキルを使用しないでください。

• 数学や数式だけのアニメーション（→ manim-video）
• 画像生成やミーム（→ meme-generation、画像モデル）
• ライブビデオ会議やストリーミング

クイックリファレンス

npx hyperframes init my-video               # scaffold a project
cd my-video
npx hyperframes lint                        # validate before preview/render
npx hyperframes preview                     # live-reload preview (long-lived server, port 3002)
npx hyperframes render --output final.mp4   # render to MP4
npx hyperframes doctor                      # diagnose environment issues

preview は、Chrome のレンダーワーカーを起動したままにする長時間稼働型の Next.js サーバーです。作業が終わったら必ず停止してください（クリーンアップを参照）。停止し忘れた preview は、アイドル状態の chrome-headless-shell ワーカーを稼働させ続けます。GPU のないホスト（WSL、コンテナー、CI）では、ソフトウェア WebGL（swiftshader）によって各ワーカーが CPU コアを 1 つずつ無期限に使用します。

レンダーフラグ：--quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker（再現可能）· --strict。

CLI の完全なリファレンス：references/cli.md。

セットアップ（初回のみ）

bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

このスクリプトは次の処理を行います。

1. Node.js >= 22 と FFmpeg がインストールされていることを確認します（未インストールの場合は修正方法を表示します）。
2. hyperframes CLI をグローバルにインストールします（npm install -g hyperframes@>=0.4.2）。
3. Puppeteer を使用して chrome-headless-shell を事前キャッシュします。Chrome の HeadlessExperimental.beginFrame キャプチャパスで最高品質のレンダリングを行うには、必須です。
4. npx hyperframes doctor を実行して、結果を報告します。

セットアップに失敗した場合は、references/troubleshooting.mdを参照してください。

手順

1. HTML を書く前に計画する

コードに着手する前に、次の点を大まかに明確にします。

• 内容 — 物語の流れ、重要な場面、感情の山場
• 構成 — コンポジション、トラック（動画／音声／オーバーレイ）、再生時間
• ビジュアルアイデンティティ — 色、フォント、動きの特性（爆発的／映画的／流動的／技術的）
• ヒーローフレーム — 各シーンで、最も多くの要素が同時に表示される瞬間。最初に構築する静的なレイアウトです。

ビジュアルアイデンティティの必須確認（HARD-GATE）。 コンポジションの HTML を書く前に、ビジュアルアイデンティティを必ず定義してください。デフォルトや汎用的な色（#333、#3b82f6、Roboto など、この手順を省略したことが分かるもの）でコンポジションを書かないでください。次の順に確認します。

1. プロジェクトルートに DESIGN.md があるか？ → そこに記載された色、フォント、動きのルール、「してはいけないこと」の制約をそのまま使用します。

2. ユーザーがスタイルを指定しているか（例：「Swiss Pulse」「ダークでテッキー」「高級ブランド」）？ → ## Style Prompt、## Colors（役割を付けた 3～5 個の 16 進数カラーコード）、## Typography（1～2 種類のフォントファミリー）、## What NOT to Do（3～5 個のアンチパターン）を含む最小限の DESIGN.md を生成します。

3. どちらにも当てはまらないか？ → HTML を書く前に、次の 3 つの質問をします。

   • 雰囲気は？（爆発的／映画的／流動的／技術的／混沌とした／温かみのある）
   • キャンバスは明るくしますか、暗くしますか？
   • ブランドカラー、フォント、ビジュアルの参考資料はありますか？

   回答をもとに DESIGN.md を生成します。すべてのコンポジションで、配色とタイポグラフィを DESIGN.md またはユーザーからの明示的な指示に基づかせてください。

2. スキャフォールド

npx hyperframes init my-video --non-interactive

テンプレート：blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。--example <name> を渡してテンプレートを選択し、--video clip.mp4 または --audio track.mp3 を渡してメディアを含めて開始します。

3. アニメーションの前にレイアウトを作成する

まず、ヒーローフレーム用の静的な HTML+CSS を作成します。まだ GSAP は使いません。.scene-content コンテナはシーン全体を埋める必要があります（width:100%; height:100%; padding:Npx）。また、display:flex と gap を使用します。コンテンツを内側に押し込むにはパディングを使い、コンテンツコンテナに position: absolute; top: Npx を指定することは避けてください（残りのスペースよりコンテンツが大きい場合、はみ出します）。

ヒーローフレームが適切に見えるようになってから、gsap.from() で登場アニメーション（CSS の位置へアニメーション）を追加し、gsap.to() で退出アニメーション（その位置からアニメーション）を追加します。

データ属性のスキーマと構成ルールの詳細は、references/composition.md を参照してください。

4. GSAP でアニメーションする

すべての構成で、次の要件を満たす必要があります。

• タイムラインを登録する：window.__timelines["<composition-id>"] = tl
• 一時停止状態で開始する：gsap.timeline({ paused: true }) — 再生はプレーヤーが制御します。
• repeat には有限の値を使用する（repeat: -1 はキャプチャエンジンが動作しなくなるため使用しないでください）。次の式で計算します：repeat: Math.ceil(duration / cycleDuration) - 1。
• 決定論的にする — Math.random()、Date.now()、または実時間に依存するロジックは使用しません。疑似乱数が必要な場合は、シード付き PRNG を使用してください。
• 同期的に構築する — タイムラインの構築で async／await、setTimeout、または Promise を使用しません。

GSAP の主要な API（トゥイーン、イージング、スタッガー、タイムライン）については、references/gsap.md を参照してください。

5. シーン間のトランジション

複数シーンの構成にはトランジションが必要です。ルール：

1. シーン間には必ずトランジションを使用します — ジャンプカットは使用しません。
2. すべてのシーン要素に必ず登場アニメーションを使用します（gsap.from(...)）。
3. 最後のシーン以外では退出アニメーションを使用しません — トランジションが退出アニメーションの役割を果たします。
4. 最後のシーンはフェードアウトしてもかまいません。

npx hyperframes add <transition-name> を使用してシェーダートランジション（flash-through-white、liquid-wipe など）をインストールします。一覧：npx hyperframes add --list。

6. 音声、字幕、TTS、音声リアクティブ、ハイライト

• 音声： 常に独立した <audio> 要素を使用します（動画は muted playsinline です）。
• TTS： npx hyperframes tts "Script text" --voice af_nova --output narration.wav。--list で音声を一覧表示します。音声 ID の先頭文字は言語を表します（a／b＝英語、e＝スペイン語、f＝フランス語、j＝日本語、z＝中国語など）。CLI が音素変換のロケールを自動推定するため、--lang は上書きする場合のみ指定します。英語以外の音素変換には、システム全体に espeak-ng をインストールする必要があります。
• 字幕： npx hyperframes transcribe narration.wav → 単語レベルの文字起こしが生成されます。文字起こしのトーン（盛り上げ／企業向け／チュートリアル／ストーリーテリング／ソーシャル）に合わせてスタイルを選びます（references/features.md の表を参照）。言語に関するルール： 音声が英語であると確認できていない場合は、.en Whisper モデルを使用しないでください。.en は英語以外の音声を文字起こしするのではなく翻訳します。すべての字幕グループには、終了トゥイーン後に tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) による確実な非表示処理を必ず追加してください。追加しないと、グループが後続のシーンでも表示されたままになります。
• 音声リアクティブなビジュアル： 音声帯域（低音／中音／高音）を事前に抽出し、タイムライン内で for ループと tl.call(draw, [], f / fps) を使ってフレームごとにサンプリングします。1 つの長いトゥイーンでは音声に反応しません。低音は scale（脈動）、高音は textShadow／boxShadow（発光）、全体の振幅は opacity／y／backgroundColor に割り当てます。ありがちなイコライザーバーの表現は避け、コンテンツに合ったビジュアルを選び、その動きを音声で制御します。
• マーカー風のハイライト： テキストを強調するハイライト、円、バースト、落書き、スケッチアウトのエフェクトは、決定論的な CSS＋GSAP で実現できます。references/features.md#marker-highlighting を参照してください。シークに完全対応し、アニメーション SVG フィルターは使用しません。
• シーン遷移： 複数シーンの構成では、必ずトランジションを使用してください（ジャンプカットは禁止です）。CSS プリミティブ（押し出しスライド、ぼかしクロスフェード、ズームスルー、ブロックの段階表示）か、npx hyperframes add で追加できるシェーダートランジション（flash-through-white、liquid-wipe、cross-warp-morph、chromatic-split など）から選びます。ムードとエネルギーの表は references/features.md#transitions にあります。同じ構成内で CSS トランジションとシェーダートランジションを混在させないでください。

7. リント、検証、検査、プレビュー、レンダリング

npx hyperframes lint              # catches missing data-composition-id, overlapping tracks, unregistered timelines
npx hyperframes validate          # WCAG contrast audit at 5 timestamps
npx hyperframes inspect           # visual layout audit — overflow, off-frame elements, occluded text
npx hyperframes preview           # live browser preview
npx hyperframes render --quality draft --output draft.mp4    # fast iteration
npx hyperframes render --quality high --output final.mp4     # final delivery

hyperframes validate はすべてのテキスト要素の背後にある背景ピクセルをサンプリングし、コントラスト比が 4.5:1 未満（大きなテキストの場合は 3:1 未満）のときに警告します。hyperframes inspect はレイアウト側の補完ツールです。複数のタイムスタンプでページを実行し、静的なリントでは検出できない問題（4.5 秒のときだけ字幕がセーフエリアを越えて折り返す、タイトルが最も長いバリエーションのときにカードがはみ出す、トランジションシェーダーの背後に要素が隠れるなど）を検出します。吹き出し、カード、字幕、または文字組みが詰まった構成では、特に inspect を実行してください。

8. ウェブサイトから動画へ（ユーザーが URL を提示した場合）

references/website-to-video.md にある、キャプチャから動画作成までの 7 ステップのワークフローを使用します：キャプチャ → DESIGN.md → SCRIPT.md → ストーリーボード → 構成 → レンダリング → 納品。

クリーンアップ

render は一度だけ実行されます（完了するとワーカーは終了します）。preview はそうではありません。バックグラウンドで Next.js サーバーを起動し、停止するまで Chrome ワーカーを常駐させます。実行したままにしないでください。GPU のないホストでは、各アイドルワーカーの swiftshader プロセスが CPU コアを 1 つ占有し、プレビューを何日も開いたままにすると複数のプロセスが積み重なります。

ユーザーの確認が終わったら（または新しいプレビューを開始する前に）、プレビューを停止してください：

pkill -f "hyperframes.*preview"     # the Studio server (frees port 3002)
pkill -f chrome-headless-shell      # its render workers; only safe if nothing else uses them

ほかのツールが chrome-headless-shell を使用しているか不明な場合は、先に確認してください：pgrep -af chrome-headless-shell。ホストが応答しなくなった場合（多数のアイドルワーカーが CPU を使い続けている場合）も、同じ方法で復旧してください。references/troubleshooting.md を参照してください。

落とし穴

• previewを起動したままにする — Chrome ワーカーを保持する長時間稼働サーバーです。WSL／コンテナー／CI では、アイドル状態のワーカーがそれぞれ CPU コアを 1 つ使用します（ソフトウェア WebGL）。完了したら停止してください — クリーンアップを参照してください。

• HeadlessExperimental.beginFrame' wasn't found — Chromium 147 以降ではこのプロトコルが削除されています。hyperframes@>=0.4.2を使用していることを確認してください（自動検出してスクリーンショットモードにフォールバックします）。回避策：export PRODUCER_FORCE_SCREENSHOT=true。 hyperframes#294とreferences/troubleshooting.mdを参照してください。

• システムの Chrome（chrome-headless-shellではないもの） — レンダリングがハングし、120 秒後にタイムアウトします。npx puppeteer browsers install chrome-headless-shellを実行してください（setup.sh がこれを実行します）。hyperframes doctorで使用されるバイナリを確認できます。

• repeat: -1をどこかで使用する — キャプチャエンジンが動作しなくなります。必ず有限の繰り返し回数を計算してください。

• 後から表示されるクリップ要素に対してgsap.set()を使用する — ページ読み込み時には要素が存在しません。代わりに、タイムライン内でクリップのdata-start以降の位置にtl.set(selector, vars, timePosition)を使用してください。

• コンテンツのテキスト内に<br>を入れる — 強制改行ではレンダリングされたフォント幅が考慮されないため、自然な折り返しと<br>によって二重に改行されます。max-widthを使用してテキストを折り返してください。例外：各単語を意図的に別々の行にする短いディスプレイタイトル。

• visibilityまたはdisplayをアニメーションさせる — GSAP ではこれらをトゥイーンできません。autoAlphaを使用してください（visibilityとopacityの両方を処理します）。

• video.play()またはaudio.play()を呼び出す — 再生はフレームワークが管理します。これらを自分で呼び出さないでください。

• タイムラインを非同期で構築する — キャプチャエンジンはページ読み込み後にwindow.__timelinesを同期的に読み込みます。タイムラインの構築をasync、setTimeout、または Promise でラップしないでください。

• 単独のindex.htmlを<template>でラップする — ブラウザーからすべてのコンテンツが隠れてしまいます。<template>を使用するのは、data-composition-src経由で読み込むサブコンポジションのみです。

• 音声に動画を使用する — 常にミュートした<video>と、別の<audio>を使用してください。

検証

レンダリングの前後に、次の手順を実行してください。

1. Lint、検証、検査を実行： npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect（lint は構造上の問題を、validate はコントラストの問題を、inspect はビジュアルレイアウトやオーバーフローの問題を検出します — 警告が表示された場合は troubleshooting.md を参照してください）。
2. アニメーションの構成 — 新しいコンポジションや大幅なアニメーション変更を行う場合は、アニメーションマップを実行してください。npx hyperframes initでスキルスクリプトがプロジェクトにコピーされるため、パスはプロジェクト内のものを使用します：

   node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
     --out <composition-dir>/.hyperframes/anim-map
   

   各トゥイーンの概要、ASCII ガントタイムライン、スタッガーの検出、デッドゾーン（アニメーションのない状態が 1 秒を超える区間）、要素のライフサイクル、フラグ（offscreen、collision、invisible、paced-fast 0.2 秒未満、paced-slow 2 秒超）を含むanimation-map.jsonが 1 つ出力されます。概要とフラグを確認し、それぞれを修正するか、理由を説明してください。小さな編集では省略してください。
3. ファイルの存在とサイズがゼロでないこと： ls -lh final.mp4。
4. 長さがdata-durationと一致すること： ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4。
5. ビジュアルを確認： コンポジションの中間フレームを抽出します：ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png。
6. 想定どおり音声が含まれていること： ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1。

hyperframes renderが失敗した場合は、npx hyperframes doctorを実行し、報告時にその出力を添付してください。

参考資料

• composition.md — データ属性、タイムラインの契約、必須ルール、タイポグラフィ／アセットのルール
• cli.md — すべての CLI コマンド（init、capture、lint、validate、inspect、preview、render、transcribe、tts、doctor、browser、info、upgrade、benchmark）
• gsap.md — HyperFrames の GSAP コア API（トゥイーン、イージング、スタッガー、タイムライン、matchMedia）
• features.md — 字幕、TTS、オーディオリアクティブ、マーカーのハイライト、トランジション（必要に応じて読み込み）
• website-to-video.md — キャプチャから動画作成までの7ステップのワークフロー
• troubleshooting.md — OpenClaw の修正、環境変数、よくあるレンダリングエラー