vishalvana-belwo/belwo-claude-skills

Graba un video tutorial narrado

Escribes un archivo de escenas: cada escena es un fragmento de narración más los clics que ocurren mientras se reproduce. Los scripts convierten la narración en voz, manejan la aplicación en un Chromium sin cabeza a 1600×900 fijos mientras capturan la pantalla, y construyen un MP4 con la voz superpuesta y subtítulos incrustados. Se añaden un cursor visible, ondas de clic, anillos de resalte y tarjetas de título sobre la página.

Todos los comandos siguientes usan PY, que significa python en Windows y python3 en macOS, y DV, que significa "${CLAUDE_SKILL_DIR}/scripts/demo_video.py". Cada comando imprime líneas de estado simples (SCENE …, RECORDED …, CHECK OK, ERROR …); léelas en lugar de adivinar.

1. Configuración (una vez por máquina)

PY "${CLAUDE_SKILL_DIR}/scripts/setup_env.py"

Crea un entorno privado en ~/.claude-demo-video con Playwright, Chromium y edge-tts, luego verifica ffmpeg. Termina con READY o con exactamente lo que falta. ffmpeg es una herramienta del sistema: pide permiso al usuario antes de instalarlo (winget install --id Gyan.FFmpeg -e en Windows, brew install ffmpeg en macOS). Los scripts también buscan en las carpetas de instalación habituales (WinGet, Chocolatey, Scoop, Homebrew). Si ffmpeg está en otro lugar, configura DEMO_VIDEO_FFMPEG_DIR con su carpeta para cada comando.

2. Acordar el video con el usuario antes de escribir nada

Pregunta o confirma según el contexto:

• Quién lo verá y por qué (un revisor aprobando una función, un cliente, personal nuevo). Esto define el tono y qué explicar.
• Qué mostrar, en qué orden. Propón una lista de escenas con una línea cada una y obtén una confirmación. Apunta a 3 a 8 minutos.
• Voz. La opción predeterminada es una voz neural natural en inglés (edge-tts). Informa al usuario que el texto de la narración se envía al servicio de voz de Microsoft para generar el audio. Debe contener solo explicaciones de funciones, nunca datos. La alternativa es la voz del sistema sin conexión (--offline): nada sale de la máquina, pero suena robótico.
• Datos. Graba solo datos de demostración: personas ficticias, correos @example.com, proyectos claramente falsos. Nunca registres registros reales de clientes o empleados, y nunca apuntes el grabador a producción.

3. Preparar la aplicación

• La aplicación debe estar en ejecución y accesible desde esta máquina, generalmente una compilación local.
• Si las pantallas necesitan datos, escribe un script de siembra y un script de limpieza correspondiente para los datos demo, y ejecuta la siembra. Etiqueta las filas demo (por ejemplo, IDs que comiencen con DEMO-) para que la limpieza no toque nada más.
• Asegúrate de que el correo saliente y las notificaciones estén desactivados, o solo vayan a direcciones falsas, porque el paseo hace clic en botones reales (enviar, aprobar…).
• Las escenas que cambian datos (aprobar, eliminar) solo se pueden grabar una vez por siembra. Vuelve a sembrar antes de cada regrabación.

4. Escribir el archivo de escenas

Crealo en el proyecto del usuario, por ejemplo demo-videos/<nombre>.py, nunca dentro de la carpeta de la habilidad. Comienza desde ${CLAUDE_SKILL_DIR}/reference/scenes-template.py. Para un ejemplo real completo, consulta ${CLAUDE_SKILL_DIR}/reference/zentrio-timesheet-example.py, que creó un video de aprobación de 6 minutos.

CONFIG = {'url': 'https://localhost:7101/MyTimesheet', 'ready': '#tsCards .tsw-card', 'sign_in': True}

async def week(r):
    await r.click('.tsw-row:has-text("Approval screen")')
    await r.spot('.tsw-panel', 3)

SCENES = [
    ('week', "Haz clic en una fila de tarea y el panel de registro se abre justo debajo.", week),
]

• CONFIG['url'] es la primera página. ready es un selector que solo es visible una vez que la página está cargada y se ha iniciado sesión. Así es como el grabador sabe que el inicio de sesión funcionó.
• Narración: de una a tres frases cortas habladas por escena. Explica por qué algo es importante, no solo qué hay en pantalla. Escribe números y símbolos como deben decirse ("dos punto tres cero"). No pongas datos en la narración.
• Las acciones se ejecutan mientras se reproduce su narración. Hazlas más cortas que la narración; el grabador espera a que la narración termine antes de comenzar la siguiente escena.

Ayudantes de escena (r es el grabador; cualquier otra cosa está disponible como r.page, la página de Playwright):

Ayudante	Hace
await r.goto('/ruta', wait_for=sel)	abre una página (relativa a CONFIG['url'])
await r.click(objetivo, dx=.5, dy=.5)	mueve el cursor visible allí y hace clic; dx/dy eligen el punto dentro del elemento
await r.move_to(objetivo)	mueve el cursor sin hacer clic
await r.type(objetivo, 'texto')	hace clic en un campo y escribe visiblemente
await r.select(objetivo, valor)	elige una opción de menú desplegable
await r.press('ControlOrMeta+K')	atajo de teclado (Ctrl en Windows, Cmd en macOS)
await r.spot(objetivo, segundos, pad)	anillo de resalte naranja
await r.card(kicker, titulo, lineas, viñetas) / await r.uncard()	tarjeta de título a pantalla completa (intro, resumen, outro)
await r.confirm_click(objetivo, show=4)	para botones que llaman a confirm(): muestra un diálogo similar, luego acepta
await r.download(objetivo)	hace clic en una descarga y devuelve la ruta del archivo guardado
await r.show_file(ruta)	muestra un archivo local, por ejemplo una vista previa HTML que hiciste de un informe descargado
await r.scroll_top(), await r.scroll_x(selector, px)	desplazamiento suave
await r.clear_toasts(selector)	elimina notificaciones emergentes que cubren botones
await r.wait(segundos)	pausa

objetivo es un selector CSS o de Playwright ('button:has-text("Aprobar")') o un Localizador (r.page.locator('tr', has_text='Aarav').first).

5. Generar la narración, grabar y revisar

PY DV voice  demo-videos/<nombre>.py     # audio por escena; imprime la duración de cada escena
PY DV record demo-videos/<nombre>.py     # maneja la aplicación y captura fotogramas
PY DV stills demo-videos/<nombre>.py     # dos fotogramas por escena en <nombre>-video/stills/

Inicio de sesión. Con 'sign_in': True, si la aplicación no ha iniciado sesión, se abre una ventana del navegador y el grabador imprime SIGN_IN_NEEDED. Dile al usuario que inicie sesión en esa ventana. Nunca escribas credenciales ni pidas contraseñas. La sesión se guarda en <nombre>-video/.profile para que las regrabaciones no necesiten otro inicio de sesión.

Revisa cada fotograma antes de construir, leyendo las imágenes:

• página correcta, panel abierto, cursor donde dice la narración;
• nada cubriendo la acción (notificaciones, banners de cookies, un menú de perfil);
• la imagen no está estirada ni cortada;
• ningún dato personal real en pantalla.

Una línea SCENE_ERROR o un fotograma incorrecto significa arreglar esa función de escena y grabar de nuevo (vuelve a sembrar primero si las escenas cambiaron datos). reference/lessons.md enumera los fallos vistos hasta ahora y sus soluciones. Léelo cuando algo parezca extraño.

6. Construir, verificar y entregar

PY DV build demo-videos/<nombre>.py [--out "ruta/Nombre.mp4"]
PY DV check "ruta/Nombre.mp4" --size 1600x900

run hace voz, grabación, fotogramas, construcción y verificación de una sola vez, una vez que se sabe que las escenas funcionan. Informa al usuario la ruta y duración del video, y qué muestra. No lo subas ni compartas a menos que ellos lo pidan.

7. Limpiar

• PY DV clean demo-videos/<nombre>.py elimina el inicio de sesión guardado. Haz esto siempre al terminar, porque contiene una sesión real. --all también elimina fotogramas, imágenes fijas y audio.
• Ejecuta el script de limpieza de datos demo y detén cualquier proceso de la aplicación que hayas iniciado.

Notas de plataforma

• macOS: usa python3. Los subtítulos los dibuja Chromium y se superponen al video, por lo que se ven igual en todas partes y no necesitan un ffmpeg compilado con libass (el de Homebrew no lo tiene). La grabación es sin cabeza, por lo que las pantallas Retina no cambian el tamaño del video.
• --headed graba en una ventana visible. Úsalo solo cuando una aplicación rechace navegadores sin cabeza, y pide al usuario que no toque ni redimensione la ventana mientras graba.
• DEMO_VIDEO_HOME mueve el entorno privado; DEMO_VIDEO_FFMPEG_DIR apunta a una carpeta de ffmpeg.