De página interactiva a video
Este directorio es la herramienta. Un navegador sin cabeza recorre la página interactiva como un lector (desplazándose, haciendo clic, arrastrando, con el cursor visible), graba la pantalla mientras lo hace, le añade voz humana y produce un MP4 en 1080p.
La grabación y la composición son automáticas; tú debes escribir el guion para cada página interactiva: entender la página, decidir qué explicar, qué omitir y qué acciones realizar en cada paso. Esta es la mayor parte del trabajo.
lib/record.mjsEl grabador: abre la página, inyecta el cursor y los subtítulos, captura fotogramas para comprimirlos en video y graba el audio de la propia página.lib/make.mjsProceso completo para el tipo explicativo: sintetiza la narración → las operaciones se ejecutan según la duración de la narración mientras se graba → compone el video final y los subtítulos.lib/voice.mjs+lib/tts.pyClonación de voz (IndexTTS-2).lib/subtitles.mjsDivisión de subtítulos, estimación de duración y detección de silencios (incluye pruebas,npm test).examples/demo/Un pequeño ejemplo listo para ejecutar (una página interactiva pequeña + su guion). Ejecútalo primero para verificar que el entorno funciona.examples/Dos ejemplos reales de otros tipos, pero no se pueden ejecutar directamente (dependen de los archivos de la página interactiva correspondiente). Sirven para aprender la estructura.
La configuración del entorno está en el README. Los archivos intermedios se escriben en work/ del directorio actual, y el video final en out/. Ejecuta la herramienta en el directorio donde quieras que aparezca el video.
Clasificación previa
| A: Explicativo | B: Con sonido propio | |
|---|---|---|
| Características de la página | Sin voz humana; el lector lee y opera por sí mismo | Tiene su propio audio original, efectos de sonido y subtítulos; avanza automáticamente al desplazarse |
| Sonido del video | Se escribe una narración aparte y se clona la voz | Se graba el audio de la propia página; solo se añade voz humana a las partes sin texto sonoro |
| Ejemplo | examples/explainer-involution.mjs | examples/selfvoiced-jensen.mjs |
| Comando | node lib/make.mjs <guion>.mjs | node <guion>.mjs |
Para crear un nuevo episodio: copia el ejemplo correspondiente y modifícalo. Los comentarios en los ejemplos explican qué hace cada sección.
Principios
- Haz videos explicativos completos, no avances cortos.
- El ritmo debe ser ajustado: las partes sin narración deben ser lo más breves posible. Una vez generado el video, revisa los "segmentos sin voz" y, si duran más de diez segundos, intenta acortarlos o eliminarlos.
- Donde haya texto, debe haber voz humana, no solo sonido de tecleo.
- Si alguna parte de la página interactiva no queda bien en video, modifícala o elimínala (acorta minijuegos, reduce el número de preguntas). Solo modifica durante la grabación, no toques los archivos originales de la página (ver
transformen el tipo B). - La primera versión debe ser completa antes de mostrarla a nadie; no hagas preguntas intermedias.
Tipo A: Explicativo
- Lee la página interactiva por completo y escribe el guion:
url,hideCss(para ocultar navegación, barras de progreso, etc.),setup,segments. Cada segmento tiene{ id, say, run }:sayes la narración (también los subtítulos) yrun(ctx, t)son las operaciones durante esa narración;await t.at(0.5)espera a que la narración llegue a la mitad antes de actuar.ctxproporcionascrollTo / click / move / drag / wait / card. - La narración es para que la audiencia la escuche, no para leer el texto de la página. Elimina las partes que no funcionen bien en video (experimentos de exploración libre, listas largas, referencias).
- Audio de referencia: escribe
voice: 'ruta'en el guion, o coloca el archivovoice/ref.waven el directorio actual. Debe tener entre diez y treinta segundos, ser silencioso, con una sola persona hablando. - Primero genera una versión sin voz:
node lib/make.mjs <guion>.mjs --silent. Estima la duración de cada segmento según el número de palabras, solo genera subtítulos, y en unos minutos podrás ver el ritmo y las imágenes de todo el video. La generación de voz es lenta; no la actives hasta que hayas ajustado las imágenes. - Una vez que las imágenes estén definidas, elimina
--silentpara generar el video con voz. Para ajustar segmentos específicos, usa--only idDeSegmento,idDeSegmento.
lib/tts.py normaliza la velocidad de todos los segmentos, acorta las pausas dentro de las frases, reduce el ruido y alinea el volumen; si la velocidad o el tono son extraños, lo repite automáticamente.
Tipo B: Con sonido propio
- Lee el código fuente de la página interactiva y determina tres cosas: cómo se navega (desplazamiento / clics), dónde se detiene para esperar al lector (interacciones) y qué texto no tiene sonido.
- Copia el ejemplo y modifícalo:
serve: Sirve la carpeta local como un sitio web (con interceptación de solicitudes, sin abrir puertos).INTERACTIONS: Cada interacción define "cómo reconocerla (selector) + cómo actuar". Usa movimientos reales del ratón, arrastres y clics. Si se agota el tiempo de espera, activa el "saltar" de la página.- Bucle principal: Si no está esperando una interacción, desplázate hacia abajo con la rueda; si el texto se está escribiendo, espera; si la narración no ha terminado, también espera.
transform: Modifica temporalmente el script al enviarlo al navegador (acorta minijuegos, reduce pausas, añade narración), sin tocar el archivo original. Las modificaciones deben basarse en coincidencias exactas del texto original; si no coinciden, muestra un error, no permitas que fallen silenciosamente.
- Texto sin sonido: haz una lista y pásala a
synthesize()para sintetizarlo; durante la grabación, registra el momento en que el texto comienza a aparecer y mézclalo en el audio final según esos puntos. Desactiva el sonido de tecleo en las partes con voz humana, y ajusta la velocidad de aparición según la duración de la voz. - Usa
--max segundospara grabar solo el principio;--from posiciónpara empezar desde un punto intermedio; cuando todo esté bien, graba el video completo (grabación en tiempo real, el video durará lo que dure la página).
Problemas comunes
- Sonido: Chrome sin cabeza debe usar
--disable-audio-output(ya está enlib/record.mjs). Si usas--mute-audio, el motor de sonido se monta en la tarjeta de sonido del sistema; si el sonido del sistema es inestable, el audio de la página se detiene, arruinando toda la grabación. - Nitidez: La resolución 1080p se logra con
--force-device-scale-factor=1.5+ ventana de 1280×720. No useszoomCSS (porque100vhse desajusta y los diseños adhesivos se tuercen). - Narrativa de desplazamiento: En páginas con GSAP ScrollTrigger, después de cambiar la altura (por ejemplo, al expandir una sección), debes disparar un evento
resize; de lo contrario, la posición de activación quedará desactualizada. - Bloqueos: Los ejemplos incluyen un watchdog; si la página no se mueve o el audio no avanza durante más de 40 segundos, se detiene. Si ves "atascado", investiga la causa antes de volver a grabar; no lo intentes de nuevo al azar.
- La generación de voz es lenta: IndexTTS-2 tarda desde decenas de segundos hasta minutos por frase en una computadora portátil. Para treinta o cuarenta frases, reserva al menos media hora. Si solo quieres ejecutar una tarea de este tipo a la vez en la máquina, configura
HEAVY_LOCK. - Disco duro: Una grabación de 20 minutos genera unos 1.5 GB de archivos intermedios.
Verificación obligatoria después de generar
Claude no puede escuchar audio. Debes comunicar esto al usuario de forma clara, sin ambigüedades.
- Fotogramas clave: Extrae entre cuarenta y cincuenta fotogramas distribuidos uniformemente, combínalos en una imagen y revísalos; luego revisa por separado el momento de cada interacción para confirmar que se realizaron correctamente y que no se quedaron a medias.
- Registros: Cada interacción debe aparecer; no debe haber "error", "no terminó solo, saltado" ni "atascado"; el número de errores de la página debe ser 0.
- Sonido: La duración de la pista de audio debe coincidir con la del video; no debe haber cortes en medio; revisa la lista de "segmentos sin voz".
- Al informar, especifica: qué partes has revisado visualmente, qué partes solo puede revisar una persona (pronunciación, tono, palabras entremezcladas en chino e inglés); qué contenido has modificado o eliminado de la página; y qué segmentos sin voz son demasiado largos.
Reglas sobre la voz
- Solo clona tu propia voz, o voces para las que tengas autorización explícita.
- Si la narración sintetizada se mezcla con audio original real en el mismo video, indica en la descripción al publicar que la narración es sintética.