media-use

**插件安装：**如果此技能位于 HyperFrames 插件中，请在运行设置或检查最新状态的命令前，遵循插件执行规则。

HyperFrames 中的媒体

媒体会作为本地文件存放在项目的 assets/ 中，并附有一条台账记录；渲染时绝不会获取媒体。使用一个动词即可查找或创建媒体：

npx hyperframes media-use resolve --type <type> --intent "<what you need>" --project <dir>

它会输出一行：resolved <id> → <path> (<type>, <metadata>)。先用 --candidates 列出可复用的素材，再自行判断是否合适；复用、导入（--from）和接纳的说明见 references/resolve.md。

两种获取方式

需求	HeyGen（品质最佳）	免费，无需账户
音乐（bgm）	10k+ 曲目的目录	本地 MusicGen（audio/references/bgm.md）
音效（sfx）		Openverse；捆绑了 21 个离线音效
图片、图标	素材搜索，75k+	本地 FLUX（mflux），如已安装
Logo（logo）		theSVG、GitHub 头像、favicon；绝不重新绘制
旁白（voice）	HeyGen 语音、语音克隆	npx hyperframes tts（设备端运行 Kokoro；需要 Python 3.10+，并运行 pip install kokoro-onnx soundfile）
主持人讲话	虚拟形象视频（--type video）	本地 LTX 可生成通用片段，如已安装
转录文本		npx hyperframes transcribe（Parakeet 或 whisper）
抠像	heygen background-removal	npx hyperframes remove-background
调色、LUT、视觉风格		npx hyperframes media-treatment

**宿主应用。**在提供自有媒体工具的应用中，优先使用这些工具。设置了 HEYGEN_API_BASE 时，HeyGen 费用由宿主承担：不要询问 heygen CLI 或要求登录；如果调用遭到拒绝，请原样转达宿主的消息并停止。

**HeyGen。**安装 heygen CLI，并使用 heygen auth login --oauth 登录：OAuth 会话会使用订阅额度中的免费额度；API 密钥（--api-key）会扣除 API 额度。运行 npx hyperframes media-use resolve --doctor 检查设置。如果请求需要 HeyGen（主持人或虚拟形象、HeyGen 语音、目录音乐），但未安装 heygen 或尚未登录，请告知用户如何获取：安装链接、用于免费额度的 heygen auth login --oauth，或用于额度计费的 API 密钥。然后提供免费方案，或等待用户决定。除 resolve 外，同一 CLI 还可生成文本转视频（heygen video-agent create）、带录制音轨的虚拟形象视频（heygen video create）、克隆语音（heygen voice clone create）、配音（heygen lipsync）、翻译视频（heygen video-translate），以及从长视频中剪辑短片（heygen ai-clipping）：配方见 references/operations.md。

**免费方案。**免费列中的所有工具都无需账户；本地模型需选择安装（references/setup-providers.md）。未安装 heygen 时，使用 resolve 获取音乐、图片和图标会失败，并说明原因；使用 CC BY 音效时请标注来源（audio/references/sfx.md）。--local-only 会跳过所有网络服务提供方。

**费用。**对于你决定发起的付费调用（包括虚拟形象视频），请先确认费用；用户要求的调用则直接执行。用户指定生成器时，使用 --provider <name> 固定服务提供方。

实拍素材的视觉效果

如果反馈指出实拍素材太暗、太平淡或太乏味、需要复古或印刷质感、需要隐藏人脸，或需要揭示效果，这都属于媒体处理需求：请阅读 references/media-treatments.md。检查实际的 <img>/<video>，选择一种处理意图，从 npx hyperframes media-treatment --capabilities --json 开始，然后使用 --capability <id>；绝不要使用 --all。使用 npx hyperframes media-treatment 保存最终处理效果；对于已支持的效果，不要用 CSS 或 SVG 代替，也不要仅为编码曝光或暖色调而生成 .cube。

主动提议一次，不要擅自添加

构建或审查内容时，只扫描一次，查找明确的问题（画面中的文字没有旁白、用 emoji 代替图标、占位图片、无声剪辑、超过 10 s 没有音乐、色偏），并在一次询问中提出具体的修复建议。没有明显问题就不要提议；尊重“保持原样”的要求。

查阅位置

任务	阅读
解析、复用、采用、摄取、标记	references/resolve.md
调色、LUT、grade-compare	references/grading.md
配音、音乐、音效、字幕、转录	references/audio.md
剪辑、重新构图或转换媒体；HeyGen 配方	references/operations.md
视觉处理、实时效果、叠加、揭示	references/media-treatments.md
安装、登录、提供商、RAM 梯度	references/setup-providers.md
已放置轨道上的淡入淡出、增益、闪避、自动化、效果、总线	references/mixing.md
本地命令：调色、抠像、响度、节拍	references/local.md
已记住的偏好	references/memory.md