ZardLi1115/zedclaw

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 ~/.zedclaw/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. ユーザーがスタイルを指定したか（例：「スイスパルス」、「ダークでテクニカル」、「ラグジュアリーブランド」） → 最小限の DESIGN.md を生成し、## Style Prompt、## Colors（役割付きの3～5つの16進数）、## 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() エグジット（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. 最終シーンはフェードアウトしても構いません。

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 → 単語レベルのトランスクリプト。トランスクリプトのトーンからスタイルを選択します（hype / corporate / tutorial / storytelling / social — references/features.md の表を参照）。言語ルール: 音声が英語であると確認されていない限り、.en whisperモデルを絶対に使用しないでください — .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 — すべてのコンテンツがブラウザから隠されます。<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
   

   単一の animation-map.json を出力します。これには、トゥイーンごとのサマリー、ASCIIガントチャートタイムライン、スターガー検出、デッドゾーン（アニメーションなしの>1秒）、要素ライフサイクル、およびフラグ（offscreen、collision、invisible、paced-fast <0.2s、paced-slow >2s）が含まれます。サマリーとフラグをスキャンし、それぞれを修正するか正当化します。小さな編集ではスキップします。
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の修正、環境変数、一般的なレンダリングエラー