HyperFrames メディア
コンポジションに必要なオーディオおよびメディアアセット(ナレーション(TTS)、背景音楽 + 効果音、文字起こし、キャプション、背景除去)を作成し、そのデータを 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 つの機能はすべて 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 + words)。リクエストファイルなしで HeyGen TTS だけが必要な場合に使用します。
完全なフラグ一覧と audio_meta.json のスキーマは scripts/audio.mjs のヘッダコメントにあります。以下のリファレンスでは、各機能のプロバイダ詳細とエッジケースをカバーしています。
事前チェック — 音声生成前にサインイン状態を確認
音声や BGM を生成する前には、必ずこれを実行してください。 完全なワークフロー内であっても、「BGM/ナレーションを生成して」という単発リクエストであっても同様です。HeyGen 認証情報がないことは、ローカルエンジンに静かにフォールバックする理由にはなりません。まずサインインを推奨し、ユーザーに判断を委ねてください。共有の事前チェックを実行し、その出力をそのまま中継してください。独自の「キーがありません」というプロンプトを作ったり、per-repo の .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に保存されます(per-repo の.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 パスは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/<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 |
非交渉ルール
- 単一エンジン、ベンダコピー禁止。
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をチェーンします。単独で使用する場合、HeyGen には--wordsを渡すか、オーディオファイルに対して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経由で再構築するか、存在する場合はそのワークフローの明示的なオーバーライド機構を使用してください。