Find background music, sound effects, images, and icons from existing assets, shared caches, or HeyGen. Save selected files locally and register them in an inventory, giving the agent a usable file path.
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 needs background music, sound effects, images, or icons.
Review the instructions the agent will receive before you install.
Resolve media needs into frozen local files. One verb, four types, zero context noise.
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.
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
Returns one line: resolved <id> → <path> (<type>, <metadata>)
| 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) |
# 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)
| 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 |
.media/manifest.jsonl for exact-prompt matchassets/ directory for unregistered files matching the need~/.media/ for reusable asset.media/<type>/, register in manifest, regenerate index.mdThe agent gets back one line. Candidates, scores, provenance stay on disk.
Most HyperFrames projects already have assets in assets/. media-use adopts them:
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 extracts real duration and dimensions. During resolve, unregistered files in assets/ matching the intent are adopted on the fly.
After resolve or adopt, read .media/index.md for the full inventory:
# .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
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.
.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)| 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:
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>
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".
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Create 3D objects from text or images, choose catalog assets for repeated scenery, and inspect the results in Blender. The workflow checks geometry, materials, scale, and ground contact while recording asset sources and generation costs.
Generate background music and songs with lyrics using ACE-Step 1.5, with controls for duration, tempo, and musical key. You can also restyle reference audio and separate vocals or individual instruments from mixed tracks.
Build voice assistants and conversational characters with ElevenLabs. Configure voices, language models, and external tools, then connect conversations to a website widget or use Twilio integration for outbound phone calls.
Create AI video clips from text or reference images, choosing among providers to match the task and budget. Supports vertical social videos, product photo animation, and conversational editing of existing clips with Gemini Omni Flash.
Generate video clips from text descriptions or reference images through multiple API services. Compare available providers by cost and task needs, choose aspect ratios, track generation progress, and refine existing clips through conversational editing with Gemini Omni.
Generate and edit images and videos through Atlas Cloud using one API key across multiple model families. Choose supported models for each task, download the results, and retain details about the model, inputs, and estimated cost.