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 # プロジェクトをスキャフォールド
cd my-video
npx hyperframes lint # プレビュー/レンダリング前に検証
npx hyperframes preview # ライブリロードブラウザプレビュー(ポート3002)
npx hyperframes render --output final.mp4 # MP4にレンダリング
npx hyperframes doctor # 環境問題を診断
レンダリングフラグ: --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"
スクリプトの内容:
- Node.js >= 22とFFmpegがインストールされていることを確認します(インストールされていない場合は修正手順を表示)。
hyperframesCLIをグローバルにインストールします(npm install -g hyperframes@>=0.4.2)。- Puppeteerを介して
chrome-headless-shellをプリキャッシュします — ChromeのHeadlessExperimental.beginFrameキャプチャパスを通じて最高品質のレンダリングを行うために必須です。 npx hyperframes doctorを実行し、結果を報告します。
セットアップが失敗した場合の詳細は references/troubleshooting.md を参照してください。
手順
1. HTMLを書く前に計画する
コードに触れる前に、高いレベルで以下を明確にします:
- 何を — ナラティブアーク、重要な瞬間、感情的なビート
- 構造 — コンポジション、トラック(ビデオ/オーディオ/オーバーレイ)、期間
- ビジュアルアイデンティティ — 色、フォント、モーションの特性(爆発的/シネマティック/流動的/テクニカル)
- ヒーローフレーム — 各シーンにおいて、最も多くの要素が同時に表示される瞬間。最初に構築する静的レイアウトです。
ビジュアルアイデンティティゲート(ハードゲート)。 コンポジションHTMLを書く前に、ビジュアルアイデンティティを定義する必要があります。デフォルトまたは汎用的な色(#333、#3b82f6、Robotoはこのステップがスキップされたことを示します)でコンポジションを書かないでください。以下の順序で確認します:
-
プロジェクトルートに
DESIGN.mdがあるか? → その正確な色、フォント、モーションルール、および「やってはいけないこと」の制約を使用します。 -
ユーザーがスタイルを指定したか(例:「Swiss Pulse」、「ダークでテクい」、「高級ブランド」) → 最小限の
DESIGN.mdを生成します。## Style Prompt、## Colors(役割を持つ3~5のHEX値)、## Typography(1~2ファミリー)、## What NOT to Do(3~5のアンチパターン)を含めます。 -
上記のいずれでもない場合 → 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()エグジット(CSS位置からアニメーション)を追加します。
完全なデータ属性スキーマとコンポジションルールについては 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. シーン間のトランジション
マルチシーンコンポジションにはトランジションが必要です。ルール:
- シーン間では常にトランジションを使用する — ジャンプカットは禁止です。
- すべてのシーン要素にエントランスアニメーションを常に使用する(
gsap.from(...))。 - 最終シーンを除いてエグジットアニメーションは決して使用しない — トランジションがエグジットです。
- 最終シーンはフェードアウトしても構いません。
シェーダートランジション(flash-through-white、liquid-wipeなど)をインストールするにはnpx hyperframes add <transition-name>を使用します。完全なリスト: npx hyperframes add --list。
6. オーディオ、キャプション、TTS、オーディオリアクティブ、ハイライト
- オーディオ: 常に別個の
<audio>要素(ビデオはmuted playsinline)。 - TTS:
npx hyperframes tts "スクリプトテキスト" --voice af_nova --output narration.wav。--listで音声を一覧表示します。音声IDの最初の文字は言語をエンコードします(a/b=英語、e=スペイン語、f=フランス語、j=日本語、z=中国語など) — CLIは自動的にフォネマイザーロケールを推測します。上書きする場合のみ--langを渡します。非英語の音素化にはシステム全体にespeak-ngがインストールされている必要があります。 - キャプション:
npx hyperframes transcribe narration.wav→ 単語レベルの書き起こし。書き起こしのトーンからスタイルを選択します(hype / corporate / tutorial / storytelling / social —references/features.mdの表を参照)。言語ルール: オーディオが英語であると確認されていない限り、.enWhisperモデルを絶対に使用しないでください —.enは非英語のオーディオを書き起こさず翻訳します。すべてのキャプショングループは、そのエグジットトゥイーンの後に硬いtl.set(el, { opacity: 0, visibility: "hidden" }, group.end)キルを持たなければなりません — そうでないとグループが後続のグループに漏れて表示されます。 - オーディオリアクティブビジュアル: オーディオバンド(低音/中音/高音)を事前に抽出し、タイムライン内で
tl.call(draw, [], f / fps)のforループを使用してフレームごとにサンプリングします — 単一の長いトゥイーンはオーディオに反応しません。低音→scale(パルス)、高音→textShadow/boxShadow(グロー)、全体的な振幅→opacity/y/backgroundColorをマッピングします。イコライザーバーの決まり文句は避けてください — コンテンツがビジュアルを導き、オーディオがその動作を駆動するようにします。 - マーカースタイルのハイライト: テキスト強調のためのハイライト、サークル、バースト、スクリブル、スケッチアウトエフェクトは決定的なCSS+GSAPです —
references/features.md#marker-highlightingを参照してください。完全にシーク可能で、アニメーション化されたSVGフィルターはありません。 - シーントランジション: すべてのマルチシーンコンポジションはトランジションを使用しなければなりません(ジャンプカット禁止)。CSSプリミティブ(プッシュスライド、ブラークロスフェード、ズームスルー、千鳥ブロック)またはシェーダートランジション(
flash-through-white、liquid-wipe、cross-warp-morph、chromatic-splitなど)から選択します。インストールはnpx hyperframes addを使用します。ムードとエネルギーテーブルはreferences/features.md#transitionsにあります。同じコンポジション内でCSSトランジションとシェーダートランジションを混在させないでください。
7. リント、検証、インスペクト、プレビュー、レンダリング
npx hyperframes lint # 欠落したdata-composition-id、重複トラック、未登録タイムラインを検出
npx hyperframes validate # 5つのタイムスタップでWCAGコントラスト監査
npx hyperframes inspect # ビジュアルレイアウト監査 — オーバーフロー、フレーム外要素、隠されたテキスト
npx hyperframes preview # ライブブラウザプレビュー
npx hyperframes render --quality draft --output draft.mp4 # 高速イテレーション
npx hyperframes render --quality high --output final.mp4 # 最終出力
hyperframes validateは、すべてのテキスト要素の背後にある背景ピクセルをサンプリングし、コントラスト比が4.5:1未満(大きなテキストの場合は3:1未満)の場合に警告します。hyperframes inspectはレイアウト側のコンパニオンです — 複数のタイムスタンプでページを実行し、静的リントでは見えない問題(4.5秒でのみセーフエリアを超えてラップするキャプション、タイトルが最長のバリアントである場合にオーバーフローするカード、トランジションシェーダーの後ろに隠れてしまう要素)をフラグします。特に吹き出し、カード、キャプション、またはタイトなタイポグラフィを含むコンポジションではinspectを実行してください。
8. ウェブサイトから動画へ(ユーザーがURLを指定した場合)
references/website-to-video.md の7ステップキャプチャから動画へのワークフローを使用します: キャプチャ → DESIGN.md → SCRIPT.md → ストーリーボード → コンポジション → レンダリング → 納品。
落とし穴
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でラップしないでください。 <template>でラップされたスタンドアロンindex.html— すべてのコンテンツがブラウザから隠されます。data-composition-srcを介してロードされるサブコンポジションのみが<template>を使用します。- オーディオにビデオを使用する — 常にミュートされた
<video>+ 別個の<audio>を使用してください。
検証
レンダリングの前後に:
- リント + 検証 + インスペクトがパス:
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(リントは構造的問題、検証はコントラスト、インスペクトはビジュアルレイアウト/オーバーフロー問題をキャッチします — 警告が表示された場合は troubleshooting.md を参照)。 - アニメーション振り付け — 新しいコンポジションまたは重要なアニメーション変更の場合、アニマップを実行します。
npx hyperframes initはスキルスクリプトをプロジェクトにコピーするため、パスはプロジェクトローカルです:
単一のnode skills/hyperframes/scripts/animation-map.mjs <composition-dir> \ --out <composition-dir>/.hyperframes/anim-mapanimation-map.jsonを出力します。これには、トゥイーンごとの概要、ASCIIガントタイムライン、スターガー検出、デッドゾーン(アニメーションのない>1秒)、要素ライフサイクル、フラグ(offscreen、collision、invisible、paced-fast<0.2秒、paced-slow>2秒)が含まれます。概要とフラグをスキャンし、それぞれを修正または正当化します。小さな編集ではスキップします。 - ファイルが存在し、サイズがゼロでない:
ls -lh final.mp4。 - 期間が
data-durationと一致する:ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4。 - ビジュアルチェック: コンポジション中間のフレームを抽出:
ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png。 - 期待される場合にオーディオが存在する:
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修正、環境変数、一般的なレンダリングエラー