hyperframes

HyperFrames — まずはこちら

HyperFrames は HTML から動画をレンダリングします。コンポジションは HTML ファイルで、その DOM で data-* 属性を使ってタイミングを宣言し、アニメーションランタイムはシーク可能で、メディア再生はフレームワークが管理します。作成時の仕様全体は /hyperframes-core に記載されています。コンポジションの HTML を書く前にお読みください。

以下は、機能マップ（必要に応じて読み込むドメインスキル）と、インテントルーター（「動画を作って」というあらゆるリクエストに対してワークフローを選ぶ方法）です。

機能マップ — ドメインスキル

必要に応じて読み込む個別の機能です。動画作成のワークフロー全体ではありません。「動画を作って」というリクエストには、以下のインテントルーターを使用してください。

目的	スキル
HTML コンポジションを作成／編集する — data-* の仕様、クリップ、トラック、サブコンポジション、変数	/hyperframes-core
アニメーション — 個別のモーション、シーンの設計図、トランジション、ランタイムアダプター（GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU）	/hyperframes-animation
クリエイティブディレクション — frame.md / design.md、配色、タイポグラフィ、ナレーション、ビート計画、音声リアクティブ	/hyperframes-creative
メディア — TTS ナレーション、BGM、文字起こし、背景除去、字幕	/hyperframes-media
メディアの解決 — HeyGen カタログから BGM、SFX、画像、アイコンを見つけて .media/ に保存し、マニフェストで追跡	/media-use
CLI の開発ループ — 初期化、リント、検証、検査、プレビュー、レンダリング、公開、診断	/hyperframes-cli
レジストリのブロック／コンポーネントをインストールする（hyperframes add）	/hyperframes-registry

---

インテントルーティング — ワークフローを選ぶ

このセクションではトップレベルのワークフローのみを扱い、その内部のリファレンスや上記のドメインスキルは読み込みません。

ルーティングの前に — 仕様ではなく入力を確認する

ルーティングには、動画の内容、つまり入力と題材を把握する必要があります。入力が指定されていない場合（URL、製品、トピック、アセットのない「自社のことを動画にして」など）は、ワークフローに進む前に質問してください。ワークフローを決めること自体がルーティングの判断です。質問は最大 2 つです。

• 入力 — 製品（URL／概要）、一般的なウェブサイト、GitHub PR、解説するトピック、または既存のトーキングヘッド動画のいずれかですか？

仕様のデフォルト — 質問せずに伝える（ルートは変わりません）：アスペクト比は 16:9（TikTok／Reels／Shorts など、縦型の用途が明示されている場合のみ 9:16 を使用）。ナレーション／字幕の言語はユーザーの言語です。選択したワークフローでは、最初のステップで固有の詳細を改めて確認します。

ワークフロー早見表

ワークフロー	用途
/product-launch-video	マーケティング／製品のローンチ／プロモーション — URL、概要、スクリプトから作成します（サイト名のみが指定されている場合も含みます）
/website-to-video	一般的なウェブサイトを動画に変換します — サイトツアー、ポートフォリオ／ランディングページの紹介、サイトのビジュアルを使ったソーシャルクリップ
/faceless-explainer	テキストをもとにトピック／概念を解説します — 製品もURLも不要で、すべてのビジュアルはLLMが生成します
/pr-to-video	GitHubのPR／コード変更から、変更履歴／新機能紹介／修正／リファクタリングの解説動画を作成します
/embedded-captions	既存のトーキングヘッド動画にキャプション／字幕を追加します（映像素材は変更しません）
/talking-head-recut	既存のトーキングヘッド動画にデザインされたグラフィックオーバーレイを追加して仕上げます — ローワーサード、データコールアウト、キネティックタイトル、引用テキストなど
/motion-graphics	短い、ナレーションなしの、デザイン主導のモーショングラフィックス — キネティックタイポグラフィ、統計／グラフの見せ場、ロゴの演出、ローワーサードのオーバーレイなど
/music-to-video	音楽トラックからビートに同期した動画を作成します — リリックビデオ、スライドショー、キネティックプロモーションなど。音楽に合わせてテンポを調整します（ユーザー画像／動画をビートグリッドに合わせてカットすることもできます）
/slideshow	プレゼンテーション／ピッチデッキ／インタラクティブデッキ — 個別のスライド、断片、分岐、ホットスポットで構成されます。出力はレンダリングされた動画ではなく、操作可能なデッキです
/general-video	その他すべて — 長尺または複数シーンの動画、静止画のループ／ポスター、カスタム構成など
/remotion-to-hyperframes	既存のRemotion（React）構成をHyperFramesに移行します（新規作成ではなく移行）

使い分け（混同しやすい場合のみ）：

• 動きが主役でナレーションなし（約10秒未満で、動きそのものがメッセージ）→ 入力に関係なく /motion-graphics。
• URL またはスクリプト — 特定の製品を宣伝する場合（サイト名を挙げるだけの場合も含む）→ /product-launch-video、製品とは無関係な一般的なサイトの場合 → /website-to-video、GitHub PR のリンクの場合 → /pr-to-video、製品やサイトを扱わずに概念を説明する場合 → /faceless-explainer。製品とトピックのどちらなのか、またはローンチと一般的なサイトのどちらなのかが本当に不明な場合は、質問を1つします。
• 既存の映像素材 — 話し言葉をそのまま字幕にする場合 → /embedded-captions、デザインされたオーバーレイカードを使う場合 → /talking-head-recut。どちらも映像素材そのものの編集（タイミング変更／色調変更／画角変更／並べ替え／音声編集）は行いません。これは NLE による編集であり、対象範囲外です。
• 音楽トラックが入力（音声ファイル、または音声を取り出す動画）で、ナレーションなしの場合 → /music-to-video — 音楽のビートやエネルギーに合わせてテンポを決めます。（ナレーション付きのコンテンツは、上記の入力に合ったワークフローを使います。/motion-graphics は、音楽に合わせるものではない、短くナレーションのないモーション向けです。）
• プレゼンテーション／ピッチデック／インタラクティブデック（スライドが個別に分かれており、ナビゲーションや発表者モードがあるもの）→ /slideshow — 出力はレンダリングされた動画ではなく、ナビゲーション可能なデックです。「slideshow」と明示されたリクエストはそのまま進めます。関連するきっかけとなる語句（「deck」「slides」「presentation」「convert this page」）がある場合は、作成を始める前に /slideshow でスライドショーかどうかを確認し、そうでなければ適切なスライドショー以外のワークフローに切り替えます。
• 長さは目安であり、制限ではありません — ワークフローは意図に基づいて選びます。作品が明らかに約3分を超える場合、または静止画／ループ／カスタム形式の場合に限り /general-video を使います。

適合するワークフローがインストールされていない場合

ワークフローを選んだら、実際に利用できるか確認してください。適合するワークフローのスキルがインストールされていない場合は、推測で代替せず、まずインストールするようユーザーに伝えてください。

• このワークフローのみ： npx skills add heygen-com/hyperframes --skill <workflow-name>（例：--skill pr-to-video — 先頭に / を付けないワークフロー名）。
• すべてのワークフローを一度に： npx skills add heygen-com/hyperframes --all（コアとすべてのワークフロー。選択メニューは表示されません）。

インストール後、該当するワークフローのスキルを読み直して続行してください。

スキルを最新の状態に保つ

HyperFrames のスキルにはバージョンが付けられています。npx hyperframes init は、インストール済みのスキルを GitHub 上の最新バージョンと照合し、古いものや不足しているものがあればスキル一式をすべてインストールまたは更新します。そのため、新しく init したプロジェクトには常に最新のスキル一式がそろいます。最新の状態のプロジェクトで init を再実行しても何も行われません。チェックは GitHub との短いやり取りで完了します。オフラインの場合やレート制限に達した場合は、短いタイムアウト後にインストールへ切り替えるため、ネットワークの一時的な問題で init が完全に失敗することはありません。作成ワークフローでは init を実行するため、新しいプロジェクトを開始するたびにこのチェックが行われ、スキルが古ければ GitHub から最新のスキルが取得されます。--skip-skills フラグは現在無効化されています（skills.sh レジストリの更新を待つ間の一時的な措置です）。このフラグを渡してもチェックはスキップされず、すべての init で GitHub が確認されます。CI／テストでは HYPERFRAMES_SKIP_SKILLS=1 環境変数を使ってチェックを回避します。

タスクが予想外の動作をする場合や、時間のかかるビルドの前には、インストール済みのスキルが最新かどうか確認してください。

• 確認： npx hyperframes skills check（機械可読形式の判定結果が必要な場合は --json を追加します。古いスキルまたは不足しているスキルがあると、ゼロ以外の終了コードを返します）。
• 更新： npx hyperframes skills update — スキル一式をすべて最新に更新し、未インストールのスキルもインストールします（init のインストール手順と同じです）。

render／lint／validate の実行時にスキルが古いと検出された場合、CLI も1行のリマインダーを表示します。

ワークフローの詳細

/product-launch-video

• 入力： マーケティング対象の製品 — （a） 製品 URL（ヘッドレス Chrome でクロールし、アセットとブランドトークンを取得）、（b） リンクがなくても製品のサイトを記載したスクリプト／概要（ユーザーがオプトアウトしない限り、PLV がサイトを特定してクロール）、または （c） 特定可能なサイトがない、あるいは「スクレイピングしない」スクリプト（キャプチャなしモード — パレットとデザインシステムを提供するスタイルプリセットを選択）。提供されたスクリプトは、ナレーションの原文そのままにも、シーンごとに再構成することもできます — PLV が確認します。
• 出力： HyperFrames のコンポジションによる製品ローンチ／SaaS プロモーション → MP4。（最適な長さは 30～90 秒）。
• トリガー： 「X のローンチ動画」「自社サイトのプロモーション」「自分の SaaS を 1 分で説明」「スクリプトを 60 秒のプロモーションに変換」「テキストのみのローンチ動画、スクレイピングなし」。

/website-to-video

• 入力： 動画に変換する一般的なウェブサイト／URL — 目的が製品ローンチではなく、サイトそのものを動画にする場合。ヘッドレス Chrome でキャプチャし、実際のスクリーンショットとブランドアセットを取得します。
• 出力： サイト内のビジュアルを使って作成するサイトツアー／ポートフォリオ／ランディングページのショーケース／ソーシャルクリップ → MP4。
• トリガー： 「このウェブサイトを動画に変換」「 のサイトツアー」「ホームページからソーシャルクリップを作成」「URL しかありません — 何か作って」。

/faceless-explainer

• 入力： 製品のマーケティングやキャプチャ対象のサイトを伴わない、解説対象の任意のテキスト — トピック、記事、メモなど。（/product-launch-video から派生。ヘッドレス Chrome は使用しません）。
• 出力： 顔出しなしの解説動画 → MP4。すべてのビジュアルをシーンごとに LLM が生成します（タイポグラフィ／抽象表現／図解／データビジュアライゼーション）。pin-and-paper プリセットが付属します。（最適な長さは 30～90 秒）。
• トリガー： 「X についての顔出しなし解説動画」「DNS の仕組みを動画で説明」「この記事を解説動画に変換」「メモから解説動画を作成」。

/pr-to-video

• 入力： GitHub プルリクエスト — PR URL、owner/repo#N 形式の参照、または「この PR」。gh CLI で読み込みます（スクレイピング対象のサイトではありません）。
• 出力： コード変更の解説動画（変更履歴／機能紹介／修正／リファクタリング）→ MP4 — 差分のハイライト、変更前／変更後、ファイルツリー、影響を示すシーン。≤（最適な長さは 30～90 秒）。
• トリガー： 「この PR について動画を作成」「PR #1187 を変更履歴動画に変換」「github.com/org/repo/pull/123 からリリースノート動画を作成」。

/embedded-captions

• 入力： 字幕を追加する既存のトーキングヘッド動画（MP4） — URL や概要ではなく、実際の映像です。ローカルで文字起こし（Whisper、API キー不要）し、マッティング（RVM）を行うことで、被写体を字幕の手前に表示できます。
• 出力： そのままの映像に字幕レイヤーを追加 — Standard（原文どおりのローワーサードレール＋クライマックス部分を被写体の背後に埋め込み）または Cinematic（すべての字幕を被写体の背後に合成）。長さは問いません。
• トリガー： 「この動画にキャプション／字幕を追加」「被写体の背後に字幕を配置」「クリップにシネマティックな字幕を追加」。

/talking-head-recut

• 入力： 画面上のグラフィックを加えて仕上げる既存のトーキングヘッド／インタビュー／ポッドキャスト動画（MP4） — 実際の映像です。ローカルで文字起こしします（Whisper）。クリップは編集せず、全編をそのまま背景で再生します。
• 出力： トランスクリプトに同期した、タイミング調整済みのグラフィックオーバーレイカードを加えた同じ映像 — 動きのあるタイトル、ローワーサード、データコールアウト、引用文、サイドパネル、ピクチャーインピクチャーなど。長さは問いません。
• トリガー： 「この動画を仕上げて」「トークにグラフィックオーバーレイ／ローワーサード／データコールアウトを追加」「このインタビューをグラフィック付きの編集動画に変換」。

/motion-graphics

• Input: 動きそのものがメッセージとなる、デザイン重視の短いモーショングラフィックです。通常は約10秒未満で、ナレーションはありません。ジャンル：キネティックタイポグラフィ、数値のカウントアップ、チャートの演出、ロゴの短いアニメーション、ローワーサード／オーバーレイ、検索結果をもとにしたページ／ツイート／見出しのショット。
• Output: 短いモーショングラフィック → MP4、またはローワーサード／コールアウト用の透過オーバーレイ（アルファチャンネル付きの WebM／MOV）。
• Triggers: 「8秒のロゴアニメーション」「この数値をアニメーションにする」「キネティックタイポグラフィのイントロ」「このツイートをモーショングラフィックにする」「透過ローワーサードオーバーレイ」。

/music-to-video

• Input: 音楽トラック（音声ファイル、または音声を抽出する動画）。ナレーションやウェブサイトのキャプチャは含みません。ユーザーが提供する画像／動画を織り込むこともできます。トラックを一度解析して決定的なビート／エネルギーマップ（audiomap.json）を作成し、それをもとに動画全体を構成します。
• Output: 音楽に合わせてペースを調整するビート同期型の HyperFrames コンポジション → MP4。タイポグラフィとテンプレートが基本となるため、動画の完成にアセットは一切必要ありません。提供されたメディアがあれば、同じビートグリッドに合わせて編集します（ビートに合わせたカット／ケン・バーンズ効果）。ジャンル（リリックビデオ、スライドショー、キネティックプロモ）は、フレームごとの選択から生まれるものであり、パイプラインがジャンルに応じて分岐することはありません。
• Triggers: 「この曲の動画を作って」「このトラックからビート同期動画を作って」「リリックビデオ」「この音楽を動画にして」「このビートに合わせたミュージックビジュアライザー／キネティックプロモ」。

/slideshow

• Input: 作成するプレゼンテーション／ピッチデッキ／インタラクティブデッキ（概要、アウトライン、またはスライドに変換する既存のページ）。レンダリング済み動画の依頼ではありません。意図が曖昧な場合は、作成前に「HyperFrames のスライドショーとして作成しますか？」と確認します。
• Output: 実行可能な HyperFrames コンポジションと、プレイヤーの SlideshowController が読み込むJSON アイランド。これにより、GSAP タイムラインを操作可能なデッキに変換します。個別のスライド、段階的な表示、分岐シーケンス、ホットスポットナビゲーション、プレゼンターモード、スピーカーノートに対応します。成果物はデッキであり、MP4 ではありません。
• Triggers: 「ピッチデッキ／プレゼンテーション／スライドデッキを作って」「インタラクティブデッキ」「このページをスライドに変換して」「プレゼンターモード付きのスライドショー」。

/general-video

• Input: 上記以外のあらゆる依頼（クリエイティブブリーフ、アニメーション化する単一の要素、作成中のコンポジションの編集など）。入力の種類や長さは問いません。
• Output: 元のフロー（デザインシステム → プロンプトの展開 → 計画 → アニメーション前のレイアウト → 作成（hyperframes-* スキルに委任）→ 検証）を用いた HyperFrames コンポジション（長さ／形式は問いません）。
• Triggers: 「タイトルカードを作って」「これをアニメーションにして」「長めのブランド動画／ショーリール」「複数シーンのコンポジション」「静的なループ／ポスター」、上記のどの項目にも当てはまらない「動画を作って」という依頼。

/remotion-to-hyperframes

• Input: 既存のRemotion（React）コンポジションのソース。ユーザーがポート／変換／移行を明示的に依頼した場合に限ります（Remotion → HyperFrames の一方向）。入力からの新規作成には使いません。Remotion への言及だけでは対象になりません。
• Output: Remotion ソースから変換した HyperFrames HTML コンポジション。Remotion のレンダリング結果と照合して評価します（SSIM 評価ハーネス＋段階的なテストコーパス）。
• Triggers: 「Remotion プロジェクトを HyperFrames にポートして」「この Remotion コンポジションを変換して」「Remotion から移行して」。