Communitygithub.com

chrislitality-svg/script-to-video

Convierte cualquier documento textual (informes de ingeniería, artículos científicos, manuales, divulgación) en un video corto vertical 3:4 (1080×1440, 60–150 segundos). Renderizado puramente con código: HTML de archivo único con línea de tiempo determinista → capturas cuadro por cuadro con Playwright → codificación con ffmpeg. Sin software de edición, sin APIs de video AI, 100% local y de bajo costo, reproducible cuadro a cuadro. Ideal para: convertir documentos existentes en videos; narración de datos/videos de divulgación; producción de videos en lote, auditables y reproducibles; ejecución directa por modelos LLM con capacidad de programación.

¿Qué es script-to-video?

Esta skill transforma cualquier tipo de documento (informes, artículos, manuales, materiales divulgativos) en un video corto de formato vertical (1080×1440, 60–150 segundos) sin necesidad de software de edición tradicional ni APIs de generación de video por IA. El flujo de trabajo se basa en un pipeline reproducible compuesto por: narración (TTS con edge-tts), línea de tiempo sincronizada con la duración real de la voz, animaciones CSS/Canvas en un único archivo HTML, captura de cuadros con Playwright y codificación final con ffmpeg. Todo el proceso es local, de código abierto y bajo costo. La skill está diseñada para ser utilizada tanto por humanos como por agentes de IA con capacidad de programación (como Claude Code, Cursor, etc.). Incluye nueve etapas modulares con auditorías automáticas y manuales para garantizar la calidad: verificación de texto fuera de límites, superposición de elementos, sincronización audio-video, y siete comprobaciones finales (bucle sin costuras, presencia de pista de audio, visibilidad de subtítulos, etc.). El resultado es un video listo para publicar, acompañado de un archivo SRT de subtítulos y un texto promocional.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add chrislitality-svg/script-to-video

Preguntar en tu IA favorita

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

Documentación

script-to-video · Documento → Video corto vertical de divulgación

Tres principios rectores a los que se debe volver en cada decisión:

  1. Línea de tiempo determinista: La animación es una función pura setTime(t) — en el mismo instante siempre se renderiza la misma imagen. Esto permite auditoría saltando cuadros, capturas segmentadas en paralelo, prueba de ciclo, y cambiar una constante para acelerar o ralentizar todo el video.
  2. La línea de tiempo se guía por la duración real de la locución: Primero se graba la locución, se mide la duración de cada frase, y luego se definen los límites de las escenas — el audio y el video se sincronizan naturalmente, sin necesidad de alineación ASR.
  3. Los ojos del usuario no deben ser el primer control de calidad: La auditoría programática (sin superposiciones ni desbordamientos) debe ser cero antes de capturar cuadros; la inspección visual de cuadros clave es la última barrera para la estética.

Proceso (nueve pasos; si alguno falla, se vuelve al paso anterior)

Documento ─▶ ① Constitución de datos ─▶ ② División de texto y subtítulos ─▶ ③ Locución (duración real)
     ─▶ ④ Sincronización de línea de tiempo ─▶ ⑤ Animación anim.html ─▶ ⑥ Doble auditoría cero + inspección visual de cuadros clave
     ─▶ ⑦ Música + mezcla + masterización ─▶ ⑧ Captura cuadro por cuadro → codificación → composición ─▶ ⑨ Siete comprobaciones → entrega

① Constitución de datos

Lee el documento completo y crea una lista fija con todos los números, hechos, nombres de personas que deben aparecer en el video. Escríbela en shots/facts.md. A partir de ese momento, cualquier imagen, texto o subtítulo solo puede hacer referencia a esa lista, está prohibido improvisar.

  • Los números verificables deben destacarse; los detalles no verificables deben omitirse (mejor menos información que información falsa).
  • Cada número se menciona una sola vez, en el pico emocional.
  • Los números deben aparecer "acompañados de un evento": dibujo que crece, conteo sincronizado, caída.

② División de texto y subtítulos

Escribe el guion en shots/vo_lines.json: una frase por línea, cada una de 4 a 12 segundos, total de 8 a 16 frases para todo el video.

  • Los primeros 5 segundos deciden si el espectador continúa: elige entre dinero/conflicto/suspense para la primera frase (ejemplo: "¿Y si te dieran X para construir un camino... te atreverías?").
  • Estructura de referencia: Gancho → Problema → Negación → Solución → Prueba → Resultado → Personaje → Cierre (se puede recortar).
  • Para cada frase, especifica manualmente la división de subtítulos ("cues": [...], cada bloque ≤18 caracteres), es más fiable que una división mecánica por puntuación.

③ Locución

Ejecuta python templates/vo_tts.py (por defecto usa edge-tts, gratuito; si hay GPU local se puede cambiar a modelo de clonación de voz, ver references/audio.md). Cada frase genera un archivo wav y la duración real en audio/vo/vo_dur.json.

  • Los números y años en chino deben escribirse carácter por carácter (2022 → 二零二二); el punto decimal se escribe "点".
  • Ocasionalmente el TTS no responde: el script debe reintentar y permitir reanudar desde el último punto.

④ Sincronización de línea de tiempo

Ejecuta python templates/sync.py: la duración de cada escena = 0.25s de anticipación + duración de la frase + respiro al final (0.5–1.9s). Automáticamente escribe la TL (línea de tiempo) y CUES (subtítulos) en anim.html, y genera shots/timeline.json para la mezcla de audio. Si se cambia la locución, es obligatorio volver a ejecutar este paso, y se debe escalar los momentos de sincronización de VO dentro de la escena según la proporción de la duración nueva respecto a la anterior.

⑤ Animación

Copia templates/anim.html y modifica las escenas. El esqueleto incluye: sistema de diseño estilo plano/ingenieril, funciones auxiliares, auditor, transición de barrido, capa de subtítulos, y 3 escenas de ejemplo. Modo de trabajo:

  • Cada escena defscene(id, cam=>{...; return (t,d)=>{...}}) donde el render es una función pura.
  • Dos capas de movimiento: acción principal (dibujar línea/caída) + capa continua (línea punteada que avanza/flotación/pulso).
  • La cámara siempre tiene un ligero zoom (1.4%–3%) — la imagen nunca es estática.
  • "Primero salir, luego entrar": los elementos viejos deben desaparecer completamente antes de que entren los nuevos; evitar superposición.
  • Para las normas visuales y el lenguaje de animación: lee references/design-system.md y references/motion.md.

⑥ Auditoría + inspección visual (control de calidad obligatorio)

Ejecuta en el navegador auditText() (texto fuera de límites) y auditOverlap() (elementos superpuestos). Debe dar cero para poder capturar cuadros. El auditor no detecta "fealdad": para cada escena, elige el cuadro de máximo contenido visual y captúralo para inspección visual (recortes de texto, composición vacía, colores incorrectos, formas). Cualquier error grave debe corregirse de inmediato. Si la superposición es intencional por diseño, añade al elemento data-okov="1" para eximirlo.

⑦ Sonido

python templates/music.py genera música ligera sintetizada (sin riesgos de copyright); o usa música propia (cuidado con los derechos de autor). python templates/mix.py: normaliza el VO por RMS → reduce la música cuando hay voz (ducking) → solo efectos de sonido en los acentos (máximo 2 thuds por escena, nada de whoosh de fondo — los efectos son signos de puntuación, no fondo musical) → limitador de pico envolvente personalizado → ffmpeg loudnorm dos pasos hasta -14 LUFS / TP -1.5.

⑧ Renderizado

python templates/shoot.py 0 <dur> a --html anim.html   # ×N segmentos en paralelo
python templates/render.py                              # codificación → verificación del último cuadro → unión → composición

Playwright captura cuadro por cuadro (device_scale_factor=2, JPEG q93) → segmentos codificados con x264 crf19 → verificación del último cuadro de cada segmento contra la imagen original (RMS<8, detecta segmentos corruptos sin errores de código) → concat → composición de audio y video (pan copia explícitamente a estéreo, +faststart).

⑨ Siete comprobaciones

python templates/check.py: bucle sin costuras (RMS entre primer y último cuadro <5) · pista de audio presente · subtítulos visibles · orden de colores de estilo (en cada cuadro B>G>R para evitar desviación cromática) · cuadros en blanco · tamaño/duración · faststart. Solo se entrega si todas pasan. Entregables: video final mp4 + subtítulos srt + texto promocional (título ≤15 caracteres / descripción de una frase / etiquetas).

Entorno

python 3.10+, pip install playwright numpy soundfile pillow edge-tts
playwright install chromium
ffmpeg (disponible en PATH)

Convención de directorios (para cada proyecto)

<project>/
├── shots/vo_lines.json    # Texto + división de subtítulos (única fuente de contenido)
├── shots/facts.md         # Constitución de datos
├── shots/timeline.json    # Generado por sync.py, para mezcla
├── tools/web/anim.html    # Animación (copia de templates/anim.html y modificación)
├── audio/vo|music|mix/    # Sonido
└── out/                   # Cuadros, segmentos, video final

Líneas rojas

  • No inventar: los datos, nombres de personas, eventos deben tener fuente; no pasar a locución si hay [por verificar].
  • El color rojo solo expresa significado de "juicio" (marcar eliminación/aceptación), nunca como decoración.
  • Si se usa música externa, primero verificar la licencia; por defecto usar música sintetizada.
  • Si hay nombres de personas/empresas reales con números, verificar uno por uno contra la constitución de datos antes de entregar.

Referencias

ArchivoContenido
references/design-system.mdSistema visual: disciplina de color, tres niveles de tamaño de fuente, etiquetas de gráficos, sintaxis de dibujo
references/motion.mdLista de lenguaje de animación: cuándo usar cada tipo de animación, parámetros
references/audio.mdPipeline de sonido: selección de TTS, fórmulas de mezcla, objetivos de masterización
references/pitfalls.mdLista de problemas conocidos (ordenados por costo; si hay problemas, consultar aquí primero)
templates/Esqueleto ejecutable y scripts del pipeline

Skills relacionados