media-use
Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.
1How It Works & Mechanism
The core is a 'single-verb' CLI architecture: SKILL.md unifies all eight types of media needs (BGM, SFX, image, icon, logo, voice, color grade, and LUT) into a single `resolve` command, where the agent converts user intent into `--intent`, persists search noise directly to disk, and outputs only a single line of results.
```bash node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir> ``` Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search noise stays on disk.
Lookup-type capabilities (bgm/sfx/image/icon/voice) default to the HeyGen catalog free-usage path, requiring pre-installation and OAuth login via the heygen CLI along with a `--doctor` self-check, without which they will not function.
First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `node <SKILL_DIR>/scripts/resolve.mjs --doctor`.
Generation capabilities operate on a dual-track system of 'cloud default + local optional': BGM generation uses Google Lyria (requires $GOOGLE_API_KEY/$GEMINI_API_KEY) with fallback to local MusicGen; voice uses HeyGen TTS or local Kokoro; image uses local mflux; video uses local LTX—all executed via lib/ scripts.
Generate BGM using Google Lyria RealTime API. Usage: python lyria-recipe.py --output <path> --duration <seconds> [tuning flags] Requires: $GOOGLE_API_KEY or $GEMINI_API_KEY environment variable (treated as aliases).
Logo resolution follows the chain 'svgl → simple-icons → GitHub avatar → domain favicon', strictly avoiding hand-drawn marks; these are real providers performing network requests (logo-provider.mjs).
https://api.svgl.app https://cdn.jsdelivr.net/npm/simple-icons
Media operations (cut, reframe, transform, duck, loudness, subtitle chunking, error diffusion, HEVC) are implemented via custom Node scripts + ffmpeg; for instance, freeze.mjs enforces SSRF protections on 'freezing remote URLs' (blocking localhost, private subnets, and link-local addresses).
/^(localhost|.*\.local|.*\.internal|127\.|10\.|0\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|\[?(::1|::ffff:127\.|f[cd][0-9a-f]{2}:|fe80:))/i;
Cross-project memory/caching is implemented through real filesystem structures: project-level `.media/` + global `~/.media/` (content-addressed via SHA-256), with preferences and full recipes persisted across project and global tiers, managed via prefs.mjs/recipe.mjs.
- `.media/manifest.jsonl`: machine SSOT, one JSON record per line - `~/.media/`: global cross-project reuse cache (content-addressed, SHA-256)
Telemetry is enabled by default but deliberately coarse-grained: PostHog events contain only media type/source/provider without intent text or file paths, featuring opt-out switches via DO_NOT_TRACK / HYPERFRAMES_NO_TELEMETRY / CI / dev, and sharing identity configuration in ~/.hyperframes/config.json with the hyperframes CLI.
It records only the media TYPE, the resolution SOURCE, and the winning PROVIDER: never the intent text, file names, or paths, and `$ip:null` so no IP is stored. Best-effort and non-blocking (a resolve never waits on or fails from telemetry).
2Core Capabilities
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | heygen CLI（HeyGen，OAuth free-usage / api-key） |
| cli | ffmpeg/ffprobe（adopt 探测、signalstats、cut、duck bake、loudnorm） |
| cli | mflux-generate / parakeet-mlx / ltx-2-mlx / codex（本地或订阅生成器，opt-in） |
| api | HeyGen REST API |
| api | Google Lyria RealTime（BGM 生成，google-genai） |
| api | ElevenLabs TTS（可选，tts.mjs 分支） |
| network | PostHog 遥测 |
| network | logo 源：svgl / simple-icons(jsdelivr) / GitHub 头像 / DuckDuckGo favicon |
| network | LUT CDN |
| network | 本地模型下载/安装（Hugging Face、uv/pip、git） |
| package | @hyperframes CLI 内联能力（Kokoro TTS、remove-background 等） |
4Recommended Governance & Evidence
- scripts/: Executes local scripts or commands: node <SKILL_DIR>/scripts/resolve.mjs (for each --type; executed directly by agent)
- 网络端点: Declares external network access: api.heygen.com/v3 (catalog/TTS/avatar, with X-HeyGen-Client-Source: media-use attribution)
- 本地工作目录: File read/write and artifact output: Project `.media/`: manifest.jsonl, index.md, preferences.json, recipes/<name>/, and local asset persistence
5Second-Pass Verification
- [ok] external_deps 中每个 CLI/API/网络端点的调用点真实存在 — 逐一反查：heygen CLI（setup-providers.md 安装/登录段）、ffmpeg（工具表）、Lyria（lyria-recipe.py 头部 docstring + bgm.mjs lyriaConfigured）、PostHog（telemetry.mjs 常量）、logo 源（logo-provider.mjs URL 常量）、LUT CDN（luts/index.json 记录）均有源码落点。
- [ok] 安全结论有无漏网网络调用 — URL 全量扫描覆盖 scripts/audio/luts/references；未发现扫描范围外的域；遥测为默认唯一自发性外发，opt-out 与注释一致。
- [ok] 凭证读取面是否如描述（env/.env/~/.heygen） — heygen.mjs 头注释与 loadEnvFromDir 实现（walk ≤5 dirs、shell env 优先）与描述一致；audio/scripts/lib/{heygen,tts,bgm}.mjs 分别读 HEYGEN/ELEVENLABS/GEMINI key。
- [ok] SSRF 防护声称 — freeze.mjs 第 57 行正则实际拦截 localhost/*.local/*.internal/127./10./169.254./192.168./172.16-31 与 IPv6 环回；freeze.test.mjs 同时断言拦截内网样例。
- [ok] 是否有将远程内容当指令/可执行代码的路径 — 下载资产均为数据文件（audio/image/cube）；脚本为随包源码；未发现下载即执行路径。
- [ok] 功能声明夸大检查（media treatments、10k+ 曲库、75k+ 向量） — 目录规模数字来自 HeyGen 服务端宣称（SKILL.md 表格原文），skill 侧可验证的是调用点与回退链存在；『produce voiceover…background removal』对应 audio/ 引擎脚本与 provider 表。超出本地可验证的部分按供应商宣称标注。
6Verdict & Scenarios
e19482b5849526de…