media-use

**插件安装：**如果此技能位于 HyperFrames 插件中，请在运行设置或检查更新命令前遵循插件执行规则。独立安装请继续参照下方的更新说明。

media-use

HyperFrames 的媒体操作系统：解析 · 生成 · 操作 · 记忆 — 所有媒体类型，一个技能，零上下文噪声。

仅当环境中设置了 HEYGEN_API_BASE 时（由宿主应用设置，并使用其自己的密钥为 HeyGen 付费）：HeyGen 媒体已付费。不要要求用户安装或登录 heygen CLI，也不要提供其 OAuth 免费额度；此处的目录搜索、TTS 和虚拟形象调用都会通过宿主进行。如果同一宿主还提供自己的 HeyGen 工具，请优先使用这些工具。如果宿主拒绝某次调用，请原样告知用户宿主给出的消息（其中会说明解决方法，例如在应用的 Settings 中添加或更换密钥），然后停止；除非用户提出要求，否则不要切换到其他提供方。

其他情况下的首次运行（未设置 HEYGEN_API_BASE），如果要使用 HeyGen 媒体（目录搜索、TTS、虚拟形象视频）：请安装并登录 heygen CLI（免费使用方式），然后通过 npx hyperframes media-use resolve --doctor 进行验证。设置和提供方：references/setup-providers.md。

在宿主应用中使用音乐和音效时：如果运行环境中的应用提供自己的音乐或音效工具，请使用这些工具。未设置 HEYGEN_API_BASE 时，resolve --type bgm 会通过 heygen CLI 搜索 HeyGen 目录；如果没有 CLI，则会失败并说明原因。resolve --type sfx 会搜索 Openverse（仅限 CC0 和 CC BY，无需账户），离线时则回退到内置库；请按照 audio/references/sfx.md 的说明为 CC BY 音效署名。

未设置 HEYGEN_API_BASE 时，在生成配音或虚拟形象视频之前，请告知用户：使用 OAuth 登录 heygen CLI（heygen auth login --oauth）可获得 TTS 配音和虚拟形象视频的免费额度，而 API 密钥会消耗 API 额度。

Resolve — 唯一动词

npx hyperframes media-use resolve --type <type> --intent "<description>" --project <dir>

返回一行：resolved <id> → <path> (<type>, <metadata>)。所有搜索噪声都会保留在磁盘上。

类型	单行用途
bgm	背景音乐（通过 heygen CLI 搜索 HeyGen 目录，包含 10k+ 首曲目）
sfx	音效（Openverse CC0 / CC BY，离线时使用包含 21 个文件的内置库）
image	照片、背景（HeyGen 资源搜索，包含 75k+ 个矢量图）
icon	图标、符号（透明）
logo	官方品牌标志（theSVG → GitHub 头像 → favicon；绝不重新绘制）
voice	TTS 配音（HeyGen 免费使用方式；可选的本地 Kokoro）
grade	经过测量的校正候选项；更广泛的润色/风格化请参阅 Media Treatments
lut	用户提供或明确选定的、可重复使用且经过验证的 .cube 文件

解析新资源前，请使用 --candidates 列出可重复使用的候选项，并自行判断是否合适 — 有关复用规则、所有标志、导入（--from）和采用方法，请参阅 references/resolve.md。

将宽泛的视觉反馈视为媒体处理意图

当用户明确要求修复、润色、风格化、遮挡、强调或呈现摄影媒体时，即使他们没有提到调色或特效，也要阅读 references/media-treatments.md。检查实际的 <img>/<video>，选择一个主要意图，然后采用确定性的持久化和验证方式。 可以使用匹配的配方作为可选的测试起点，也可以检查 hyperframes media-treatment --capabilities --json，然后使用 --capability <id> 请求一个相关类别／特效，并根据规范控制项组合自定义处理方案。常规创作时，绝不要加载 --all。处理方案可以组合校正、预设、润饰、兼容的着色器特效、受支持的关键帧，以及可选的 Registry 覆盖层。只添加有来源依据的有限调整和兼容部分，绝不要仅为让结果看起来更精致而添加特效。使用 hyperframes media-treatment 持久化最终组合后的载荷。

采用逐步升级的工作流。对于视频，检查一张标有前／中／后期的联系表，而不是分别读取各帧。对于常规校正或润色，应用一个候选方案并检查一张处理后的联系表。只有当结果存在歧义、涉及时间变化、风格化、基于 LUT、对 HDR/LOG 敏感、涉及隐私或对品牌至关重要时，才升级为检查单帧或动态草稿证据。

对于常规校正或润色，持久化最终处理方案的预设／调整 JSON。 不要仅为了编码曝光、阴影、对比度或暖色调而生成 .cube LUT。只有用户提供 LUT，或所选处理方案明确包含 LUT 时，才使用 LUT。resolve --type grade --for ... --analyze 提供的是测量证据，并不意味着可以用生成的 LUT 替换所选处理方案。 不要用 CSS/SVG 覆盖层重新实现受支持的晕影、颗粒、模糊、像素化、颜色或处理特效；这会绕过 Studio 控件以及规范的预览／渲染着色器路径。

主动一些——进行一次媒体机会扫描

人类通常无法判断哪些媒体素材能提升作品质量，而你可以。在创建或审查作品时，进行一次有依据的扫描，然后询问一次——不要悄悄添加，也不要对每项素材都反复提醒。

只有在存在具体信号时，才提出机会：

检测到的信号	建议
屏幕上的文字／没有画外音的脚本	TTS 旁白（音频引擎）
表情符号或样式设为图标的 <div>	使用真正的 icon
占位图、尺寸很小或看起来被放大的图像	更好的 image（和／或放大——参见 references/operations.md）
硬切镜头／转场没有声音	转场 sfx
时长超过约 10 秒且没有背景音乐	bgm
画面看起来曝光不足／过度或偏色	校正调色（使用 hyperframes media-treatment --selector '#hero' --analyze --json 检查）
摄影媒体在视觉上显得平淡或偏离主题	一个具体且适合素材来源的预设或自定义处理，并注明预期目标
有意义的媒体入场／揭示效果显得静态	一种受支持且可安全跳转的处理动画；除非请求也有充分理由使用预设，否则保留颜色

让帮助不变成骚扰的规则：有据可依，不泛泛而谈（没有信号 → 不提出建议）；明确且具体（提出具体修复方案并选好默认值——由人类批准全部／部分／不采纳）；每个项目只问一次（集中提出一次；尊重“保持现状”）；只提出建议，绝不悄悄修改（尤其是调色：先提出方案并预览——灰度世界“校正”会毁掉刻意营造的日落或霓虹效果）。

去哪里查找——只读取任务需要的文件

任务	阅读
解析／复用／采纳／导入、标志、级联、清单	references/resolve.md
调色、LUT、智能调色（--for）、调色对比	references/grading.md
旁白／TTS、音乐、SFX、字幕、转录（音频引擎）	references/audio.md
剪切／重新构图／变换现有媒体、精确误差扩散、HEVC	references/operations.md
感知素材来源的创意处理、实时效果、叠加、揭示	references/media-treatments.md
安装与身份验证、提供方表格、RAM 梯度、--local-only、--provider	references/setup-providers.md
记忆的偏好与冻结的配方（用户记忆）	references/memory.md
归属矩阵、使用统计、遥测、隐私（面向维护者）	references/meta.md