every-app/video-skills

Video narrado

La persona graba una sola toma de sí misma hablando sobre un guion gráfico. El agente edita la toma y anima capturas de pantalla reales del producto: cada escena comienza, cada clic aterriza y cada búsqueda se escribe en el momento exacto en que se nombra. El video completo es código (una composición de HyperFrames más una lista de edición), por lo que una nueva toma, una pantalla cambiada o un orden diferente es una re-ejecución, no una re-edición.

El video se adapta a la narración, nunca al revés. La persona dirige el gusto; el agente produce cortes, muestra fotogramas y pregunta.

Configuración

• ffmpeg en PATH, uv, Node 20+ con npx (HyperFrames 0.8.62 se ejecuta mediante npx), y Playwright con Chromium para las capturas. Funciona en macOS, Linux y Windows.
• Whisper se ejecuta localmente: mlx-whisper en Apple Silicon, faster-whisper en otros. uv run instala el que corresponda.
• SK=<directorio de esta habilidad>/scripts. Cada herramienta se ejecuta como uv run $SK/<herramienta>.py; cada una declara sus propias dependencias.
• Trabaja en una carpeta fuera de los archivos rastreados de cualquier repositorio (un .logs/<video>/ ignorado por git, o una carpeta temporal):

<trabajo>/
  assets/            capturas, fondo, tarjeta final
  storyboard.json    las escenas -> storyboard/index.html
  takes/<nombre>/    una carpeta por toma grabada: salida de sonda, transcripciones, edit.json, la narración cortada y la cámara web
  video.py           el script de composición -> comp/ (index.html, renders/)
  NOTES.md           cada decisión: cortes y por qué, inicios de escena, comandos de reconstrucción

1. Resumen

Confirma en un breve intercambio, ofreciendo valores predeterminados:

• Formato: video de lanzamiento, demo de funcionalidad o tutorial (references/formats.md). Un video de lanzamiento no debe superar los 2:00, incluida la tarjeta final.
• Audiencia, los tres o cuatro momentos clave que el video debe cubrir y el llamado a la acción.
• Datos de ejemplo que se vean bien: un negocio o búsqueda de ejemplo que se lea de un vistazo para esta audiencia.
• Marca: una imagen de fondo (o el gradiente predeterminado), una tarjeta final (la imagen OG del producto funciona bien), la URL que se muestra en la barra de título de la ventana.

2. Captura

Capturas de pantalla reales del producto en funcionamiento a 1440x900, 2x, a partir de un script de Playwright basado en $SK/capture.mjs: fotogramas por pulsación para cualquier cosa escrita en pantalla, estados antes y después para cualquier clic, tomas largas para cualquier desplazamiento y puntos de clic medidos para el puntero. Si la aplicación requiere inicio de sesión, pasa login y la primera ejecución abre una ventana del navegador para que la persona inicie sesión una vez. Nunca dibujes la interfaz de usuario ni edites píxeles. Revisa cada captura antes de usarla. Detalles y el pase de privacidad: references/capture.md.

3. Guion gráfico (Storyboard)

Escribe storyboard.json, una tarjeta por escena: la captura de pantalla, lo que está en pantalla, de tres a seis viñetas de lo que se debe decir (notas breves, no oraciones completas) y segundos aproximados. Constrúyelo y muéstralo:

uv run $SK/storyboard.py storyboard.json storyboard/

Es una página simple, una sección por escena. Publica storyboard/ (index.html más frames/) cuando el sistema pueda publicar una página; de lo contrario, ábrelo localmente. Itera hasta que la persona esté lista para grabar, luego entrega las notas de grabación en references/storyboard-and-recording.md. Una vez que esté grabando a partir de él, no cambies el guion gráfico sin preguntar.

4. Grabación

La persona graba una sola toma, cámara web y voz en un solo archivo (cualquier grabador de cámara web: QuickTime, Photo Booth, Cámara de Windows, OBS), hablando a través de las escenas. Los errores están bien: se reinicia la frase y continúa. Varias tomas están bien; cada una recibe su propia carpeta de toma.

5. Edición de la toma

uv run $SK/probe.py <grabación> takes/<nombre>       # take.wav, cam.mp4, take.json; ver still.jpg, re-ejecutar con --crop si es necesario
uv run $SK/transcribe.py takes/<nombre>              # dos pasadas: normal y otra que escribe las muletillas
uv run $SK/analyze.py takes/<nombre>                 # candidatos: pausas largas (con cortes), muletillas, reinicios, sonidos extraños
uv run $SK/trace.py takes/<nombre> <a>:<b>           # colocar cada corte en la traza de energía (--fine para filas de 5 ms)
uv run $SK/splicetest.py takes/<nombre> c1=<a>:<inicio del corte>,<fin del corte>:<b>   # escuchar un corte: debe leerse como la oración prevista
uv run $SK/jump.py takes/<nombre> <inicio del corte>:<fin del corte> --slide 0.3        # qué tan visible es el corte en la burbuja de la cámara web
# escribir takes/<nombre>/edit.json, luego:
uv run $SK/edit.py takes/<nombre>                    # edl.json; imprime la narración editada y las muletillas conservadas: léelo todo
uv run $SK/build.py takes/<nombre>                   # narration-edit.wav, cam-edit.mp4 (crossfades y fundidos de cámara web en cada corte)
uv run $SK/master.py takes/<nombre>                  # narration.wav a -16 LUFS

Dos niveles de edición (references/editing.md):

• Ligera, la predeterminada: cortar reinicios y falsos comienzos, y recortar pausas muertas (una pausa de más de ~1,1 s deja 0,7 s, 0,9 s en un cambio de escena). Cada "um" y pequeña vacilación se mantiene.
• Menos muletillas, cuando se solicite: también eliminar la mayoría de los "um" que aparecen solos entre frases, y recortar pausas de más de ~0,8 s a aproximadamente 0,55 s. Dejar cualquier muletilla pegada a una palabra vecina.
• Cada corte se sitúa en el tono de sala en la traza y pasa una prueba de empalme antes de incorporarse. Los cortes por reinicio se colocan en cambios de escena cuando sea posible, para que el corte de imagen oculte el salto en la burbuja.

6. Componer según las palabras

uv run $SK/cues.py takes/<nombre>       # words.json, la hoja de señales (transcripciones a nivel de clip de la narración final)
NV_SCRIPTS=$SK ASSETS=assets uv run --with numpy python video.py   # el script de composición -> comp/; imprime cada señal en contexto
uv run $SK/render.py comp lint
uv run $SK/render.py comp snapshot 1,14.2,22.5,40.1

Escribe video.py a partir del ejemplo práctico, examples/openseo-launch/video.py: inicios de escena y tiempos de señal de la hoja de señales, capas de cámara sobre las capturas y una coreografía sincronizada con las palabras. Las posiciones de las señales del ejemplo solo se ajustan a su propia edición: reancla cada una y lee la tabla de señales que imprime después de cada cambio en la edición. Las reglas de sincronización están en references/composition.md; las más importantes:

• Una escena comienza 0,3 s antes de su primera palabra, o exactamente en un corte en la pausa anterior.
• Cada acción aterriza en la palabra que la nombra: el clic en "copiar", la escritura mientras se dice la búsqueda, el zoom en un número mientras se menciona, el puntero en cada elemento mientras se nombra.
• El primer fotograma es el póster: toda la aplicación, sin fundido de entrada. Algo se mueve en cada fotograma.
• Una etiqueta corta por momento clave. Captura el inicio de cada escena, clic y etiqueta, y revísalos antes de renderizar.

7. Renderizar y verificar

uv run $SK/render.py comp render
uv run $SK/composite.py comp takes/<nombre> comp/renders/<video>-1080p.mp4
uv run $SK/check.py comp/renders/<video>-1080p.mp4 comp takes/<nombre>
uv run $SK/filmstrip.py comp/renders/<video>-1080p.mp4 comp/renders/filmstrip.png

Nada se entrega a la persona hasta que la verificación muestre la ventana en cada fotograma, cada punto de cámara web en el desplazamiento de fotograma 0, una mediana de audio de 0 ms y aproximadamente -16 LUFS, y hayas leído la transcripción y revisado la tira de fotogramas (references/verification.md).

8. Revisión e iteración

• Entrega a la persona la ruta del mp4, lo que se cortó y cualquier cosa que deba escuchar.
• Mantén NOTES.md actualizado: cada corte con su motivo, inicios de escena, comandos de reconstrucción. Espera varias rondas.
• Las variantes son económicas: otra toma, una edición ligera y otra con menos muletillas, un orden diferente de escenas. Cada una es una carpeta de toma o un script de composición; con subagentes, constrúyelas en paralelo con nombres de archivo separados para que nunca colisionen.

Reglas estrictas

• Solo capturas reales. Oculta lo que no forma parte de la historia (un banner, un aviso de cookies); nunca pintes sobre píxeles.
• Verifica que las capturas y grabaciones no contengan secretos ni datos personales (claves API, correos electrónicos y nombres de otras personas, datos de clientes, URLs de localhost) antes de renderizar; enmarca alrededor de ellos o vuelve a capturar, y revoca cualquier clave que haya aparecido en pantalla. El propio nombre o correo electrónico de la persona en la aplicación está bien una vez que ella lo confirme.
• Las grabaciones y la sesión de inicio de sesión de la persona permanecen en su máquina. No publiques nada sin que te lo pidan.

Lo que aún causa problemas: references/gotchas.md.