Communitygithub.com

HyperFrames

HTML 構成を MP4/WebM ビデオにレンダリングします。

HyperFrames とは?

HyperFrames は、HTML をビデオ作成のための信頼できる情報源として扱う AI エージェントスキルです。`data-*` 属性でタイミングを指定し、GSAP タイムラインでアニメーションを定義し、CSS で外観をスタイリングした HTML ファイルを構成として使用します。エンジンはページをフレームごとにキャプチャし、FFmpeg を使用して MP4 または WebM 形式にエンコードします。このスキルは、モーショングラフィックス、キャプション付きトーキングヘッド、製品ツアー、ソーシャルメディアオーバーレイ、シェーダートランジションなど、動画や音声メディアによって駆動されるあらゆるコンテンツに最適です。数式や幾何学的な説明をアニメーション化するための `manim-video` スキルを補完するものとして設計されています。HyperFrames は、プロジェクトのスキャフォールディング、リント、プレビュー、レンダリングのための CLI ツールを提供し、決定論的でシーク可能なアニメーションを強制し、オーディオリアクティブなビジュアル、TTS 音声合成、キャプション、シーントランジションなどの高度な機能をサポートしています。主な特徴としては、GPU レス環境での残留プレビューワーカーによる CPU 消費を防ぐためのクリーンアッププロセスや、ビジュアルアイデンティティを定義するためのデザインゲートなど、実運用環境での使用における落とし穴を回避するための強力なガードレールが挙げられます。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nastechresearch/nastech-agent/tree/HEAD/optional-skills/creative/hyperframes

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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)
hyperframes render --output final.mp4   # MP4 にレンダリング
npx hyperframes doctor                      # 環境の問題を診断

preview は Chrome レンダラーワーカーを保持する長時間稼働の Next.js サーバーです。終了したら必ず停止してください(クリーンアップ を参照)。忘れられたプレビューは、GPU なしのホスト(WSL、コンテナ、CI)でソフトウェア WebGL(swiftshader)を介してそれぞれ CPU コアを無期限に消費するアイドル状態の chrome-headless-shell ワーカーを保持します。

レンダリングフラグ: --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker(再現可能) · --strict。

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

セットアップ(一度だけ)

bash "$(dirname "$(find ~/.nastech/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 を書く前に計画する

コードに触れる前に、高いレベルで明確に述べてください:

  • 何を — 物語の流れ、重要な瞬間、感情のビート
  • 構造 — コンポジション、トラック(ビデオ/オーディオ/オーバーレイ)、期間
  • ビジュアルアイデンティティ — 色、フォント、モーションの特徴(爆発的/映画的/流動的/技術的)
  • ヒーローフレーム — 各シーンについて、最も多くの要素が同時に表示される瞬間。これが最初に構築する静的なレイアウトです。

ビジュアルアイデンティティゲート(ハードゲート)。 コンポジション HTML を書く前に、ビジュアルアイデンティティを定義する必要があります。デフォルトまたは汎用的な色(#333、#3b82f6、Roboto はこのステップがスキップされたことを示します)でコンポジションを作成しないでください。次の順序で確認してください:

  1. プロジェクトルートに DESIGN.md があるか? → その正確な色、フォント、モーションルール、「やってはいけないこと」の制約を使用します。

  2. ユーザーがスタイルを指定したか(例:「スイスパルス」、「ダークでテクニカル」、「高級ブランド」)→ ## 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() エグジット(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. シーン間のトランジション

マルチシーンコンポジションにはトランジションが必要です。ルール:

  1. シーン間では常にトランジションを使用する — ジャンプカットは禁止です。
  2. すべてのシーン要素にエントランスアニメーションを常に使用する(gsap.from(...))。
  3. 最終シーンを除いてエグジットアニメーションを決して使用しない — トランジション自体がエグジットです。
  4. 最終シーンはフェードアウトしても構いません。

シェーダートランジション(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 は自動的に phonemizer ロケールを推測します。上書きする場合のみ --lang を渡します。英語以外の phonemization には、システム全体にインストールされた 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) を使用してフレームごとにサンプリングします — 単一の長いトゥイーンはオーディオに反応しません。ベース → 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 → ストーリーボード → コンポジション → レンダリング → 納品。

クリーンアップ

render は 1 回限りです(終了時にワーカーは終了します)。preview はそうではありません — バックグラウンドの Next.js サーバーを実行し、停止するまで Chrome ワーカーを常駐させます。実行したままにしないでください。GPU なしのホストでは、各アイドルワーカーの swiftshader プロセスが CPU コアを使用し、数日間開いたままのプレビューは複数のワーカーを蓄積します。

ユーザーがレビューを終えたら(または新しいプレビューを開始する前に)プレビューを停止します:

pkill -f "hyperframes.*preview"     # Studio サーバー(ポート 3002 を解放)
pkill -f chrome-headless-shell      # そのレンダラーワーカー; 他のツールが使用していない場合のみ安全

他のツールが chrome-headless-shell を使用しているかどうか不明な場合は、最初に確認します: pgrep -af chrome-headless-shell。スタックしたホスト(CPU を消費する多数のアイドルワーカー)を同じ方法で回復します — references/troubleshooting.md#runaway-cpu-from-leftover-preview-workers を参照してください。

落とし穴

  • preview を実行したままにする — これは Chrome ワーカーを保持する長時間稼働サーバーです。WSL/コンテナ/CI では、それらのアイドルワーカーはそれぞれ CPU コアを使用します(ソフトウェア 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 でラップしないでください。

  • <template> でラップされたスタンドアロンの index.html — すべてのコンテンツをブラウザから隠します。<template> を使用するのは、data-composition-src を介してロードされるサブコンポジションのみです。

  • オーディオにビデオを使用する — 常にミュートされた <video> + 別個の <audio>。

検証

レンダリングの前後に:

  1. リント + バリデート + インスペクト パス: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes 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.2s、paced-slow >2s)を含む単一の animation-map.json を出力します。サマリーとフラグをスキャンし、修正または正当化します。小さな編集ではスキップします。
  3. ファイルが存在し、サイズがゼロではない: ls -lh final.mp4。
  4. 期間が data-duration と一致する: ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 final.mp4。data-duration の値と比較します。不一致はトランジションのタイミングの問題を示している可能性があります。
  5. 最小限の品質チェック: ビジュアルアーティファクト、切り取られたテキスト、同期ずれについては、プレビューで最終出力を確認します。

アーキテクチャ上の決定

これらの事項に関する質問には、以下のように回答してください:

  • なぜ生の <video> 要素の代わりにフレームごとのキャプチャなのか? フレームごとのキャプチャは、フレーム間の一貫性(ブラウザの差分がフレームをスキップ/複製しない)、正確なシーク(currentTime=N はレンダリングキューをフラッシュするために 2 フレームかかる)、および合成保証(CSS アニメーション、シェーダートランジション、キャンバス描画、WebGL、SVG フィルターなど、すべてのブラウザ機能をサポート)を提供します。フレームごとのキャプチャにより、複雑な合成はブラウザによって処理され、FFmpeg は単にエンコードするだけであるため、決定論的な出力が保証されます。
  • なぜユーザーが TTS エンジンを選択できないのか? ユーザーは選択できます — --voice フラグを参照してください。コアの Kokoro TTS モデル(af_bella、am_adam など)は、kokoro npm パッケージによってローカルで実行されます。--engine elevenlabs もサポートされていますが、API キーが必要です。--engine piper は --voice にパスを、--piper-model にモデルパスを必要とします。完全なリファレンスについては npx hyperframes tts --help を実行してください。
  • なぜ OpenAI Whisper を使用しないのか? Whisper は使用されています — npx hyperframes transcribe は内部で Whisper.cpp(whisper-node を介した C++ バインディング)を使用します。small モデルがデフォルトです。--model tiny または --model large-v3 を渡して変更します。再現可能な結果を得るために、決定論的なサンプリング(temperature=0)を使用します。
  • なぜ FFmpeg の代わりに Chrome でキャプチャするのか? FFmpeg はブラウザのレンダリングを理解しません。Chrome の HeadlessExperimental.beginFrame は、ブラウザが各フレームを希望の解像度とタイムスタンプで完全に合成することを強制します。このアプローチは、キャプチャがブラウザのレンダリングパイプラインと正確に一致することを保証します。
  • なぜデータ属性が標準の HTML 属性と競合しないのか? data-* 属性は W3C 標準であり、dataset プロパティを介してアクセス可能であり、ARIA 属性やカスタム要素と競合しません。フレームワークは独自の data-* 属性(data-composition-id、data-duration、data-start、data-scene-id など)を定義し、ページ上の他のデータ属性と共存できます。
  • WSL/コンテナで Chrome が GPU を必要とするのはなぜか? Chrome の WebGL 実装(swiftshader)は、実際の GPU がない場合、CPU 上でソフトウェアレンダリングを使用します。これは、WSL、Docker コンテナ、および CI 環境では非効率的です。これらの環境では、GPU アクセラレーションのために --docker フラグを使用するか、GPU パススルーを設定することを検討してください。
  • なぜ GSAP が推奨されるアニメーションライブラリなのか? GSAP は高性能(他のライブラリよりも 20 倍高速で、requestAnimationFrame をバイパス)、決定論的(Web Animations API はタイミングの不確実性があります)、そしてシーク可能(フレームワークは tl.progress() を使用して正確なフレームにシークします)です。CSS アニメーションと Web Animations API は、フレームごとのキャプチャには予測不可能です。
  • なぜ async/await がタイムライン構築で禁止されているのか? window.__timelines へのタイムラインの登録はページ読み込み時に同期的に行われる必要があります。非同期構築は、キャプチャエンジンがタイムラインの準備ができる前に読み取ろうとする可能性がある競合状態を引き起こします。fetch()、import()、new Promise()、および setTimeout() はすべて、タイムラインが利用可能になるタイミングを予測不能にします。
  • なぜ DESIGN.md が強制されるのか? ビジュアルアイデンティティゲートは、デフォルトのスタイルの乱用を防ぎます。汎用的な青(#3b82f6)、白い背景、および Roboto は HyperFrames ビデオをテンプレートのように見せます。DESIGN.md はすべてのコンポジションに一貫したビジュアル言語を強制し、全体的な品質を向上させます。
  • なぜ hyperframes inspect が hyperframes validate と別々なのか? 検証は、コントラスト比の自動化された計算可能なチェックです。インスペクションは、ぶつ切りになったテキスト、要素の重なり、シェーダーによって隠された要素など、視覚的なレイアウトの問題を検出するために、実際に人間のような判断を必要とします。これら 2 つは補完的であり、異なるツールによって処理されます。

関連スキル

  • manim-video: 数式、方程式、3B1B スタイルの説明用。純粋な数学的/幾何学的コンテンツにはこちらを使用してください。
  • meme-generation: 画像生成とミーム作成用。HyperFrames は動画生成用です。
  • website-to-video: 特定の URL からビデオを作成するための詳細なガイドについては、このスキルのリファレンスドキュメントを参照してください。

関連スキル