Communitygithub.com

HyperFrames メディア

コンポジション向けの音声・メディアアセットを作成します。TTS(HeyGen / ElevenLabs / Kokoro)、BGM、効果音、文字起こし、キャプション、背景除去などを統合オーディオエンジンで管理。

HyperFrames メディア とは?

このスキルは、HyperFrames コンポジションで使用するオーディオおよびメディアアセットを生成・管理するための統合エンジンです。中心となる `scripts/audio.mjs` は、TTS(HeyGen / ElevenLabs / Kokoro のマルチプロバイダ)、BGM(HeyGen ライブラリ検索またはローカル生成)、効果音(HeyGen 検索または組み込みライブラリ)、Whisper による文字起こし・Word タイムスタンプ取得、背景除去、キャプション・歌詞・カラオケスタイル編集など、すべてのオーディオ機能を単一のリクエストファイルで扱います。認証情報の有無に応じてプロバイダチェーンが自動選択され、デフォルトでは HeyGen が優先され、認証情報がない場合はローカルモデルや組み込みアセットにフォールバックします。このスキルは Claude Code や Cursor などの AI エージェント環境で使用され、開発者は `audio_request.json` を用意してエンジンを実行するだけで、高度なオーディオパイプラインを構築できます。各モジュールの詳細やエッジケースは `references/` 配下のドキュメントを参照してください。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/whyiloveher2411/_biong_backend_FE/tree/HEAD/agent/skills/hyperframes-media

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 認証情報ありなし
TTSHeyGen Starfish REST(ネイティブ Word タイムスタンプ)→ ElevenLabs → Kokoro(transcribe をチェーンして Word 取得)
BGMHeyGen 音楽検索Lyria → MusicGen ローカル生成(デタッチ)
SFXHeyGen 効果音検索(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 タイムスタンプ
1HeyGen(Starfish)$HEYGEN_API_KEY / hyperframes auth loginはい、ネイティブ — --words narration.words.json で取得
2ElevenLabs$ELEVENLABS_API_KEY が設定されているなし — 後で transcribe をチェーン
3Kokoro-82M(ローカル、54 音声)常に利用可能(キー不要)なし — 後で transcribe をチェーン

公開されている hyperframes tts CLI はローカルのみのビルドであることが多く(--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出力先フォールバック(認証情報なし)
BGMmusicassets/bgm/track.mp3(検索)· track.wav(生成)Lyria / MusicGen 生成
SFXsound_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
トランスクリプト処理 — 入力形式、品質ゲート、クリーンアップ、APIreferences/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 を参照。

関連スキル