Communitygithub.com

digitalsamba/claude-code-video-toolkit

Composición de video en Python con moviepy 2.x — superposición de texto determinista sobre video generado por IA (LTX-2, SadTalker), composición de clips y proyectos de video en un solo archivo build.py. Úsalo cuando necesites añadir etiquetas, subtítulos o barras inferiores a salidas de LTX-2 o SadTalker, construir anuncios cortos en Python puro sin Remotion, o hacer composición de video programática.

¿Qué es claude-code-video-toolkit?

Este skill está diseñado para desarrolladores que trabajan con herramientas de IA generativa como LTX-2 y SadTalker, y necesitan añadir texto determinista (legible, preciso y consistente) sobre el video generado. moviepy es la biblioteca central que permite superponer texto renderizado con PIL (Python Imaging Library) como ImageClip, evitando el bug de recorte de ascendentes/descendentes que tiene TextClip en moviepy 2.x. El patrón principal consiste en generar el video limpio con IA y luego componer el texto de forma determinista, garantizando que nombres, precios, atribuciones y cualquier otro contenido textual sea perfecto. El skill incluye recetas detalladas para títulos, barras inferiores, superposiciones tintadas, composiciones lado a lado y mezcla de audio con música con reducción de volumen, todas ilustradas con ejemplos funcionales en el directorio `examples/`. Es ideal para noticias, documentales, avances publicitarios, videos para redes sociales, tutoriales y demostraciones de productos, donde la precisión del texto es crítica.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/digitalsamba/claude-code-video-toolkit/tree/HEAD/.claude/skills/moviepy

Preguntar en tu IA favorita

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

Documentación

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 SadTalkerConstruir revisiones de sprint largas o demostraciones de producto
Construir espacios publicitarios de menos de 30s en un solo build.pyTrabajo 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 existentesCualquier cosa donde el ciclo de vida del proyecto (planificación → render) importe
Quieres cero Node.js / sin carga mental de ReactQuieres 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:

FormaUso en LTX-2Uso en SadTalker
Tarjeta de título sobre metraje principal"PRESENTANDO A LONGARM" sobre un metraje cinematográfico de LTX-2n/a
Barra inferior / placa de nombren/a"Lugh — Dios Guerrero Antiguo" bajo una cabeza parlante
Subtítulo de cita"Me voy a casa." sobre un cameo de personaje de LTX-2Igual, sobre una cabeza parlante de SadTalker
Atribución de marcaLogotipo + URL con fundido en el último segundoIgual
Superposición tintada para contrasteCapa azul marino semitransparente detrás del textoIgual

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éneroQué superponesPor qué moviepy es la opción correcta
Noticias / periodismo de entrevistasPlacas de nombre del hablante, barras de ubicación, banners de noticias de última hora, atribución de fuente, citas destacadasLos nombres deben escribirse correctamente (editorial/legal). La categoría más grande por volumen.
Segmentos documentalesBarras inferiores del entrevistado, títulos de capítulos, créditos de fuente de archivo, sellos de ubicaciónMismo requisito de confianza que las noticias.
Avances / spots promocionalesTarjetas de título, superposiciones de créditos ("DEL DIRECTOR DE…"), fechas, tarjetas de cita, CTAsTemporizados 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 hashtagsLa mayor parte de la visualización social está en silencio; los subtítulos son innegociables.
Demostraciones de producto con anotacionesLlamadas de precio, etiquetas de funciones, punteros "haz clic aquí" sobre grabaciones de pantalla, etiquetas de antes/despuésLos precios y nombres de producto deben ser exactos.
Tutoriales / explicadoresSuperposiciones de números de paso, subtítulos de comandos de terminal, llamadas de atajos de tecladoLos 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 (no subclip), with_duration / with_start / with_position (no set_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.
  • OffthreadVideo es solo para Remotion. moviepy usa VideoFileClip. No mezcles ambos.
  • Redimensionar requiere Pillow ≥ 10.0 para el remuestreo LANCZOS. Si ves errores ANTIALIAS, actualiza Pillow.
  • ColorClip toma tuplas RGB, no cadenas hexadecimales. Usa (20, 24, 38), no "#141826".
  • El audio en VideoFileClip se carga por defecto. Llama a .without_audio() si solo quieres el visual — componer con audio que no quieres causará caídas silenciosas de VO en CompositeAudioClip.
  • Siempre establece size=(W, H) en CompositeVideoClip. Sin ello, las dimensiones de salida siguen al primer clip, que puede ser más pequeño que tu objetivo.

Cuándo usar qué

TareaHerramienta
Animar una imagen fijatools/ltx2.py --input
Cabeza parlante a partir de retrato fotorrealistatools/sadtalker.py
Cabeza parlante a partir de personaje estilizadotools/ltx2.py --input (consulta el skill de ltx2)
Añadir una etiqueta/subtítulo/barra inferior a cualquiera de los anterioresmoviepy + PIL (este skill)
Convertir/comprimir/redimensionar un archivo existenteffmpeg (consulta el skill de ffmpeg)
Video largo, impulsado por un sistema de diseñoRemotion (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

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

digitalsamba/claude-code-video-toolkit

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

digitalsamba/ideogram4

Prompting patterns for Ideogram 4 text-to-image — best-in-class in-image text rendering and exact color/layout control via structured JSON captions. Use when generating images that need legible on-image text (title cards, thumbnails, logos, signage, CTAs), precise brand colors, or controlled spatial layout. Triggers include title slide image, thumbnail with text, on-image text, legible text in image, brand color palette image, bounding-box layout, Ideogram.

digitalsamba/parody-short

Comedy shorts about a group's own life - a team's launch, quarter end, office move or leaving do; a club's season; a class's year; a family's Christmas - or about a shared topic everyone recognises (video calls, the return to the office), told in a borrowed genre (80s action intro, creature feature, Dickens Christmas ad, heist, nature documentary) and starring the group's real, animated photos or an invented cast. Covers mining the group's own context for in-jokes (chat, email, calendars,...

digitalsamba/synthetic-ui-demo

Product demo and release-notes videos with no screen recording. Rebuild the app's screens as static React from its source code, then drive them in Remotion with a scripted cursor and camera (lib/components Stage + Cursor). Use when making a product walkthrough, feature demo, release-notes or changelog video for an app whose source you can read, or when a Playwright recording would be flaky, need test data, or go stale. Triggers include synthetic demo, rebuild the UI, release video, feature...

Skills relacionados