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 SadTalker | Construindo revisões de sprint longas ou demonstrações de produto |
Construindo spots publicitários de até 30s em um único build.py | Trabalho 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 existentes | Qualquer coisa onde o ciclo de vida do projeto (planejamento → renderização) importa |
| Você quer zero Node.js / nenhuma sobrecarga mental com React | Você 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:
| Formato | Uso com LTX-2 | Uso com SadTalker |
|---|---|---|
| Cartela de título sobre cena heroica | "APRESENTANDO LONGARM" sobre um b-roll cinematográfico do LTX-2 | n/a |
| Tarja inferior / placa de nome | n/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-2 | Mesmo, sobre uma cabeça falante do SadTalker |
| Atribuição de marca | Logotipo + URL com fade-in no último segundo | Mesmo |
| Sobreposição colorida para contraste | Camada azul escuro semitransparente atrás do texto | Mesmo |
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ênero | O que você sobrepõe | Por que moviepy é a escolha certa |
|---|---|---|
| Jornalismo / reportagem com cabeça falante | Placas de nome do entrevistado, barras de localização, banners de notícias de última hora, atribuição de fonte, citações em destaque | Nomes devem estar escritos corretamente (editorial / legal). A maior categoria em volume. |
| Segmentos de documentário | Tarjas inferiores do entrevistado, títulos de capítulo, créditos de fonte de arquivo, selos de localização | Mesmo requisito de confiabilidade do jornalismo. |
| Trailers / spots promocionais | Cartelas de título, sobreposições de créditos ("DO DIRETOR DE…"), informações de data, cartelas de citação, CTAs | Cronometrados 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 hashtags | A maioria da visualização em redes sociais é sem som; legendas são obrigatórias. |
| Demonstrações de produto com anotações | Destaques de preço, rótulos de recursos, indicadores de "clique aqui" sobre gravações de tela, rótulos de antes/depois | Preços e nomes de produtos devem estar exatos. |
| Tutoriais / explicadores | Sobreposições de números de etapa, legendas de comandos de terminal, destaques de atalhos de teclado | Nú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ãosubclip),with_duration/with_start/with_position(nãoset_durationetc.),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 usaVideoFileClip. Não misture os dois.- Redimensionar requer Pillow ≥ 10.0 para o reamostrador LANCZOS. Se você vir erros
ANTIALIAS, atualize o Pillow. ColorClipaceita 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 emCompositeAudioClip. - Sempre defina
size=(W, H)emCompositeVideoClip. Sem isso, as dimensões de saída seguem o primeiro clipe, que pode ser menor que o seu alvo.
Quando usar o quê
| Tarefa | Ferramenta |
|---|---|
| Animar uma imagem estática | tools/ltx2.py --input |
| Cabeça falante a partir de retrato fotorrealista | tools/sadtalker.py |
| Cabeça falante a partir de personagem estilizado | tools/ltx2.py --input (veja skill ltx2) |
| Adicionar um rótulo/legenda/tarja inferior a qualquer um dos acima | moviepy + PIL (esta skill) |
| Converter / comprimir / redimensionar um arquivo existente | ffmpeg (veja skill ffmpeg) |
| Vídeo longo orientado por design system | Remotion (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