open-kbs/skills-demo-video

Video demo

Produce un MP4 Full HD que demuestra el sitio o la aplicación en vivo del proyecto: grabaciones reales de pantalla, una voz en off en el idioma del usuario, subtítulos incrustados, una pista musical y un enlace para compartir. Todo se ejecuta dentro del contenedor con agent-browser, ffmpeg y el proxy de IA del proyecto (facturado a los créditos del proyecto). Resultado típico: 1–3 min, 10–20 MB, aproximadamente 1–2 horas de trabajo del agente. Todo el trabajo vive en video/ (build/ y out/ quedan fuera de git).

Cuándo usarlo

• "Haz un video que muestre cómo funciona el sistema", promocional, anuncio, demo para cliente
• Un walkthrough para una oferta, una nota de versión o una página de aterrizaje
• No para grabaciones que el usuario haga por sí mismo: en ese caso, escribe un guion de rodaje en docs/demo/script.md (escena, acción, texto a decir)

Pipeline (cada paso es reanudable: una re-ejecución omite la salida ya terminada)

Paso	Comando	Salida
0. Configuración	bash .claude/skills/demo-video/setup.sh	ffmpeg, fuentes de subtítulos, carpetas video/
1. Guion	escribir video/vo/narrator.json y video/scenes.mjs (partir de examples/)	el plan
2. Voz en off	node .claude/skills/demo-video/tts.mjs video/vo/narrator.json video/build/vo	s01.wav… + s01.txt (lo que se dijo)
3. Tomas	source .claude/skills/demo-video/rec-lib.sh luego take_start, mark, take_stop	video/build/rec/<take>.mp4 + .marks
4. Tarjetas	card_take <nombre> "file://$PWD/video/cards/<nombre>.html?…" <segundos>	video/build/rec/card-<nombre>.mp4
5. Sonidos	node .claude/skills/demo-video/sfx.mjs	video/build/sfx/chime.wav, click.wav
6. Edición	node .claude/skills/demo-video/compose.mjs video/scenes.mjs	video/out/<nombre>.mp4 (+ música si no se proporciona)
7. QA	node .claude/skills/demo-video/listen.mjs video/out/<nombre>.mp4 "<pregunta>" y capturas de fotogramas	correcciones, luego paso 6 nuevamente
8. Publicación	node .claude/skills/demo-video/publish.mjs video/out/<nombre>.mp4 --cover 16	clave en el almacenamiento del proyecto + JPG de portada

(.agents/skills/demo-video/ si se instaló con npx skills add.)

Cómo hacerlo bien

Guion primero. De 10 a 15 líneas de narrador, una idea por línea, de 8 a 15 palabras, en el idioma del usuario. Solo hechos: nunca afirmes números, clientes o premios que no puedas verificar en los datos propios del proyecto. Coloca nombres de marca y acrónimos en pronounce para que se lean correctamente. Cada línea se corresponde con una escena.

Voz. El proxy no tiene modelo TTS; tts.mjs usa el modelo Live (gemini-3.8-live) leyendo cada línea textualmente, conserva la mejor de 3 pruebas comparando la transcripción del propio modelo con el guion (80 % de coincidencia de palabras) y escribe un WAV por línea. Voces: Kore, Charon, Puck, Fenrir, Aoede. Una voz para el narrador; otra diferente para un rol de "cliente". Lee los s*.txt después de la ejecución y regenera cualquier línea que difiera (rm su wav y vuelve a ejecutar).

Tomas. Comienza desde un estado limpio: contexto de navegador fresco, carrito vacío, sin borradores de formularios guardados (agent-browser eval 'sessionStorage.clear()' e igual para localStorage que use la aplicación), inicia sesión antes de grabar para que no se escriba ninguna contraseña en cámara. Escribe con typeslow, llama a mark <etiqueta> antes de cada clic en el que se hará un corte en la edición, espera las respuestas de IA con wait_gone "<texto de búsqueda>", nunca desplazas el elemento que estás mostrando fuera de pantalla. Haz clic por referencia de elemento (@e12 de snapshot), no por texto de etiqueta. take_start establece el viewport a 1600×900 (el valor predeterminado es 1280×720, demasiado pequeño para 1080p); una toma por escena. Cuando el producto tenga un agente de voz, graba un intercambio real a través de su propia API (examples/voice-exchange.mjs) y reprodúcelo sobre una tarjeta en lugar de fingirlo.

Tarjetas. examples/cards/ tiene una intro (números animados, logotipo, píldoras), una tarjeta de llamada de voz y un outro. Copia a video/cards/, cambia colores, logotipo y textos según la marca. Pasa tiempos en la URL (?t1=<s>) para que las animaciones coincidan con la voz.

Edición (scenes.mjs). Cada escena son piezas de una toma [toma, entrada, salida, velocidad, zoom?] más audio ['vo:s01', en]. Acelera las esperas 2–5×, haz zoom zoom en paneles con texto pequeño, inserta un chip chapter en cada nueva sección, usa cap: 'left' cuando los subtítulos inferiores cubran la interfaz que se muestra, añade sfx de campanilla en momentos de éxito (añadido al carrito, pedido realizado). La edición se almacena en caché por escena; solo las escenas modificadas se vuelven a renderizar.

Audio. La pista musical se sintetiza con compose.mjs (sin riesgo de licencia) y se atenúa bajo la voz; configura music: 'ruta/al/track.mp3' en scenes.mjs para usar tu propia pista. La salida se normaliza a −16 LUFS.

QA antes de entregar. listen.mjs envía la mezcla a Gemini: pregunta sobre dicción, palabras mal pronunciadas, equilibrio música-voz, fallos y silencios largos. Luego captura un fotograma por escena a resolución completa (ffmpeg -ss <t> -i out.mp4 -frames:v 1 f.png) y revísalo: subtítulos superpuestos a la interfaz, texto cortado, estado incorrecto en pantalla. Corrige y vuelve a ejecutar el paso 6.

Entrega. Elimina los pedidos/datos de prueba que crearon las tomas, ejecuta agent-browser close --all, haz commit de video/ herramientas y guion (no build/, out/). Proporciona el enlace, la ruta local, una breve lista de lo que muestra el video y cualquier cosa del producto que hayas corregido durante la grabación (grabar un flujo de principio a fin suele encontrar errores reales; corrígelos, afectan a usuarios reales).

Publicación

publish.mjs sube al almacenamiento del proyecto con el tipo de contenido correcto (la subida simple al almacenamiento sirve el video como descarga) e imprime la URL pública: con "storage": { "cloudfront": "media" } en openkbs.json el archivo está en <sitio>/media/<clave> una vez que openkbs deploy haya configurado esa ruta. Sin almacenamiento en el CDN, coloca el archivo en site/ y despliega, o comparte un openkbs storage download. --cover <segundos> también sube un fotograma JPG como miniatura.

Requisitos

• Contenedor Studio: ffmpeg (la configuración lo instala), agent-browser, JWT del proxy en ~/.openkbs/projectJWT. Fuera de Studio, establece OPENKBS_API_KEY.
• Las fuentes para subtítulos se descargan mediante setup.sh en video/build/fonts (Golos Text, Fira Sans Extra Condensed: Latín + Cirílico, OFL).