Communitygithub.com

digitalsamba/claude-code-video-toolkit

Composição de vídeo em Python com moviepy 2.x — sobreposição de texto determinístico em vídeo gerado por IA (LTX-2, SadTalker), composição de clipes, projetos de vídeo em único arquivo build.py. Use para adicionar legendas/captions/tarjas inferiores a saídas de LTX-2 ou SadTalker, criar spots publicitários curtos em Python puro sem Remotion, ou fazer composição de vídeo programática.

O que é claude-code-video-toolkit?

Este skill fornece um toolkit completo para composição de vídeo programática em Python, centrado na biblioteca moviepy 2.x. Ele é projetado especificamente para o cenário onde texto determinístico e preciso precisa ser sobreposto a vídeos gerados por IA (como saídas de LTX-2 ou SadTalker), que não conseguem renderizar texto legível de forma confiável. O princípio fundamental é 'texto confiável': nomes, preços e atribuições devem estar corretos, algo que modelos generativos não garantem. O skill oferece padrões claros de uso, incluindo a renderização de texto via PIL (para evitar um bug conhecido de clipping do TextClip do moviepy 2.x), a criação de linhas do tempo ancoradas em áudio para edições precisas, e receitas comuns como tarjas inferiores, sobreposições com opacidade e composições lado a lado. Ele também estabelece critérios claros para quando usar moviepy (spots curtos, sobreposições únicas) versus Remotion (projetos longos, baseados em design system). Dois exemplos executáveis em 'examples/' demonstram todos os padrões na prática, tornando o aprendizado imediato e acionável.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

moviepy para Produção de Vídeo

moviepy é a biblioteca principal do toolkit para colocar texto determinístico sobre vídeos gerados por IA e para construir projetos de vídeo curtos em um único arquivo Python, sem a necessidade do ecossistema Remotion.

O princípio fundamental é texto confiável: qualquer gênero onde o texto precisa ser legível, preciso e consistente (legal, editorial ou comercialmente) é um gênero onde o texto renderizado por IA é inaceitável e uma etapa de sobreposição com moviepy é a correção natural. Nomes devem estar escritos corretamente. Preços devem ser exatos. Atribuições de fonte devem estar perfeitas em nível de pixel. Modelos de geração de IA não garantem nada disso.

Quando usar moviepy vs. Remotion

Use moviepy quando…Use Remotion quando…
Sobrepondo texto/rótulos em uma saída LTX-2 ou SadTalkerConstruindo revisões de sprint longas ou demonstrações de produto
Construindo spots publicitários de até 30s em um único build.pyTrabalho multi-template, multi-marca e com foco em design
Compondo visuais orientados a dados (matplotlib FuncAnimation → mp4)Qualquer coisa que precise de componentes React ou reuso de design system
Transformações pontuais em arquivos de vídeo existentesQualquer coisa onde o ciclo de vida do projeto (planejamento → renderização) importa
Você quer zero Node.js / nenhuma sobrecarga mental com ReactVocê quer pré-visualização com hot-reload no Remotion Studio

Duas referências executáveis para tudo neste skill estão em examples/:

  • examples/quick-spot/build.py — spot publicitário de 15 segundos. Linha do tempo ancorada em áudio, sobreposição de texto, opcional narração + música com redução de volume. Renderiza silencioso imediatamente, sem ativos externos.
  • examples/data-viz-chart/build.py — gráfico de série temporal animado com título determinístico e atribuição de fonte. Demonstra a divisão matplotlib (dados) + moviepy (texto confiável).

Ambos executam com uv run build.py e produzem um out.mp4 real imediatamente. Leia-os junto com este skill — cada padrão abaixo é demonstrado em funcionamento neles.

Dependências. moviepy, Pillow e matplotlib estão declarados no pyproject.toml raiz e instalados com a configuração Python de uma linha do toolkit: uv sync. Se você encontrar Missing dependency ao executar um exemplo, execute esse comando a partir da raiz do repositório — os arquivos build.py dos exemplos dirão o mesmo em sua mensagem de erro e serão encerrados de forma limpa, em vez de exibir um traceback simples.

O caso de uso principal: texto em vídeo gerado por IA

Tanto LTX-2 quanto SadTalker produzem apenas visuais:

  • LTX-2 não consegue renderizar texto legível de forma confiável (o modelo alucina formas de letras — veja a skill ltx2 em "Bad Prompts").
  • SadTalker produz uma cabeça falante sem legendas, rótulos, tarjas inferiores ou contexto.

A solução é gerar o visual de forma limpa e, em seguida, compor o texto deterministicamente sobre ele com moviepy. Este é o padrão canônico neste toolkit:

from moviepy import VideoFileClip, ImageClip, CompositeVideoClip

# 1. Visual gerado por IA (saída LTX-2 ou SadTalker)
bg = VideoFileClip("lugh_ltx.mp4").without_audio()

# 2. Texto renderizado via PIL → ImageClip (veja "Renderização de texto" abaixo)
title = (
    ImageClip("text_cache/intro_title.png")
    .with_duration(2.0)
    .with_start(0.5)
    .with_position(("center", 880))
)

# 3. Composição
final = CompositeVideoClip([bg, title], size=(1920, 1080))
final.write_videofile("lugh_with_caption.mp4", fps=30, codec="libx264")

Formatos comuns que isso assume:

FormatoUso com LTX-2Uso com SadTalker
Cartela de título sobre cena heroica"APRESENTANDO LONGARM" sobre um b-roll cinematográfico do LTX-2n/a
Tarja inferior / placa de nomen/a"Lugh — Deus Guerreiro Antigo" sob uma cabeça falante
Legenda de citação"Estou indo para casa." sobre uma aparição de personagem LTX-2Mesmo, sobre uma cabeça falante do SadTalker
Atribuição de marcaLogotipo + URL com fade-in no último segundoMesmo
Sobreposição colorida para contrasteCamada azul escuro semitransparente atrás do textoMesmo

Gêneros onde isso se destaca

O padrão "visual de IA + sobreposição de texto determinístico" é o pipeline de produção natural para vários estilos de vídeo. Se a solicitação corresponder a um destes, use moviepy por padrão:

GêneroO que você sobrepõePor que moviepy é a escolha certa
Jornalismo / reportagem com cabeça falantePlacas de nome do entrevistado, barras de localização, banners de notícias de última hora, atribuição de fonte, citações em destaqueNomes devem estar escritos corretamente (editorial / legal). A maior categoria em volume.
Segmentos de documentárioTarjas inferiores do entrevistado, títulos de capítulo, créditos de fonte de arquivo, selos de localizaçãoMesmo requisito de confiabilidade do jornalismo.
Trailers / spots promocionaisCartelas de título, sobreposições de créditos ("DO DIRETOR DE…"), informações de data, cartelas de citação, CTAsCronometrados com precisão, com muito texto, cada quadro importa. O exemplo q2-townhall-longarm-ad é exatamente isso.
Redes sociais (Reels, TikTok, Shorts)Legendas precisas para visualização sem som, sobreposições de hashtagsA maioria da visualização em redes sociais é sem som; legendas são obrigatórias.
Demonstrações de produto com anotaçõesDestaques de preço, rótulos de recursos, indicadores de "clique aqui" sobre gravações de tela, rótulos de antes/depoisPreços e nomes de produtos devem estar exatos.
Tutoriais / explicadoresSobreposições de números de etapa, legendas de comandos de terminal, destaques de atalhos de tecladoNúmeros de etapa devem estar em sequência, comandos devem ser copiáveis.

Ajustes menores, mas reais: vídeos musicais (sobreposições de letras), vídeos de reação (atribuição de fonte), resumos esportivos (sobreposições de placar), tours imobiliários (preço / m²), palestras de conferências (placa do palestrante + sessão).

Para legendas completas baseadas em SRT (longa duração, com código de tempo, multilíngue) moviepy é viável, mas não ideal — use ffmpeg com o filtro subtitles ou uma ferramenta dedicada de legendas. moviepy é melhor para sobreposições colocadas manualmente, não para trilhas de legendas em massa.

Renderização de texto — use PIL, não TextClip

Problema crítico: o TextClip(method='label') do moviepy 2.x tem um bug de bounding box apertada que corta ascendentes e descendentes das letras (o topo das maiúsculas, as caudas de g/p/y). No Apple Silicon, você verá caracteres com bordas cortadas e pode não perceber o que está errado por horas.

A solução alternativa: renderize o texto para um PNG transparente via PIL e, em seguida, carregue-o como um ImageClip. Armazene em cache o resultado por hash de conteúdo para que as reconstruções sejam 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)

O helper completo (com kwargs para negrito, posição, fades e ergonomia mais limpa) está em examples/quick-spot/build.py — copie-o em vez de reimplementá-lo.

Padrão de linha do tempo ancorada em áudio

Para edições no estilo de anúncio onde cada quadro importa, gere a narração por cena primeiro e ancore cada visual a timestamps absolutos conhecidos. Isso elimina completamente a deriva de temporização. Veja CLAUDE.md → Video Timing → Audio-Anchored Timelines para o padrão completo. A versão resumida:

# Linha do tempo ancorada em áudio (25s):
#   Cena 1 tired      0,3 → 3,74  (áudio 3,44s)
#   Cena 2 worries    4,0 → 8,88  (áudio 4,88s)

text_clip("TIRED OF",     start=0.5,  duration=1.2)
text_clip("THIRD-PARTY",  start=1.0,  duration=1.8)
vo_clip("01_tired.mp3",   start=0.3)
vo_clip("02_worries.mp3", start=4.0)

Receitas comuns

Texto em um único clipe gerado por IA

from moviepy import VideoFileClip, ImageClip, CompositeVideoClip

bg = VideoFileClip("ltx_hero.mp4").without_audio()
caption = (
    ImageClip(render_text_png("THE FUTURE OF AGENTS", 140, "#FFFFFF"))
    .with_duration(bg.duration)
    .with_position(("center", 880))
)
CompositeVideoClip([bg, caption], size=bg.size).write_videofile("captioned.mp4", fps=30)

Tarja inferior sobre uma cabeça falante do SadTalker

from moviepy import VideoFileClip, ImageClip, ColorClip, CompositeVideoClip

talking = VideoFileClip("narrator_sadtalker.mp4")
W, H = talking.size

# Barra semitransparente na 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("Ancient Warrior God", 36, "#FFFFFF"))
    .with_duration(talking.duration)
    .with_position((80, H - 80))
)
CompositeVideoClip([talking, bar, name, title]).write_videofile("with_lower_third.mp4", fps=30)

Sobreposição colorida para contraste de texto em cenas movimentadas

O b-roll do LTX-2 é frequentemente visualmente movimentado demais para texto legível. Coloque uma camada azul escura semitransparente entre o vídeo e o texto:

from moviepy import ColorClip

tint = (
    ColorClip((W, H), color=(20, 24, 38))
    .with_duration(duration)
    .with_opacity(0.55)
)
# Ordem de composição: bg → tint → text
CompositeVideoClip([bg, tint, text_clip])

Composição 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)

Mixar narração por cena com música com redução de volume

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),  # reduzir sob a narração
    AudioFadeIn(0.5),
    AudioFadeOut(1.5),
])
vo = [
    AudioFileClip(f"scenes/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)

Problemas comuns

  • moviepy 2.x renomeou métodos. Use subclipped (não subclip), with_duration / with_start / with_position (não set_duration etc.), with_effects([...]) em vez de .fadein()/.fadeout(). Muitos tutoriais online ainda mostram a sintaxe 1.x — desconfie.
  • TextClip(method='label') corta ascendentes/descendentes. Sempre use a solução alternativa com PIL acima.
  • OffthreadVideo é exclusivo do Remotion. moviepy usa VideoFileClip. Não misture os dois.
  • Redimensionar requer Pillow ≥ 10.0 para o reamostrador LANCZOS. Se você vir erros ANTIALIAS, atualize o Pillow.
  • ColorClip aceita tuplas RGB, não strings hexadecimais. Use (20, 24, 38), não "#141826".
  • Áudio em VideoFileClip é carregado por padrão. Chame .without_audio() se quiser apenas o visual — compor com áudio indesejado causará quedas silenciosas de VO em CompositeAudioClip.
  • Sempre defina size=(W, H) em CompositeVideoClip. Sem isso, as dimensões de saída seguem o primeiro clipe, que pode ser menor que o seu alvo.

Quando usar o quê

TarefaFerramenta
Animar uma imagem estáticatools/ltx2.py --input
Cabeça falante a partir de retrato fotorrealistatools/sadtalker.py
Cabeça falante a partir de personagem estilizadotools/ltx2.py --input (veja skill ltx2)
Adicionar um rótulo/legenda/tarja inferior a qualquer um dos acimamoviepy + PIL (esta skill)
Converter / comprimir / redimensionar um arquivo existenteffmpeg (veja skill ffmpeg)
Vídeo longo orientado por design systemRemotion (veja skill remotion)

Referências

  • Exemplo executável — spot publicitário curto: examples/quick-spot/build.py
  • Exemplo executável — visualização de dados com sobreposição de texto: examples/data-viz-chart/build.py
  • Linhas do tempo ancoradas em áudio: 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...

Habilidades Relacionadas