media-use

プラグインのインストール： セットアップや最新状態の確認コマンドを実行する前に、このスキルが HyperFrames プラグイン内にある場合は、プラグイン実行ルールに従ってください。単独でインストールしている場合は、以下の更新手順に従ってください。

media-use

HyperFrames のメディア OS です。解決・生成・操作・記憶を、あらゆるメディア形式で、1 つのスキルにまとめ、コンテキストのノイズをゼロにします。

環境に HEYGEN_API_BASE が設定されている場合に限ります（ホストアプリが設定し、独自のキーで HeyGen の料金を負担しています）。HeyGen のメディアはすでに支払い済みです。heygen CLI のインストールやサインインを依頼したり、OAuth の利用枠を案内したりしないでください。ここでのカタログ検索、TTS、アバターの呼び出しはホスト経由で行われます。同じホストから独自の HeyGen ツールも提供されている場合は、まずそれを使ってください。ホスト経由の呼び出しが拒否された場合は、ホストのメッセージをそのまま伝えてください（アプリの設定でキーを追加または置き換えるなど、修正方法が示されています）。その後は停止し、依頼されない限り別のプロバイダーに切り替えないでください。

それ以外の場合（HEYGEN_API_BASE が設定されていない）の初回実行で HeyGen メディア（カタログ検索、TTS、アバタービデオ）を使うときは、heygen CLI をインストールしてサインインしてください（無料利用の方法）。その後、npx hyperframes media-use resolve --doctor で確認します。セットアップとプロバイダーについては、references/setup-providers.md を参照してください。

ホストアプリ内で音楽や効果音を扱う場合、実行環境のアプリが独自の音楽ツールまたは効果音ツールを提供していれば、それを使ってください。HEYGEN_API_BASE が設定されていない場合、resolve --type bgm は heygen CLI 経由で HeyGen カタログを検索し、CLI がなければその旨を示して失敗します。resolve --type sfx は Openverse（CC0 と CC BY のみ、アカウント不要）を検索し、オフライン時は同梱ライブラリにフォールバックします。CC BY の効果音は、audio/references/sfx.md の指示に従ってクレジットを表記してください。

HEYGEN_API_BASE が設定されていない場合、ナレーション音声またはアバタービデオを生成する前に、次のことを伝えてください。OAuth で heygen CLI にサインインする（heygen auth login --oauth）と、TTS ナレーションとアバタービデオに無料利用枠が適用されます。一方、API キーを使うと API クレジットが課金されます。

解決 — 唯一の動詞

npx hyperframes media-use resolve --type <type> --intent "<description>" --project <dir>

1 行で返します：resolved <id> → <path> (<type>, <metadata>)。検索時のノイズはすべてディスク上に保存されます。

種類	1 行での用途
bgm	BGM（heygen CLI 経由の HeyGen カタログ、1 万曲以上）
sfx	効果音（Openverse CC0／CC BY、オフライン時は 21 ファイルの同梱ライブラリ）
image	写真、背景（HeyGen アセット検索、7 万 5 千点以上のベクター）
icon	アイコン、シンボル（透明）
logo	公式ブランドマーク（theSVG → GitHub アバター → ファビコン。描き直し禁止）
voice	TTS ナレーション（HeyGen 無料利用の方法、Kokoro のローカル利用は任意）
grade	測定に基づく補正候補。幅広い仕上げやスタイリングは Media Treatments に従います
lut	ユーザー提供または明示的に選択された、再利用可能で検証済みの .cube ファイル

新規に解決する前に、--candidates で再利用可能な候補を一覧表示し、自分で適合性を判断してください。再利用のルール、すべてのフラグ、取り込み（--from）、採用については references/resolve.md を参照してください。

広範なビジュアルフィードバックをメディア処理の意図として扱う

ユーザーが写真メディアの修正、ブラッシュアップ、スタイリング、ぼかし、強調、表示を明示的に依頼した場合、カラーグレーディングやエフェクトに言及していなくても、references/media-treatments.md を確認してください。実際の <img>／<video> を確認し、主要な意図を1つ選んでから、決定論的な永続化と検証を行います。一致するレシピがあれば、テスト済みの初期設定として任意で使用するか、hyperframes media-treatment --capabilities --json を確認したうえで、--capability <id> を使って関連するファミリー／エフェクトを1つ指定し、正規のコントロールからカスタム処理を組み立てます。通常の作成では、--all を読み込まないでください。処理には、補正、プリセット、仕上げ、互換性のあるシェーダーエフェクト、サポート対象のキーフレーム、任意の Registry オーバーレイを組み合わせられます。ソースに根拠のある範囲内の調整と互換性のある要素だけを追加し、見栄えを単に洗練させるためだけにエフェクトを追加しないでください。最終的な結合済みペイロードは hyperframes media-treatment で永続化します。

段階的にエスカレーションするワークフローを1つ使います。動画では、フレームを個別に確認するのではなく、ラベル付きの冒頭／中間／終盤のコンタクトシートを1つ確認してください。通常の補正やブラッシュアップでは、候補を1つ適用し、処理後のシートを1つ確認します。結果が曖昧な場合、時間的な変化がある場合、スタイライズされている場合、LUTベースの場合、HDR／LOG に敏感な場合、非公開の場合、またはブランド上重要な場合に限り、個別フレームや動きのあるドラフトでの確認にエスカレーションします。

通常の補正やブラッシュアップでは、最終処理のプリセット／調整 JSON を永続化します。 露出、シャドウ、コントラスト、暖かみを表現するだけのために .cube LUT を生成しないでください。LUT を使用するのは、ユーザーが提供した場合、または選択した処理が明示的にLUTを使用する場合に限ります。resolve --type grade --for ... --analyze は測定の根拠であり、選択した処理を生成したLUTに置き換える許可ではありません。サポート対象のビネット、粒状感、ぼかし、ピクセル化、カラー、処理エフェクトを CSS／SVG オーバーレイで再現しないでください。これは Studio のコントロールと正規のプレビュー／レンダー用シェーダーパスを迂回します。

積極的に提案する — メディアの改善機会を確認する

どのメディアを加えれば作品がよくなるか、人間にはたいてい判断できません。あなたには判断できます。コンポジションを作成またはレビューするときは、根拠のある確認を1回行い、その後1回だけ提案してください。黙って追加したり、アセットごとに何度も促したりしないでください。

具体的な兆候がある場合に限り、改善機会を提示してください。

検出した兆候	提案
画面上のテキスト、またはナレーションのない台本	TTS ナレーション（オーディオエンジン）
絵文字、またはアイコンとしてスタイル設定された<div>	本物のiconを解決する
プレースホルダー、小さすぎる、または拡大されたように見える画像	より適切なimage（および／またはアップスケール — references/operations.mdを参照）
音声のない急なシーンカット／トランジション	トランジション用のsfx
BGM のない約10秒を超える作品	bgm
露出不足／過多、または色かぶりに見える映像	補正グレーディング（hyperframes media-treatment --selector '#hero' --analyze --jsonで確認します）
写真メディアに視覚的な平坦さがあり、話題にも合っていない	ソースに適した具体的なプリセット、またはカスタム処理を1つ提示し、意図する対象を明示する
意味のあるメディアの登場／見せ場が静的に感じられる	シーク時の安全性が確認された対応アニメーションを1つ提示する。依頼でプリセットも正当化されない限り、色は維持する

提案が役立つものであり、しつこくならないようにするためのルール：根拠を示し、一般論にしない（兆候がなければ提案しない）；明確な見解を持ち、具体的にする（初期設定を選んだ具体的な修正案を提示し、人間がすべて／一部／なしを承認する）；プロジェクトごとに1回（まとめて1回だけ尋ね、「そのままにする」という意向を尊重する）；提示するだけで、黙って変更しない（特にカラーグレーディングは提案してプレビューする。グレーワールド補正は、意図的な夕焼けやネオンのルックを台無しにします）。

確認箇所 — タスクに必要なファイルだけを読む

タスク	読むファイル
解決／再利用／採用／取り込み、フラグ、カスケード、インベントリー	references/resolve.md
カラーグレーディング、LUT、スマートグレード（--for）、グレード比較	references/grading.md
ナレーション／TTS、音楽、SFX、字幕、文字起こし（オーディオエンジン）	references/audio.md
既存メディアのカット／リフレーム／変換、正確な誤差拡散、HEVC	references/operations.md
ソースを考慮したクリエイティブ処理、リアルタイムエフェクト、オーバーレイ、見せ場	references/media-treatments.md
インストールと認証、プロバイダーテーブル、RAM 要件の目安、--local-only、--provider	references/setup-providers.md
記憶された設定と固定レシピ（ユーザーメモリ）	references/memory.md
所有権マトリックス、使用統計、テレメトリー、プライバシー（メンテナー向け）	references/meta.md