Video Demo de Estudio
Crea un video narrado de ~90–180 segundos de cualquier producto que el usuario nombre — una app de macOS, un sitio web, una CLI, cualquier cosa que puedas grabar la pantalla. El único componente fijo es el backend de narración: la API Studio de video-studio-mlx (POST /studio/tts), que clona una voz y valida cada línea. El tema del demo es arbitrario y cambia cada vez. Mantén esa separación en mente: no asumas que el objetivo del demo es el propio video-studio-mlx (eso es solo el ejemplo en references/).
Principio fundamental: narración primero, anclaje de duración exacta
Genera la narración antes de cualquier material de video. /studio/tts devuelve la duración exacta de cada segmento y marcas de tiempo por palabra — estos datos determinan toda la línea de tiempo y todos los efectos de enfoque. Luego graba el material generosamente y ajusta cada clip a su segmento. Cortar primero y poner la voz después obliga a un reajuste de tiempo frágil.
Generalmente no puedes reproducir o escuchar el resultado. Trata esto como una restricción firme: verifica el video extrayendo fotogramas, y verifica el contenido de audio y la sincronización ejecutando ASR en fragmentos del archivo terminado. Construye todo para que pueda ser verificado de esta manera.
Flujo de trabajo
- Escribe un guion gráfico por escena — texto de la narración, acción en pantalla, subtítulo, y (por escena) qué elementos nombra la narración para que el enfoque pueda señalarlos. Apunta a ~2.1 palabras/segundo (≈170 palabras ≈ 80s). Copia
references/storyboard.example.jsona<trabajo>/storyboard.json. Redacta la narración para que cada elemento nombrado esté realmente visible y en orden en el material de esa escena. Escribe para el oído: deletrea las palabras como se hablan, no como se escriben — expande abreviaturas y siglas ("expresión regular" no "regex", "versión tres" no "v3"), evita símbolos desnudos (~,/,&), y escribe números/unidades como palabras cuando tengas dudas. El TTS lee el texto literal y el ASR valida contra él, por lo que las abreviaturas escritas no solo se pronuncian mal sino que sesgan el WER. - Genera la narración —
scripts/generate_narration.py <storyboard.json>. Hace POST de cada escena a/studio/tts, clonando cada escena desde una misma voz fija (elref_audiodel usuario, o una instrucciónvoiceque diseña una vez — ver abajo), lo valida con ASR, y escribenarration/manifest.jsonconduration_s,wer, ywordspor palabra, por segmento. (Verreferences/studio-api.md.) - Graba el objetivo — un clip por escena de la app/sitio (ver Grabación), más un mapa de rectángulos de elementos con nombre para los elementos a los que el enfoque señalará.
- Compone —
scripts/compose.py <storyboard.json>: enmarca el material en un escenario degradado, quema subtítulos de Pillow, aplica zoom lento en tomas heroicas, aplica enfoque anclado a la narración (zoom + anillo), transiciones con xfade, coloca la narración en la línea de tiempo calculada, y multiplexa. - Verifica — extrae un fotograma por escena; extrae un fotograma en el tiempo de cada palabra hablada del enfoque y confirma que el resalte esté sobre el elemento nombrado; aplica ASR a dos o tres fragmentos para confirmar que la línea correcta cae en la escena correcta.
Prerrequisitos
- La API Studio accesible (por defecto
http://127.0.0.1:8100). La configuración, clonación y el contrato de alineación/marcas de tiempo por palabra están enreferences/studio-api.md. - Un wav de referencia de 3–15s (mono 24 kHz) más su transcripción exacta para la clonación — confirma la transcripción con
/asrprimero (la calidad de la clonación depende de la alineación audio↔texto, no de una longitud "recomendada"). - Una sola voz para todo el video. Cada escena es una llamada separada a
/studio/tts, por lo que la voz solo se mantiene consistente si cada llamada clona una misma referencia compartida. Si el usuario proporciona una referencia, clona a partir de ella; de lo contrario, establece una instrucción de diseño devoiceen el guion gráfico ygenerate_narration.pydiseña un clip por adelantado y clona cada escena a partir de él (en caché, por lo que las re-ejecuciones mantienen la misma voz). Sin ninguna de las dos, cada escena se sintetiza de forma independiente y el timbre se desvía entre escenas — evítalo para videos reales. - ffmpeg con
avfoundation(captura en macOS),zoompan,xfade,gblur.drawtexta menudo falta (sin libfreetype) — los subtítulos se renderizan con Pillow. - Para objetivos web: Playwright (o Puppeteer) para grabación determinista + rectángulos de elementos.
Grabación del objetivo
Cada escena necesita dos cosas del producto objetivo:
- un clip grabado de pantalla (graba más que la narración — los resultados y los spinners aparecen segundos después de un clic), y
- un mapa de rectángulos de elementos con nombre: para cada elemento que la narración nombrará, su rect en píxeles del material de video (el espacio de coordenadas que usa el clip compuesto).
El kit de herramientas de la interfaz de usuario del objetivo decide cómo obtienes estos. Dos backends:
Una app de macOS — AppleScript + ffmpeg avfoundation
- Graba
avfoundation "Capture screen N"y recorta en vivo a la ventana de la app. Prueba una vez (graba ~1.5s, extrae un fotograma, confirmacrop=W:H:X:Y). La pantalla es Retina, por lo que el recorte físico = DPR × lógico (DPR suele ser 2). - Controla con System Events. Encuentra las primitivas confiables para el kit de herramientas de esta app — difieren por app. Precauciones generales que se repiten:
- Los clics coordinados a menudo no se registran en listas de SwiftUI/AppKit; usa
selectde AX oAXPressen el elemento. - Los controles segmentados se exponen como
AXRadioButtons; consúltalos por rol. - Las consultas AX justo después de un cambio de vista pueden competir (resultados vacíos) — reintenta, o evita la navegación dentro de la sesión por completo.
- Si la navegación es inestable, vuelve a lanzar la app ya en el estado necesario (a través de argumentos de lanzamiento / variables de entorno / un esquema de URL que la app soporte) y solo activa la única acción en cámara. Barato y determinista.
- Los clics coordinados a menudo no se registran en listas de SwiftUI/AppKit; usa
-capture_cursor 0(las acciones AX no mueven el puntero, por lo que el cursor permanece fuera del cuadro). Para un cursor visible, sintetiza uno en postproducción (ver Enfoque).- Mapa de elementos: consulta la
position+sizede AX de cada elemento y convierte a píxeles de material de video:(global − origen_ventana) × DPR. Si el kit de herramientas oculta los rectángulos de campos, mide desde un fotograma de material cuadriculado. Confía en el fotograma del material sobre los números AX desactualizados si no coinciden (el estado de desplazamiento difiere); verifica cada fotograma de enfoque.
Un sitio web — Playwright (recomendado sobre captura de pantalla)
- Graba con
recordVideo; establecerecordVideo.sizeigual alviewporty normaliza el webm a tu fps antes de componer. - Espacio de coordenadas (el #1 problema común): Playwright graba al tamaño del viewport, por lo que cuando
recordVideo.size == viewport, los píxeles del material == píxeles CSS.deviceScaleFactor: 2solo agudiza el renderizado — NO escala el video grabado, y unrecordVideo.sizemás grande que el viewport solo añade área negra adicional (la página permanece arriba a la izquierda a 1×, NO se escala para llenar). Por lo tanto,boundingBox()da píxeles de material directamente — NO multipliques por DPR. (Si alguna vez grabas a un tamaño diferente, escala los rectángulos portamañoGrabado / viewport.) Siempre verifica superponiendo un rectángulo conocido en un fotograma extraído antes de grabar todas las escenas — una suposición incorrecta de DPR coloca silenciosamente cada anillo de enfoque en el lugar equivocado. - Captura cada rectángulo en una posición de desplazamiento fija: haz todo el desplazamiento primero, deja que se estabilice, luego lee todos los
boundingBox(), luego mantenlo. Los anillos viven en coordenadas del material y deben permanecer pegados mientras la cámara hace zoom/panorámica. Emite la pista de interacción desde el reloj de la página si deseas enfoque automático. - Primero estabiliza la página: desactiva animaciones CSS /
prefers-reduced-motion, descarta los banners de cookies, oculta la barra de desplazamiento, ywaitForLoadState('networkidle')para que nada aparezca en cámara. Autenticación automática a través de unaddInitScriptque siembralocalStorageantes de la navegación, cuando la app lo soporta. - Movimiento: para páginas largas, captura una captura de pantalla de página completa y haz una panorámica (un Ken Burns vertical) en lugar de grabar desplazamiento en vivo entrecortado.
Material de video con modelo real — muestra resultados genuinos, oculta la espera. Cuando una escena debe ejecutar un modelo lento en vivo (subtítulos/chat/inferencia reales), graba el flujo real pero comprime las esperas en el tiempo: marca cada ventana de clic → resultado (un reloj monótono desde el inicio de la página), luego comprime SOLO esas ventanas con ffmpeg (trim+setpts+concat; la acción permanece a 1×) y congela el último fotograma (tpad=stop_mode=clone) para que cualquier duración de escena se reproduzca en el resultado. Primero calienta el modelo con una solicitud desechable — una carga en frío puede ser 10–40× una llamada en caliente (por ejemplo, un modelo de visión: ~38s en frío → ~5s en caliente). Redacta y temporiza la narración sobre el clip comprimido; mantén estas escenas en reproducción simple (la acción lleva el movimiento). Receta completa + fragmentos: references/playwright-recording.md.
Un ejemplo completo de macOS (selectores exactos, hooks de entorno, rectángulo de recorte, rectángulos de elementos y un grabador listo para usar) está en references/video-studio-mlx-app.md — ese ejemplo resulta demostrar la misma app que aloja la API Studio, pero trata sus detalles como ilustrativos; tu objetivo tendrá los suyos propios.
Composición (scripts/compose.py)
Impulsada por configuración, independiente del objetivo. Cada escena se convierte en un clip normalizado a 1080p: el material se escala dentro de una tarjeta enmarcada sobre un escenario degradado oscuro (sombra suave), un subtítulo de Pillow (píldora en tercio inferior para pasos, título grande + subtítulo con cortina para heroico), desvanecimientos de clip + subtítulo, luego una gradación final compartida (color + curva S + sombras frías + viñeta + grano de película + eliminación de bandas) para que capturas dispares se lean como una película dirigida ("grade": false lo desactiva, o pasa un bloque para ajustar strength/tint). Las escenas heroicas reciben un tratamiento cinematográfico: un empuje Ken Burns con atenuación (ease-out) que se desvía lentamente sobre la imagen fija, un fondo oscuro esmerilado detrás de la tarjeta, y una aparición gradual de título luego subtítulo. Los clips se encadenan con transiciones xfade por escena (por defecto fade; establece transition/xfade_dur por escena — fadeblack funciona bien al entrar en una heroica). Audio: la narración se coloca con adelay en la línea de tiempo maestra y se mezcla con amix (normalize=0); una pista de music opcional se duckea con sidechain debajo de la voz en off y la mezcla final se masteriza con loudnorm a −16 LUFS (solo voz aún se masteriza).
Efectos de enfoque — anclados a la narración (zoom + anillo siguen las palabras)
El enfoque debe apuntar a lo que la narración está nombrando, exactamente cuando lo dice — por lo tanto se crea como frase → elemento, temporizado a partir de marcas de tiempo de palabras, nunca colocado a mano en segundos y nunca fijado a un elemento durante toda una escena. Una escena declara una view (qué mapa de rectángulos de elementos) y una lista de focus (los nombres de elemento/vista son los que sean de tu app objetivo):
"view": "main",
"focus": [
{ "say": "search", "element": "search_field" },
{ "say": "results", "element": "result_list" },
{ "say": "generate", "element": "primary_button", "zoom": 1.7 }
]
Cómo lo resuelve compose:
- Cuándo —
resolve_phraseencuentra la ejecución contigua de palabras que coinciden consayen laswordsdel segmento y devuelve [inicio,fin]. Las palabras repetidas no son ambiguas: la lista de palabras es posicional — elige poroccurrence(por defecto la primera). Se reproduce en tiempo de cliplead + inicio_palabra. - Dónde —
elementes un rect enelements.jsonbajo laviewde la escena (o unamap:keypara referenciar un mapa compartido, por ejemplo, una barra lateral persistente). - Cámara —
zoompanmulti-fotograma clave (focus_camera), smoothstep absoluto basado enon. Entre dos enfoques se desliza directamente objetivo→objetivo por defecto; solo vuelve a la vista completa cuando el siguiente objetivo está TANTO lejos (fuera del viewport del zoom anterior) COMO el intervalo es largo (focus_gap_full, ~2.2s) — por lo tanto un elemento adyacente/ya visible solo se desplaza un poco en lugar de un molesto zoom-out/zoom-in. Los desplazamientos son a velocidad constante (duración = distancia ÷focus_pan_speedpx/s, limitado porfocus_move_min): la cámara mantiene el encuadre anterior, luego se desliza a un px/s fijo llegando cuando comienza la siguiente palabra — los desplazamientos cercanos y lejanos se sienten igual, no "lento luego rápido"."focus_pan": truefuerza el deslizamiento directo en todas partes. - Anillo — dibujado en coordenadas del material antes de la cámara, por lo que permanece pegado al elemento mientras hace zoom/desplazamiento; se desvanece dentro/fuera alrededor de la frase.
- Zoom y anillo están desacoplados y el zoom se auto-limita para ajustar (
fit_zoom): el zoom se reduce para que el elemento resaltado quede completamente encuadrado, y un objetivo ancho cae a solo anillo (z=1) para que no se recorte. No los emparejes por defecto — ambos existen solo para señalar el ojo; elige lo que se ajuste al tamaño del objetivo.ring:falseda un zoom suave sin anillo.
Datos de soporte y extensiones:
- Mapa de elementos (
elements.json): rectángulos con nombre por vista en píxeles de material. Ver Grabación para cómo obtenerlos; verifica revisando cada fotograma de enfoque. - Captura más grande de lo que presentas para que el zoom se mantenga nítido — la cámara recorta el material nativo al tamaño en escenario, por lo que ~1.7× todavía tiene píxeles reales. En macOS, la captura Retina ya sobremuestrea. En la web,
deviceScaleFactorNO agranda el video grabado (ver Grabación) — para obtener sobremuestreo, graba a unviewport/recordVideo.sizemás grande que la tarjeta en escenario (por ejemplo, captura 1920 de ancho, presenta en una tarjeta de ~1456), no aumentando DPR. - El grabador puede emitir una pista de interacción (
emit_track.py) para quetrack_to_effectsderive automáticamente un zoom+anillo por clic; elfocusen línea es la ruta precisa. La estructura está abierta para superposiciones decursor/spotlightusando los mismos rectángulos + tiempos de palabras.
Nota de diseño (por qué frase→elemento, no marcadores de señal del lado de la API): las marcas de tiempo de las palabras ya son una lista posicional, por lo que el compositor posee "qué elemento / qué ocurrencia" — la API Studio sigue siendo una primitiva limpia (audio + tiempos de palabras) utilizable para demostrar cualquier producto. El material de video debe mostrar realmente el elemento nombrado (sin desplazamiento/estático) en ese momento; redacta la narración para que lo haga.
Matemáticas de línea de tiempo (mantén el video y el audio consistentes)
- duración de escena
d_i = narración_i + pad_i(pad≈ 2 paso / 3.4 heroico). - inicio de escena en la línea maestra es acumulado por transición:
start_0 = 0,start_i = start_(i−1) + d_(i−1) − T_i, dondeT_ies la duración de xfade HACIA la escenai(por escenaxfade_dur, por defectoxfade; limitado por debajo de ambos clips adyacentes). Con cadaT_i = Testo se reduce aΣ d_(<i) − i·T. - coloca la narración
ienstart_i + lead(lead ≈ 0.8, después del fundido cruzado entrante) — el mismostart_irecalculado, por lo que el audio se mantiene sincronizado. Aseguratin_i + d_i ≤longitud del clip fuente.
Verificación (todas las comprobaciones en falso positivo, el usuario final no las reprocesa)
Después de la composición, ejecuta scripts/verify.py (o verifica manualmente):
- Fotograma de enfoque: para cada elemento de enfoque, extrae el fotograma en el tiempo
t_enfoquey confirma (usando detección de bordes simple + umbral de color) que el elemento está dentro del rectángulo esperado y que el anillo (si lo hay) rodea ese rect. Esto atrapa rectángulos de elementos incorrectos y desajustes de DPR. - Verificación de línea: para el primer y último segmento, extrae el audio (
ffmpeg -vn), ejecutareferences/studio-api.md/asr, y confirma que la transcripción coincide con la narración esperada (ignora puntuación/mayúsculas). Una alta dispersión de WER entre segmentos apunta a una fuga de audio de otro clip. - Fotograma de cierre:
ffmpeg -sseof -3 -i out.mp4 -update 1 -q:v 1 lastframe.jpg. Debería mostrar el estado final de la última escena (no un fundido a negro repentino o un grano de película estático). - La verificación más robusta es una extracción de tira de película:
scripts/verify.pypuede extraer un fotograma cada N segundos y embeberlos en un PDF de contacto para revisión visual sin renderizar de nuevo.
Scripts y estructura de referencia
scripts/generate_narration.py— Llama a la API de TTS, maneja colas de solicitudes, escribe el manifiesto.scripts/compose.py— El motor de composición FFmpeg. Aceptastoryboard.jsony--output out.mp4.scripts/verify.py— Verificación automática de fotogramas de enfoque + ASR.references/— Documentación de API, plantillas de storyboard, ejemplos.<trabajo>/— Directorio de trabajo creado por el script, contiene material de video, elementos.json, etc.
Manejo de errores y notas operativas
- La API de narración puede fallar. Si una solicitud POST a /studio/tts falla (timeout, error 500), reintenta hasta 2 veces con un backoff exponencial (1s, 2s). Si todas fallan, aborta la generación de ese segmento y reporta el error en
narration/manifest.jsoncon"status": "failed". El proceso de composición luego ignorará los segmentos fallidos (no audio para esa escena) — el verificador los marcará. Para un video funcional, necesitas éxito en todos los segmentos. - Los tamaños de archivo importan. La composición FFmpeg es intensiva en memoria; para videos >120s a 1080p, monitorea el uso de RAM. Si usas un bucle de música largo, recórtalo a la duración del video con
ffmpeg -t duración_videoantes de pasarlo a compose. - Nombres de archivos y rutas. Todos los scripts esperan rutas relativas al directorio de trabajo (
<trabajo>/). Las rutas absolutas en storyboard.json causarán errores en los scripts de referencia. Usa./grabaciones/escena_01.mp4no/Users/user/Desktop/grabaciones/escena_01.mp4.
Referencias clave
references/studio-api.md— Documentación completa de la API, incluyendo formato de solicitud/respuesta, configuración del servidor y contratos de alineación de palabras.references/storyboard.example.json— Storyboard de ejemplo que muestra la estructura JSON y los campos.references/video-studio-mlx-app.md— Ejemplo detallado de grabación de una app macOS, incluyendo selectores de AppleScript, rectángulos de recorte y mapa de elementos.references/playwright-recording.md— Receta y fragmentos de código para grabación optimizada de sitios web con Playwright, incluyendo compresión de espera y trucos de estabilización.