demo-video

Demo video

Graba la aplicación real (nunca un simulacro o un video antiguo) en un navegador headless nuevo, la narra con Edge TTS, incrusta subtítulos y genera un MP4. Un demo consta de dos archivos escritos para su proceso, narration.json y flow.cjs; todo lo demás es el comando demo-video-kit en esta carpeta. El ejemplo de trabajo es examples/todomvc/.

<kit> abajo significa node <esta carpeta>/bin/demo-video-kit.js (esta carpeta es, por ejemplo, ~/.claude/skills/demo-video); cuando el proyecto del usuario tiene el kit instalado, npx demo-video-kit funciona igual. <kit> help lista todos los comandos.

La solicitud determina el trabajo

Solicitud	Hacer
"Crear un demo para "	Todo el flujo de trabajo a continuación, en demos/<proceso>/ del proyecto del usuario
"Las pantallas de cambiaron, rehacer el demo"	Ejecutar en seco las nuevas pantallas (paso 2), corregir flow.cjs y, si las palabras ya no encajan, narration.json; luego pasos 4 a 8
"Añadir recuadros al video existente" (sin nueva grabación)	Medir los recuadros en la aplicación en ejecución, escribir annotations.json, ejecutar <kit> annotate <demo-dir> (ver Resaltes)
"... sin resaltes"	Omitir toda opción highlight; nada más cambia
"Cambiar la voz / velocidad / redacción"	Editar narration.json (voice, rate, texto del segmento), luego pasos 4 a 8: las duraciones de los clips determinan la sincronización en pantalla, por lo que el video siempre se graba de nuevo

Reglas (siempre)

1. Real y fresco. Una nueva sesión de navegador; la aplicación real; datos reales. Nunca falsifiques un resultado, un número o un estado; anuncia el éxito solo después de que la aplicación lo muestre.
2. Seguro. Solo un entorno local o de pruebas: cada ejecución realmente crea lo que el flujo crea. Nunca imprimas ni almacenes credenciales: provienen del entorno (por ejemplo DEMO_EMAIL, DEMO_PASSWORD); una contraseña se muestra solo como puntos. Pide una cuenta de prueba si no se conoce ninguna.
3. Imagen. 1920x1080, 16:9, 30 FPS, MP4 H.264 + AAC, grabado en headless para que nada se recorte. Un cursor visible que se desliza hacia cada objetivo y un anillo de clic ligero; sin zoom, sin movimientos de cámara, sin transiciones elegantes. Antes de actuar sobre algo, desplázalo completamente a la vista; lee páginas largas de arriba a abajo, lo suficientemente lento para leer.
4. Sonido. Edge TTS, voz predeterminada en-IN-NeerjaNeural (lista otras con <kit> voices en- u otro filtro). Un clip por segmento de narración; los clips nunca se superponen; la narración describe solo lo que está en pantalla o está por suceder en esa escena.
5. Sin pausa mayor de 7 segundos. Ningún tramo sin narración puede alcanzar los 7 segundos. Cuando el grabador advierta, o verify.py falle, alarga o divide la narración de ese segmento, o acelera sus acciones, y graba de nuevo.
6. Ritmo. Sin prisas: cada valor ingresado debe ser visible antes de continuar.
7. Sigue la aplicación. Deriva rutas, etiquetas y botones de la aplicación en ejecución (ejecución en seco), nunca de memoria. Nombra los botones como lo hace la aplicación.
8. Las salidas quedan fuera de git. El audio generado, las compilaciones y los MP4 no se confirman a menos que se solicite.
9. Resaltes. Cada demo marca con un recuadro rojo lo que la narración señala, a menos que la solicitud diga "sin resaltes".

Resaltes

Un recuadro rojo (4 px, #E11D48, a 6 px del elemento) se dibuja en vivo en la página mientras el video se graba, por lo que sigue el desplazamiento y forma parte de la imagen. Recuadro por defecto: cada elemento del menú en el que se hace clic para llegar a la pantalla, los botones que inician el proceso, cada bloque de datos ingresados en una página de revisión, y el botón de envío final. No recuadres cada campo que se escribe: el cursor y la escritura ya lo muestran.

API en flow.cjs:

• goto / click / type / pick (loc, ..., { highlight }): highlight: true recuadra el elemento al que va el cursor; highlight: <locator> recuadra otro elemento en su lugar (por ejemplo toda su fila o bloque).
• Un recuadro permanece hasta que el cursor se mueve al siguiente objetivo. { keep: true } mantiene también los recuadros actuales; k.clearHighlights() los elimina; k.highlight(loc) añade uno sin mover el cursor.
• Cada recuadro añade una entrada highlight a marks en build/timeline-raw.json.

Para un video ya grabado sin recuadros, <kit> annotate <demo-dir> los dibuja después desde annotations.json. Esto es un recurso de respaldo; grabar de nuevo es más fácil y preciso.

Flujo de trabajo

1. Configuración. Ejecuta <kit> doctor (ver Configuración) y verifica que la aplicación responda en su URL.
2. Ejecución en seco. Con las herramientas del navegador Playwright, recorre el flujo real sin grabar y sin el envío final: anota la ruta de cada pantalla, las etiquetas y nombres getByRole, las opciones de los menús desplegables, los diálogos, el botón final y lo que sucede después.
3. Escribe el demo: <kit> init <demo-dir> --url <url de la app> crea un iniciador que ya funciona; o copia examples/todomvc/. Luego edita:
   • narration.json: título, voz, velocidad, pronounce (escrito → hablado) y segmentos {id, scene, text}. Divide una escena en varios segmentos donde sus acciones tomen tiempo, para que la narración de cada segmento dure aproximadamente lo mismo que sus acciones.
   • flow.cjs: runDemo(__dirname, async (k) => { ... }) con un k.segment(id, async (at, clip) => { ... }) por segmento de narración. Usa k.click / k.type / k.pick / k.goto / k.scrollBy; at(seconds) espera un punto en el clip (por ejemplo clip.cues[0].end). Espera en elementos, nunca en "network idle". Devuelve lo que se verificó. Mantén require(process.env.DEMO_KIT || 'demo-video-kit'): el comando establece DEMO_KIT.
4. Créalo. <kit> run <demo-dir> (con DEMO_BASE_URL y las credenciales en el entorno) ejecuta audio, grabación, renderizado y verificación. Cada línea WARNING del grabador, y cada línea FAIL de la verificación, infringen la regla 5: corrige y ejecuta de nuevo. Después de cambiar solo flow.cjs, --from record omite el audio; después de cambiar solo subtítulos o codificación, --from render omite la grabación.
5. Míralo. build/check/contact-sheet.png: cada fotograma muestra la pantalla completa, el cursor, el paso correcto, subtítulos legibles y recuadros en los elementos que la narración nombra. El video es <demo-dir>/<nombre de la carpeta>.mp4.
6. Entrega. Informa la ruta del MP4, duración, formato, laguna más larga, qué creó la ejecución, y cualquier cosa que difiera de la solicitud porque la aplicación funciona de manera diferente.

Configuración

Node 18+ y Google Chrome (o Microsoft Edge: el grabador recurre a él, o establece DEMO_BROWSER=msedge). Ejecuta npm install una vez en esta carpeta; las voces (msedge-tts), ffmpeg (ffmpeg-static) y playwright-core vienen con él, y el grabador descarga su propio ffmpeg pequeño de Playwright en su primera ejecución. <kit> doctor verifica todo, incluido el acceso a Internet, que las voces necesitan.

Trampas conocidas

Trampa	Evitar
Banda gris, página cortada en la parte inferior	Nunca grabar en una ventana de navegador visible; demo-kit.cjs graba en headless a 1920x1080
waitForLoadState('networkidle') se cuelga en aplicaciones que sondean	Esperar en un elemento en su lugar
Un diálogo de interfaz headless informa como oculto	Esperar en un campo dentro del diálogo, no en el diálogo
Escape dentro de un menú desplegable cierra todo el diálogo	Seleccionar una opción en lugar de presionar Escape
Un tramo silencioso mientras se escriben muchos campos	Dividir la narración de ese segmento; type() acepta { delay } (por defecto 32 ms)
Etiquetas mostradas en mayúsculas por CSS	Coincidir con el texto real, no con la mayúscula mostrada
Un recuadro alrededor solo de una etiqueta, no de su bloque	Recuadrar el padre de la etiqueta (xpath=..) o el abuelo (xpath=../..)