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> = このスキルのディレクトリ
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(文字起こしをチェーンして単語を取得) |
| 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 認証情報がないことは、ローカルエンジンに黙ってフォールバックする理由にはなりません。まずサインインを推奨し、ユーザーに判断させてください。共有の事前チェックを実行し、その出力をそのまま中継してください — 独自の「キーがない」プロンプトを工夫したり、リポジトリごとの .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/<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は非英語音声を静かに翻訳します。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を介して再構築するか、ワークフローの明示的なオーバーライドメカニズムが存在する場合はそれを使用してください。