Communitygithub.com

TVideo — tu app web real en videotutoriales 1080p con subtítulos

Plugin de Claude Code que graba tu app web real con Playwright y un cursor visible, y luego la edita con Hyperframes: subtítulos por paso en cualquier idioma, zoom y aro de resalte en cada control, sonidos de clic, música y TTS opcional, un MP4 1080p por tarea.

¿Qué es TVideo — tu app web real en videotutoriales 1080p con subtítulos?

Paso 1 de la receta Video tutorial (el paso a paso), de JiramedFirst/TVideo (publicado el 2026-10-08, MIT, GIF de demo de 33 s y capturas en el README). Pide un tutorial sobre una app de staging: Claude divide el pedido en un clip por tarea y acuerda la lista contigo, escribe un script de Playwright por clip y lo ensaya sin grabar para comprobar cada selector, y luego graba video.webm con timeline.json y clicks.json. El editor de Hyperframes coloca el material sobre un lienzo con tu marca, congela la imagen donde hace falta tiempo para leer, hace zoom y rodea el control que hay que pulsar, añade un sonido por clic, música y narración HeyGen opcional, y renderiza en 1080p. La edición se genera desde plan.json y la línea de tiempo de pasos, así que tras un cambio de interfaz basta con grabar, importar, construir y renderizar. Credenciales solo por variables de entorno, pregunta antes de tocar entornos compartidos y nunca completa un pago real.

Compatible con~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JiramedFirst/TVideo/tree/HEAD/plugin/skills/tvideo

Preguntar en tu IA favorita

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

Documentación

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.

NecesidadVerificaciónSolución
Node ≥ 20node -vinstalar Node
ffmpeg / ffprobeffmpeg -versionbrew install ffmpeg / apt
Hyperframes CLI + habilidadesnpx hyperframes --versionnpx hyperframes skills update general-video (también instala media-use, hyperframes-audio)
Chromium para Playwrighten 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:

  1. 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.
  2. 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).
  3. 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.
  4. Idioma de la interfaz de usuario y los subtítulos (TV_LOCALE, lang).
  5. 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.
  6. 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 mask para 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 deja TV_USERNAME sin 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

  1. Crea una carpeta de trabajo por proyecto, por ejemplo tvideo-work/<app>/, luego copia templates/recorder/ → recorder/ y ejecuta npm i allí.
  2. 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).
  3. Escribe una especificación por clip en recorder/clips/NN-name.spec.ts, siguiendo clips/01-example.spec.ts: createTimeline primero; cada paso visible para el espectador es tl.step('<texto del subtítulo>', …) que termina en un expect; clics mediante tap()/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.
  4. 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

  1. Extrae fotogramas para encontrar coordenadas: bash <skill>/scripts/frames.sh assets/footage.mp4 frames <t1> <t2> …. Buenos momentos: cada clic en clicks.json menos ~0.3 s (el cursor ya está en el control — esa es su posición), y el endMs de 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).
  2. 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: true cuando 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.
  3. node build.mjs luego npx hyperframes check. Corrige cada error; las advertencias de contraste durante la aparición gradual de un subtítulo son esperadas e inofensivas.
  4. Verifica con tus propios ojos: build.mjs imprime 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

  1. Abre una vista previa: npx hyperframes render --quality draft -o renders/draft.mp4 y open (la vista previa de Studio npx hyperframes preview --background también funciona, pero su búsqueda puede tartamudear en clips largos; el renderizado nunca lo hace).
  2. 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.
  3. Final: npx hyperframes render --quality delivery -o renders/<nombre-del-clip>.mp4. Informa la ruta, duración y tamaño.
  4. 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 el examples/demo-app del repositorio de plugins, emparejado con plan.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

Skills relacionados