HyperFrames Media
コンポジションに必要な音声・メディアアセット(ナレーション(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(ネイティブワードタイムスタンプ) | → 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は厳格で、一致しなければスキップします(デタッチド生成は開始しません)。 - 出力(
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 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 |
絶対に守るべきルール
- 単一エンジン、コピー禁止。
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を介して再構築するか、そのワークフローの明示的なオーバーライドメカニズムを利用してください。