HyperFrames Media
コンポジションに必要なオーディオおよびメディアアセット(ナレーション(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認証情報がないことは、サイレントにローカルエンジンにフォールバックする理由にはなりません。まずサインインを推奨し、ユーザーに判断を委ねてください。共有の事前チェックを実行し、その出力をそのまま中継してください。独自の「キーが見つかりません」プロンプトをでっち上げたり、リポジトリごとの .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ヒントも含まれます。この出力をそのまま中継し、独自の言葉で言い換えないでください。 その後、STOPしてユーザーが選択するのを待ちます(サインインするか、「go」/「local」と言ってオフラインで続行するか)。何かを生成する前にこの判断を待ちます。これは通過的な注意事項ではなく、実際の意思決定ポイントです。他の質問に折りたたんだり、自分で先に進んだりしないでください。(例外:自律型/非対話モードでは、ステータスを記録してオフラインで続行します。) npx hyperframes auth status --jsonは{ configured, recommended_action, offline_engines }を返し、決定論的な分岐を可能にします。- CLIが実行できない場合(PATHにない、
npxが取得できない)→ それでもサインインを推奨し(npx hyperframes auth login)、ユーザーの選択のためにSTOPしてください。「認証情報なし」をローカル生成の暗黙の許可として扱わないでください。
認証情報の解決、完全なキーの優先順位、およびローカル依存関係リストについては、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を渡してください。 デフォルトの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はテキストクエリでランク付けされます。効果音は具体的に指定してください(glass shatterなど、dramatic soundではありません)。該当なしの場合はスキップし、レンダリングをブロックしません。SFXは音声+BGMの下、音量約0.35に配置されます。references/sfx.md/references/bgm.mdを参照してください。 - ワークフローのキャプションHTMLは生成された出力として扱ってください。 プリセットベースの動画の場合、再利用可能なスキンソースは
.hyperframes/caption-skin.htmlにあり、ワークフロースクリプトはcompositions/captions.htmlを書き込みます。スキンを修正するために生成されたcompositions/captions.htmlを編集しないでください。ワークフローのcaptions.mjsを介して再構築するか、存在する場合はそのワークフローの明示的なオーバーライドメカニズムを使用してください。