Communitygithub.com

JacobLinCool/video-studio-mlx

Produce un video demo o promocional narrado y pulido de CUALQUIER aplicación o sitio web. La grabación de pantalla es real del producto que muestras; la narración es generada y validada por ASR a través de la API High Level Studio de video-studio-mlx (/studio/tts, clonación de voz opcional). Cubre la escritura del guion primero, la grabación del objetivo (app macOS vía AppleScript o sitio web vía Playwright), la composición con ffmpeg (marco con escenario, subtítulos PNG, zoom heroico, enfoque con zoom y anillo anclado a la narración) y la verificación de fotogramas y ASR.

¿Qué es video-studio-mlx?

Esta habilidad te permite crear videos demo narrados y pulidos (de 90 a 180 segundos) de cualquier producto que el usuario nombre: una app de macOS, un sitio web, una CLI, etc. 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 mediante reconocimiento de voz (ASR). El tema del demo es arbitrario y cambia cada vez. La habilidad se basa en un principio fundamental: generar la narración antes de cualquier grabación, utilizando las duraciones exactas y marcas de tiempo palabra por palabra que devuelve la API para definir toda la línea de tiempo y los efectos de enfoque. Luego se graba el material generosamente y se ajusta cada clip a su segmento de narración. El flujo de trabajo incluye: escribir un guion gráfico por escena, generar la narración con la API, grabar la aplicación o sitio objetivo (usando AppleScript para apps macOS o Playwright para sitios web), y componer el video final con ffmpeg, aplicando efectos como zoom heroico, subtítulos, transiciones, y enfoque anclado a la narración (zoom + anillo que sigue las palabras). Finalmente, se verifica el video extrayendo fotogramas y ejecutando ASR en segmentos para confirmar la sincronización. La habilidad soporta tanto aplicaciones macOS como sitios web, con instrucciones detalladas para cada plataforma, incluyendo la obtención de mapas de rectángulos de elementos para los efectos de enfoque.

Compatible con~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JacobLinCool/video-studio-mlx/tree/HEAD/.agents/skills/studio-demo-video

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

  1. 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.json a <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.
  2. 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 (el ref_audio del usuario, o una instrucción voice que diseña una vez — ver abajo), lo valida con ASR, y escribe narration/manifest.json con duration_s, wer, y words por palabra, por segmento. (Ver references/studio-api.md.)
  3. 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á.
  4. 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.
  5. 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 en references/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 /asr primero (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 de voice en el guion gráfico y generate_narration.py diseñ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. drawtext a 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:

  1. 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
  2. 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, confirma crop=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 select de AX o AXPress en 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.
  • -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+size de 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; establece recordVideo.size igual al viewport y 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: 2 solo agudiza el renderizado — NO escala el video grabado, y un recordVideo.size má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 por tamañ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, y waitForLoadState('networkidle') para que nada aparezca en cámara. Autenticación automática a través de un addInitScript que siembra localStorage antes 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_phrase encuentra la ejecución contigua de palabras que coinciden con say en las words del segmento y devuelve [inicio,fin]. Las palabras repetidas no son ambiguas: la lista de palabras es posicional — elige por occurrence (por defecto la primera). Se reproduce en tiempo de clip lead + inicio_palabra.
  • Dónde — element es un rect en elements.json bajo la view de la escena (o una map:key para referenciar un mapa compartido, por ejemplo, una barra lateral persistente).
  • Cámara — zoompan multi-fotograma clave (focus_camera), smoothstep absoluto basado en on. 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_speed px/s, limitado por focus_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": true fuerza 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:false da 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, deviceScaleFactor NO agranda el video grabado (ver Grabación) — para obtener sobremuestreo, graba a un viewport/recordVideo.size má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 que track_to_effects derive automáticamente un zoom+anillo por clic; el focus en línea es la ruta precisa. La estructura está abierta para superposiciones de cursor/spotlight usando 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, donde T_i es la duración de xfade HACIA la escena i (por escena xfade_dur, por defecto xfade; limitado por debajo de ambos clips adyacentes). Con cada T_i = T esto se reduce a Σ d_(<i) − i·T.
  • coloca la narración i en start_i + lead (lead ≈ 0.8, después del fundido cruzado entrante) — el mismo start_i recalculado, por lo que el audio se mantiene sincronizado. Asegura tin_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_enfoque y 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), ejecuta references/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.py puede 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. Acepta storyboard.json y --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.json con "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_video antes 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.mp4 no /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.

Skills relacionados