HyperFrames Media
コンポジションに必要な音声およびメディアアセット（ナレーション（TTS）、BGM＋効果音、文字起こし、キャプション、背景除去）を作成し、そのデータを HTML で利用・アニメーション化します。アセットをコンポジションに配置するには hyperframes-core を参照してください。
音声エンジン — TTS・BGM・SFX の唯一のソース
ワークフローは、自前で音声処理を実装したり、別のベンダーコピーを使ったりしてはいけません。エンジンは scripts/audio.mjs ただひとつです。このエンジンは、プロバイダに依存しない audio_request.json を受け取り audio_meta.json（およびアセットを assets/voice|bgm|sfx 以下に）書き出します。
# <MEDIA_DIR> = このスキルのディレクトリ
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
3つの機能すべてが ただひとつのスイッチ に依存します — HeyGen の認証情報が存在するかどうか（$HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen から解決され、CLI 引数ではありません）。
| 機能 | HeyGen 認証情報あり | なし |
|---|---|---|
| TTS | HeyGen Starfish REST（ネイティブの単語タイムスタンプ） | → ElevenLabs → Kokoro（単語タイムスタンプには transcribe を連結） |
| BGM | HeyGen 音楽 検索 | Lyria → MusicGen ローカル 生成（非同期） |
| SFX | HeyGen 効果音 検索（min_score 0.4） | バンドルされた21ファイルのライブラリ（assets/sfx/） |
- リクエスト（
audio_request.json）:{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }。idは各行を呼び出し元のモデル（フレーム番号、シーンIDなど）に結びつけます。bgm.modeはretrieve | generate | none。省略時は自動（認証情報ありなら検索、なければ生成）。明示的なretrieveは厳格で、非同期生成を開始せずスキップします（wait-bgmステップのない呼び出し元向け）。 - 出力（
audio_meta.json、id キー）:{ tts_provider, voice_id, bgm, bgm_pending, …, voices: [{ id, path, duration_s, words }], sfx: [{ id, name, file, source, offset_s, duration_s, volume }], total_duration_s }。 --only tts,bgm,sfxでサブセットを実行し、既存の--outに マージ します（例: 最初に TTS+BGM、効果音キューができたら SFX）。- BGM 生成は 非同期 で起動されます（
bgm_pending: true）。アセンブル前にscripts/wait-bgm.mjsを実行してください。 scripts/heygen-tts.mjsは、同一のコードを使用した単発の CLI です（1テキスト → wav + 単語）。リクエストファイルが不要な場合に使用します。
完全なフラグ一覧と audio_meta.json スキーマは scripts/audio.mjs のヘッダーコメントにあります。以下の参照は、各機能のプロバイダ詳細とエッジケースを説明します。
事前チェック — 音声生成前にログイン状態を表示
音声や BGM を生成する前には必ずこれを実行してください — 完全なワークフロー内でも、「BGM/ナレーションを生成して」という単発のリクエストでも同様です。 HeyGen の認証情報がないからといって、黙ってローカルエンジンにフォールバックしてはいけません。まずはログインを推奨し、ユーザーに判断を委ねます。共有の事前チェックを実行し、その出力をそのまま中継してください — 独自の「キーがありません」というプロンプトを作ったり、リポジトリごとの .env にキーを書き込んだりしないでください。
npx hyperframes auth status
- ログイン済み → アカウント情報が表示されます。処理を進めてください。
- 未ログイン（ここで
exit 1が返ることが期待されます — 「未ログイン」はエラーではなく正常な状態です）→ 登録を促すガイダンスが表示されます。ログインを推奨してください:npx hyperframes auth loginはブラウザ OAuth です — ログインとアカウント作成を同時に行います（このリポジトリの CLI から常に利用可能です）。既存の HeyGen API キー（app.heygen.com/settings/api から取得）を使用するには、npx hyperframes auth login --api-keyを実行します。これにより共有の~/.heygenに保存されます（リポジトリごとの.envは不要）。出力には、ローカルエンジンの音声/BGM のフォールバック先と、依存関係が不足している場合のpipヒントも含まれます。この出力をそのまま中継してください — 自分の言葉で言い換えないでください。 その後、ユーザーが選択するまで待機して停止してください — ログインするか、「go」/「local」と言ってオフラインで続行するかを選びます — 何かを生成する前に。これは単なる通過点ではありません。実際の判断ポイントです。他の質問に折りたたんだり、自分で勝手に先に進んだりしないでください。（例外: 自律的 / 非対話モードでは、ステータスを確認しオフラインで続行します。） npx hyperframes auth status --jsonは{ configured, recommended_action, offline_engines }を返します。決定論的な分岐に使用できます。- CLI が実行できない場合（PATH にない、
npxが取得できない）→ それでも ログインを推奨 し（npx hyperframes auth login）、ユーザーの選択を待って停止してください — 「認証情報がない」ことをローカル生成の黙認として扱わないでください。
認証情報の解決、完全なキーの優先順位、ローカル依存関係のリストは references/requirements.md にあります。
プロバイダチェーン（エンジンの詳細）
TTS — 利用可能な最初のプロバイダが使用されます（エンジン経由、または npx hyperframes tts "..."）。
| 順序 | プロバイダ | 検出条件 | 単語タイムスタンプ |
|---|---|---|---|
| 1 | HeyGen（Starfish） | $HEYGEN_API_KEY / hyperframes auth login | はい、ネイティブ — --words narration.words.json を渡して取得 |
| 2 | ElevenLabs | $ELEVENLABS_API_KEY が設定されている場合 | いいえ — 後で transcribe を連結 |
| 3 | Kokoro-82M（ローカル、54音声） | 常に（キー不要） | いいえ — 後で transcribe を連結 |
公開されている
hyperframes ttsCLI はローカル専用ビルドであることが多いです（--helpには「Kokoro-82M」と表示され、--provider/--wordsはありません）。そのため、$HEYGEN_API_KEYが設定されていても、黙って Kokoro にフォールバックします。エンジンの HeyGen パスが自己完結型のscripts/heygen-tts.mjs（REST）であり、CLI ではない理由はここにあります。CLI は Kokoro パスでのみ使用されます。詳細はreferences/tts.mdを参照してください。
BGM & SFX — デフォルトでは HeyGen 音声ライブラリ（/v3/audio/sounds）から 検索 されます。認証情報は HeyGen TTS と同じものを使用し、認証情報がない場合のフォールバックは上記のスイッチに従います。
| アセット | HeyGen の type | 保存先 | フォールバック（認証情報なし） |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3（検索） · track.wav（生成） | Lyria / MusicGen 生成 |
| SFX | sound_effects（min_score 0.4） | assets/sfx/<スラッグ>.mp3 | バンドルされた21ファイルのライブラリ（assets/sfx/* + manifest.json） |
references/bgm.md と references/sfx.md を参照してください。
ルーティング
| タスク | 参照先 |
|---|---|
音声エンジン — リクエスト/メタスキーマ、--only、スイッチ | scripts/audio.mjs（ヘッダーコメント） |
npx hyperframes tts / heygen-tts.mjs — プロバイダ、音声、単語 | references/tts.md |
| BGM — HeyGen 検索 + ローカル Lyria / MusicGen 生成 | references/bgm.md |
| SFX — HeyGen 検索（min_score 0.4）+ バンドルローカルライブラリ | references/sfx.md |
npx hyperframes transcribe — Whisper、モデルルール、出力形式 | references/transcribe.md |
npx hyperframes remove-background — 透明な切り抜き | references/remove-background.md |
| TTS → 文字起こし → キャプション（録音ナレーションなし） | references/tts-to-captions.md |
| キャプション作成 — スタイル検出、レイアウト、単語グループ化、終了処理 | references/captions/authoring.md |
| トランスクリプト処理 — 入力形式、品質ゲート、クリーンアップ、API | references/captions/transcript-handling.md |
| キャプションモーション — カラオケ、マーカー効果、音声反応 | references/captions/motion.md |
| モデルキャッシュ、システム依存関係、トラブルシューティング | references/requirements.md |
厳守ルール
- 単一エンジン、ベンダーコピー禁止。 音声は
scripts/audio.mjs（または単発 HeyGen TTS 用のheygen-tts.mjs）を介して生成します。ワークフロー内で TTS/BGM/SFX を再実装しないでください —audio_request.jsonアダプターを作成し、エンジンを呼び出してください。 - 「HeyGen 利用可能」= 解決可能な認証情報であり、CLI ではない。 すべてのスイッチは
heygenCredential()に依存します。公開されているhyperframes ttsは Kokoro 専用である可能性があり、hyperframes bgm/hyperframes sfxコマンドはそもそも存在しません。 - 音声 ID はプロバイダ固有。
am_michaelは Kokoro 専用です。HeyGen の UUID は Kokoro では動作しません。--voiceを渡す場合は、--providerも固定して、ユーザーの環境変更によるプロバイダの暗黙の切り替わりを防いでください。 transcribeには常に--modelを渡す。 CLI のデフォルトsmall.enは非英語の音声を黙って翻訳します。references/transcribe.md→ 「言語ルール」を参照してください。- HeyGen は単語タイムスタンプを返します。ElevenLabs / Kokoro は返しません。 エンジンは後者の2つに対して自動的に
transcribeを連結します。スタンドアロンでは、--wordsを HeyGen に渡すか、音声ファイルに対してtranscribeを実行してください。 - キャプションはフラットな単語配列形式
{ id, text, start, end }を消費します。references/transcribe.md→ 「出力形式」を参照してください。 remove-background --background-outputは穴を開ける処理であり、インペイントではありません。 「人物のいないシーン」が必要な場合は、別のツールが必要です。references/remove-background.md→ 「適切でない場合」を参照してください。- BGM/SFX のデフォルトは HeyGen 検索。認証情報なしのフォールバックは生成（BGM）またはバンドルライブラリ（SFX）。
/audio/soundsはテキストクエリでランク付けされます — 効果音は具体的に命名してください（dramatic soundではなくglass shatter）。一致しない場合はスキップされ、レンダリングをブロックすることはありません。SFX は音声 + BGM の下で音量約0.35になります。references/sfx.md/references/bgm.mdを参照してください。 - ワークフローのキャプション HTML は生成された出力として扱います。 プリセットベースの動画の場合、再利用可能なスキンソースは
.hyperframes/caption-skin.htmlにあり、ワークフロースクリプトはcompositions/captions.htmlを書き込みます。生成されたcompositions/captions.htmlを編集してスキンを修正しないでください。ワークフローのcaptions.mjs経由で再構築するか、そのワークフローの明示的なオーバーライドメカニズム（存在する場合）を使用してください。