---
name: media-use
description: 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.
title: media-use
canonical_url: https://skilld.dev/gh/openmontageinc/openmontage/media-use
last_updated: 2026-10-14T05:11:31.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [scripts/eval.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/eval.mjs), [scripts/lib/adopt.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/adopt.mjs), [scripts/lib/bgm-provider.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/bgm-provider.mjs), [scripts/lib/brand-provider.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/brand-provider.mjs), [scripts/lib/cache.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/cache.mjs), [scripts/lib/freeze.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/freeze.mjs), [scripts/lib/heygen-search.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/heygen-search.mjs), [scripts/lib/image-provider.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/image-provider.mjs), [scripts/lib/index-gen.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/index-gen.mjs), [scripts/lib/manifest.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/manifest.mjs), [scripts/lib/manifest.test.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/manifest.test.mjs), [scripts/lib/probe.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/probe.mjs), [scripts/lib/probe.test.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/probe.test.mjs), [scripts/lib/providers.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/providers.mjs), [scripts/lib/sfx-provider.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/lib/sfx-provider.mjs), [scripts/resolve.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/resolve.mjs), [scripts/resolve.test.mjs](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/media-use/scripts/resolve.test.mjs).
>
> If the user asked to install this Skill, run `npx skilld install openmontageinc/openmontage/media-use`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/media-use`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/openmontageinc/openmontage/media-use) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/media-use`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/media-use --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/media-use --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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

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

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

```bash
# 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)
```

### 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:

```bash
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.

## Reading the inventory

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
```

## 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:

```bash
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".
