script-to-video · Documento → Video corto vertical de divulgación
Tres principios rectores a los que se debe volver en cada decisión:
- 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. - 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.
- 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
| Archivo | Contenido |
|---|---|
| references/design-system.md | Sistema visual: disciplina de color, tres niveles de tamaño de fuente, etiquetas de gráficos, sintaxis de dibujo |
| references/motion.md | Lista de lenguaje de animación: cuándo usar cada tipo de animación, parámetros |
| references/audio.md | Pipeline de sonido: selección de TTS, fórmulas de mezcla, objetivos de masterización |
| references/pitfalls.md | Lista de problemas conocidos (ordenados por costo; si hay problemas, consultar aquí primero) |
| templates/ | Esqueleto ejecutable y scripts del pipeline |