media-use
メディア需要を凍結したローカルファイルに解決します。一つの動詞、四つのタイプ、コンテキストノイズゼロ。
使用タイミング
コンポジションがBGM、効果音、画像、アイコンなどのメディアを必要とするときはいつでも resolve を呼び出します。media-use は HeyGen カタログを検索し、最適な結果をダウンロード、ローカルに凍結し、マニフェストに登録します。エージェントは一行の結果を受け取るだけです。すべての検索ノイズはディスク上に残ります。
Resolve
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
一行を返します: resolved <id> → <path> (<type>, <metadata>)
タイプ
| タイプ | 見つけるもの | プロバイダー |
|---|---|---|
bgm | 背景音楽 | HeyGen オーディオカタログ (1万以上) |
sfx | 効果音 | バンドルされた19ファイルライブラリ + HeyGen カタログ |
image | 写真、背景 | HeyGen アセット検索 (7万5千以上のベクター) |
icon | アイコン、ロゴ | HeyGen アセット検索 (type=icon) |
使用例
# 背景音楽
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "明るいテック系ローンチ" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
# 効果音
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "ひゅーっ" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
# 画像
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "グラデーションのテック背景" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)
# アイコン
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "ロケット" --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 | 一行結果の代わりにJSONを出力 |
仕組み
- プロジェクト
.media/manifest.jsonlを確認し、プロンプトが完全一致するかをチェック - 既存の
assets/ディレクトリをスキャンし、ニーズに合致する未登録ファイルを探す - グローバルキャッシュ
~/.media/で再利用可能なアセットを確認 - プロバイダー経由で検索（HeyGen オーディオカタログ、HeyGen アセット検索）
- ファイルを
.media/<type>/に凍結、マニフェストに登録し、index.mdを再生成
エージェントは 一行 を受け取ります。候補、スコア、出典情報はディスク上に残ります。
既存プロジェクトの取り込み
ほとんどの 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 実行時に、intent に一致する 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 明るいテック系ローンチ
sfx_001 sfx 0.6s — .media/audio/sfx/sfx_001.mp3 ひゅーっ
image_001 image — 1920×1080 .media/images/image_001.jpg グラデーションのテック背景
icon_001 icon — 200×200 .media/images/icon_001.png ロケット
プロジェクト間再利用
アセットは resolve 時に自動的にキャッシュされます。同じプロンプトに対する後続の resolve は ~/.media/ のグローバルキャッシュにヒットします — 再ダウンロードもプロバイダー呼び出しもありません。アセットを明示的に organize --promote <id> で昇格させると、全プロジェクトで再利用可能になります。
ファイル
.media/manifest.jsonl— 機械用の唯一の真実源、1行に1JSONレコード.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 # 最新版を ~/.local/bin にインストール
heygen update # すでにインストール済みの場合: v0.1.6以上が必要
export HEYGEN_API_KEY=<your-key> # または: 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は「プロバイダーが解決できませんでした」となります。