TVideo — videos tutoriales desde una aplicación web real
Estás produciendo videos cortos que enseñan a los usuarios finales cómo realizar una tarea en una aplicación web. Los espectadores no son técnicos: cada fotograma debe ser tranquilo, legible y real. El flujo de trabajo tiene dos mitades que se encuentran en tres archivos:
grabador (Playwright) ──► video.webm + timeline.json + clicks.json ──► editor (Hyperframes) ──► MP4
- Grabador (
templates/recorder/) maneja la aplicación real, dibuja un cursor visible y registra cuándo comienza/termina cada paso y cuándo se realiza cada clic. - Editor (
templates/editor/build.mjs) coloca el metraje en un lienzo con marca, mantiene una imagen fija donde el espectador necesita tiempo para leer, acerca + rodea el control a presionar, coloca un sonido de clic en cada clic y renderiza.
Debido a que la edición se genera a partir de esos archivos, una regrabación después de un cambio en la interfaz de usuario es solo: grabar → importar → compilar → renderizar. Mantenlo así — nunca edites manualmente index.html; cambia plan.json / tvideo.config.json y reconstruye.
Fase 0 — Verificación previa
Ejecuta estas comprobaciones al inicio de cada sesión — junto con tu primera respuesta si estás haciendo preguntas breves, para que el usuario no tenga que esperar — y corrige las carencias antes de grabar; una herramienta faltante encontrada a mitad de la grabación arruina una toma.
| Necesidad | Verificación | Solución |
|---|---|---|
| Node ≥ 20 | node -v | instalar Node |
| ffmpeg / ffprobe | ffmpeg -version | brew install ffmpeg / apt |
| Hyperframes CLI + habilidades | npx hyperframes --version | npx hyperframes skills update general-video (también instala media-use, hyperframes-audio) |
| Chromium para Playwright | en el directorio del grabador: npx playwright install chromium | — |
Lee references/hyperframes-notes.md una vez si no has usado Hyperframes en esta sesión (reglas de composición que el script de compilación ya sigue y por qué).
Fase 1 — Breve (pregunta, no asumas)
Recopila, en una ronda corta, qué cambios afectan el trabajo:
- URL de la aplicación y entorno. Prefiere un entorno de staging/UAT/demo. La grabación maneja la aplicación en tiempo real: los formularios se envían, los registros se crean, los correos salen. Dilo claramente y obtén un sí antes de grabar contra algo compartido.
- Inicio de sesión: una cuenta de demo dedicada (nombre de usuario/contraseña mediante variables de entorno — nunca pegadas en el chat ni escritas en archivos). Si el inicio de sesión necesita OTP/2FA, planea que el usuario pegue el código durante la ejecución (consulta
references/recording.md). - Los flujos: un video por tarea. Divide "cómo usar el sistema" en clips de 30–120 s cada uno (iniciar sesión, crear X, editar/cancelar X, descargar Y…). Pregunta el orden en que el espectador debería verlos.
- Idioma de la interfaz de usuario y los subtítulos (
TV_LOCALE,lang). - Marca: archivo de logotipo, 1–2 colores, fuente si el idioma lo necesita (IBM Plex Sans Thai incluido cubre tailandés + latín). Los valores predeterminados son un azul marino/verde neutro.
- Audio: subtítulos + efectos de sonido de clic son el valor predeterminado. Música: pista CC BY incluida o ninguna. La narración es opcional y consume cuota de TTS — consulta
references/narration.md.
Decisiones de seguridad (decídelas en la breve, antes de cualquier grabación)
Estos videos se distribuyen y la grabación realiza acciones reales. Explica la compensación, recomienda la opción segura y deja que el usuario decida — luego síguela.
- De quién son los datos en pantalla. Nada que la audiencia no deba ver: nombres de otros clientes, pedidos reales, correos electrónicos/direcciones/números de teléfono personales, etiquetas de prueba internas. Recomienda una cuenta de demo ficticia. Si el usuario insiste en una cuenta personal o real, di exactamente lo que será visible, obtén un OK explícito y planea
maskpara cada valor personal (verifícalos en las capturas de pantalla). Si no estás seguro de si un valor es real, pregunta. - Pasos irreversibles o financieros (pagar, transferir, enviar a un tercero real, eliminar, publicar). Nunca completes un pago real u otra acción irreversible solo para filmarlo. Prefiere un modo sandbox/prueba (tarjeta de prueba, pasarela de staging); si no hay ninguno, graba hasta la pantalla de confirmación final, detente allí y deja que el último subtítulo explique el clic final. Dilo en la breve.
- Producción vs staging. Grabar en un sitio de producción en vivo necesita un sí explícito después de que hayas enumerado lo que creará (pedidos, correos electrónicos, cambios de stock) y cómo se limpiará. Prefiere flujos que sean de solo lectura o reversibles allí.
- Credenciales. Las contraseñas y OTP van en variables de entorno / un archivo local que el usuario controla, nunca en el chat ni en archivos que crees. Un nombre de usuario/correo electrónico que el usuario ya escribió no es un secreto, pero no lo repitas en archivos más allá de
TV_USERNAME. - Inicio de sesión de terceros (Google, Microsoft, SSO, captcha). El inicio de sesión automatizado allí generalmente encuentra comprobaciones de bots o 2FA. Haz que el usuario inicie sesión una vez manualmente en un navegador con interfaz gráfica (
npx playwright codegen --save-storage=.auth/state.json <URL de inicio de sesión>), luego graba con esa sesión guardada y dejaTV_USERNAMEsin establecer. - Publicación. Antes de entregar, vuelve a mirar en busca de datos personales y mantén el crédito de música en el outro (CC BY requiere atribución). Las páginas públicas son una audiencia más estricta que la capacitación interna: aplica las reglas de privacidad estrictamente.
Fase 2 — Descubrir y ensayar
- Crea una carpeta de trabajo por proyecto, por ejemplo
tvideo-work/<app>/, luego copiatemplates/recorder/→recorder/y ejecutanpm iallí. - Descubrir: abre cada página de un flujo (Playwright MCP / herramientas del navegador, o un script desechable) y elige selectores estables — prefiere roles/etiquetas/test-ids sobre clases CSS. Anota cosas que no se filmarán bien (consulta recording.md: menús desplegables nativos
<select>, selectores de fecha, saltos de desplazamiento instantáneos, ventanas de reserva). - Escribe una especificación por clip en
recorder/clips/NN-name.spec.ts, siguiendoclips/01-example.spec.ts:createTimelineprimero; cada paso visible para el espectador estl.step('<texto del subtítulo>', …)que termina en unexpect; clics mediantetap()/typeInto();glideTo()antes de cualquier cosa debajo del pliegue;hold()después de momentos clave;await tl.save()al final. Elige valores como lo haría un usuario — elige de listas desplegables/calendarios en lugar de escribir códigos. - Ensayar:
TV_REHEARSE=1 npx playwright test— sin video, sin pausas. Corrige cada fallo aquí; cuesta segundos en lugar de una toma arruinada.
Fase 3 — Grabar
npx playwright test (o un clip: npx playwright test clips/02-). Cada clip escribe video.webm, timeline.json, clicks.json en test-results/<clip>/. Cópialos inmediatamente (el siguiente paso lo hace) — Playwright borra test-results/ en la siguiente ejecución.
Un paso fallido significa que la aplicación hizo algo inesperado (validación, una regla de negocio, carga lenta). Lee la captura de pantalla del fallo, corrige la especificación o los datos, vuelve a ejecutar ese clip. Nunca aflojes una aserción solo para obtener una toma; una toma verde de un flujo roto enseña a los usuarios lo incorrecto.
Fase 4 — Configurar la edición
Un proyecto de Hyperframes por clip, junto al grabador (por ejemplo tvideo-work/<app>/clip-02/). hyperframes init escribe sus propios archivos de inicio; copiar la plantilla sobre ellos es intencional (build.mjs regenera index.html). Ejecuta desde la carpeta de trabajo:
npx hyperframes init clip-02 --non-interactive --example=blank
cp -R <skill>/templates/editor/. clip-02/
cp clip-02/tvideo.config.example.json clip-02/tvideo.config.json # marca, fuente, logotipo, música, idioma
cp clip-02/plan.example.json clip-02/plan.json # título, outro, un paso por tl.step
ls recorder/test-results/ # el nombre de la carpeta del clip es largo — encuéntralo aquí
bash <skill>/scripts/import.sh recorder/test-results/<esa-carpeta> clip-02
bash <skill>/scripts/sfx.sh clip-02 # click-soft, whoosh-short, chime, sparkle
En tvideo.config.json: establece lang y readingCharsPerSec (≈15 inglés, ≈12 tailandés — los scripts más lentos se leen más lento), los colores de la marca y logo (una ruta, o null para tarjetas solo texto). Mantén music.credit — la pista incluida es CC BY.
Los pasos de plan.json se asignan 1:1, en orden a los tl.step del grabador (la compilación rechaza un desajuste). Los subtítulos en plan.json son lo que el espectador lee — mantenlos como instrucciones cortas ("Haz clic en "Guardar""), no narración. Generalmente las etiquetas de tl.step ya son buenos subtítulos; cópialos.
Fase 5 — Medir, compilar, verificar
- Extrae fotogramas para encontrar coordenadas:
bash <skill>/scripts/frames.sh assets/footage.mp4 frames <t1> <t2> …. Buenos momentos: cada clic enclicks.jsonmenos ~0.3 s (el cursor ya está en el control — esa es su posición), y elendMsde cada paso menos 0.3 s (el resultado establecido). Lee los PNG de tamaño completo. Las coordenadas están en los píxeles de la grabación (por ejemplo, 1280×800). - Añade por paso según sea necesario (detalles en
references/editing.md):zoom {scale,at}+ring {x,y,w,h}en el control a presionar — el zoom se centra en el anillo (el punto fijo de un zoom debe estar en el control, o el control se desliza hacia el borde y se recorta);holdFirst: truecuando el control desaparece una vez hecho clic (un botón que navega a otro lugar) — muestra primero el fotograma anterior al clic;mask {x,y,w,h,text,after}para cubrir un valor que no debe enviarse;chimeAfter: <s>para un momento de éxito.
node build.mjsluegonpx hyperframes check. Corrige cada error; las advertencias de contraste durante la aparición gradual de un subtítulo son esperadas e inofensivas.- Verifica con tus propios ojos:
build.mjsimprime dónde cae cada paso en la línea de tiempo de SALIDA (el tiempo de salida ≠ tiempo de grabación — la introducción y las pausas lo desplazan). Captura instantánea dentro de esas ventanas —npx hyperframes snapshot --at <t…> --no-end, una dentro de cada imagen fija que tenga un anillo, cada máscara, cada punto medio del paso — y lee la hoja de contactos. Los anillos deben estar en el control, las máscaras deben cubrir exactamente, los subtítulos deben coincidir con lo que está en pantalla.
Fase 6 — Revisar y renderizar
- Abre una vista previa:
npx hyperframes render --quality draft -o renders/draft.mp4yopen(la vista previa de Studionpx hyperframes preview --backgroundtambién funciona, pero su búsqueda puede tartamudear en clips largos; el renderizado nunca lo hace). - Itera sobre los comentarios editando el plan/config y reconstruyendo — o regrabando cuando el metraje en sí está mal (ritmo, un salto, datos incorrectos). Corrige los problemas del metraje en la fuente, no con superposiciones.
- Final:
npx hyperframes render --quality delivery -o renders/<nombre-del-clip>.mp4. Informa la ruta, duración y tamaño. - Limpia lo que la grabación creó en la aplicación (pedidos/reservas de demo) si el entorno es compartido y di lo que limpiaste.
Cuando algo sale mal
references/troubleshooting.md enumera los fallos que este flujo de trabajo ya ha encontrado y sus causas reales (deriva de metraje/línea de tiempo, selects nativos, ventanas de reserva, resultados de prueba sobrescritos, lint de superposición de SFX, tartamudeo en la vista previa). Revísalo antes de depurar desde cero.
Archivos en esta habilidad
templates/recorder/— Proyecto de Playwright:cursor.ts,timeline.ts,auth.setup.ts,playwright.config.ts,clips/01-example.spec.ts(escrito para elexamples/demo-appdel repositorio de plugins, emparejado conplan.example.json)templates/editor/—build.mjs,plan.example.json,tvideo.config.example.json,assets/fonts(OFL),assets/music(CC BY)scripts/—import.sh,frames.sh,sfx.sh,voice.mjs(TTS opcional)references/—recording.md,editing.md,narration.md,hyperframes-notes.md,troubleshooting.md