hyperframes-helper

Hyperframes ヘルパー

Hyperframes を使ってモーショングラフィックス動画を作成するための実用的なキットです。Hyperframes は HeyGen のオープンソース HTML-to-MP4 レンダラーです。目標に合わせて選べる、必要な労力が異なる3つのレベルを用意しています。

Hyperframes とは

Hyperframes はオープンソースの動画コンポジションフレームワークです。HTML/CSS/GSAP を記述すると、決定論的な MP4 がレンダリングされます。出力はモーショングラフィックスのように見えますが、ソースは単なるウェブページです。そのためエージェントとの親和性が高く、LLM は初回から作成できます。React/Remotion のバンドラーをあれこれ扱う必要はありません。

• GitHub: https://github.com/heygen-com/hyperframes
• ドキュメント: https://hyperframes.heygen.com
• ライセンス: Apache 2.0 — 無料で完全にローカルで動作し、HeyGen API キーは不要です

Hyperframes のインストール

必要なのは Node.js だけです。Hyperframes は npx で実行できます。

# Verify Node is available
node --version

# See what Hyperframes can do
npx hyperframes@latest --help

# Scaffold a new project
npx hyperframes@latest init my-video
cd my-video

# Add the official agent skills (gives you /hyperframes, /gsap, /website-to-hyperframes)
npx skills add heygen-com/hyperframes

# Open Studio (live preview at http://localhost:3002)
npx hyperframes@latest preview

# Lint your composition
npx hyperframes@latest lint

# Render to MP4
npx hyperframes@latest render -o output.mp4 --fps 30

初回のレンダリング時に Chrome（約101 MB）がダウンロードされます。以降はキャッシュされます。

このキットは Hyperframes の上に構築されています。どのレベルで作業するかを決めた後に利用する、パターン、テンプレート、レシピのレイヤーです。

---

3つのレベル

必要な複雑さは、実現したい内容によって異なります。目的に合ったレベルを選んでください。

---

レベル 1 · ウェブサイトから動画へ

最も手早い方法です。すでにウェブページ、コンポーネント、アニメーション CSS がある場合、それを MP4 に変換します。

こんなときに使います：

• ウェブ上で美しいアニメーションコンポーネントを見つけ、6秒のループ動画にしたい
• ブランドサイトがあり、15秒のヒーローアニメーションを動画ファイルにしたい
• インタラクティブなデモを手早くキャプチャしたい

方法：

# In your Hyperframes project
/website-to-hyperframes

公式の Hyperframes ウェブサイトから動画へのスキルで、最初から最後まで処理できます。ページをキャプチャし、Hyperframes コンポジションとしてラップしてからレンダリングします。詳しくはHyperframes のドキュメントをご覧ください。

ソース HTML を見つける方法：

• 21st.dev — 高品質な React コンポーネントのサンプルが見つかります。Hyperframes のシーンとしてうまく使えるものも多くあります。React のラッパーを取り除き、HTML/CSS/アニメーションを残してください。
• CodePen — 「shader」「particles」「loader」で検索すると、自己完結型のアニメーション CSS ペンが多数見つかります。
• Hyperframes レジストリ — npx hyperframes@latest catalog を実行すると、Hyperframes 自体に含まれるブロックやコンポーネントが表示されます。

出力： フレームレートを指定してキャプチャした、決定論的な単一の MP4 です。

---

レベル 2 · ストーリーボード

オリジナルのモーショングラフィックスを一から制作する際、本格的なコンポジションに取りかかる前にレイアウトを反復調整したい場合に使います。Studio での反復には1サイクルあたり約15分かかりますが、ストーリーボード HTML なら約1分です。

こんなときに使います：

• オリジナルのモーショングラフィックス動画（イントロ、フック、広告、レッスンの予告編）を制作する
• 依頼内容はあるものの、ショットリストがまだ明確でない
• GSAP を記述する前に、ビジュアルプランを共有したい

方法：

1. templates/storyboard-template.html をプロジェクトに storyboard.html としてコピーします
2. シーンカードに内容を記入します。1920×1080 のレイアウトプレビューを縮小表示し、各シーンのモーションに関するメモを添えます
3. ブラウザーで開き、レビュアーとファイルパスを共有します
4. HTML 上で反復調整します。プレビュー枠内で要素をドラッグして配置し、モーションメモを書き直します
5. 内容が確定してから、初めて本番のコンポジションに進みます

ストーリーボードテンプレートには、以下が含まれます：

• タイトル、メタ情報のピル、比率に応じた横型タイムラインバーを備えたヘッダー
• ナビゲーション用の固定目次
• シーンカード（2ペイン構成：縮小レイアウトプレビュー＋メモパネル）
• あらかじめスタイルが設定されたプレースホルダー要素：動画フレーム、テキストパネル、サンプルカード、透かし、モーション矢印
• コンポジションテンプレートと同じタイポグラフィおよびカラートークン

レビュアーが使えるマークアップ方法：

• ファイルを開き、インラインで `` タグを追加します
• ページのスクリーンショットを撮り、矢印を書き込みます
• チャットで「シーン3は X にしてください」のように説明するだけでも構いません

時間を節約できる理由： ストーリーボードの反復でレイアウトのミスを見つけるたびに、15分かかるコンポーズ・リント・プレビューのサイクルを省けます。ストーリーボードを5回見直せば、コンポジションの作業を1回分節約できます。

---

レベル 3 · ガイド付き動画

実際のカメラでの撮影を中心に、完全にカスタム制作します。RoboNuggets の制作パイプライン全体を、3 つのステップで進めます。

┌──────────────┐    ┌─────────────────┐    ┌───────────────────┐
│ STEP 01      │ ─→ │ STEP 02         │ ─→ │ STEP 03           │
│ Cut the      │    │ Storyboard the  │    │ Add in motion     │
│ Video        │    │ Title Cards     │    │ graphics          │
└──────────────┘    └─────────────────┘    └───────────────────┘

使用する場面：

• トークヘッド形式のオープニングとエンディング
• カメラに映るレッスンの導入
• 実際の録画を編集し、その上にモーショングラフィックスを追加する動画

ステップ 01 · 動画をカットする

2 回に分けて処理します。無音部分のカット、その後に撮り直し部分のカットです。どちらも ffmpeg を使用します。

パス A — 無音部分のカット（templates/silence-cut.sh）

ffmpeg -i input.mkv -af "silencedetect=noise=-30dB:d=0.4" -f null - 2>&1 | grep silence

すべての無音区間が出力されます。両側に 0.04 秒のパディングを加えたキープ範囲を作成し、GOP キーフレーム間隔を 1 秒にして再エンコードします（Hyperframes 対応）。テンプレートには、filter_complex trim/atrim/concat の一連の処理が含まれています。

パス B — 文字起こし（templates/transcribe-whisper.py）

pip install faster-whisper
python templates/transcribe-whisper.py input_silence_cut.mp4

単語単位のタイムスタンプ付きで、*.transcript.json と *.transcript.txt が出力されます。

faster-whisper を WhisperX より使う理由：Windows では torchaudio が不安定です（libtorchaudio の読み込みエラー）。faster-whisper は CTranslate2 を使用するため、torch に依存しません。

パス C — 撮り直し部分のカット（templates/cut-retakes.py）

単語単位の文字起こしから、撮り直し部分のまとまりを特定します。最後のテイクを残すルールを適用します。フレーズが繰り返されている場合は、最後のテイクだけを残し、それより前の部分（言い直し、前の試み、「最初からやり直します」といった合図）をすべてカットします。KEEPS の範囲をスクリプトに入力して実行します。

**代替ツール：**手作業を省きたい場合は、video-use をご利用ください。フィラーや言い直しをカットできる、自動動画編集エージェントです。実行ごとに時間がかかり、細かな調整項目も少なくなりますが、スクリプトを書く必要はありません。

ヒント：script-review.html を用意して、現在のスクリプトと修正案を並べて表示しましょう。撮り直し部分には赤い取り消し線を引き、最後のテイクは緑色で強調し、カット箇所の一覧（範囲、長さ、削除される内容、理由）に番号を付けます。再エンコードする前に、レビュー担当者がカットを承認できます。

ステップ 02 · タイトルカードのストーリーボードを作成する

大きな制作パイプラインの中でレベル 2 を適用します。templates/storyboard-template.html を使って、編集した動画に重ねるタイトルカードやオーバーレイのシーンを計画します。

よく使われるタイトルカードのパターン：

• 画面片側のフローティングカード（右または左）を、話の一区切りごとに 1 枚配置し、文字起こしに合わせて進めます
• 重要な場面には 中央に大きなテキスト を配置します。「大幅なアップグレード」、「オープンソース」、「無料かつオープンソース」など
• アニメーション付きの強調表示（曲線の下線、光る単語、脈打つ枠線）
• ブランド表示のコーナーピル（左上のステータスピル、右上のカウンター、左下のブランドピル）

コピーして使える実装例は templates/recipes.md をご覧ください。

ステップ 03 · モーショングラフィックスを追加する

特定のタイミングで登場する、画面中央のモーショングラフィックスを追加します。よく使われる要素は次のとおりです。

• シェーダーフラッシュ — Three.js のフラグメントシェーダーを使った、0.5〜1 秒のトランジション演出
• ワイヤーフレームの地球儀 — 国境線とハーフトーンのドットを描画する D3 の geoOrthographic を、透明なキャンバス上で使用
• クロマキー合成したキャラクター — グリーンスクリーン上で 3D レンダリングしたアイコンを反転させ、SVG の feColorMatrix フィルターで背景を除去
• ロゴの組み立て表示 — セグメントを順番にフェードインさせ、その後、ゆっくり呼吸するようなループを再生
• 締めくくりの大きなテキストとアイコン — ブランドロゴを並べた、最後のタグライン

各パターンのコピーして使えるレシピは templates/recipes.md にあります。

**構成のヒント：**各モーショングラフィックスはキャンバスの中央から始め、片側へスライドするアニメーションを付けながら、反対側にラベルをフェードインさせます。モーショングラフィックスを 3 つ続けて配置すれば、画面を混み合わせずにストーリーを伝えられます。

---

重要なフレームワークルール（リンターで見落としやすい点）

これらは必須です。守らないと、どれも Hyperframes のリンターエラーが発生します。

1. 時間指定されたすべての要素には、class="clip"、data-start、data-duration、data-track-index が必要です。 例外はありません。

2. GSAP でクリップ要素をアニメーションさせてはいけません。 フレームワークがクリップの表示を管理します。class="clip" の div の不透明度や表示状態をアニメーションさせると、gsap_animates_clip_element エラーが発生します。対処法：各シーンを外側の clip-shell と、内側のアニメーション可能な div で囲みます。

3. 同じトラック上のクリップは、わずかな時間でも重なってはいけません。 浮動小数点の精度が問題になります。start=23.85, duration=4.55 は 28.400000002 で終了し、start=28.40 と衝突します。再生時間を 4.54 に短縮するか、別のトラックに移動してください。

4. 視覚的に重なる要素は、別々のトラックに配置する必要があります。 4 枚のサンプルカードが同時に表示される場合は、トラック 12、13、14、15 に 1 枚ずつ配置します。

5. GSAP のタイムラインは一時停止し、登録する必要があります。

   window.__timelines = window.__timelines || {};
   const tl = gsap.timeline({ paused: true });
   // ... tl.from(...) ...
   window.__timelines["main"] = tl;  // matches data-composition-id
   

6. ロジックは決定論的にしてください。 Math.random()、Date.now()、fetch() は使用できません。レンダリングはフレーム単位のシークで行われます。

7. 動画には muted を使用し、別の <audio> 要素を用意してください。 <video> タグ経由で音声を再生すると、フレームシークが正しく動作しません。

8. ソース動画には短い間隔のキーフレーム（1 秒の GOP）が必要です。

   ffmpeg -i in.mp4 -c:v libx264 -preset fast -crf 18 \
     -r 30 -g 30 -keyint_min 30 \
     -force_key_frames "expr:gte(t,n_forced*1)" \
     -c:a aac -b:a 192k -movflags +faststart out.mp4
   

9. Canvas ベースのアニメーションは、タイムラインのティックごとに再描画する必要があります。 requestAnimationFrame は使用しないでください。tl.eventCallback('onUpdate', () => drawCanvas(tl.time())) を使用します。

10. クリップ要素には hard kill は必須ではありません。 フレームワークがクリップの終了時にハードカットします。クリップ要素に対して tl.set(..., {visibility: hidden}) を使用しないでください。

11. repeat: -1（無限リピート）は禁止されています。 リンターエラー：gsap_infinite_repeat。保持時間から有限の回数を算出してください。

    const HOLD = 6.0, CYCLE = 1.6;
    const repeats = Math.max(0, Math.floor(HOLD / CYCLE) - 1);
    tl.to('.element', { ..., repeat: repeats, yoyo: true });
    

12. 同じ src を持つ複数の <audio> 要素を使うと、エコーが発生します。 フレームワークはクリップの表示を制御しますが、Studio プレビューでは、事前に読み込まれた複数の音声要素が同時に再生されます。事前にカットしたクリーンな音声ファイルを指定する <audio> クリップを 1 つだけ使用してください。

13. 疑似要素（::before／::after）は GSAP でアニメーションできません。 実際の DOM 子 div に置き換えてください。

14. Studio が自動的に割り当てるインラインの style="z-index: N" は、前後関係が逆になる場合があります。 Studio で編集した後、六角形の背景やビネットが動画の前面に表示される場合は、インラインの z-index を一括削除してください。

    import re
    s = open('index.html').read()
    out = re.sub(r' style="z-index: \d+"', '', s)
    open('index.html', 'w').write(out)
    

15. 契約済み動画のフレームで発生するスタッキングコンテキストの注意点。 #videoFrame { z-index: 2 } の場合、z-index を指定していない兄弟要素の float-text はその下に隠れます。float 要素に明示的な z-index ≥ 2 を設定するか、videoFrame の z-index を削除し、背面に配置する要素（シェーダーなど）を DOM 内で videoFrame より前に置いてください。

16. z-index: -1 を指定すると、要素が body の背景の背後に隠れることがあります。 body { background: #000 } の場合、z-index: -1 の要素は body の背景描画よりも背面にレンダリングされ、見えなくなります。代わりに DOM の順序を利用し、「背面」に配置する要素を DOM 内で先に置き、z-index は指定しないでください。

複数クリップでカット編集するパターン（Studio でドラッグ可能なカット）

Hyperframes Studio では、ソースの途中でクリップを分割することは明確にできません（ドキュメントを参照）。代わりに、次の方法を使用します。

カットしていないソースをディスク上に保持し、タイムラインに複数の <video> クリップを定義して、それぞれ異なる data-media-start を設定します。Studio で任意のクリップの左ハンドルをドラッグすれば、ffmpeg を再実行することなく、そのセグメントのカット境界をその場で微調整できます。

<div id="videoFrame">
  <video class="stage-video clip" data-start="0.00" data-duration="2.56"
         data-media-start="2.24" data-track-index="2" muted playsinline preload="auto"
         src="assets/source-uncut.mp4"></video>
  <video class="stage-video clip" data-start="2.56" data-duration="3.74"
         data-media-start="9.12" data-track-index="3" muted playsinline preload="auto"
         src="assets/source-uncut.mp4"></video>
  
</div>

注意点：音声はこの方法では分割できません（ルール 12 のとおり、エコーが発生します）。cut-retakes.py でクリーンな音声ファイルを 1 つにカットし、<audio> クリップを 1 つだけ使用してください。Studio で動画の境界をドラッグした場合は、同期を保つために音声もカットし直す必要があります。

Studio でドラッグ編集する必要がなく、一度きりの納品でよい場合は、ffmpeg でカットした単一の source.mp4 と、単一の <audio> source.mp4 を使用するのが簡単です。

Studio の編集制限（公式ドキュメントに基づく）

Studio でサポートされている操作は次のとおりです。

• ✅ クリップを水平方向にドラッグ → data-start を更新
• ✅ クリップを行間でドラッグ → data-track-index を更新
• ✅ 右側のハンドルをドラッグ → data-duration を更新（末尾をトリミング）
• ✅ メディアクリップの左側のハンドルをドラッグ → data-start と data-media-start を更新（ソースの先頭をトリミング）
• ✅ 行を垂直方向に並べ替え → インラインの z-index を更新
• ❌ ソースの途中でクリップを分割／カットする
• ❌ メディア以外（モーション）クリップの先頭をトリミングする
• ❌ キーボードショートカット
• ❌ 複数選択
• ❌ 元に戻す／やり直す

出典：https://hyperframes.heygen.com/guides/timeline-editing

最高品質でレンダリングする

cd [project] && npx hyperframes@latest render \
  -o renders/final.mp4 \
  --fps 30 --quality high --crf 16 --gpu

• --quality high — 最高品質のティア
• --crf 16 — 見た目上ほぼ無劣化（値が低いほどファイルサイズが大きく、高品質になります。標準は18〜23です）
• --gpu — GPU エンコーディング
• 16コア環境でのレンダリング時間：動画と GSAP を含む30秒のコンポジションで約2.5〜3分

レンダリングは2つまで並行して実行できます。Hyperframes はレンダリングごとに5〜6個の Chrome ワーカープロセスを起動するため、2つのレンダリングでリソースをうまく共有できます。

レシピ

templates/recipes.md には、コピーして使えるパターンが10個用意されています。基本を習得したら、ぜひ活用してください。

1. リキッドグラスカード — すりガラス風の iOS スタイルの背景ぼかしに、光沢と屈折を加えたもの
2. パルスボーダー — カードの縁に単色の回転グラデーションを表示
3. 白いグローのテキスト — 動画上でも読みやすくする複数レイヤーの text-shadow
4. 曲線の下線 — em で強調された部分の下にアニメーション SVG 曲線を表示
5. クロマキー — SVG feColorMatrix によるグリーンスクリーンの除去
6. 複数クリップのカット編集 — 上記の data-media-start パターン
7. パルスリング — ロゴの周囲に同心円状の外向きパルスを表示
8. コーナーノート — ステータス／カウンター／ブランドのピル型装飾
9. D3 地球儀 — ハーフトーンドットをあしらったワイヤーフレームの地球。キャンバスは透明
10. ピクセルアートのアイコン列 — 小さなキャラクターアイコンのサンプル行（8×8 ピクセルグリッド）

このキットに含まれるファイル

hyperframes-helper/
├── SKILL.md                          ← this file
└── templates/
    ├── composition-template.html     ← scaffold: tokens, hex mesh, GSAP, watermark
    ├── storyboard-template.html      ← Level 2 storyboard, 5-scene starter
    ├── recipes.md                    ← copy-paste pattern library (10 recipes)
    ├── silence-cut.sh                ← Step 01 / Pass A: ffmpeg silence trim
    ├── transcribe-whisper.py         ← Step 01 / Pass B: faster-whisper transcript
    └── cut-retakes.py                ← Step 01 / Pass <your-project-path> last-take-rule retake removal

レベル3の地球儀モーショングラフィックには、Natural Earth の陸地ジオメトリも必要です。ダウンロードして、.js ファイル内で window.NE_LAND = ...; としてラップし、コンポジションの assets/ フォルダーに配置してください。

参考資料

• Hyperframes GitHub： https://github.com/heygen-com/hyperframes
• Hyperframes ドキュメント： https://hyperframes.heygen.com
• Studio 編集ガイド： https://hyperframes.heygen.com/guides/timeline-editing
• video-use（代替の動画エディター）： https://github.com/browser-use/video-use
• 21st.dev（HTML コンポーネントのリファレンス）： https://21st.dev
• GSAP ドキュメント： https://gsap.com/docs

---

RoboNuggets の Jay が作成しました。表示を付与すれば、CC BY 4.0 のもとで自由にご利用いただけます。