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 + 単語)。リクエストファイルなしで 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はテキストクエリでランク付けされます — 効果音は具体的に名前を付けてください(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を介して再構築するか、そのワークフローの明示的なオーバーライドメカニズム(存在する場合)を使用してください。