Communitygithub.com

HyperFrames メディア(starter-nextjs)

音声・メディアアセット生成スキル(TTS、BGM、効果音、文字起こし、キャプション、背景除去)。統一エンジン scripts/audio.mjs を介し、HeyGen / ElevenLabs / Kokoro のマルチプロバイダTTS、HeyGen音声ライブラリ・ローカル生成のBGM・SFX、Whisper文字起こし、背景除去、キャプション作成を提供。

HyperFrames メディア(starter-nextjs) とは?

HyperFrames Media スキルは、AIエージェント(Claude Code、Cursor、Codexなど)向けに、音声およびメディアアセットを一元管理するパイプラインを提供します。コアとなる `scripts/audio.mjs` スクリプトが、音声合成(TTS)、BGM、効果音(SFX)を単一のリクエストファイル `audio_request.json` で処理し、統一された `audio_meta.json` を出力します。TTSはHeyGen(ネイティブワードタイムスタンプ付き)→ ElevenLabs → Kokoro(ローカル)のチェーンで動作し、BGM/SFXもHeyGenライブラリ検索→ローカル生成・バンドルライブラリへと段階的にフォールバックします。また、Whisperを使った文字起こしやキャプション作成(カラオケ・字幕スタイル・単語単位のアニメーションを含む)、背景除去機能も備えています。プラットフォームに依存せず、CLI(`npx hyperframes`)とエージェントワークフローの両方で利用可能で、認証状態を確認するプリフライトが必須です。認証がない場合でもローカルエンジンで動作するため、インストール直後からすぐに使えます。

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

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

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

ドキュメント

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 認証情報あり認証情報なし
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 は厳格で、一致しなければスキップします(デタッチド生成は開始しません)。
  • 出力(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 はテキストクエリでランク付けされます。効果音は具体的に名前を付けてください(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 を介して再構築するか、そのワークフローの明示的なオーバーライドメカニズムを利用してください。

Individual skills in this repo

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

1345AbhishekKumar/starter-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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.

関連スキル