demo-video
Necesitas un video terminado y diseñado de una aplicación. Esta habilidad es el pipeline probado y listo para usar. Se basa en HyperFrames (HTML→video) pero añade las partes que son dolorosas de redescubrir: cómo grabar la aplicación tú mismo, las soluciones de ffmpeg de esta máquina, las recetas de edición exactas, el sistema de diseño con marca y las trampas que hacen perder horas.
Nada aquí tiene marca. El aspecto es un diseño con fichas intercambiables; de qué marca es un video es un paso, no una suposición — véase Fase 0B.
🚦 Las fases se agrupan por tema, no por orden de trabajo
Lee esto antes de seguir cualquier cosa a continuación en secuencia. Los mecanismos de captura están documentados primero porque van juntos, pero la captura no es lo primero que haces:
El concepto viene primero: ¿para qué es ESTO? → el arco → PLAN.md (+ SCRIPT.md) → APROBADO
(ese es el trabajo de la habilidad `video-plan`, no esta) │
│
↓ solo ahora existe el metraje ────────────────────────────────────────────────────────────────┘
Fase 0 entorno → 0B marca → 1A captura / 1B ingesta → 3 preparación → 4 composición
→ 5 verificación → 6 renderizado
Grabar primero parece más rápido y no lo es: el arco es lo que cambia bajo revisión, y cada escena capturada contra un arco no acordado se vuelve a capturar. Las Fases 0 y 0B son las dos cosas que puedes ejecutar temprano: instalan herramientas y definen la paleta. Todo en la Fase 1 espera un plan aprobado.
🚀 Probarlo — el camino rápido
🚨 Quien llama elige este modo. Tú nunca lo haces. Puedes OFRECERLO, en una pregunta. No puedes deducirlo de las circunstancias, y estas en particular no son consentimiento:
- adjuntaron o desempaquetaron el paquete de la habilidad — así es como alguien instala una herramienta, no una declaración sobre lo que quiere hacer con ella;
- la solicitud suena exploratoria, o vino sin un resumen;
- es lo primero que han pedido;
- encontrarías el camino rápido más conveniente.
Alguien que dice "hazme un video de example.com" ha pedido un video de example.com. Decidir por ellos que realmente querían un borrador desechable les entrega un borrador silencioso y sin marca en 1080p cuando esperaban una pieza terminada — y las partes que te saltaste (el arco, las palabras, la marca) son exactamente las que no se pueden agregar después.
Cuando no esté claro, pregunta. "¿Es esto una prueba rápida, o un video que realmente le mostrarás a alguien?" Una línea, y resuelve en cuál de los dos modos estás.
Las puertas de aprobación a continuación existen porque un video que alguien verá es caro de equivocarse. Una ejecución desechable no lo es, y someter a un revisor a una ronda de concepto para averiguar si la captura funciona es cómo se abandona una buena herramienta en los primeros diez minutos. Ambos fallos son reales; solo quien llama sabe cuál se aplica.
El camino rápido, una vez que quien llama lo ha elegido:
- Repítelo — una frase: "tomando esto como una prueba rápida, así que me salto las rondas de aprobación y la marca; di la palabra para el proceso completo." Confirmar es mejor que anunciar: le da a quien llama que está en el otro modo una última oportunidad barata para corregirte.
- Un
PLAN.mdde dos líneas — el arco como una frase, tres o cuatro escenas. SinSCRIPT.md, sin ronda de aprobación. - La paleta neutral. Sin extracción de marca, sin vista previa para aprobar.
- Silencioso. Sin narración, sin clave de ElevenLabs, sin verificación de transcripción.
- Solo 1080p. Sin 4K, sin paso de publicación.
- Solo interno — no se muestra a un cliente y no va a ningún lugar público. Si resulta que alguien quiere mostrarlo, ese es un video diferente: ejecútalo correctamente en lugar de agregar aprobación retroactivamente a un borrador.
Todo lo demás en este archivo sigue aplicándose: la ruta de captura, la verificación, la cancelación por consentimiento ambiguo. Esas no son ceremonias; son lo que evita que un video roto parezca bueno.
🛑 La puerta del concepto
Esta habilidad no comienza con una solicitud. Comienza con un PLAN.md aprobado (más un SCRIPT.md textual para cualquier cosa dirigida al cliente). El camino rápido anterior es la única excepción, y solo está disponible cuando nadie fuera de la sala verá el resultado.
Si no hay uno, ese es el trabajo de la habilidad video-plan, y toma una pasada: para qué es el video, demo vs guía, el idioma, el arco, la lista de escenas, el texto. Haz eso primero y vuelve. Leer la aplicación para escribir el plan está bien — grabarla no.
Dos cosas que debes independientemente de quién escribió el plan, y ambas son preguntas, no anuncios:
Pregunta si analizar primero. "¿Debería mirar la aplicación y proponer qué mostrar, o ya lo sabes?" Leer un producto correctamente cuesta tiempo real, y quien llama puede tener una pantalla de inicio diferente o una idea terminada. No gastes sus minutos en tu suposición.
Consigue que la lista de escenas sea aprobada antes de filmar. No todo el PLAN.md re-aprobado — el plan ya está aprobado — sino la lista concreta de tomas que estás a punto de grabar: estas cuatro escenas, en este orden, destacando estas cosas. Toma un mensaje y es el último momento barato. Después de la captura, cambiar el orden significa volver a grabar, porque una escena cortada contra un arco diferente no encaja en un corte existente.
Confirma el origen de la captura en el chat. Qué entorno se graba, y por lo tanto qué versión del producto, es decisión del usuario y el objetivo se mueve.
🚦 Primera decisión: ¿de dónde viene el metraje?
Si el sujeto es una página web a la que puedas acceder → GRÁBALA TÚ MISMO. No pidas una grabación de pantalla.
¿URL accesible? ── sí ──┬── es TUYA (o de tu cliente, con un resumen)
│ │ └─▶ Fase 1A · captura (references/playwright-capture.md)
│ │
│ └── es un sitio web DE OTRA PERSONA
│ └─▶ Fase 1A · captura, más references/foreign-sites.md
│ (puerta de permiso, muros de consentimiento, encabezados
│ fijos, desviación de rects de carga diferida — LÉELO
│ PRIMERO, las primitivas de captura no son seguras en un
│ DOM ajeno tal cual)
no (aplicación de escritorio, Figma, herramienta nativa, móvil,
o el usuario ya te entregó un .mov)
▼
Fase 1B · ingesta de una grabación de pantalla
La aplicación propia y el sitio de terceros son el mismo pipeline con una pasada de captura diferente. La composición, el sistema de diseño, la capa de verificación y la locución no cambian; la extracción de marca ya lee cualquier sitio web en vivo. Lo que cambia es que por defecto solo eres público, no puedes sembrar estado, no debes escribir nada, y estás midiendo un DOM que se mueve bajo tus pies. (Una captura autenticada de terceros es posible y desaconsejada: necesita aprobación explícita por dominio, el bloqueo del navegador activado y el archivo de sesión destruido al final — references/foreign-sites.md §0.)
Esto no es una preferencia de estilo — la ruta de captura es mejor metraje y aproximadamente la mitad del trabajo. Una grabación de pantalla manual te obliga a aplicar ingeniería inversa a la línea de tiempo a partir de píxeles, buscar y cortar los reintentos del autor, medir cada foco a mano, recortar el marco del navegador y auditar la privacidad. Una captura scriptada no tiene ninguno de esos problemas por construcción, está libre de Chrome, te permite elegir el tamaño del texto y se puede re-ejecutar cuando la interfaz de usuario cambie. Medido en el mismo flujo: 71 s de grabación de pantalla que necesita escaneo denso de fotogramas contra una captura de 28 s con cada tiempo de origen y rect de elemento entregado en beats.json — y 1.5 veces el tamaño del texto en el fotograma terminado.
Aun así, si el usuario ya ha grabado algo, míralo antes de capturar. Codifica su modelo de su propio producto: qué capacidad mostrar, en qué orden y cuál es el punto. Ese juicio editorial es lo único que la ruta de captura no te da gratis.
Lee las referencias bajo demanda — no las precargues:
| Necesidad | Lee |
|---|---|
| ¿de qué marca es este video? (fichas, logotipo, tipografía — un sitio web funciona) | references/brand-style.md |
| conduce y graba la aplicación tú mismo; 2x; cursor; auth; beats.json | references/playwright-capture.md |
| el objetivo es un sitio web que NO posees (puerta de permiso, muros de consentimiento, encabezados fijos, desviación de rects de carga diferida, medios en vivo) | references/foreign-sites.md — lee ANTES de capturar |
| ejecutando sin cabeza en un contenedor o CI (fuentes CJK/emoji faltantes, Chromium muere en la primera captura, "El ejecutable no existe" justo después de instalar) | references/container-capture.md |
después de cambiar cualquier cosa en capture-lib.js | node <skill>/scripts/test-foreign-sites.mjs — fixtures locales, sin red; cada caso es un defecto que se envió |
| el foco enmarcó los píxeles equivocados y las coordenadas eran correctas | references/foreign-sites.md §4 — mide con stableRect, no boundingBox |
| re-capturar en otro idioma; re-temporizar un corte existente sin reconstruir la línea de tiempo | references/playwright-capture.md §9-10 |
| entregaron un .mov lleno de reintentos — selecciona y corta las tomas limpias | references/multiple-takes.md |
| ffmpeg/CLI no se ejecuta, "0 GB libres", bunx, permisos | references/pitfalls.md §6 + ejecuta scripts/setup-render-env.sh |
| comandos exactos de corte/recorte/velocidad/fotograma fijo/eliminar fotogramas | references/ffmpeg-recipes.md |
| el aspecto: ventana, foco, tarjetas, fundidos cruzados, fotogramas congelados | references/design-system.md (+ assets/template.html) |
| construyendo una guía de funciones en dos partes (paneles de concepto, escenas de acción, coreografía) | references/guide-track-build.md |
| narración / locución de ElevenLabs, cuota + trampas de voz | references/voiceover.md |
| ¿la voz realmente DICE el guión? (nombres de marca, acrónimos) | scripts/verify-narration.mjs — salida 1 = arreglar |
| la aplicación se renderiza vacía, da 500, o "offline" ANTES de que captures | references/pitfalls.md §17 |
| el contrato de TIMELINE.md; actuar sobre comentarios de "arrastra en 0:12" | references/timeline-and-review.md |
| ¿dónde pongo el foco? (nunca a ojo) | references/design-system.md → "NUNCA a ojo las coordenadas" |
| un borde del foco sigue cortando algo, sea cual sea el relleno que uses | scripts/measure-spots.mjs — mide el espacio en blanco del diseño en su lugar |
| el control genuinamente no se puede enmarcar (sin banda de 6px en algún borde) | references/design-system.md → "A veces no hay cuadro" |
| el marco de la aplicación se superpone donde va la tarjeta de subtítulos | references/design-system.md → colocación de tarjeta por escena + dividir una tarjeta en el corte |
| la imagen fija muestra el estado DESPUÉS del clic (foco en espacio vacío) | references/playwright-capture.md §16 — congela en la marca _hover |
| un mensaje de chat scriptado desapareció; el agente "terminó" pero no lo había hecho | references/playwright-capture.md §17-18 |
| "¿por qué mi metraje está congelado / desalineado / dando error?" | references/pitfalls.md |
| anillos negros perdidos en los clics; una corrección que silenciosamente no hizo nada | references/pitfalls.md §11-13 |
| una verificación dijo PASS pero la cosa está mal | references/pitfalls.md §15 |
| antes de cada renderizado (auditoría mecánica, salida 1 = arreglar) | scripts/audit-composition.mjs |
| ¿el sujeto es realmente visible? (despeje del foco + oclusión de tarjeta; salida 1 = arreglar, salida 2 = no se pudo verificar) | scripts/verify-material.mjs |
| después de las instantáneas: recorte ampliado por foco (una lectura de fotograma completo se pierde el texto cortado) | scripts/crop-spots.mjs |
| ¿el fotograma muestra de lo que la voz ESTÁ HABLANDO? (guías narradas, por tema) | scripts/verify-topics.mjs |
| la aplicación registra lo que haces — instantánea antes, restaura después | scripts/app-state.mjs |
| documentos de formación independientes junto al video (solo si se pide) | references/companion-docs.md |
Trabaja el bucle en instantáneas, no en renderizados. snapshot --at t1,t2,… cuesta segundos; un renderizado cuesta minutos. Ajusta el encuadre, las coordenadas del foco, el texto y la privacidad en imágenes fijas, luego renderiza una vez y verifica el movimiento.
Fase 0 — Entorno (una vez por máquina/sesión)
Un comando maneja todos los casos — macOS o Linux, una máquina saludable, un ffmpeg faltante o reducido, un HyperFrames faltante o el falso error statfs "0 GB libres". No diagnostiques a mano:
render_env="$(bash <skill>/scripts/setup-render-env.sh)" && eval "$render_env"
No uses source <(…). Bash informa el estado de source, no de la sustitución de proceso que lo alimenta, por lo que un bootstrap que muere a medio camino — sin red, una instalación fallida — informa éxito y te deja con la mitad de sus exportaciones establecidas. Capturar primero saca a la superficie el fallo y no aplica nada cuando falla.
Instala hyperframes (fijado) si está ausente, resuelve un ffmpeg completo, parchea la verificación de disco solo si este sistema operativo realmente tiene el error, y exporta HYPERFRAMES_FFMPEG_PATH, HYPERFRAMES_FFPROBE_PATH, PRODUCER_BROWSER_GPU_MODE y HYPERFRAMES_CLI.
Busca filtros, no un binario llamado ffmpeg. El pipeline necesita fps/pad (Fase 3 fijación de fotogramas), crop (Fase 1B eliminación del marco del navegador) y freezedetect (audit-composition.mjs + el barrido de silencio de la Fase 6). Dos compilaciones reducidas están comúnmente ya en PATH y pasan una verificación ingenua antes de fallar a medio pipeline: el ffmpeg incluido de Playwright y el paquete de compositor de Remotion. Orden de resolución: un ffmpeg completo del sistema → brew (macOS) → los paquetes ffmpeg-static/ffprobe-static en ~/.hyperframes-cli (todas las plataformas, sin sudo — la ruta normal en Linux) → un paquete de compositor de Remotion envuelto como último recurso, que advierte porque no tiene freezedetect, por lo que esas dos verificaciones de congelación pasan silenciosamente y debes verificar a mano (errores comunes #1, #16).
Luego renderiza a través de la CLI local a la que te apunta ($HYPERFRAMES_CLI), nunca bunx/npx hyperframes — esos re-materializan una copia nueva cada vez
…
[truncado para traducción]