HyperFrames メディア は何をしますか?
コンポジションに必要なオーディオおよびメディアアセット(ナレーション(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 つの機能すべては、1 つのスイッチ(HeyGen の認証情報が存在するかどうか)で動作を切り替えます。認証情報は $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen から解決され、CLI からは設定しません:
| 機能 | HeyGen 認証情報あり | なし |
|---|---|---|
| TTS | HeyGen Starfish REST(ネイティブ Word タイムスタンプ) | → ElevenLabs → Kokoro(transcribe をチェーンして Word 取得) |
| 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は、リクエストファイルを使わずに HeyGen TTS だけが必要な場合の単発 CLI です(1 テキスト → wav + 単語)。
完全なフラグ一覧と audio_meta.json のスキーマは scripts/audio.mjs のヘッダーコメントにあります。以下のリファレンスでは、各機能のプロバイダ詳細とエッジケースをカバーしています。
プロバイダチェーン(エンジンの内部詳細)
TTS — 利用可能な最初のプロバイダが優先されます(エンジン、または npx hyperframes tts "..."):
| 順序 | プロバイダ | 検出条件 | Word タイムスタンプ |
|---|---|---|---|
| 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 パスは、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 |
| ベトナム語 TTS スクリプト — 句読点、音声学(TTS レイヤー) | references/tts-vi.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は非英語音声を暗黙的に翻訳します。references/transcribe.md→ 「言語ルール」を参照。- HeyGen は Word タイムスタンプを返すが、ElevenLabs / Kokoro は返さない。 エンジンは後者 2 つに対して自動的に
transcribeをチェーンします。スタンドアロンでは、HeyGen に--wordsを渡すか、オーディオファイルに対してtranscribeを実行してください。 - キャプションはフラットな Word 配列形式を消費(
{ id, text, start, end })。references/transcribe.md→ 「出力形式」を参照。 remove-background --background-outputは穴抜き、インペイントではない。 「人のいないシーン」が必要な場合は別のツールが必要です。references/remove-background.md→ 「適切なツールではない場合」を参照。- BGM/SFX はデフォルトで HeyGen 検索;認証情報なしのフォールバックは生成(BGM)または組み込みライブラリ(SFX)。
/audio/soundsはテキストクエリでランク付けされます。エフェクト名は具体的に指定してください(ガラスが割れる音、劇的な音ではなく)。一致しない場合はスキップされ、レンダリングはブロックされません。SFX は音声+BGM の下、音量約 0.35 で配置されます。references/sfx.md/references/bgm.mdを参照。