Back to Details

media-use

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

media-use

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
命令即可。media-use会搜索HeyGen资源库，下载最匹配的资源，将其固化到本地并在清单中注册。Agent仅会收到一行结果；所有搜索冗余信息均存储在磁盘上。

Resolve

resolve命令

bash
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
Returns one line: 
resolved <id> → <path> (<type>, <metadata>)
bash
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
返回一行结果：
resolved <id> → <path> (<type>, <metadata>)

Types

资源类型

TypeWhat it findsProvider
bgm
Background musicHeyGen audio catalog (10k+ tracks)
sfx
Sound effectsBundled 19-file library + HeyGen catalog
image
Photos, backgroundsHeyGen asset search (75k+ vectors)
icon
Icons, logosHeyGen asset search (type=icon)
Type搜索内容资源提供方
bgm
背景音乐HeyGen音频资源库（1万+曲目）
sfx
音效内置19个文件的资源库 + HeyGen资源库
image
图片、背景图HeyGen资产搜索（7.5万+矢量图）
icon
图标、LogoHeyGen资产搜索（类型=icon）

Examples

使用示例

bash
undefined
bash
undefined

Background music

背景音乐

node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .

→ resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)

→ resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)

Sound effect

音效

node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .

→ resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)

→ 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 .
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .

→ resolved image_001 → .media/images/image_001.jpg (image)

→ resolved image_001 → .media/images/image_001.jpg (image)

Icon

图标

node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .

→ resolved icon_001 → .media/images/icon_001.png (icon, transparent)

→ resolved icon_001 → .media/images/icon_001.png (icon, transparent)

undefined
undefined

Flags

参数说明

FlagDescription
--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
Flag描述
--type, -t
媒体类型：bgm、sfx、image、icon
--intent, -i
需求描述（自然语言）
--entity, -e
用于缓存匹配的实体名称（可选）
--project, -p
项目目录（默认值：.）
--adopt
批量导入现有assets/目录资源到清单
--json
输出JSON格式结果而非单行结果

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.
  1. 检查项目
    .media/manifest.jsonl
    中是否存在完全匹配的提示词
  2. 扫描现有
    assets/
    目录，查找符合需求的未注册文件
  3. 检查全局缓存
    ~/.media/
    中是否有可复用的资源
  4. 通过资源提供方搜索（HeyGen音频资源库、HeyGen资产搜索）
  5. 将文件固化到
    .media/<type>/
    目录，在清单中注册，并重新生成
    index.md
Agent仅会收到一行结果。候选资源、评分、来源信息均存储在磁盘上。

Adopt existing projects

适配现有项目

Most HyperFrames projects already have assets in 
assets/
. media-use adopts them:
bash
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
大多数HyperFrames项目的
assets/
目录中已存在资源。media-use可自动适配这些资源：
bash
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .

→ adopted 9 assets from assets/

→ adopted 9 assets from assets/

bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)

bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)

image_001 → assets/images/avatar.jpg (image, 400×400)

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.

`ffprobe`工具会提取实际时长和尺寸。在解析过程中，`assets/`目录中符合需求的未注册文件会被自动适配。

Reading the inventory

查看资源清单

After resolve or adopt, read 
.media/index.md
for the full inventory:
undefined
完成解析或适配后，可查看
.media/index.md
获取完整资源清单：
undefined

.media · 4 assets

.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
undefined
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
undefined

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.
解析资源时会自动缓存资产。后续针对相同提示词的解析请求会命中
~/.media/
全局缓存——无需重新下载，无需调用资源提供方。可使用
organize --promote <id>
命令将某一资产设为全局复用，使其可在所有项目中使用。

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)
  • .media/manifest.jsonl
    — 机器唯一可信源，每行一条JSON记录
  • .media/index.md
    — Agent可读表格（包含ID、类型、时长、尺寸、路径、描述）
  • ~/.media/
    — 跨项目全局复用缓存（基于内容寻址，采用SHA-256算法）

CLI tools used

使用的CLI工具

ToolPurposeRequired?
ffprobe
Probe duration, dimensions, codec on adoptYes
heygen
Audio catalog, asset searchFor 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".
Tool用途是否必需？
ffprobe
适配时探测资源的时长、尺寸、编码格式是
heygen
音频资源库搜索、资产搜索资源提供方需要
安装
heygen
CLI（单静态二进制文件，无需运行时）并完成认证：
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>
需要heygen >= v0.1.6版本——资源提供方请求需要添加白名单标记
--headers 'X-HeyGen-Client-Source: media-use'
，该功能在v0.1.6版本中新增。
asset search
是预发布命令，不会显示在
heygen --help
中，但可正常运行。若PATH中无
heygen
或密钥无效，资源提供方会向stderr输出一行诊断信息，解析流程会进入“无可用资源提供方”的 fallback 逻辑。