hyperframes-media

HyperFrames Media

コンポジションに必要な音声・メディアアセット（ボイスオーバー（TTS）、BGM＋効果音、文字起こし、字幕、背景の削除）を作成し、そのデータを HTML で使用してアニメーション化します。アセットをコンポジションに配置する方法については、hyperframes-core を参照してください。

オーディオエンジン — TTS・BGM・SFX に共通のソース

ワークフローごとに音声処理を独自に実装したり、ベンダーのコピーを用意したりする必要はありません。エンジンは scripts/audio.mjs の 1 つだけです。中立的な audio_request.json を受け取り、audio_meta.json（および assets/voice|bgm|sfx 配下のアセット）を書き出します。

# <MEDIA_DIR> = this skill's directory
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json

3 つの機能すべてが、1 つのスイッチ（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＋単語）。リクエストファイルなしで HeyGen TTS を使いたい場合に便利です。

フラグの一覧と 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 tts CLI は、ローカル専用ビルドであることがよくあります（--help に「Kokoro-82M」と表示され、--provider / --words はありません）。また、$HEYGEN_API_KEY が設定されていても、通知なしに Kokoro にフォールバックします。そのため、エンジンの HeyGen パスでは、CLI ではなく、自己完結型の scripts/heygen-tts.mjs（REST）を使用します。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/<slug>.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

絶対に守るルール

• エンジンは1つ、同梱コピーは禁止です。 音声の生成には 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 は、英語以外の音声を気づかないまま翻訳します。「Language Rule」については references/transcribe.md を参照してください。
• HeyGen は単語単位のタイムスタンプを返しますが、ElevenLabs／Kokoro は返しません。 後者の2つでは、エンジンが自動的に transcribe を連続実行します。単独で実行する場合は、HeyGen には --words を渡すか、音声ファイルに対して transcribe を実行してください。
• 字幕では、{ id, text, start, end } を含むフラットな単語配列形式を使用します。 「Output Shape」については references/transcribe.md を参照してください。
• remove-background --background-output は穴を切り抜く処理であり、インペイントではありません。 「人物のいないシーン」には別のツールが必要です。詳細は「When NOT the right tool」を 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 で再構築するか、そのワークフローに明示的なオーバーライド機構がある場合は、それを使用してください。