media-use: Antes de obtener audio/imágenes, ejecuta
/media-usepara resolver BGM/SFX/imágenes del catálogo de HeyGen. Ejecuta--adoptprimero para registrar activos existentes. Consulta la habilidad/media-use.
De Lanzamiento de Producto a HyperFrames
Usa esta habilidad para capturar un producto, entender su marca, planificar un video de lanzamiento y construirlo cuadro por cuadro en HyperFrames.
Confirma la ruta antes del Paso 0. Eres el orquestador. Ejecuta cada paso, verifica su compuerta, y solo entonces continúa al siguiente paso. Esta habilidad es para un producto que se está comercializando, lanzando, promocionando o revelando, incluyendo solicitudes como "promo para nuestro sitio" cuando el propósito es promocional. Enruta otras intenciones a otro lugar: un recorrido general de sitio web no relacionado con un lanzamiento ->
/general-video; un explicador de tema sin producto ->/faceless-explainer; un PR de GitHub ->/pr-to-video; subtítulos en material existente ->/embedded-captions; un gráfico animado corto sin narración ->/motion-graphics. Si el usuario dice solo "haz un video" o la ruta es incierta, lee primero/hyperframes.
Eres el orquestador. Trabaja en videos/<proyecto>/. Ejecuta los pasos en orden y pasa cada compuerta antes de continuar. Los pasos con compuerta de usuario son el Paso 0, el Paso 3 y el Paso 6. Haz cada paso tú mismo excepto el Paso 5, donde despachas un subagente por cuadro. No pongas reglas de diseño o movimiento aquí; esas viven en el subagente trabajador de cuadros, en las reglas locales de esta habilidad ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/, y en hyperframes-creative.
Flujo de trabajo: Paso 0 configuración -> hyperframes.json; Paso 1 captura -> capture/; Paso 2 sistema de diseño -> frame.md; Paso 3 storyboard/guion -> STORYBOARD.md y SCRIPT.md; Paso 3.1 audio -> audio_meta.json; Paso 4 diseño visual -> STORYBOARD.md enriquecido; Paso 5 cuadros -> compositions/frames/NN-*.html y index.html; Paso 6 renderizado final -> renders/video.mp4.
Paso 0: Configuración y Resumen
Objetivo: Fijar el resumen básico del video y crear el proyecto HyperFrames si es necesario.
Inicializa solo si falta hyperframes.json. Nombra <proyecto> a partir de la marca o dominio en kebab-case, por ejemplo acme-promo; nunca uses el nombre del espacio de trabajo o la marca de tiempo.
npx hyperframes init "videos/<proyecto>" --non-interactive --example=blank — init verifica las habilidades instaladas contra las últimas en GitHub y actualiza el conjunto global si alguna está desactualizada.
Muestra el estado de inicio de sesión antes del resumen — ejecuta npx hyperframes auth status y transmite su salida textualmente (no la parafrasees ni la reescribas). Informa si la voz/BGM usará HeyGen o motores locales y, cuando no se haya iniciado sesión, cómo iniciarla. Si no ha iniciado sesión, DETENTE y espera a que el usuario elija: iniciar sesión, o decir "offline"/"ir" para continuar con motores locales — antes de preguntar por el resumen o cualquier otra cosa. Trátalo como un punto de decisión real, no una nota pasajera; no incluyas la elección en la pregunta del resumen, y no escribas claves en un .env por repositorio. (En modo autónomo, anota el estado y continúa offline). Consulta ../hyperframes-media → Preflight para la guía canónica.
Compuerta: hyperframes.json existe, y el ángulo, duración, relación de aspecto e idioma están fijados; se mostró el estado de inicio de sesión (iniciado sesión, o continuando offline).
Paso 1: Capturar activos
Objetivo: Recopilar el material fuente, las señales de marca y los activos utilizables para el video.
Clasifica la entrada y elige la ruta. URL explícita -> captúrala y usa el sitio para la narración y los activos. Script/resumen pegado -> guárdalo textualmente como user_script.txt, pregunta una vez "¿usarlo textualmente o reestructurarlo?", guarda la respuesta como VO_MODE, luego resuelve el objetivo de captura: URL en el texto -> úsala; solo nombre de marca -> WebSearch, confirma la URL en una línea, luego rastrea; sin URL/sitio -> ruta sin captura.
Ejecuta la captura con: npx hyperframes capture "<URL>" -o ./capture
Si existe GEMINI_API_KEY, GOOGLE_API_KEY o una clave de OpenRouter, la captura subtitula automáticamente los activos en capture/extracted/asset-descriptions.md. Esto no es una compuerta de revisión. Sin una clave de visión, usa el contexto DOM y continúa.
Ruta sin captura: crea capture/extracted/tokens.json, capture/extracted/visible-text.txt, capture/extracted/asset-descriptions.md y capture/assets/ manualmente. tokens.json debe ser { "title": "", "description": "", "colors": [], "fonts": [] }; completa título/descripción a partir del resumen cuando sea posible. visible-text.txt contiene el resumen o script completo. asset-descriptions.md debe indicar que no se capturaron activos a menos que el usuario haya dado notas sobre activos.
Compuerta: existen capture/extracted/tokens.json, capture/extracted/visible-text.txt, capture/extracted/asset-descriptions.md y capture/assets/; puedes expresar la marca en una oración clara. Trata asset-descriptions.md como el inventario principal de activos. Si falta después de una captura real, detente e informa que la captura está incompleta. Si existe capture/BLOCKED.md, síguelo.
Paso 2: Sistema de Diseño
Objetivo: Elegir un preset de cuadro ya incluido; un script lo convierte en el frame.md + piel de subtítulos de este video.
Tú haces la única decisión — qué preset. Lee ../hyperframes-creative/references/design-spec.md y elige el preset cuyo estilo se adapte mejor a la marca y al resumen. Luego ejecuta:
node <SKILL_DIR>/scripts/build-frame.mjs --preset <nombre> --hyperframes .
El script hace el resto de forma determinista: copia el FRAME.md del preset -> frame.md y remezcla sobre los tokens de marca en capture/extracted/tokens.json (mapea los colores de la marca sobre las claves de color del preset según el rol — tinta, lienzo, acentos — manteniendo claves/estructura/componentes; intercambia las fuentes de display + cuerpo del preset por las de la marca), copia la piel de subtítulos del preset a .hyperframes/caption-skin.html, y se autovalida (sale con 1 si hay un mapeo roto). Procede al siguiente paso tan pronto como salga con 0 — sin editar manualmente la especificación.
tokens.json sin colores/fuentes de marca (ej. sin captura) -> el script conserva la paleta propia del preset, un diseño completo y entregable. Si el resumen nombra colores/fuentes de marca que la captura no encontró, agrégalos a capture/extracted/tokens.json antes de ejecutar (o usa el design.md del usuario para poblarlo); solo ajusta frame.md manualmente después si un mapeo realmente lo necesita.
Compuerta: build-frame.mjs salió con 0 — frame.md existe a partir de un preset nombrado, y (cuando el preset incluye una) .hyperframes/caption-skin.html existe como fuente de la piel de subtítulos.
Paso 3: Storyboard y Guion
Objetivo: Convertir el resumen y el material capturado en un plan de historia cuadro por cuadro aprobado.
Lee references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes-core/references/storyboard-format.md y ../hyperframes-core/references/script-format.md. Úsalos para escribir STORYBOARD.md y, cuando se necesite narración, SCRIPT.md.
Usa story-design.md para el blueprint de la historia, el gancho, la lógica de persuasión, los beats, VO_MODE y las elecciones de activos. Como guía suave, consulta el menú rol->blueprint en ../hyperframes-animation/blueprints-index.md: para cada beat, anota un id de blueprint candidato cuando uno encaje. La verdad de la historia aún decide qué beats existen — nunca fuerces un beat para que encaje en un blueprint, y nunca inventes un beat solo porque una forma probada esté disponible. Elige los asset_candidates de cada cuadro visual de capture/extracted/asset-descriptions.md (el inventario canónico) — no navegues por capture/assets/ en bruto. No le pidas al usuario que elija activos a menos que ese inventario falte o sea inutilizable. Usa los campos exactos requeridos de las referencias de storyboard y guion.
Después del borrador, muestra un resumen cuadro por cuadro. En ese mismo mensaje, pide al usuario dos cosas: (a) aprobar o solicitar cambios, y (b) si quiere una vista previa en vivo del andamio del storyboard (npx hyperframes preview) — ábrela solo si dice sí. Itera hasta que esté aprobado, y lleva la elección de vista previa al Paso 6.
Compuerta: STORYBOARD.md existe, cada cuadro visual tiene asset_candidates, SCRIPT.md existe cuando se necesita narración, y el usuario aprobó el plan cuadro por cuadro.
Paso 3.1: Audio
Objetivo: Generar narración, tiempos de palabras, música y metadatos de audio a partir del guion aprobado.
Inicia el audio después de la aprobación del Paso 3. Ejecútalo en segundo plano, luego continúa al Paso 4.
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
El script de audio maneja la narración, los tiempos de palabras, la búsqueda de BGM en la biblioteca musical de HeyGen y los metadatos de temporización. El estado de ánimo de BGM proviene del campo music: del storyboard. Esto utiliza la API de Audio de HeyGen para recuperación, no generación, y usa la misma credencial ~/.heygen que TTS. Para detalles del proveedor, lee ../hyperframes-media/references/tts.md.
Si no hay narración y no hay SCRIPT.md, omite la generación de voz. BGM aún puede ejecutarse si el storyboard tiene un estado de ánimo musical.
Compuerta: el trabajo de audio ha comenzado, o el proyecto está marcado como silencioso.
Paso 4: Diseño Visual de Cuadros
Objetivo: Añadir la dirección visual, la intención de diseño y las elecciones de movimiento a cada cuadro del storyboard.
Edita STORYBOARD.md en su lugar. No crees otro storyboard. Usa frame.md como fuente de verdad para color, tipografía, sensación de diseño y estilo.
Lee references/visual-design.md, ../hyperframes-animation/blueprints-index.md, references/motion-language.md y ../hyperframes-animation/rules-index.md. Usa visual-design.md para el método (la secuencia de tomas con código de tiempo, el vocabulario de Diseño en línea y el bloque requerido ## Video direction). Usa ../hyperframes-animation/blueprints-index.md para elegir la forma de toma de cada cuadro. Usa motion-language.md (el vocabulario de movimiento + la doctrina de movimiento) y ../hyperframes-animation/rules-index.md (nombres de reglas válidos) para el movimiento — no inventes nombres de movimiento.
Para cada cuadro visual, escribe una secuencia de tomas con código de tiempo en STORYBOARD.md según el método de visual-design.md: elige el blueprint del cuadro (o compón), instáncialo con el contenido de ESTE producto, y ritma la revelación de cada Escena con la voz en off para que el cuadro se desarrolle durante toda su duración en lugar de cargar todo al inicio y luego congelarse. Indica el diseño y el movimiento en línea por Escena (vocabularios en visual-design.md y motion-language.md). Añade un bloque ## Video direction para todo el video.
No cambies la historia, el guion, las elecciones de activos, asset_candidates, transition_in ni el material fuente capturado. No escribas HTML en este paso.
Escenifica los activos nombrados después de que el diseño visual esté bloqueado:
node <SKILL_DIR>/scripts/stage-assets.mjs --storyboard ./STORYBOARD.md --hyperframes .
Compuerta: cada cuadro visual tiene una secuencia de tomas con código de tiempo cuyas revelaciones están ritmadas con la voz en off (sin carga frontal); existe ## Video direction; assets/ contiene los activos nombrados.
Paso 5: Construir Cuadros
Objetivo: Construir cada cuadro del storyboard como una composición HTML y ensamblar el video reproducible.
Espera a que termine el audio del Paso 3.1 si se inició. Luego sincroniza duraciones y obtén SFX; omite ambos si es silencioso.
node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
La sincronización de duración es mecánica: la duración real de la voz gana; los cuadros silenciosos mantienen estimaciones; nunca edites manualmente las duraciones sincronizadas.
Antes del despacho, lee sub-agents/frame-worker.md y ../hyperframes-core/references/subagent-dispatch.md. Despacha un subagente por cuadro, en paralelo si es posible; de lo contrario, ejecuta trabajadores en oleadas. Cada trabajador recibe exactamente un cuadro.
Cada contexto de trabajador debe incluir PROJECT_DIR, frame_id, tamaño del lienzo, estado de subtítulos y banda de exclusión si los subtítulos están habilitados, y RULES_DIR como la ruta absoluta a ../hyperframes-animation/rules/ de esta habilidad. Cada trabajador lee frame.md, su propio bloque ## Frame N de STORYBOARD.md, la receta de regla local (../hyperframes-animation/rules/<id>.md) para cada movimiento citado, y la plantilla del blueprint del cuadro (../hyperframes-animation/blueprints/<id>.md). Cada trabajador escribe solo compositions/frames/NN-*.html. Los trabajadores nunca deben editar STORYBOARD.md.
A medida que cada trabajador regresa, el orquestador marca ese cuadro como animated en STORYBOARD.md.
Después de que existan los tiempos de audio, construye los subtítulos en segundo plano y ensambla el índice:
node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
captions.mjs usa el archivo .hyperframes/caption-skin.html del proyecto (copiado en el Paso 2) como apariencia de subtítulos, inyectando tokens de marca desde frame.md; sin piel presente, renderiza la píldora predeterminada integrada. captions: skipped (<motivo>) es válido. Continúa sin subtítulos cuando se omitan explícitamente.
Compuerta: cada cuadro está marcado como animated, existe index.html, y los subtítulos están construidos u omitidos explícitamente.
Paso 6: Finalizar
Objetivo: Verificar el video ensamblado, obtener la aprobación del usuario y renderizar el MP4 final.
Inyecta transiciones, ejecuta comprobaciones, pausa para revisión, luego renderiza.
node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .
node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html
npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect
npx hyperframes snapshot --at <frame-midpoints>
snapshot une los cuadros capturados en una hoja de contactos (snapshots/contact-sheet.jpg). Échale un vistazo; si nada está claramente roto, continúa — no te demores aquí.
Si un comando falla, muestra stderr y detente — no acumules comandos de recuperación. Arrégialo tú mismo: la edición segura más barata en compositions/frames/NN-*.html, luego vuelve a ejecutar la comprobación fallida.
Después de que las comprobaciones pasen, pausa para la revisión del usuario. El video está ensamblado, visible y editable en Studio. Gestiona la vista previa solo una vez entre el Paso 3 y el Paso 6: ábrela si el usuario lo pidió antes, ofrécela si la rechazó antes, y no preguntes de nuevo si ya está revisando en Studio.
Vista previa: npx hyperframes preview
Renderiza solo cuando el usuario lo solicite.
npx hyperframes render videos/<proyecto>/renders/video.mp4
El renderizado es el paso final en el workflow principal. Este paso también puede importar el renderizado a la biblioteca de activos del proyecto después de la finalización.
Compuerta: todas las comprobaciones de transición pasaron, se tomaron capturas de pantalla y el usuario aprobó; el MP4 renderizado existe (si el usuario lo solicitó).