heygen-com/hyperframes

プラグインのインストール: セットアップや更新コマンドの前に、このスキルがHyperFramesプラグイン内にある場合は、プラグイン実行ルール に従ってください。スタンドアロンインストールの場合は、以下の更新手順を参照してください。

最初に、このスキルを最新の状態に保ってください — ユーザーに確認してから実行: npx hyperframes skills update talking-head-recut。すべてが最新の場合は高速なno-opで終わり、そうでなければこのスキルとそれが依存するコアドメインスキルを更新してから作業を開始します。

トーキングヘッド・リカット

Talking Head Recutは、ローカル動画をそのままフル再生し、その上にタイミングを合わせたデザイン性の高いグラフィックカード（タイトル、ローワーサード、データコールアウト、引用、サイドパネル、ピクチャー・イン・ピクチャー）を重ねます。これは話されている内容に同期します。エージェントはカードのデザイン（タイミング＋内容）を行い、各カードのHTMLを会話内で直接記述し、単一の合成HTMLをアセンブルして hyperframes 経由でMP4にレンダリングします。固定されたアーキタイプリストや所定のカード構造はなく、オーバーレイは実際の書き起こしから自然に生成されます。

フロントドアは /hyperframes です。 このスキルは、既存のトーキングヘッドクリップをデザイン性の高いグラフィックカード（タイトル、ローワーサード、データコールアウト、引用、サイドパネル、PiP）でパッケージ化します — プレーンなキャプション（話し言葉をテキストとして表示）ではありません。クリップはそのまま再生されます。 その他の意図 — プレーンな字幕、スタンドアロンのグラフィック、ゼロからの動画作成 — または不明な点があれば → まず /hyperframes を読んでください：インテントレイヤーがすべてのルートの決定を担当します。

embedded-captions のグラフィックパッケージ版（兄弟関係）。 キャプションは_話し言葉_を読みやすい字幕として追加します。これに対して、このスキルは再生中の動画の上に_デザインされたグラフィック_を追加します。プレーンな字幕 → embedded-captions。ゼロから動画を作成する場合 → 作成ワークフロー（product-launch-video / faceless-explainer / …）。

/hyperframes 経由でルーティングされた場合、インテントレイヤーは入力（どのクリップか）のみを確認し、レンダリング戦略に関する質問は先送りされた質問として通知します — アスペクト比、レイアウト、スタイルグループ、カード数はステップ7で、プローブされたフッテージと書き起こしに基づいて推奨されます。レイヤーの実行形状に関する質問は適用されません。BRIEF.md が存在する場合、確認された入力とユーザーノートが含まれています — 最初に読んでください。

調査可能な中間ファイル（作業ディレクトリ内）:

• metadata.json — 長さ / 幅 / 高さ / fps
• audio.mp3 — 抽出された音声
• transcript.json — フラットな単語配列 [{ text, start, end }, …]（Whisper; segmentsやwordsラッパーはなし）
• storyboard.json — 簡易カードアウトライン（エージェントの計画）
• public/cards/card-XX.html — カードごとのHTML断片
• public/index.html — 最終的な合成構成
• output.mp4 — レンダリングされた動画

CLI解決

# hyperframes — 文字起こし（ローカルWhisper）+ アセンブルされたHTMLのMP4へのレンダリング
npx hyperframes --help

このスキルは完全に hyperframes CLIとシステムの ffmpeg / ffprobe 上で動作します。文字起こしはローカルの Whisper を hyperframes transcribe 経由で使用します — サードパーティサービス、APIキー、レート制限のあるプロキシは不要です。

ワークフロー

1. 環境の確認

npx hyperframes doctor          # ffmpeg, ヘッドレスブラウザ, レンダリング依存関係
# バンドルされたアセットの確認:
ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"

必要条件:

• ffmpeg / ffprobe（システム）
• <SKILL_DIR>/assets/fonts/*.woff2, <SKILL_DIR>/assets/vendor/gsap.min.js（このスキルにバンドルされ、ステップ9で作業ディレクトリにステージングされます）

文字起こしにはキー不要 — hyperframes transcribe はWhisperをローカルで実行します（ステップ4）。

macOSで hyperframes render を使用する場合、強く推奨:

export PRODUCER_BROWSER_GPU_MODE=hardware

2. 作業ディレクトリの作成

すべての成果物は videos/<プロジェクト名>/ 以下に配置されます — 他の動画ワークフロー（product-launch-video / faceless-explainer / pr-to-video）と同じ規則です。カレントディレクトリはワークスペースルートに保ち、以下のすべてはこの1つのサブディレクトリ以下に書き込まれます。

VIDEO_PATH="/絶対パス/input.mp4"
WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
mkdir -p "$WORK_DIR"

3. 音声とメタデータの抽出

# メタデータ — 長さ / 幅 / 高さ / fps
ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,r_frame_rate \
  -show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json"
# 音声
ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3"

出力: metadata.json（width/height/durationを読み取る; fpsは r_frame_rate の分数を評価、例: 30000/1001 → 29.97）+ audio.mp3。

4. 文字起こし

npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en

ローカル Whisper — APIキー不要、プロキシ不要、レート制限なし。単語レベルの transcript.json を作業ディレクトリに書き込みます（単語の text + start / end タイムスタンプ）。これを読み取って、ステップ6でカードのタイミングを決めるための単語/文のタイミングを取得します; 句読点やポーズで自分で単語を文にグループ化して、セグメントレベルのチャンクが必要な場合に備えてください。

メディアの長さにクランプすること。 Whisperは最終単語の end が実際のクリップ長をわずかに超えることがあります — すべてのカードの endSec と composition.durationSeconds を metadata.json の長さにクランプしないと、レンダリング時に動画の後に黒いテールが表示されます。

5. 文字起こしの修正

transcript.json は単語オブジェクトのフラットな配列です — [{ "text": "...", "start": s, "end": s }, …]（segments 配列や words ラッパーはなし; 単語ごとのキーは text）。これを読み取り、明らかなASRエラーを修正します:

• 同音異義語、製品名、専門用語、句読点
• 単語の text をその場で編集; start / end タイムスタンプは保持
• 事前にグループ化された segments 配列はありません — カードのタイミングのためにセグメントレベルのチャンクが必要な場合は、自分で単語を文にグループ化します（終端の句読点やポーズで分割）

6. 軽量なストーリーボードの作成（チャット内）

CLIは不要。 transcript.json + metadata.json を読み取り、直接カードをデザインします。storyboard.json はエージェント内部の計画用成果物です — 消費するCLIコマンドはありません; ステップ9で作成する合成HTMLを駆動する同じアウトラインを、タイミングと内容について明確に考えるために存在します。以下の例と一貫した形状を保つことで、同じアウトラインがステップ9で作成する合成を駆動できます:

{
  "schemaVersion": 3,
  "composition": {
    "fps": 30,
    "width": 1080,
    "height": 1920,
    "durationSeconds": 121.2,
    "layout": "portrait",
    "themeId": "noir",
    "seed": 42
  },
  "videoTrack": {
    "sourcePath": "input-video.mp4",
    "startSec": 0,
    "endSec": 121.2,
    "bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
  },
  "subtitles": { "enabled": false },
  "cards": [
    {
      "id": "card-01",
      "intent": "話し手の真夜中の不安な質問でフックする",
      "startSec": 0.5,
      "endSec": 13.0,
      "accentIndex": 0,
      "zone": "fullscreen",
      "contentHints": {
        "kicker": "率直な質問",
        "title": "午後11時の魂の探求",
        "detail": "クライアントの60秒音声メッセージ: '人民元が上昇した場合、私の米ドル保険は大きな損失になるということですか？'"
      }
    }
  ]
}

必須カードフィールド:

フィールド	種類	目的
id	string	カードHTMLとGSAPセレクターで使用される安定したID
intent	string	自然言語による説明; カード合成に供給される
startSec / endSec	number	秒単位の時間（endSec > startSec）
accentIndex	0 | 1 | 2 | 3 | 4	このカードが使用する5つのテーマアクセントカラーのうちどれか
zone	列挙型（下記参照）	カードがキャンバス上のどこに配置されるか
contentHints	object	自由形式のバッグ; エージェントはここにキッカー/タイトル/詳細/データ/引用を入れます
archetype (optional)	string	自由形式のラベル; カードのパターンを覚えておくために付けることができます; 省略時は自由形式（デフォルト）
transition (optional)	列挙型: cut | fade | slide | wipe	宣言的なカード間トランジション

5つの zone 値:

zone	解決された境界	使用タイミング
fullscreen	キャンバス全体をカバー	ヒーローモーメント、大きな数字、マントラ
whiteboard-area	40pxマージン（またはポートレート高さの45%）でインセット	密集したデータ/注釈付きコンテンツ
lower-third	下部30%の帯	表示されている動画上の注釈
side-panel	右42%（ランドスケープ）または下部40%（ポートレート）	データが片側、動画が反対側
video-overlay	キャンバス全体、ほぼ透明なカードを想定	フルブリード動画上の注釈オーバーレイ

ステップ9で合成をアセンブルする際に、各カードの zone を上記の表に従ってカードホストラッパー上のピクセル境界に解決します。動画の境界は合成レベルで1回だけ設定されます（videoTrack.bounds）; 動画をカード間で「移動」させるには、合成の<script>内で#video-wrapに対するGSAPトゥイーンを作成します（ステップ9参照）。

所定のカードロールはなく、所定のナラティブアークもありません。 カードは動画が実際に語る内容から生まれます — すべて引用でもすべてデータでもよく、数字で始まることもストーリーで始まることもあります。書き起こしにリズムを決めさせてください。

テイクアウトの数は？— 長さと密度から自動推論。 固定の上限はありません。動画の長さからベースペースを選び、その後情報密度で調整します。下限のみ固定: 最低5枚のカード — 短い動画でもリズムが生まれるように。

ステップ1 — 長さによるベースペース（中程度の密度での自然な秒/カード）:

動画の長さ	ベースペース（カードあたりの秒数）	根拠
< 60秒（短いリール）	6–8秒	視聴者は短尺動画では速いカットを期待する
60秒 – 3分	8–12秒	通常のソーシャルペース
3 – 10分	12–20秒	呼吸の余地を与える; 各カードがより多くを担う
10 – 30分	20–35秒	長尺講義/インタビューのリズム
> 30分	30–60秒	エピソード的、チャプター風の感触

ステップ2 — 密度乗数（ベースペースを乗算）:

書き起こし内のシグナル	乗数	効果
高密度 — 多くの数字、明確な主張、スタッカート調のペース、リスト的な列挙、1～2文ごとに新しいアイデア	× 0.7	より速くカット、より多くのカード
中密度 — データとナラティブが混在したフロー	× 1.0	ベースペース
低密度 — 1つの拡張ストーリー、繰り返されるリフレーミング、ゆっくりとした内省的なペース、展開する単一の議論	× 1.5	より遅くカット、より少ないカード

ステップ3 — 計算:

secPerCard = basePace × densityMultiplier
cardCount  = max(5, round(videoDurationSec / secPerCard))

例（注意 — 上限なし; 長い動画は自然に多くのカードを生成します）:

• 30秒リール、単一のオチ（低密度） → 7 × 1.5 = 10.5秒/カード → round(30/10.5)=3 → 下限 5 カード
• 60秒内省的なモノローグ（低密度） → 10 × 1.5 = 15秒/カード → 4 → 下限 5 カード
• 121秒トーキングヘッド、豊富なデータ（高密度） → 10 × 0.7 = 7秒/カード → 17 カード
• 5分インタビュー、混合密度 → 16 × 1.0 = 16秒/カード → 19 カード
• 10分ディープダイブ、高密度 → 16 × 0.7 = 11秒/カード → 55 カード
• 30分講義、中密度 → 28 × 1.0 = 28秒/カード → 64 カード
• 1時間ポッドキャスト、低密度 → 45 × 1.5 = 67.5秒/カード → 53 カード

カードが約15秒以上保持される場合、よりリッチなカードを計画してください（データブロック、マルチステップの表示、段階的なアニメーションで展開するいくつかのサブポイント）— 静的なひとことを8秒以上続けると退屈になります。多くのカードが30秒を超える長尺の作品では、タイムラインをサブコンポジションにチャンク分割することを検討してください（チャプターごとに1つの.html、data-composition-srcでマウント）— ファイルごとのGSAPタイムラインを管理可能に保つためです — 詳細は timeline_track_too_dense HyperFramesリント警告を参照してください。

content はプレーンな文字列（"Title: annualized 5.69%\nNotes: ..."）またはデータをキャプチャする任意のJSON形状にできます。エージェントがカードごとに形状を決定します。

オプションのアウトロ。 このスキルには固定のブランドアウトロは付属していません。ユーザーが終了カードを希望する場合、自分でニュートラルなものをデザインしてください（ワードマーク＋1行のタグライン、約1.5-2秒、フェードイン -> 短いホールド -> フェードアウト）、それを cards[] に追加し、composition.durationSeconds を延長して、アウトロの.html断片も作成します。