moviepy para Producción de Video
moviepy es la biblioteca principal del toolkit para poner texto determinista sobre video generado por IA y para construir proyectos de video cortos en un solo archivo Python sin la cadena de herramientas de Remotion.
El principio más profundo es texto confiable: cualquier género donde el texto tenga que ser legible, preciso y consistente (legal, editorial o comercialmente) es un género donde el texto renderizado por IA es inaceptable y un paso de superposición con moviepy es la solución natural. Los nombres deben estar escritos correctamente. Los precios deben ser exactos. Las atribuciones de origen deben ser perfectas píxel a píxel. Los modelos de generación de IA no pueden garantizar nada de eso.
Cuándo usar moviepy vs. Remotion
| Usar moviepy cuando… | Usar Remotion cuando… |
|---|---|
| Superponer texto/etiquetas sobre una salida de LTX-2 o SadTalker | Construir revisiones de sprint largas o demostraciones de producto |
Construir espacios publicitarios de menos de 30s en un solo build.py | Trabajo con múltiples plantillas, múltiples marcas y mucho diseño |
Componer visualizaciones basadas en datos (matplotlib FuncAnimation → mp4) | Cualquier cosa que necesite componentes React o reutilización de sistemas de diseño |
| Transformaciones únicas en archivos de video existentes | Cualquier cosa donde el ciclo de vida del proyecto (planificación → render) importe |
| Quieres cero Node.js / sin carga mental de React | Quieres previsualización con recarga en caliente en Remotion Studio |
Dos referencias ejecutables para todo lo que hay en este skill viven en examples/:
examples/quick-spot/build.py— espacio publicitario de 15 segundos. Línea de tiempo anclada a audio, superposición de texto, voz en off opcional + música con reducción de volumen. Se renderiza silencioso de fábrica sin activos externos.examples/data-viz-chart/build.py— gráfico de serie temporal animado con título determinista y atribución de fuente. Demuestra la división matplotlib (datos) + moviepy (texto confiable).
Ambos se ejecutan con uv run build.py y producen un out.mp4 real de inmediato. Léelos junto con este skill; cada patrón que aparece a continuación se muestra funcionando allí.
Dependencias. moviepy, Pillow y matplotlib están declarados en el pyproject.toml raíz e instalados con la configuración de Python de una línea del toolkit: uv sync. Si te encuentras con Missing dependency al ejecutar un ejemplo, ejecuta ese comando desde la raíz del repositorio; los archivos build.py de los ejemplos te dirán lo mismo en su mensaje de error y saldrán limpiamente en lugar de imprimir un traceback desnudo.
El caso de uso principal: texto sobre video generado por IA
Tanto LTX-2 como SadTalker generan imágenes visuales desnudas:
- LTX-2 no puede renderizar texto legible de forma confiable (el modelo alucina formas de letras — consulta el skill de ltx2 en "Prompts Malos").
- SadTalker genera una cabeza parlante sin subtítulos, etiquetas, barras inferiores ni contexto.
La solución es generar el visual limpiamente, luego componer texto sobre él de forma determinista con moviepy. Este es el patrón canónico en este toolkit:
from moviepy import VideoFileClip, ImageClip, CompositeVideoClip
# 1. Visual generado por IA (salida de LTX-2 o SadTalker)
bg = VideoFileClip("lugh_ltx.mp4").without_audio()
# 2. Texto renderizado mediante PIL → ImageClip (ver "Renderizado de texto" más abajo)
title = (
ImageClip("text_cache/intro_title.png")
.with_duration(2.0)
.with_start(0.5)
.with_position(("center", 880))
)
# 3. Composición
final = CompositeVideoClip([bg, title], size=(1920, 1080))
final.write_videofile("lugh_with_caption.mp4", fps=30, codec="libx264")
Formas comunes que toma esto:
| Forma | Uso en LTX-2 | Uso en SadTalker |
|---|---|---|
| Tarjeta de título sobre metraje principal | "PRESENTANDO A LONGARM" sobre un metraje cinematográfico de LTX-2 | n/a |
| Barra inferior / placa de nombre | n/a | "Lugh — Dios Guerrero Antiguo" bajo una cabeza parlante |
| Subtítulo de cita | "Me voy a casa." sobre un cameo de personaje de LTX-2 | Igual, sobre una cabeza parlante de SadTalker |
| Atribución de marca | Logotipo + URL con fundido en el último segundo | Igual |
| Superposición tintada para contraste | Capa azul marino semitransparente detrás del texto | Igual |
Géneros donde esto destaca
El patrón "visual de IA + superposición de texto determinista" es el pipeline de producción natural para varios estilos de video. Si la solicitud coincide con uno de estos, usa moviepy por defecto:
| Género | Qué superpones | Por qué moviepy es la opción correcta |
|---|---|---|
| Noticias / periodismo de entrevistas | Placas de nombre del hablante, barras de ubicación, banners de noticias de última hora, atribución de fuente, citas destacadas | Los nombres deben escribirse correctamente (editorial/legal). La categoría más grande por volumen. |
| Segmentos documentales | Barras inferiores del entrevistado, títulos de capítulos, créditos de fuente de archivo, sellos de ubicación | Mismo requisito de confianza que las noticias. |
| Avances / spots promocionales | Tarjetas de título, superposiciones de créditos ("DEL DIRECTOR DE…"), fechas, tarjetas de cita, CTAs | Temporizados con precisión, con mucho texto, cada fotograma importa. El ejemplo q2-townhall-longarm-ad es exactamente esto. |
| Formato corto social (Reels, TikTok, Shorts) | Subtítulos palabra por palabra para visualización sin sonido, superposiciones de hashtags | La mayor parte de la visualización social está en silencio; los subtítulos son innegociables. |
| Demostraciones de producto con anotaciones | Llamadas de precio, etiquetas de funciones, punteros "haz clic aquí" sobre grabaciones de pantalla, etiquetas de antes/después | Los precios y nombres de producto deben ser exactos. |
| Tutoriales / explicadores | Superposiciones de números de paso, subtítulos de comandos de terminal, llamadas de atajos de teclado | Los números de paso deben ser secuenciales, los comandos deben poder copiarse y pegarse. |
Ajustes menores pero reales: videos musicales (superposiciones de letras), videos de reacción (atribución de fuente), resúmenes deportivos (superposiciones de marcador), recorridos inmobiliarios (precio / m²), charlas de conferencias (placa de orador + sesión).
Para subtitulado completo basado en SRT (larga duración, con código de tiempo, multilingüe) moviepy es viable pero no ideal — usa ffmpeg con el filtro subtitles o una herramienta de subtítulos dedicada. moviepy es mejor para superposiciones colocadas a mano, no para pistas de subtítulos masivos.
Renderizado de texto — usa PIL, no TextClip
Error crítico: el TextClip(method='label') de moviepy 2.x tiene un error de bounding box ajustado que recorta los ascendentes y descendentes de las letras (la parte superior de las mayúsculas, las colas de g/p/y). En Apple Silicon verás caracteres con bordes recortados y no te darás cuenta de qué está mal durante horas.
La solución: renderiza el texto a un PNG transparente mediante PIL, luego cárgalo como ImageClip. Almacena en caché el resultado por hash de contenido para que las reconstrucciones sean gratuitas.
import hashlib
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ARIAL_BOLD = "/System/Library/Fonts/Supplemental/Arial Bold.ttf"
def render_text_png(txt, size, hex_color, cache_dir="./text_cache"):
cache = Path(cache_dir); cache.mkdir(parents=True, exist_ok=True)
key = hashlib.sha1(f"{txt}|{size}|{hex_color}".encode()).hexdigest()[:16]
path = cache / f"{key}.png"
if path.exists():
return str(path)
font = ImageFont.truetype(ARIAL_BOLD, size)
bbox = ImageDraw.Draw(Image.new("RGBA", (1, 1))).textbbox((0, 0), txt, font=font)
tw, th = bbox[2] - bbox[0], bbox[3] - bbox[1]
pad = max(20, size // 4)
img = Image.new("RGBA", (tw + pad * 2, th + pad * 2), (0, 0, 0, 0))
rgb = tuple(int(hex_color.lstrip("#")[i:i+2], 16) for i in (0, 2, 4))
ImageDraw.Draw(img).text((pad - bbox[0], pad - bbox[1]), txt, font=font, fill=(*rgb, 255))
img.save(path)
return str(path)
El helper completo (con kwargs para negrita, posición, fundidos y ergonomía más limpia) está en examples/quick-spot/build.py — cópialo en lugar de reimplementarlo.
Patrón de línea de tiempo anclada a audio
Para ediciones de estilo publicitario donde cada fotograma importa, genera primero la voz en off (VO) por escena y ancla cada visual a marcas de tiempo absolutas conocidas. Esto elimina por completo la deriva temporal. Consulta CLAUDE.md → Video Timing → Audio-Anchored Timelines para el patrón completo. La versión corta:
# Línea de tiempo anclada a audio (25s):
# Escena 1 cansado 0.3 → 3.74 (audio 3.44s)
# Escena 2 preocupaciones 4.0 → 8.88 (audio 4.88s)
text_clip("CANSADO DE", start=0.5, duration=1.2)
text_clip("TERCEROS", start=1.0, duration=1.8)
vo_clip("01_cansado.mp3", start=0.3)
vo_clip("02_preocupaciones.mp3", start=4.0)
Recetas comunes
Texto sobre un solo clip generado por IA
from moviepy import VideoFileClip, ImageClip, CompositeVideoClip
bg = VideoFileClip("ltx_hero.mp4").without_audio()
caption = (
ImageClip(render_text_png("EL FUTURO DE LOS AGENTES", 140, "#FFFFFF"))
.with_duration(bg.duration)
.with_position(("center", 880))
)
CompositeVideoClip([bg, caption], size=bg.size).write_videofile("subtitulado.mp4", fps=30)
Barra inferior sobre una cabeza parlante de SadTalker
from moviepy import VideoFileClip, ImageClip, ColorClip, CompositeVideoClip
talking = VideoFileClip("narrator_sadtalker.mp4")
W, H = talking.size
# Barra semitransparente en la parte inferior para contraste
bar = (
ColorClip((W, 140), color=(20, 24, 38))
.with_duration(talking.duration)
.with_opacity(0.75)
.with_position(("center", H - 160))
)
name = (
ImageClip(render_text_png("LUGH", 72, "#F06859"))
.with_duration(talking.duration)
.with_position((80, H - 150))
)
title = (
ImageClip(render_text_png("Dios Guerrero Antiguo", 36, "#FFFFFF"))
.with_duration(talking.duration)
.with_position((80, H - 80))
)
CompositeVideoClip([talking, bar, name, title]).write_videofile("con_barra_inferior.mp4", fps=30)
Superposición tintada para contraste de texto sobre metraje ocupado
El metraje de relleno de LTX-2 suele ser demasiado ocupado visualmente para texto legible. Coloca una capa azul marino semitransparente entre el video y el texto:
from moviepy import ColorClip
tint = (
ColorClip((W, H), color=(20, 24, 38))
.with_duration(duration)
.with_opacity(0.55)
)
# Orden de composición: bg → tint → text
CompositeVideoClip([bg, tint, text_clip])
Composición lado a lado
from moviepy import VideoFileClip, CompositeVideoClip, ColorClip
left = VideoFileClip("demo_a.mp4").resized(width=960).with_position(( 0, "center"))
right = VideoFileClip("demo_b.mp4").resized(width=960).with_position((960, "center"))
bg = ColorClip((1920, 1080), color=(0, 0, 0)).with_duration(max(left.duration, right.duration))
CompositeVideoClip([bg, left, right]).write_videofile("split.mp4", fps=30)
Mezclar VO por escena con música con reducción de volumen
from moviepy import AudioFileClip, CompositeAudioClip
from moviepy.audio.fx.MultiplyVolume import MultiplyVolume
from moviepy.audio.fx.AudioFadeIn import AudioFadeIn
from moviepy.audio.fx.AudioFadeOut import AudioFadeOut
music = AudioFileClip("music.mp3").with_effects([
MultiplyVolume(0.22), # reducir bajo VO
AudioFadeIn(0.5),
AudioFadeOut(1.5),
])
vo = [
AudioFileClip(f"escenas/0{i}.mp3").with_effects([MultiplyVolume(1.15)]).with_start(start)
for i, start in [(1, 0.3), (2, 4.0), (3, 9.1)]
]
final_audio = CompositeAudioClip([music] + vo)
Errores comunes (Gotchas)
- moviepy 2.x renombró métodos. Usa
subclipped(nosubclip),with_duration/with_start/with_position(noset_duration, etc.),with_effects([...])en lugar de.fadein()/.fadeout(). Muchos tutoriales en línea aún muestran la sintaxis de 1.x — sé escéptico. TextClip(method='label')recorta ascendentes/descendentes. Usa siempre la solución PIL anterior.OffthreadVideoes solo para Remotion. moviepy usaVideoFileClip. No mezcles ambos.- Redimensionar requiere Pillow ≥ 10.0 para el remuestreo LANCZOS. Si ves errores
ANTIALIAS, actualiza Pillow. ColorCliptoma tuplas RGB, no cadenas hexadecimales. Usa(20, 24, 38), no"#141826".- El audio en
VideoFileClipse carga por defecto. Llama a.without_audio()si solo quieres el visual — componer con audio que no quieres causará caídas silenciosas de VO enCompositeAudioClip. - Siempre establece
size=(W, H)enCompositeVideoClip. Sin ello, las dimensiones de salida siguen al primer clip, que puede ser más pequeño que tu objetivo.
Cuándo usar qué
| Tarea | Herramienta |
|---|---|
| Animar una imagen fija | tools/ltx2.py --input |
| Cabeza parlante a partir de retrato fotorrealista | tools/sadtalker.py |
| Cabeza parlante a partir de personaje estilizado | tools/ltx2.py --input (consulta el skill de ltx2) |
| Añadir una etiqueta/subtítulo/barra inferior a cualquiera de los anteriores | moviepy + PIL (este skill) |
| Convertir/comprimir/redimensionar un archivo existente | ffmpeg (consulta el skill de ffmpeg) |
| Video largo, impulsado por un sistema de diseño | Remotion (consulta el skill de remotion) |
Referencias
- Ejemplo ejecutable — espacio publicitario corto:
examples/quick-spot/build.py - Ejemplo ejecutable — visualización de datos con superposición de texto:
examples/data-viz-chart/build.py - Líneas de tiempo ancladas a audio:
CLAUDE.md → Video Timing → Audio-Anchored Timelines - Skills relacionados:
ltx2,ffmpeg,remotion