Agent Media OS — resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) handles the full cascade — project cache, global cache, HeyGen catalog search, freeze, register. Keeps search noise on disk, hands the agent a path. Use when a composition n

media use Resolve media needs into frozen local files. One verb, four types, zero context noise. When to use Call resolve whenever a composition needs media — background music, sound effects, images, or icons. media use searches the HeyGen catalog, downloads the best match, freezes it locally, and registers it in a manifest. The agent gets back one line; all search noise stays on disk. Resolve Returns one line: resolved <id → <path (<type , <metadata ) Types Type What it finds Provider bgm Background music HeyGen audio catalog (10k+ tracks) sfx Sound effects Bundled 19 file library + HeyGen catalog image Photos, backgrounds HeyGen asset search (75k+ vectors) icon Icons, logos HeyGen asset search (type=icon) Examples Flags Flag Description type, t Media type: bgm, sfx, image, icon intent, i What you need (natural language) entity, e Entity name for cache matching (optional) project, p Project directory (default: .) adopt Bulk import existing assets/ into manifest json Output JSON instead of one line result How it works 1. Check project .media/manifest.jsonl for exact prompt match 2. Scan existing assets/ directory for unregistered files matching the need 3. Check global cache ~/.media/ for reusable asset 4. Search via provider (HeyGen audio catalog, HeyGen asset search) 5. Freeze file to .media/<type / , register in manifest, regenerate index.md The agent gets back one line . Candidates, scores, provenance stay on disk. Adopt existing projects Most HyperFrames projects already have assets in assets/ . media use adopts them: ffprobe extracts real duration and dimensions. During resolve, unregistered files in assets/ matching the intent are adopted on the fly. Reading the inventory After resolve or adopt, read .media/index.md for the full inventory: Cross project reuse Assets are cached automatically on resolve. Subsequent resolves for the same prompt hit the global cache at ~/.media/ — no re download, no provider call. Promote an asset explicitly with organize promote <id to make it reusable across all projects. Files .media/manifest.jsonl — machine SSOT, one JSON record per line .media/index.md — agent readable table (id, type, dur, dims, path, description) ~/.media/ — global cross project reuse cache (content addressed, SHA 256) CLI tools used Tool Purpose Required? ffprobe Probe duration, dimensions, codec on adopt Yes heygen Audio catalog, asset search For providers Install the heygen CLI (single static binary, no runtime) and authenticate: Requires heygen = v0.1.6 — the providers tag requests with the allowlisted headers 'X HeyGen Client Source: media use' flag, added in v0.1.6. asset search is a pre launch command hidden from heygen help , but it runs. Without a heygen on PATH (or a valid key) the providers print a one line diagnostic to stderr and resolve falls through to "no provider could resolve".

media-use