media-use

media-use

メディアのニーズを、変更されないローカルファイルに解決します。動詞は1つ、種類は4つ、コンテキストのノイズはゼロです。

使用するタイミング

コンポジションにメディア（BGM、効果音、画像、アイコン）が必要なときは、resolve を呼び出します。media-use は HeyGen カタログを検索し、最適な候補をダウンロードしてローカルに固定し、マニフェストに登録します。エージェントに返されるのは1行だけで、検索結果のノイズはすべてディスクに残ります。

Resolve

node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>

次の1行を返します：resolved <id> → <path> (<type>, <metadata>)

種類

種類	検索対象	プロバイダー
bgm	BGM	HeyGen オーディオカタログ（10k+ トラック）
sfx	効果音	同梱の19ファイルライブラリ + HeyGen カタログ
image	写真、背景	HeyGen アセット検索（75k+ ベクター）
icon	アイコン、ロゴ	HeyGen アセット検索（type=icon）

例

# Background music
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)

# Sound effect
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)

# Image
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)

# Icon
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)

フラグ

フラグ	説明
--type, -t	メディアの種類：bgm、sfx、image、icon
--intent, -i	必要なもの（自然言語）
--entity, -e	キャッシュ照合用のエンティティ名（任意）
--project, -p	プロジェクトディレクトリ（デフォルト：.）
--adopt	既存の assets/ を一括インポートしてマニフェストに登録
--json	1行の結果の代わりに JSON を出力

仕組み

1. プロジェクトの .media/manifest.jsonl でプロンプトが完全一致するものを確認します
2. 既存の assets/ ディレクトリをスキャンし、必要なものに一致する未登録ファイルを探します
3. グローバルキャッシュ ~/.media/ で再利用可能なアセットを確認します
4. プロバイダー経由で検索します（HeyGen オーディオカタログ、HeyGen アセット検索）
5. ファイルを .media/<type>/ に固定し、マニフェストに登録して、index.md を再生成します

エージェントに返されるのは1行だけです。候補、スコア、出所情報はディスクに残ります。

既存プロジェクトを取り込む

ほとんどの HyperFrames プロジェクトには、すでに assets/ にアセットがあります。media-use はそれらを取り込みます：

node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
# → adopted 9 assets from assets/
#   bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
#   image_001 → assets/images/avatar.jpg (image, 400×400)

ffprobe が実際の再生時間と寸法を抽出します。resolve の実行時に、assets/ 内で意図に一致する未登録ファイルがあれば、その場で取り込みます。

インベントリを読む

resolve または adopt の実行後、完全なインベントリを確認するには .media/index.md を読みます：

# .media · 4 assets

id         type   dur   dims       path                          description
bgm_001    bgm    25s   —          .media/audio/bgm/bgm_001.mp3  upbeat tech launch
sfx_001    sfx    0.6s  —          .media/audio/sfx/sfx_001.mp3  whoosh
image_001  image  —     1920×1080  .media/images/image_001.jpg   gradient tech background
icon_001   icon   —     200×200    .media/images/icon_001.png    rocket

プロジェクト間での再利用

resolve の実行時にアセットは自動的にキャッシュされます。同じプロンプトで次回 resolve を実行すると、~/.media/ のグローバルキャッシュが使われるため、再ダウンロードもプロバイダーの呼び出しもありません。すべてのプロジェクトで再利用できるようにするには、organize --promote <id> でアセットを明示的に昇格します。

ファイル

• .media/manifest.jsonl — マシン向けの SSOT。1行につき1件の JSON レコード
• .media/index.md — エージェントが読める表（id、type、dur、dims、path、description）
• ~/.media/ — プロジェクト間で再利用するグローバルキャッシュ（コンテンツアドレス方式、SHA-256）

使用する CLI ツール

ツール	用途	必須？
ffprobe	取り込み時に再生時間、寸法、コーデックを確認	はい
heygen	オーディオカタログ、アセット検索	プロバイダー用

heygen CLI（ランタイム不要の単一静的バイナリ）をインストールし、認証します：

curl -fsSL https://static.heygen.ai/cli/install.sh | bash   # installs latest to ~/.local/bin
heygen update                                               # if already installed: needs >= v0.1.6
export HEYGEN_API_KEY=<your-key>                            # or: heygen auth login --key <key>

heygen >= v0.1.6 が必要です。プロバイダーは、v0.1.6 で追加された許可リスト対象の --headers 'X-HeyGen-Client-Source: media-use' フラグを使ってリクエストにタグを付けます。asset search はリリース前のコマンドで、heygen --help には表示されませんが、実行できます。PATH 上に heygen がない場合（または有効なキーがない場合）、プロバイダーは stderr に1行の診断メッセージを出力し、resolve は「解決できるプロバイダーがありません」にフォールバックします。