moviepy pour la production vidéo
moviepy est la bibliothèque de référence du toolkit pour mettre du texte déterministe sur une vidéo générée par IA et pour construire de courts projets vidéo Python mono-fichier sans chaîne d'outils Remotion.
Le principe sous-jacent est le texte fiable : tout genre où le texte doit être lisible, précis et cohérent (juridiquement, éditorialement ou commercialement) est un genre où le texte rendu dans l'image par IA est inacceptable et où une étape de superposition moviepy est la solution naturelle. Les noms doivent être correctement orthographiés. Les prix doivent être exacts. Les attributions de sources doivent être parfaites au pixel près. Les modèles de génération IA ne peuvent garantir rien de tout cela.
Quand utiliser moviepy vs. Remotion
| Utiliser moviepy quand… | Utiliser Remotion quand… |
|---|---|
| Superposer du texte/des étiquettes sur une sortie LTX-2 ou SadTalker | Construire des revues de sprint longues ou des démos produits |
Construire des spots de style publicitaire de moins de 30s dans un seul build.py | Travail multi-modèle, multi-marque, chargé en design |
Composer des visuels pilotés par les données (matplotlib FuncAnimation → mp4) | Tout besoin de composants React ou de réutilisation du système de design |
| Transformations ponctuelles sur des fichiers vidéo existants | Tout projet où le cycle de vie (planification → rendu) importe |
| Vous voulez zéro Node.js / sans overhead mental React | Vous voulez un aperçu avec rechargement à chaud dans Remotion Studio |
Deux références exécutables pour tout ce qui est dans ce skill se trouvent dans examples/ :
examples/quick-spot/build.py— spot de style publicitaire de 15 secondes. Timeline ancrée à l'audio, superposition de texte, VO optionnelle + musique en fond. Rendu silencieux par défaut, sans aucun asset externe.examples/data-viz-chart/build.py— graphique de série temporelle animé avec titre et attribution de source déterministes. Montre la séparation matplotlib (données) + moviepy (texte fiable).
Les deux s'exécutent avec uv run build.py et produisent immédiatement un vrai out.mp4. Lisez-les en parallèle avec ce skill — chaque motif ci-dessous y est montré en fonctionnement.
Dépendances. moviepy, Pillow et matplotlib sont déclarées dans le pyproject.toml racine et installées avec la configuration Python en une ligne du toolkit : uv sync. Si vous rencontrez Missing dependency en exécutant un exemple, exécutez cette commande depuis la racine du dépôt — les fichiers build.py des exemples vous diront la même chose dans leur message d'erreur et se termineront proprement plutôt que d'afficher une trace d'appel nue.
Le cas d'usage principal : texte sur vidéo générée par IA
LTX-2 et SadTalker produisent tous deux des visuels bruts :
- LTX-2 ne peut pas rendre de texte lisible de manière fiable (le modèle hallucine des formes de lettres — voir les "Mauvaises prompts" du skill ltx2).
- SadTalker produit une tête parlante sans légendes, étiquettes, tiers-inférieurs ni contexte.
La solution est de générer le visuel proprement, puis de composer le texte par-dessus de manière déterministe avec moviepy. C'est le motif canonique de ce toolkit :
from moviepy import VideoFileClip, ImageClip, CompositeVideoClip
# 1. Visuel généré par IA (sortie LTX-2 ou SadTalker)
bg = VideoFileClip("lugh_ltx.mp4").without_audio()
# 2. Texte rendu via PIL → ImageClip (voir "Rendu du texte" ci-dessous)
title = (
ImageClip("text_cache/intro_title.png")
.with_duration(2.0)
.with_start(0.5)
.with_position(("center", 880))
)
# 3. Composition
final = CompositeVideoClip([bg, title], size=(1920, 1080))
final.write_videofile("lugh_with_caption.mp4", fps=30, codec="libx264")
Formes courantes que cela prend :
| Forme | Utilisation LTX-2 | Utilisation SadTalker |
|---|---|---|
| Carte-titre sur séquence héro | "INTRODUCING LONGARM" sur un b-roll cinématique LTX-2 | n/a |
| Tiers-inférieur / plaque nominative | n/a | "Lugh — Dieu Guerrier Antique" sous une tête parlante |
| Légende de citation | "I am going home." sur un caméo de personnage LTX-2 | Idem, sur une tête parlante SadTalker |
| Attribution de marque | Logo + URL fondu sur la dernière seconde | Idem |
| Superposition de teinte pour le contraste | Couche semi-transparente bleu marine foncé derrière le texte | Idem |
Genres où cela brille
Le motif "visuel IA + superposition de texte déterministe" est le pipeline de production naturel pour plusieurs styles de vidéo. Si la requête correspond à l'un de ceux-ci, utilisez moviepy par défaut :
| Genre | Ce que vous superposez | Pourquoi moviepy est le bon choix |
|---|---|---|
| Actualité / journalisme d'interview | Plaques nominatives des intervenants, barres de localisation, bandeaux breaking-news, attribution de source, citations | Les noms doivent être correctement orthographiés (éditorial / juridique). La plus grande catégorie en volume. |
| Segments documentaires | Tiers-inférieurs d'interviewé, titres de chapitre, crédits de source d'archives, tampons de localisation | Même exigence de confiance que l'actualité. |
| Bandes-annonces / spots promotionnels | Cartes-titres, superpositions de crédit ("DU MÊME RÉALISATEUR QUE…"), mentions de date, cartes de citation, CTA | Chronométrage serré, beaucoup de texte, chaque image compte. L'exemple q2-townhall-longarm-ad est exactement cela. |
| Formats courts sociaux (Reels, TikTok, Shorts) | Légendes mots précis pour visionnage sans son, superpositions de hashtags | La plupart des visionnages sociaux se font en mode silencieux ; les légendes sont non négociables. |
| Démos produits avec annotations | Appels de prix, étiquettes de fonctionnalité, pointeurs "cliquez ici" sur des enregistrements d'écran, étiquettes avant/après | Les prix et les noms de produits doivent être exacts. |
| Tutoriels / vidéos explicatives | Superpositions de numéros d'étape, légendes de commandes terminal, appels de raccourcis clavier | Les numéros d'étape doivent être séquentiels, les commandes doivent pouvoir être copiées-collées. |
Cas moins fréquents mais réels : clips musicaux (superpositions de paroles), vidéos réaction (attribution de source), résumés sportifs (superpositions de score), visites immobilières (prix / m²), conférences (plaque intervenant + session).
Pour le sous-titrage complet piloté par SRT (long format, chronométré, multilingue), moviepy est faisable mais pas idéal — utilisez ffmpeg avec le filtre subtitles ou un outil de sous-titrage dédié. moviepy est meilleur pour les superpositions placées manuellement, pas pour les pistes de légendes volumineuses.
Rendu du texte — utilisez PIL, pas TextClip
Problème critique : le TextClip(method='label') de moviepy 2.x a un bug de boîte englobante serrée qui tronque les ascendantes et descendantes des lettres (le haut des capitales, les queues des g/p/y). Sur Apple Silicon, vous verrez des caractères avec des bords coupés sans réaliser ce qui ne va pas pendant des heures.
La solution de contournement : rendez le texte en PNG transparent via PIL, puis chargez-le comme ImageClip. Mettez en cache le résultat par hachage de contenu pour que les reconstructions soient gratuites.
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)
L'assistant complet (avec kwargs pour le gras, la position, les fondus et une ergonomie plus propre) se trouve dans examples/quick-spot/build.py — copiez-le plutôt que de le réimplémenter.
Motif de timeline ancrée à l'audio
Pour les montages de style publicitaire où chaque image compte, générez d'abord la VO par scène et ancrez chaque visuel à des horodatages absolus connus. Cela élimine totalement la dérive temporelle. Voir CLAUDE.md → Vidéo Timing → Timelines Ancérées à l'Audio pour le motif complet. La version courte :
# Timeline ancrée à l'audio (25s) :
# Scène 1 tired 0.3 → 3.74 (audio 3.44s)
# Scène 2 worries 4.0 → 8.88 (audio 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)
Recettes courantes
Texte sur un seul clip généré par 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)
Tiers-inférieur sur une tête parlante SadTalker
from moviepy import VideoFileClip, ImageClip, ColorClip, CompositeVideoClip
talking = VideoFileClip("narrator_sadtalker.mp4")
W, H = talking.size
# Barre semi-transparente en bas pour le 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)
Superposition de teinte pour contraste du texte sur séquences chargées
Les b-roll LTX-2 sont souvent trop chargés visuellement pour un texte lisible. Placez une couche semi-transparente bleu marine entre la vidéo et le texte :
from moviepy import ColorClip
tint = (
ColorClip((W, H), color=(20, 24, 38))
.with_duration(duration)
.with_opacity(0.55)
)
# Ordre de composition : bg → tint → text
CompositeVideoClip([bg, tint, text_clip])
Composition côte à côte
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)
Mélanger VO par scène avec musique en fond
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), # baisser sous la VO
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)
Pièges à éviter
- moviepy 2.x a renommé les méthodes. Utilisez
subclipped(passubclip),with_duration/with_start/with_position(passet_durationetc.),with_effects([...])au lieu de.fadein()/.fadeout(). De nombreux tutoriels en ligne montrent encore la syntaxe 1.x — soyez sceptique. TextClip(method='label')tronque les ascendantes/descendantes. Utilisez toujours la solution de contournement PIL ci-dessus.OffthreadVideoest exclusif à Remotion. moviepy utiliseVideoFileClip. Ne mélangez pas les deux.- Le redimensionnement nécessite Pillow ≥ 10.0 pour le rééchantillonnage LANCZOS. Si vous voyez des erreurs
ANTIALIAS, mettez à jour Pillow. ColorClipprend des tuples RGB, pas des chaînes hexadécimales. Utilisez(20, 24, 38), pas"#141826".- L'audio dans
VideoFileClipest chargé par défaut. Appelez.without_audio()si vous ne voulez que le visuel — composer avec un audio non désiré entraînera des chutes silencieuses de VO dansCompositeAudioClip. - Toujours définir
size=(W, H)surCompositeVideoClip. Sans cela, les dimensions de sortie suivent le premier clip, qui peut être plus petit que votre cible.
Quand utiliser quoi
| Tâche | Outil |
|---|---|
| Animer une image fixe | tools/ltx2.py --input |
| Tête parlante à partir d'un portrait photoréaliste | tools/sadtalker.py |
| Tête parlante à partir d'un personnage stylisé | tools/ltx2.py --input (voir skill ltx2) |
| Ajouter une étiquette/légende/tiers-inférieur à l'un des deux | moviepy + PIL (ce skill) |
| Convertir / compresser / redimensionner un fichier existant | ffmpeg (voir skill ffmpeg) |
| Vidéo longue pilotée par système de design | Remotion (voir skill remotion) |
Références
- Exemple exécutable — spot de style publicitaire court :
examples/quick-spot/build.py - Exemple exécutable — data-viz avec superposition de texte :
examples/data-viz-chart/build.py - Timelines ancrées à l'audio :
CLAUDE.md → Vidéo Timing → Timelines Ancérées à l'Audio - Skills connexes :
ltx2,ffmpeg,remotion