# Media Use

> Agent Media OS: resuelve BGM, SFX, imágenes, iconos, logos, voz, gradación de color o LUTs en un archivo local o bloque listo para usar; genera, opera y reutiliza assets en proyectos HyperFrames.

Fuente: https://skillsagentes.com/skills/heygen-com/hyperframes/media-use
Markdown: https://skillsagentes.com/skills/heygen-com/hyperframes/media-use.md

Repositorio: https://github.com/heygen-com/hyperframes
Autor: heygen-com
Licencia: Apache-2.0
Actualizado: el mes pasado
Coste de contexto: 158 tok instalada, 2k tok al activarse, 517k tok con todos los archivos del bundle
Bundle: 152 archivos, 2.0 MB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add heygen-com/hyperframes --skill media-use --agent claude-code
# Cursor
npx -y skills add heygen-com/hyperframes --skill media-use --agent cursor
# Codex
npx -y skills add heygen-com/hyperframes --skill media-use --agent codex
# Gemini CLI
npx -y skills add heygen-com/hyperframes --skill media-use --agent gemini
# Windsurf
npx -y skills add heygen-com/hyperframes --skill media-use --agent windsurf
# Cline
npx -y skills add heygen-com/hyperframes --skill media-use --agent cline
```

## Qué hace

- Resuelve BGM, SFX, imágenes, iconos, logos de marca, voces, gradación de color o LUTs en un archivo local fijo o un bloque listo para pegar, con un único verbo `resolve`
- Genera vía modelos de TTS, música o imagen cuando el catálogo no tiene el asset
- Produce voz en off, transcripción, captions y remoción de fondo mediante un motor de audio compartido
- Opera sobre el material (cortar / reencuadrar / transformar) y reutiliza assets entre proyectos
- Ejecuta una pasada proactiva de oportunidades de media, sugiriendo una idea fundamentada por proyecto

## Cuándo usarla

- Cualquier necesidad de media en un proyecto HyperFrames: BGM, SFX, imagen, icono, logo, voz, gradación de color o LUT
- Feedback vago de que el metraje se ve oscuro, plano, aburrido, o debería sentirse retro/cámara de video/impreso/ASCII
- El metraje necesita tratamiento de privacidad o un efecto de revelado/transición de media
- Se está construyendo o revisando una composición y hay que verificar si falta voz en off, iconos, música o gradación

## Qué la activa

- "Resuélveme una música de fondo para este vídeo"
- "Este metraje se ve muy plano y oscuro, arréglalo"
- "Necesito el logo oficial de esta marca, no lo dibujes a mano"
- "Añade voz en off a este guion sin narración"
- "Quiero que esta transición de escena tenga un efecto retro/cámara"

## Antes de instalar

- Requiere instalar y autenticarse en la CLI `heygen` (ruta de uso gratuito) y verificar con `node <SKILL_DIR>/scripts/resolve.mjs --doctor`.
- Necesita en el PATH: node, pip
- Variables de entorno: CANDIDATE_CAP, CODEX_HOME, DO_NOT_TRACK, HEYGEN_AUTH_COMMAND, HEYGEN_CAPTURE_PATH, HEYGEN_CONFIG_DIR, HEYGEN_DISCOVERY_MODE, HEYGEN_INSTALL_COMMAND, HEYGEN_MIN_VERSION, HEYGEN_UPDATE_COMMAND, HEYGEN_VIDEO_MODE, HEYGEN_VIDEO_RESPONSE, HF_GRADING_JSON, HYPERFRAMES_ANALYZE_TIMEOUT_MS, HYPERFRAMES_MEDIA_USE_SFX_DIR, HYPERFRAMES_NO_TELEMETRY, HYPERFRAMES_PARAKEET, INGEST_TYPES, JSON, MAX_FREEZE_BYTES, MAX_SIZE, MEDIA_USE_TELEMETRY_HOST, MIN_NODE_VERSION, PREFERENCE_KEYS, SIMPLE_ICONS_CDN, SVGL_API
- makes network requests
- reads environment config

## Archivos

- .gitignore — 17 B
- SKILL.md — 8 KB
- audio/assets/sfx/CREDITS.md — 1 KB
- audio/assets/sfx/chime.mp3 — 27 KB
- audio/assets/sfx/click-soft.mp3 — 11 KB
- audio/assets/sfx/click.mp3 — 11 KB
- audio/assets/sfx/error.mp3 — 51 KB
- audio/assets/sfx/glitch-1.mp3 — 82 KB
- audio/assets/sfx/glitch-2.mp3 — 110 KB
- audio/assets/sfx/glitch-3.mp3 — 97 KB
- audio/assets/sfx/impact-bass-1.mp3 — 66 KB
- audio/assets/sfx/impact-bass-2.mp3 — 81 KB
- audio/assets/sfx/key-press.mp3 — 4 KB
- audio/assets/sfx/manifest.json — 4 KB
- audio/assets/sfx/notification.mp3 — 77 KB
- audio/assets/sfx/ping.mp3 — 26 KB
- audio/assets/sfx/pop.mp3 — 23 KB
- audio/assets/sfx/riser.mp3 — 314 KB
- audio/assets/sfx/sparkle.mp3 — 56 KB
- audio/assets/sfx/typing.mp3 — 26 KB
- audio/assets/sfx/whoosh-cinematic.mp3 — 173 KB
- audio/assets/sfx/whoosh-short.mp3 — 18 KB
- audio/assets/sfx/whoosh.mp3 — 18 KB
- audio/references/bgm.md — 8 KB
- audio/references/captions/authoring.md — 9 KB
- audio/references/captions/motion.md — 6 KB
- audio/references/captions/transcript-handling.md — 5 KB
- audio/references/remove-background.md — 8 KB
- audio/references/requirements.md — 4 KB
- audio/references/sfx.md — 3 KB
- audio/references/transcribe.md — 3 KB
- audio/references/tts-to-captions.md — 1 KB
- audio/references/tts.md — 9 KB
- audio/scripts/audio.mjs — 13 KB
- audio/scripts/audio.test.mjs — 2 KB
- audio/scripts/heygen-tts.mjs — 4 KB
- audio/scripts/lib/bgm.mjs — 11 KB
- audio/scripts/lib/bgm.test.mjs — 1 KB
- audio/scripts/lib/concurrency.mjs — 527 B
- audio/scripts/lib/concurrency.test.mjs — 2 KB
- audio/scripts/lib/heygen.mjs — 7 KB
- audio/scripts/lib/heygen.test.mjs — 3 KB
- audio/scripts/lib/python.mjs — 3 KB
- audio/scripts/lib/python.test.mjs — 3 KB
- audio/scripts/lib/sfx.mjs — 5 KB
- audio/scripts/lib/sfx.test.mjs — 3 KB
- audio/scripts/lib/tts.mjs — 16 KB
- audio/scripts/lib/tts.spawn.test.mjs — 5 KB
- audio/scripts/lib/tts.test.mjs — 6 KB
- audio/scripts/lyria-recipe.py — 4 KB
- audio/scripts/wait-bgm.mjs — 5 KB
- luts/README.md — 1 KB
- luts/index.json — 2 KB
- references/audio.md — 2 KB
- references/grading.md — 7 KB
- references/media-treatment-recipes.md — 35 KB
- references/media-treatments.md — 14 KB
- references/memory.md — 3 KB
- references/meta.md — 7 KB
- references/operations.md — 14 KB
- references/resolve.md — 9 KB
- references/setup-providers.md — 7 KB
- references/telemetry-dashboard.md — 4 KB
- scripts/audio-duck.mjs — 4 KB
- scripts/dither.mjs — 10 KB
- scripts/dither.test.mjs — 5 KB
- scripts/eval.mjs — 15 KB
- scripts/lib/adopt.mjs — 4 KB
- scripts/lib/adopt.test.mjs — 3 KB
- scripts/lib/bgm-provider.mjs — 650 B
- scripts/lib/brand-provider.mjs — 2 KB
- scripts/lib/bundled-sfx-provider.mjs — 3 KB
- scripts/lib/bundled-sfx-provider.test.mjs — 3 KB
- scripts/lib/cache.mjs — 5 KB
- scripts/lib/candidates.mjs — 4 KB
- scripts/lib/candidates.test.mjs — 6 KB
- scripts/lib/codex-provider.mjs — 7 KB
- scripts/lib/codex-provider.test.mjs — 1 KB
- scripts/lib/coverage.test.mjs — 6 KB
- scripts/lib/cube-build.mjs — 6 KB
- scripts/lib/cube-build.test.mjs — 3 KB
- scripts/lib/cube-validate.mjs — 6 KB
- scripts/lib/cube-validate.test.mjs — 3 KB
- scripts/lib/cutlist.mjs — 6 KB
- scripts/lib/cutlist.test.mjs — 4 KB
- scripts/lib/duck.mjs — 3 KB
- scripts/lib/duck.test.mjs — 3 KB
- scripts/lib/error-diffusion.mjs — 6 KB
- scripts/lib/error-diffusion.test.mjs — 3 KB
- scripts/lib/freeze.mjs — 3 KB
- scripts/lib/freeze.test.mjs — 2 KB
- scripts/lib/grade-analyzer.mjs — 9 KB
- scripts/lib/grade-analyzer.test.mjs — 8 KB
- scripts/lib/heygen-cli.mjs — 7 KB
- scripts/lib/heygen-cli.test.mjs — 10 KB
- scripts/lib/heygen-search.mjs — 2 KB
- scripts/lib/heygen-search.test.mjs — 2 KB
- scripts/lib/heygen-video-provider.mjs — 4 KB
- scripts/lib/heygen-video-provider.test.mjs — 12 KB
- scripts/lib/image-provider.mjs — 1 KB
- scripts/lib/index-gen.mjs — 2 KB
- scripts/lib/local-models.mjs — 13 KB
- scripts/lib/local-models.test.mjs — 6 KB
- scripts/lib/local-run.mjs — 2 KB
- scripts/lib/local-run.test.mjs — 2 KB
- scripts/lib/logo-provider.mjs — 7 KB
- scripts/lib/logo-provider.test.mjs — 6 KB
- scripts/lib/ltx-video-provider.mjs — 2 KB
- scripts/lib/ltx-video-provider.test.mjs — 4 KB
- scripts/lib/lut-preset-provider.mjs — 8 KB
- scripts/lib/lut-preset-provider.test.mjs — 6 KB
- scripts/lib/manifest.mjs — 7 KB
- scripts/lib/manifest.test.mjs — 12 KB
- scripts/lib/match.mjs — 1 KB
- scripts/lib/mflux-provider.mjs — 3 KB
- scripts/lib/misses.mjs — 1 KB
- scripts/lib/misses.test.mjs — 3 KB
- scripts/lib/npx-sync.mjs — 1 KB
- scripts/lib/npx-sync.test.mjs — 2 KB
- scripts/lib/parakeet-words.mjs — 1 KB
- scripts/lib/parakeet-words.test.mjs — 1 KB
- scripts/lib/prefs-store.mjs — 6 KB
- scripts/lib/prefs-store.test.mjs — 7 KB
- scripts/lib/probe.mjs — 1 KB
- scripts/lib/probe.test.mjs — 2 KB
- scripts/lib/providers.mjs — 327 B
- scripts/lib/recipe-store.mjs — 13 KB
- scripts/lib/recipe-store.test.mjs — 13 KB
- scripts/lib/registry.mjs — 9 KB
- scripts/lib/registry.test.mjs — 10 KB
- scripts/lib/search.mjs — 906 B
- scripts/lib/search.test.mjs — 1 KB
- scripts/lib/sfx-provider.mjs — 700 B
- scripts/lib/specs.mjs — 3 KB
- scripts/lib/specs.test.mjs — 3 KB
- scripts/lib/stats.mjs — 4 KB
- scripts/lib/stats.test.mjs — 5 KB
- scripts/lib/telemetry.mjs — 8 KB
- scripts/lib/telemetry.test.mjs — 13 KB
- scripts/lib/tts-local-provider.mjs — 4 KB
- scripts/lib/tts-local-provider.test.mjs — 3 KB
- scripts/lib/usage.mjs — 2 KB
- scripts/lib/usage.test.mjs — 2 KB
- scripts/lib/voice-provider.mjs — 2 KB
- scripts/lib/voice-provider.test.mjs — 2 KB
- scripts/lib/words.mjs — 764 B
- scripts/prefs.mjs — 2 KB
- scripts/recipe.mjs — 4 KB
- scripts/resolve.mjs — 43 KB
- scripts/resolve.test.mjs — 36 KB
- scripts/transcribe.mjs — 7 KB
- scripts/transcript-cut.mjs — 7 KB

## SKILL.md

Reproducido tal cual desde heygen-com/hyperframes bajo Apache-2.0. Esta sección es el documento original y está en inglés.

**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.

# media-use

The media OS for HyperFrames: resolve · generate · operate · remember — every media type, one skill, zero context noise.

First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.

## Resolve — the one verb

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

Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search noise stays on disk.

| Type    | One-line intent                                                                  |
| ------- | -------------------------------------------------------------------------------- |
| `bgm`   | background music (HeyGen catalog, 10k+ tracks)                                   |
| `sfx`   | sound effects (bundled 19-file library + catalog)                                |
| `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors)                          |
| `icon`  | icons, symbols (transparent)                                                     |
| `logo`  | official brand marks (theSVG → GitHub avatar → favicon; never redrawn)           |
| `voice` | TTS voiceover (HeyGen free-usage path; optional local Kokoro)                    |
| `grade` | measured correction candidate; broad polish/stylization follows Media Treatments |
| `lut`   | user-provided or explicitly chosen reusable validated `.cube` file               |

Before resolving fresh, list reusable candidates with `--candidates` and judge fit yourself — reuse rules, all flags, ingest (`--from`), and adopt are in `references/resolve.md`.

## Treat broad visual feedback as media intent

When a user explicitly asks to fix, polish, stylize, obscure, emphasize, or
reveal photographic media, read `references/media-treatments.md` even if they
do not name color grading or an effect. Inspect the real `<img>`/`<video>`,
choose one primary intent, then use deterministic persistence and verification.
Use a matching recipe as an optional tested seed, or inspect
`hyperframes media-treatment --capabilities --json`, then request one relevant
family/effect with `--capability <id>` and assemble a custom treatment from
canonical controls. Never load `--all` for ordinary authoring. A treatment may
compose correction, a preset, finishing, compatible shader effects, supported
keyframes, and optional Registry overlays. Add only source-justified bounded
tuning and compatible parts, never effects merely to make the result look more
sophisticated. Persist the final combined payload with
`hyperframes media-treatment`.

Use one progressively escalating workflow. For video, inspect one labeled
early/middle/late contact sheet rather than reading frames separately. Apply one
candidate and inspect one after-sheet for ordinary correction or polish.
Escalate to individual frames or moving draft evidence only when the result is
ambiguous, temporal, stylized, LUT-based, HDR/LOG-sensitive, private, or
brand-critical.

For ordinary correction or polish, persist the final treatment's
preset/adjustment JSON.
Do not generate a `.cube` LUT merely to encode exposure, shadows, contrast, or
warmth. Use a LUT only when the user supplies one or the selected treatment
explicitly owns one. `resolve --type grade --for ... --analyze` is measurement
evidence, not permission to replace the chosen treatment with a generated LUT.
Do not recreate supported vignette, grain, blur, pixelate, color, or treatment
effects with CSS/SVG overlays; that bypasses Studio controls and the canonical
preview/render shader path.

## Be proactive — run a media opportunity pass

The human usually can't tell which media would lift the piece. You can. When you build or review a composition, do **one** grounded scan and then **ask once** — don't silently add, and don't nag per asset.

Surface an opportunity only when a concrete signal is present:

| Signal detected                                          | Offer                                                                                                  |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| On-screen text / a script with no voiceover              | TTS voiceover (audio engine)                                                                           |
| Emoji or a `<div>` styled as an icon                     | resolve real `icon`s                                                                                   |
| Image that is a placeholder, tiny, or upscaled-looking   | a better `image` (and/or upscale — see `references/operations.md`)                                     |
| Hard scene cuts / transitions with no sound              | transition `sfx`                                                                                       |
| A piece over ~10s with no music bed                      | `bgm`                                                                                                  |
| Footage that reads under/over-exposed or color-cast      | a corrective grade (inspect it with `hyperframes media-treatment --selector '#hero' --analyze --json`) |
| Photographic media that feels visually flat or off-topic | one specific source-appropriate preset or custom treatment, with the intended target named             |
| A meaningful media entrance/reveal that feels static     | one supported seek-safe treatment animation; preserve color unless the request also justifies a preset |

Rules that keep this a help, not nagware: **grounded, not generic** (no signal → no suggestion); **opinionated + concrete** (propose the specific fix with defaults chosen — the human approves **all / some / none**); **once per project** (one consolidated ask; respect "leave it"); **surface, never silently mutate** (color grades especially: propose and preview — a gray-world "correction" ruins an intentional sunset or neon look).

## Where to look — read only the file your task needs

| Task                                                                      | Read                             |
| ------------------------------------------------------------------------- | -------------------------------- |
| resolve / reuse / adopt / ingest, flags, cascade, inventory               | `references/resolve.md`          |
| color grading, LUTs, smart grade (`--for`), grade-compare                 | `references/grading.md`          |
| voiceover / TTS, music, SFX, captions, transcription (audio engine)       | `references/audio.md`            |
| cut / reframe / transform existing media, exact error diffusion, HEVC     | `references/operations.md`       |
| source-aware creative treatments, realtime effects, overlays, reveals     | `references/media-treatments.md` |
| install + auth, provider table, RAM ladders, `--local-only`, `--provider` | `references/setup-providers.md`  |
| remembered preferences + frozen recipes (user memory)                     | `references/memory.md`           |
| ownership matrix, usage stats, telemetry, privacy (maintainer-facing)     | `references/meta.md`             |

## Dónde encaja

- Categoría: [Vídeo y animación](https://skillsagentes.com/categorias/video.md) — Skills que generan, editan y animan vídeo: guion y storyboard, render, subtítulos y doblaje, y los modelos que lo producen.
- Creador: [heygen-com](https://skillsagentes.com/creators/heygen-com.md) — 25 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Pr To Video](https://skillsagentes.com/skills/heygen-com/hyperframes/pr-to-video.md): Convierte un pull request de GitHub (URL, owner/repo#N o 'este PR') en un video explicativo del cambio de código —changelog, feature, fix o refactor— construido a partir del diff, commits y archivos.
- [Product Launch Video](https://skillsagentes.com/skills/heygen-com/hyperframes/product-launch-video.md): Convierte una URL de producto o marketing, un guion pegado o un brief en un video de lanzamiento/promoción — promos SaaS, revelaciones de funciones, demos, lanzamientos de apps y empresas.
- [Hyperframes](https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes.md): Punto de entrada obligatorio para crear, editar, animar o renderizar video, animaciones o motion graphics con HyperFrames, así como para inspeccionar, validar o publicar proyectos existentes.
- [Hyperframes Cli](https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes-cli.md): Usa el flujo de desarrollo de la CLI de HyperFrames: init, add, catalog, capture, lint, check, snapshot, compare, preview, render, publish, cloud, lambda, feedback, doctor y más; también para diagnosticar fallos de build o render.
- [Faceless Explainer](https://skillsagentes.com/skills/heygen-com/hyperframes/faceless-explainer.md): Convierte texto (artículo, notas, tema o brief) en un video explicativo faceless: sin sitio ni material que capturar, los visuales se inventan por escena (tipografía, gráficos abstractos, diagramas, data-viz).

## Skills relacionadas

- [Talking Head Recut](https://skillsagentes.com/skills/heygen-com/hyperframes/talking-head-recut.md): Empaqueta un video de talking-head/entrevista/podcast existente con tarjetas gráficas superpuestas (títulos, lower-thirds, callouts, citas, PiP) sincronizadas con la transcripción, en 16:9, 9:16 o 4:5; el clip se reproduce intacto debajo.
- [General Video](https://skillsagentes.com/skills/heygen-com/hyperframes/general-video.md): Crea o edita una composición HyperFrames personalizada cuando ningún workflow especializado aplica, o cuando BRIEF.md fija flow: companion; para piezas largas o multi-escena, reels y montajes.
- [Hyperframes Creative](https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes-creative.md): Dirección creativa no animada para vídeos HyperFrames: manejo de specs de diseño (frame.md / design.md), paletas, tipografía, narración, beats, audio-reactive y composición.
- [Pr To Video](https://skillsagentes.com/skills/heygen-com/hyperframes/pr-to-video.md): Convierte un pull request de GitHub (URL, owner/repo#N o 'este PR') en un video explicativo del cambio de código —changelog, feature, fix o refactor— construido a partir del diff, commits y archivos.
- [Hyperframes Registry](https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes-registry.md): Instala, descubre y conecta blocks y components del registry en composiciones HyperFrames, incluyendo cómo autorar nuevos items para contribuir al proyecto.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)