Communitygithub.com

sairam0424/MindForge

HyperFrames を使用して、HTML ベースのビデオ合成、アニメーションタイトルカード、ソーシャルオーバーレイ、キャプション付きトーキングヘッド動画、音声連動ビジュアル、シェーダートランジションを作成します。HTMLがビデオの信頼できる情報源です。ユーザーがHTML合成からMP4/WebMをレンダリングしたい場合、メディア上でテキスト/ロゴ/チャートをアニメーション化したい場合、音声に同期したキャプションが必要な場合、TTSナレーションを希望する場合、またはWebサイトをビデオに変換したい場合に使用します。

MindForge とは?

MindForge(HyperFrames)は、HTML をビデオ作成の唯一の情報源として扱う AI エージェント向けスキルです。HTML、CSS、GSAP アニメーション、および data-* 属性を使用してビデオ合成を定義し、HyperFrames エンジンがフレームごとにキャプチャして FFmpeg で MP4/WebM にエンコードします。このスキルは、モーショングラフィックス、トーキングヘッド動画のキャプション、製品ツアー、ソーシャルオーバーレイ、シェーダートランジション、音声連動ビジュアルなどに最適です。一方、数学・幾何学的な解説動画には manim-video を使用することが推奨されています。CLI ツールが充実しており、プロジェクトのスキャフォールディング、リント、プレビュー、レンダリング、TTS、文字起こし、品質チェックなどをコマンド一つで実行できます。また、厳格なビジュアルアイデンティティの定義(DESIGN.md)や、Scene 間のトランジションの必須化、キャプションの適切な制御など、プロフェッショナルな動画制作に必要なルールが組み込まれている点が特徴です。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sairam0424/MindForge/tree/HEAD/.agent/skills/hyperframes

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

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

ドキュメント

HyperFrames

HTML がビデオの信頼できる情報源です。コンポジションは、タイミング用の data-* 属性、アニメーション用の GSAP タイムライン、および外観用の CSS を持つ HTML ファイルです。HyperFrames エンジンはページをフレームごとにキャプチャし、FFmpeg で MP4/WebM にエンコードします。

manim-video との補完関係: 数式・幾何学的な解説動画(数式、3B1Bスタイル)には manim-video を使用してください。モーショングラフィックス、キャプション付きトーキングヘッド、製品ツアー、ソーシャルオーバーレイ、シェーダートランジション、および実際のビデオ/オーディオメディアによって駆動されるものには hyperframes を使用します。

使用するタイミング

  • ユーザーがテキスト、スクリプト、またはWebサイトからレンダリングされたビデオを要求した場合
  • アニメーションタイトルカード、ローワーサード、タイポグラフィックイントロ
  • キャプション付きナレーションビデオ(TTS + 波形に同期したキャプション)
  • オーディオリアクティブビジュアル(ビート同期、スペクトラムバー、パルス発光)
  • シーン間トランジション(クロスフェード、ワイプ、シェーダーワープ、ホワイトフラッシュスルー)
  • ソーシャルオーバーレイ(Instagram/TikTok/YouTube スタイル)
  • Webサイトからビデオへのパイプライン(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 ~/.agent/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. ユーザーがスタイルを指定しましたか(例:「Swiss Pulse」、「ダークでテクニカル」、「ラグジュアリーブランド」)? → 最小限の DESIGN.md を ## Style Prompt、## Colors(役割付きで3~5色)、## Typography(1~2ファミリー)、## What NOT to Do(3~5のアンチパターン)とともに生成します。

  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() エグジット(そこ から アニメーション)を追加します。

完全な data-attribute スキーマとコンポジションルールについては 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 "スクリプトテキスト" --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) でフレームごとにサンプリングします — 単一の長いトゥイーンはオーディオに反応 しません。低音 → 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. Lint、検証、検査、プレビュー、レンダリング

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 はレイアウト面のコンパニオンで — 複数のタイムスタンプでページを実行し、静的 lint では見えない問題をフラグします(4.5秒でのみセーフエリアを超えて折り返すキャプション、タイトルが最も長いバリアントの場合にオーバーフローするカード、トランジションシェーダーの背後に隠れてしまう要素)。特に、吹き出し、カード、キャプション、またはタイトなタイポグラフィを含むコンポジションでは inspect を実行してください。

8. Webサイトからビデオへ(ユーザーが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 — キャプチャエンジンを壊します。常に有限の repeat 回数を計算してください。
  • 後で入るクリップ要素に 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>。

検証

レンダリングの前後に:

  1. Lint + validate + inspect がパス: 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.2s、paced-slow >2s)を含む単一の animation-map.json を出力します。サマリーとフラグをスキャンし、それぞれを修正するか正当化します。小さな編集の場合はスキップします。
  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 — data 属性、タイムライン契約、不可侵ルール、タイポグラフィ/アセットルール
  • 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 修正、環境変数、一般的なレンダリングエラー

関連スキル