media-use
Resuelve necesidades de medios en archivos locales congelados. Un verbo, cuatro tipos, cero ruido de contexto.
Cuándo usarlo
Usa resolve siempre que una composición necesite medios — música de fondo, efectos de sonido, imágenes o iconos. media-use busca en el catálogo de HeyGen, descarga la mejor coincidencia, la congela localmente y la registra en un manifiesto. El agente recibe una sola línea; todo el ruido de búsqueda se queda en disco.
Resolve
node <SKILL_DIR>/scripts/resolve.mjs --type <tipo> --intent "<descripción>" --project <directorio>
Devuelve una línea: resolved <id> → <ruta> (<tipo>, <metadatos>)
Tipos
| Tipo | Qué encuentra | Proveedor |
|---|---|---|
bgm | Música de fondo | Catálogo de audio de HeyGen (10k+ pistas) |
sfx | Efectos de sonido | Biblioteca empaquetada de 19 archivos + catálogo de HeyGen |
image | Fotos, fondos | Búsqueda de activos de HeyGen (75k+ vectores) |
icon | Iconos, logotipos | Búsqueda de activos de HeyGen (tipo=icono) |
Ejemplos
# Música de fondo
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "lanzamiento tecnológico alegre" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
# Efecto de sonido
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
# Imagen
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "fondo tecnológico degradado" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)
# Icono
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "cohete" --project .
# → resolved icon_001 → .media/images/icon_001.png (icon, transparente)
Banderas
| Banda | Descripción |
|---|---|
--type, -t | Tipo de medio: bgm, sfx, image, icon |
--intent, -i | Lo que necesitas (lenguaje natural) |
--entity, -e | Nombre de la entidad para coincidencia en caché (opcional) |
--project, -p | Directorio del proyecto (predeterminado: .) |
--adopt | Importación masiva de activos existentes de assets/ al manifiesto |
--json | Salida en JSON en lugar de resultado en una línea |
Cómo funciona
- Verifica
.media/manifest.jsonldel proyecto para una coincidencia exacta con la solicitud - Escanea el directorio
assets/existente en busca de archivos no registrados que coincidan con la necesidad - Verifica la caché global
~/.media/para un activo reutilizable - Busca a través del proveedor (catálogo de audio de HeyGen, búsqueda de activos de HeyGen)
- Congela el archivo en
.media/<tipo>/, lo registra en el manifiesto, regeneraindex.md
El agente recibe una línea. Los candidatos, puntuaciones y procedencia se quedan en disco.
Adoptar proyectos existentes
La mayoría de los proyectos HyperFrames ya tienen activos en assets/. media-use los adopta:
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
# → adopted 9 assets from assets/
# bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
# image_001 → assets/images/avatar.jpg (image, 400×400)
ffprobe extrae la duración y dimensiones reales. Durante resolve, los archivos no registrados en assets/ que coincidan con la solicitud se adoptan sobre la marcha.
Leer el inventario
Después de resolve o adopt, lee .media/index.md para ver el inventario completo:
# .media · 4 activos
id type dur dims path description
bgm_001 bgm 25s — .media/audio/bgm/bgm_001.mp3 lanzamiento tecnológico alegre
sfx_001 sfx 0.6s — .media/audio/sfx/sfx_001.mp3 whoosh
image_001 image — 1920×1080 .media/images/image_001.jpg fondo tecnológico degradado
icon_001 icon — 200×200 .media/images/icon_001.png cohete
Reutilización entre proyectos
Los activos se almacenan en caché automáticamente al resolver. Las resoluciones posteriores para la misma solicitud usan la caché global en ~/.media/ — sin redescarga, sin llamada al proveedor. Promociona un activo explícitamente con organize --promote <id> para hacerlo reutilizable en todos los proyectos.
Archivos
.media/manifest.jsonl— SSOT de máquina, un registro JSON por línea.media/index.md— tabla legible por el agente (id, type, dur, dims, path, description)~/.media/— caché global de reutilización entre proyectos (direccionada por contenido, SHA-256)
Herramientas CLI utilizadas
| Herramienta | Propósito | ¿Requerida? |
|---|---|---|
ffprobe | Sondear duración, dimensiones, códec al adoptar | Sí |
heygen | Catálogo de audio, búsqueda de activos | Para los proveedores |
Instala la CLI heygen (binario estático único, sin tiempo de ejecución) y autentícate:
curl -fsSL https://static.heygen.ai/cli/install.sh | bash # instala la última versión en ~/.local/bin
heygen update # si ya está instalado: necesita >= v0.1.6
export HEYGEN_API_KEY=<tu-clave> # o: heygen auth login --key <clave>
Requiere heygen >= v0.1.6 — los proveedores etiquetan las solicitudes con la bandera permitida --headers 'X-HeyGen-Client-Source: media-use', añadida en v0.1.6. asset search es un comando previo al lanzamiento oculto de heygen --help, pero funciona. Sin heygen en PATH (o una clave válida) los proveedores imprimen un diagnóstico de una línea a stderr y la resolución falla con "ningún proveedor pudo resolver".