Communitygithub.com

HyperFrames メディア

コンポジションのオーディオ/メディアアセット(TTS音声、BGM、効果音、文字起こし、キャプション、背景除去)を作成し、HTMLで利用・アニメーション化するためのスキル。

HyperFrames メディア とは?

このスキルは、HyperFrames コンポジションで使用するオーディオおよびメディアアセットの生成を一元管理します。中心となる `scripts/audio.mjs` エンジンが、TTS、BGM、効果音の3つの機能を統合し、HeyGen APIキーの有無に応じてプロバイダーを自動的に切り替えます(例:HeyGen → ElevenLabs → Kokoro のフォールバックチェーン)。さらに、Whisper による文字起こし、背景除去、キャプション作成(カラオケスタイル/単語単位のスタイリング対応)を備え、すべての機能が一貫したJSONリクエスト/メタファイルで管理されます。対応プラットフォームは主に Claude Code、Cursor、Codex などのAIエージェント環境で、`npx hyperframes` CLI と連携して動作します。このスキルは、オーディオの手作業やベンダー固有の実装を排除し、単一のエンジンと統一されたデータ形式でワークフローを簡素化することを目的としています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-supabase/tree/HEAD/.agents/skills/hyperframes-media

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

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

ドキュメント

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 認証情報あり認証情報なし
TTSHeyGen Starfish REST (ネイティブ単語タイムスタンプ)→ ElevenLabs → Kokoro(単語取得には transcribe をチェーン)
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 は同一コードの単発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 "..."):

順序プロバイダー検出条件単語タイムスタンプ
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 パスは自己完結型の scripts/heygen-tts.mjs(REST)であり、CLI では ありません。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
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

絶対的なルール

  • 単一エンジン、ベンダーコピー禁止。 オーディオは 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 を介して再構築するか、そのワークフローの明示的なオーバーライドメカニズム(存在する場合)を使用してください。

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

1345AbhishekKumar/starter-supabase

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

1345AbhishekKumar/starter-supabase

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

1345AbhishekKumar/starter-supabase

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

1345AbhishekKumar/starter-supabase

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

1345AbhishekKumar/starter-supabase

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

1345AbhishekKumar/starter-supabase

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

1345AbhishekKumar/starter-supabase

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1345AbhishekKumar/starter-supabase

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

1345AbhishekKumar/starter-supabase

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

1345AbhishekKumar/starter-supabase

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

1345AbhishekKumar/starter-supabase

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

1345AbhishekKumar/starter-supabase

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

1345AbhishekKumar/starter-supabase

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

関連スキル