Communitygithub.com

leocosta/octopus

Convierte una aplicación en ejecución en un video promocional dinámico de alta fidelidad, manejando el producto real (Chrome sin interfaz) contra un entorno de demostración, capturando capturas limpias y componiendo un montaje con diseño en movimiento (tipografía cinética, zooms cinematográficos, destacados tipo spotlight, marcos de teléfono, con música) usando HyperFrames + GSAP. Independiente de la aplicación: lee un `promo.config` y una lista de beats por proyecto; extrae automáticamente el sistema de diseño de la aplicación objetivo para que las superposiciones coincidan con su marca. Genera un master 16:9 y un corte 9:16.

¿Qué es octopus?

Este skill, `leocosta/octopus`, es una herramienta avanzada para generar videos promocionales de alta fidelidad directamente desde una aplicación real en funcionamiento. A diferencia de las grabaciones de pantalla tradicionales, este skill automatiza todo el proceso: inicia la aplicación en un navegador Chrome sin interfaz (headless) contra un entorno de demostración, captura capturas de pantalla limpias de cada pantalla y luego compone un video con efectos de diseño en movimiento profesionales. Utiliza HyperFrames (HTML a MP4) para la renderización, lo que garantiza resultados deterministas, re-ejecutables y controlables por marca, evitando los fallos comunes de las grabaciones de pantalla en vivo. El skill es independiente de la aplicación, ya que extrae automáticamente el sistema de diseño (colores, fuentes, radios) de la aplicación objetivo para que las superposiciones (tipografía cinética, zooms, destacados, marcos de teléfono) coincidan con su marca. Requiere Node 20+, Chrome de sistema, ffmpeg y un entorno de demostración ejecutable de la aplicación objetivo. El skill está diseñado para trabajar junto con `launch-feature` (que genera el guion/guion de video en prosa) y `octopus` (que convierte la lista de beats en el video final con música). Es ideal para páginas de aterrizaje, anuncios de funciones o cualquier escenario donde se necesite un video de demostración de producto de alta calidad sin la intervención manual de un editor de video.

Compatible con~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/leocosta/octopus/tree/HEAD/skills/motion-promo

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Protocolo de Video Promocional con Movimiento

Descripción General

Este skill renderiza un video promocional dinámico de un producto real, con calidad de anuncio, no una grabación de pantalla ni una maqueta. Conduce la aplicación real en un navegador sin interfaz gráfica contra un entorno de demostración, captura fotogramas limpios de cada pantalla y compone un montaje con diseño en movimiento sobre ellos: tipografía cinética, zooms cinematográficos, destacados tipo spotlight que siguen el zoom, marcos de teléfono para pantallas móviles, cortes de escena rítmicos y una banda sonora. La salida es un master en 16:9 y un corte vertical en 9:16.

Es la contraparte de renderizado de launch-feature: launch-feature escribe un video-script.md (el guion/beats en prosa); motion-promo convierte una lista de beats en el video final con música. Cuando se ejecutan ambos, se encadenan — el guion de launch-feature → los beats de motion-promo.

Por qué HyperFrames (HTML→MP4) y no grabación de pantalla: determinista, re-ejecutable, controlable por marca, y evita los modos de fallo de capturar la navegación en vivo (ver Reglas). La aplicación solo se usa para producir fotogramas + tokens de diseño; todo el movimiento se crea.

Cuándo Usarlo

  • Una página de aterrizaje / ventas necesita un video demo o de héroe del producto.
  • Anuncias una función y quieres el video renderizado, no solo el guion.
  • Tienes un tenant de demostración/sandbox con datos realistas para mostrar.

No usarlo para: tutoriales internos donde la fidelidad no importa (una captura de pantalla en bruto es más barata), o aplicaciones sin un entorno de demo ejecutable.

Prerrequisitos y Secretos

No se requieren claves API / secretos. La renderización de HyperFrames no necesita clave (HTML→MP4 local), y las fuentes (Google Fonts) + la música por defecto (incompetech) son URLs públicas. La única credencial es el inicio de sesión de demo de la aplicación objetivo, que vive en el archivo promo.config.mjs del repositorio objetivo — nunca en este skill. La autenticación es una receta conectable: authInject() devuelve valores a inyectar (token en localStorage, cookie, API-key, selección de tenant multi-paso), o authFlow(page) CONDUCE una interfaz de inicio de sesión interactiva (Azure AD / Entra, Okta, Google SSO) y el motor captura la sesión (localStorage + sessionStorage + cookies, incluyendo HttpOnly). Las credenciales SSO provienen del entorno, no del archivo. El navegador sin interfaz no puede pasar MFA interactivo — usa una cuenta de demo exenta de MFA (excepción de Acceso Condicional) o una contraseña de aplicación.

Dependencias del sistema (tú las instalas — el skill no puede): Node 20+, Chrome de sistema (google-chrome/Chromium), ffmpeg + ffprobe. Salida de red para fuentes/música.

Dependencias automáticas/bajo demanda: hyperframes se obtiene bajo demanda mediante npx (no pre-instalación). puppeteer-core es una dependencia npm andamiada — usa el Chrome de sistema y no descarga un Chromium.

Configuración: andamia templates/ en video/<slug>/ (incluye hyperframes.json; meta.json se genera con compose-gen), renombra gitignore → .gitignore, luego npm install y npm run preflight (verifica Chrome, ffmpeg/ffprobe y puppeteer-core; falla ruidosamente si falta alguno). Ejecuta el pipeline paso a paso o npm run build.

  • Un demo/sandbox ejecutable de la aplicación objetivo.

Entradas

Todo lo específico del proyecto vive en el repositorio objetivo, nunca en este skill:

  1. promo.config.mjs — el contrato (ver templates/promo.config.example.mjs). URL de la aplicación / cómo servirla, receta de autenticación, cuenta/tenant de demo, rutas de salida y preferencia de música. Los tokens de diseño se extraen automáticamente (paso 2) pero se pueden sobrescribir aquí.
  2. beats.json — la lista ordenada de tomas (ver templates/beats.schema.json). Cada beat = una pantalla (ruta o fotograma capturado) + objetivo de resaltado opcional + texto de llamada + viewport (escritorio/móvil).

Andamia ambos en video/<slug>/ dentro del repositorio objetivo desde templates/.

Protocolo

Trabaja dentro de video/<slug>/ en el repositorio objetivo. Cada paso tiene una verificación.

0. Curar los datos de demo (haz esto primero — define el éxito o fracaso del video)

Los datos de demo/sandbox suelen estar obsoletos o puestos a cero para el período actual (facturas del mes actual impagas, embudos vacíos), lo que se lee como "$0 de ingresos" junto a "en piloto automático" — activamente fuera de mensaje. Antes de capturar, escribe una semilla idempotente y relativa a la fecha actual que le dé a cada beat números saludables (ver Reglas → Datos de demo en cero). Verifica consultando las métricas que mostrará cada beat.

1. Servir la aplicación contra la API de demo, en un origen permitido por CORS

Construye/sirve la aplicación apuntando a la API de demo. El origen de servicio debe estar en la lista de permitidos CORS de la API o cada solicitud de datos será bloqueada y las pantallas se renderizarán vacías (ver Reglas → Origen CORS). Sondea la lista de permitidos de la API y sirve en un puerto permitido. Verifica: una ruta profunda devuelve 200 y una solicitud autenticada a /api/... desde ese origen devuelve 2xx.

2. Extraer el sistema de diseño de la aplicación objetivo

Ejecuta templates/engine/extract-design.mjs contra la aplicación autenticada y servida. Muestrea los estilos calculados (fondo de página, color primario/de acento de botones/enlaces, familias de fuentes de encabezado y mono, radio) → design.tokens.json. Estos alimentan la composición como variables CSS para que las superposiciones cinéticas, el acento y las fuentes coincidan automáticamente con la marca de la aplicación. Revisa y sobrescribe en promo.config si un token muestreado es incorrecto.

3. Capturar fotogramas limpios por beat

Ejecuta templates/engine/capture.mjs. Se autentica (mediante la receta authInject de la configuración), navega a la ruta de cada beat en su viewport, espera a que los datos reales lleguen (no solo network-idle — ver Reglas) y toma capturas de pantalla en assets/<beat>.png. Verifica que cada fotograma muestre contenido cargado (tamaño > ~10 KB, verifica visualmente que el elemento objetivo esté presente).

4. Definir los beats + generar la composición

Rellena beats.json (ruta/fotograma, resaltado {x,y,w,h,label} en el espacio de píxeles del fotograma — o {selector,label,padding?}, medido automáticamente por capture.mjs y preferido sobre coordenadas ajustadas manualmente, llamada {kicker,headline,sub}, viewport, duraciones). Ejecuta templates/engine/compose-gen.mjs → index.html desde templates/composition.html, inyectando tokens + beats. Mantenlo conciso: 3-5 s por beat, cortes duros, una idea por beat.

5. Obtener una pista de música gratuita

Ejecuta templates/engine/fetch-music.mjs → assets/music.mp3. La fuente predeterminada es CC-BY (incompetech); CC-BY requiere atribución (regístrala para la descripción del LP). Prefiere una pista proporcionada por el proyecto/CC0 cuando esté disponible.

6. Renderizar

npx hyperframes render → MP4 silencioso. Ejecuta hyperframes lint/inspect primero; trata el desbordamiento decorativo/de animación de salida fuera del lienzo como ruido, el recorte de texto real como una corrección.

7. Revisar fotogramas y corregir la alineación de los resaltados

Extrae fotogramas al inicio y final de cada zoom y examínalos visualmente. El defecto #1: el resaltado tipo spotlight se desvía de su objetivo durante el zoom — porque el cuadro de resaltado debe ser un hijo del contenedor escalado (ver Reglas → Seguimiento del resaltado). También verifica: sin pantallas vacías/de spinner, las pantallas móviles encajan limpiamente en el marco del teléfono, el texto es legible.

8. Mezclar la música

Ejecuta templates/engine/mux.mjs → MP4 final con puntuación musical (loudnorm, fundido de entrada/salida, -shortest). Verifica que la salida tenga una pista de audio y que coincida con la duración del video.

9. Derivar el corte 9:16

mux.mjs --reframe produce un corte de 1080×1920. No recortes al centro (corta las llamadas ancladas en la parte inferior) — usa un letterbox desenfocado que preserve todo el fotograma; los beats móviles ya están centrados.

Reglas (ganadas con esfuerzo — no las reaprendas)

  • Seguimiento del resaltado. Un rectángulo de resaltado/spotlight sobre una pantalla que hace zoom DEBE ser un hijo del mismo elemento que recibe la transformación scale, en el espacio de coordenadas de píxeles del fotograma. Como hermano, permanece fijo mientras la imagen se acerca y se desvía del objetivo a lo largo de la toma.
  • Datos de demo en cero. El período actual a menudo no está pagado/vacío. Cúralo con una semilla que sea idempotente (ids deterministas, eliminar-luego-insertar) y relativa a current_date para que se autocure cada período.
  • Origen CORS. Una compilación servida localmente que llama a una API de demo desplegada es de origen cruzado. Sirve en un origen que la API permita en su lista (sondea) — nunca deshabilites la seguridad web del navegador para solucionarlo.
  • Esperar datos reales. networkidle2 puede resolverse antes de que llegue la solicitud de datos de la aplicación → capturas un spinner. Espera adicionalmente una respuesta /api/... exitosa (o el selector de contenido objetivo) antes de tomar la captura.
  • HyperFrames sobre captura en vivo. La transmisión de pantalla CDP deja de emitir fotogramas en una página visualmente estática y funciona por debajo de los fps nominales; crear en HTML (GSAP) evita ambos problemas. Si alguna vez debes grabar en vivo, mueve el cursor y codifica a los fps efectivos.
  • Licencias de música. CC-BY (incompetech/Kevin MacLeod) necesita atribución en la descripción del LP; CC0 (Pixabay, etc.) no. Nunca subas un clip extraído sin licencia en una página publicada.
  • Concatenar con el filtro, no con el demuxer si los segmentos tienen fps variables — el demuxer descarta fotogramas silenciosamente.

Extracción del sistema de diseño (marca independiente)

La composición es neutra en cuanto a marca; extract-design.mjs llena sus variables CSS desde la propia aplicación objetivo: --bg (fondo del cuerpo), --accent (color primario/de enlace), --fg (color de encabezado), --font-hero/--font-mono (familias de fuentes calculadas), --radius. Esto es lo que permite que un solo skill produzca promociones alineadas con la marca para cualquier aplicación sin tener que seleccionar tokens manualmente. Siempre revisa los tokens muestreados — un color de bajo contraste o ad-hoc puede muestrearse incorrectamente ocasionalmente; sobrescribe en promo.config.design.

Errores

  • La aplicación no se autentica sin interfaz gráfica → la receta authInject de la configuración es incorrecta; verifica que los tokens lleguen a localStorage/cookies antes de la primera navegación.
  • Las pantallas se renderizan vacías → origen CORS (paso 1) o espera de datos (Regla) omitido.
  • Errores de renderizado fuera del lienzo → el recorte de texto real necesita fuente más pequeña / ajuste de línea; el desbordamiento decorativo/de salida es ruido.
  • Resaltado desalineado → no es un hijo del contenedor escalado (Regla).

Composición con el rol de marketer

Usa el rol de marketer para el texto: los kickers, titulares y el encuadre de valor por beat deben seguir la voz del proyecto (launch-feature's voice.md / marketer-hooks.md cuando estén presentes). Mantén el texto en pantalla a un kicker + un titular corto + una línea secundaria por beat.

Skills relacionados