Walkthrough video

Video de recorrido

Convierte una aplicación web en un video narrado completo que puede regenerarse cada vez que la aplicación cambia. Todo se ejecuta localmente: ni editor de video, ni servicio de pago.

texto narración -> voz local -> una WAV por escena + tiempos de subtítulos
app real -> escenas de Playwright -> clips + tiempos de marcadores -> assemble.py -> walkthrough.mp4 + .srt

Por qué funciona así: las tomas son la aplicación real, por lo que siempre son fieles; los pasos lentos (una respuesta de IA, una carga de página) se eliminan durante la grabación; y los "marcadores" registrados por cada escena permiten al ensamblador sincronizar el momento clave con las palabras correspondientes.

Antes de empezar

1. Pregunta solo lo que falte: qué es la aplicación y qué debe mostrar el video, quién lo ve, la duración objetivo (de 2 a 4 minutos funciona bien), el tono.
2. Verifica las herramientas (detalles en references/setup.md): Node 20+, Playwright con Chromium, FFmpeg con xfade, zoompan, loudnorm, libx264, y Python 3.11 o 3.12 con kokoro-onnx. Instala la voz (unos 350 MB) fuera del repositorio, por ejemplo en ~/video-tools.
3. Copia los archivos de trabajo al proyecto del usuario y mantén la salida generada fuera de git:

   mkdir -p e2e/video-kit && cp -R <this skill>/scripts/. e2e/video-kit/ && cp <this skill>/templates/*.mjs e2e/video-kit/
   printf '\ne2e/video-kit/clips/\ne2e/video-kit/vo/\ne2e/video-kit/build/\ne2e/video-kit/*.mp4\ne2e/video-kit/*.srt\ne2e/video-kit/spec.json\ne2e/video-kit/.*.json\n' >> .gitignore
   

   Los scripts escriben su salida junto a sí mismos, por eso se copian en lugar de ejecutarse desde aquí.
4. Lee references/toolkit-api.md una vez. Documenta los ayudantes del grabador y la sintaxis de PLAN. No reescribas rec.mjs, speak.py, overlays.mjs ni assemble.py; edita solo las partes que nombre la guía.

El flujo de trabajo: tres puertas

Detente en cada puerta y espera al usuario. Los cambios de redacción y estructura son baratos antes de grabar y caros después.

Puerta 1: storyboard. Examina el proyecto (sus documentos, rutas, pruebas de Playwright existentes) y propón de 8 a 12 escenas. Para cada una: qué aparece en pantalla, la narración (de 20 a 35 palabras, clara) y cómo se grabará. Incluye diapositivas de apertura si el usuario quiere contexto: el problema, lo que se hizo o auditó, la solución y el stack. No describas nada que la aplicación no haga realmente; pregunta si no estás seguro.

Puerta 2: redacción y voz. Escribe chunks.txt como líneas escena|texto, con un máximo de unas 12 palabras cada una (cada línea se convierte en un subtítulo). Añade nombres de productos y acrónimos a PRONOUNCE en speak.py. Ejecuta python speak.py e informa la duración de cada escena. El usuario escucha y aprueba antes de grabar.

Puerta 3: grabar, ensamblar, verificar.

1. Escribe las escenas en scenes.mjs (partiendo de scenes.template.mjs), un clip por escena, nombrado scene-N para que coincida con el plan por defecto. Graba una escena a la vez en segundo plano: node scenes.mjs <nombre>. Vuelve a grabar solo las que fallen.
2. Renderiza las diapositivas si se usan (slides.template.mjs), luego completa PLAN y LABEL en assemble.py: qué clip se muestra en cada escena y qué marcador coincide con cada línea de narración.
3. Ejecuta python assemble.py all. Escribe walkthrough.mp4 y walkthrough.srt.
4. Comprueba el resultado a partir de una hoja de contactos (uno o dos fotogramas por escena, en mosaico) en lugar de muchas imágenes separadas: nombres, fechas, subtítulos, nada cortado, nada privado. Corrige, reensambla, entrega.

Reglas importantes

• Privacidad. Usa una cuenta de demostración o prueba. Difumina o cubre cualquier cosa que muestre personas reales, correos electrónicos, números de teléfono, nombres de cuenta, claves, IDs, tokens o facturación (opts.cover, opts.init). Nunca manejes contraseñas: cuando una escena necesite inicio de sesión, pídele al usuario que inicie sesión manualmente una vez en un navegador visible (templates/auth.template.mjs) y reutiliza la sesión guardada. Nunca escribas ni muestres contraseñas ni códigos 2FA en cámara. Mantén .env, inicios de sesión guardados y perfiles de navegador fuera de git.
• No actuar en cuentas reales. Nunca hagas clic en nada que envíe, publique, programe o elimine en cuentas reales. Coloca el cursor sobre el botón y di lo que hace.
• Sin funciones inventadas. Describe solo lo que hacen el código y la aplicación en ejecución.
• La voz y el audio del micrófono no se pueden capturar desde el navegador. Muestra la interfaz y di lo que sucede.
• Verifica los puertos antes de iniciar servidores; detén lo que hayas iniciado. Ejecuta cualquier cosa que lleve más de un minuto (grabación, voz, ensamblaje) en segundo plano y espera a que termine en lugar de sondear en un bucle.
• Mantén las respuestas cortas. Informa lo que hiciste, las rutas de los archivos y cualquier cosa que no hayas podido verificar.

Lecciones de uso real

Lee references/lessons.md antes de escribir escenas. La versión corta: verifica que los datos sembrados realmente existen (los datos de prueba aleatorios pueden colisionar con datos antiguos); espera a un localizador que demuestre que una página lenta se ha dibujado; borra los filtros de búsqueda recordados antes de escribir; cierra las ventanas emergentes; enlaza directamente a los registros; envuelve los adornos no esenciales para que un fallo no detenga una escena; y mantén los 200 px inferiores de las diapositivas libres para los subtítulos.

Archivos

• scripts/rec.mjs grabador: cursor deslizante, ondas de clic, zoom, marcadores, think() para cortar esperas.
• scripts/speak.py narración a WAVs y tiempos de subtítulos.
• scripts/overlays.mjs subtítulos, etiquetas y tarjetas de título como imágenes.
• scripts/assemble.py reajusta los clips a la voz, une, superpone, mezcla audio, escribe MP4 y SRT.
• templates/ puntos de partida para escenas, un inicio de sesión guardado, diapositivas y el archivo de narración.
• references/ la guía del kit de herramientas, configuración y lecciones.

Cuando algo falla

• La voz falla con espeakng_loader/phontab: No such file: consulta references/setup.md.
• Una escena se agota esperando texto: es posible que la página no haya terminado de dibujarse, o que un filtro recordado esté ocultando el elemento. Toma una captura de pantalla en el fallo y mira.
• El video muestra una espera: envuelve el paso lento en think().
• La imagen y la voz se desincronizan: vuelve a grabar la escena, porque los tiempos de los marcadores cambian cuando cambia un script.