Communitygithub.com

メディア

HyperFrames コンポジションのためのオーディオおよびメディアアセット。統一された音声エンジン(scripts/audio.mjs)により、TTS(HeyGen / ElevenLabs / Kokoro ローカル)、BGM + 効果音(HeyGen 音声ライブラリ取得、ローカル Lyria / MusicGen による BGM 生成、認証情報不要のフォールバックとして同梱の SFX ライブラリ)、Whisper 文字起こし、背景除去、キャプション作成を提供します。

メディア とは?

HyperFrames Media スキルは、HyperFrames コンポジションに必要なすべてのオーディオ・メディアアセットを統一的に生成・管理するためのエンジンです。このスキルの中核は `scripts/audio.mjs` であり、単一の `audio_request.json` を受け取り、TTS(テキスト読み上げ)、BGM(背景音楽)、SFX(効果音)を生成し、`audio_meta.json` として出力します。複数の TTS プロバイダ(HeyGen、ElevenLabs、Kokoro ローカル)をサポートし、認証情報の有無に応じて動作を切り替える「プロバイダチェーン」を採用しています。また、Whisper による文字起こし、背景除去、キャプション(歌詞・カラオケ・ワード単位のスタイリング)作成機能も備えています。開発者はこのエンジンを介してのみ音声を生成するよう強制され、ワークフロー内で個別に音声生成を独自実装することは禁止されています(ベンダコピーの禁止)。認証情報がない場合でも、ローカルの Kokoro TTS、Lyria/MusicGen BGM 生成、同梱の SFX ライブラリがフォールバックとして動作するため、常に動作可能です。特に TTS における単語レベルのタイムスタンプは、HeyGen ではネイティブ取得可能、それ以外のプロバイダでは自動的に `transcribe` をチェーンすることで補完されます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/9018/mychat/tree/HEAD/OpenMontage/.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 + words)。リクエストファイルなしで HeyGen TTS だけが必要な場合に使用します。

完全なフラグ一覧と audio_meta.json のスキーマは scripts/audio.mjs のヘッダコメントにあります。以下のリファレンスでは、各機能のプロバイダ詳細とエッジケースをカバーしています。

事前チェック — 音声生成前にサインイン状態を確認

音声や BGM を生成する前には、必ずこれを実行してください。 完全なワークフロー内であっても、「BGM/ナレーションを生成して」という単発リクエストであっても同様です。HeyGen 認証情報がないことは、ローカルエンジンに静かにフォールバックする理由にはなりません。まずサインインを推奨し、ユーザーに判断を委ねてください。共有の事前チェックを実行し、その出力をそのまま中継してください。独自の「キーがありません」というプロンプトを作ったり、per-repo の .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 に保存されます(per-repo の .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 パスは 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 20 individual skills — each has its own dedicated page.

9018/mychat

Generate AI videos from text prompts using multiple provider gateways. Use when: (1) Generating videos from text descriptions, (2) Creating AI-generated video clips for content production, (3) Image-to-video generation with a reference image, (4) Choosing between video generation providers (VEO, Kling, Sora, Runway, Seedance, MiniMax, Gemini Omni). Supports gateways: HeyGen API, fal.ai API, Kling official direct API, and the Gemini API (Gemini Omni Flash).

9018/mychat

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

9018/mychat

Use p5.js/canvas for local procedural character effects: particles, weather, squash/stretch, walk cycles, and environmental motion.

9018/mychat

Review local character animation with schema checks, Playwright browser previews, frame sampling, and FFmpeg/ffprobe final output checks.

9018/mychat

Create videos from a text prompt using HeyGen's Video Agent. Use when: (1) Creating a video from a description or idea, (2) Generating explainer, demo, or marketing videos from a prompt, (3) Making a video without specifying exact avatars, voices, or scenes, (4) Quick video prototyping or drafts, (5) One-shot prompt-to-video generation, (6) User says "make me a video" or "create a video about X".

9018/mychat

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

9018/mychat

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

9018/mychat

Use when implementing Disney's 12 animation principles with Framer Motion in React applications

9018/mychat

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.

9018/mychat

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`).

9018/mychat

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.

9018/mychat

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`.

9018/mychat

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).

9018/mychat

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.

9018/mychat

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.

9018/mychat

Toolkit-specific Remotion patterns — custom transitions, shared components, and project conventions. For core Remotion framework knowledge (hooks, animations, rendering, etc.), see the `remotion-official` skill.

9018/mychat

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.

9018/mychat

Animate SVG character rigs with GSAP, CSS transforms, Remotion frame control, and HyperFrames-compatible browser previews.

9018/mychat

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

9018/mychat

Download video and audio from YouTube and 1000+ sites using yt-dlp. No API keys needed. Use when: (1) Downloading a video from YouTube or other sites, (2) Extracting audio from a video URL, (3) Downloading subtitles/captions from a video, (4) Getting video metadata without downloading.

関連スキル