moviepy für die Videoproduktion
moviepy ist die zentrale Bibliothek des Toolkits für deterministische Texteinblendungen auf KI-generierten Videos und für den Bau kurzer, single-file Python-Videoprojekte ohne Remotion-Toolchain.
Das zugrundeliegende Prinzip ist vertrauenswürdiger Text: Jedes Genre, in dem Text lesbar, akkurat und konsistent sein muss (rechtlich, redaktionell oder kommerziell), ist ein Genre, in dem KI-generierter Text im Bild nicht akzeptabel ist und ein moviepy-Overlay die natürliche Lösung darstellt. Namen müssen richtig geschrieben sein. Preise müssen exakt stimmen. Quellenangaben müssen pixelgenau sein. KI-Generierungsmodelle können das nicht garantieren.
Wann moviepy vs. Remotion verwenden
| Verwende moviepy, wenn... | Verwende Remotion, wenn... |
|---|---|
| Text/Labels auf LTX-2- oder SadTalker-Output überlagern | Lange Sprint-Reviews oder Produktdemos erstellen |
Kurze Werbespots unter 30s in einem einzigen build.py bauen | Multi-Template, Multi-Brand, designintensive Arbeit |
Datengetriebene Visuals komponieren (matplotlib FuncAnimation → mp4) | Alles, was React-Komponenten oder Designsystem-Wiederverwendung benötigt |
| Einmalige Transformationen auf vorhandenen Videodateien | Alles, bei dem der Projektlebenszyklus (Planung → Render) wichtig ist |
| Kein Node.js / kein React-Overhead gewünscht | Hot-Reload-Vorschau im Remotion Studio gewünscht |
Zwei ausführbare Referenzen für alles in diesem Skill finden sich in examples/:
examples/quick-spot/build.py— 15-Sekunden-Werbespot. Audio-verankerte Zeitachse, Texteinblendung, optionales Voiceover + geduckte Musik. Rendert sofort ohne externe Assets.examples/data-viz-chart/build.py— Animierter Zeitreihen-Chart mit deterministischem Titel und Quellenangabe. Zeigt die Aufteilung matplotlib (Daten) + moviepy (vertrauenswürdiger Text).
Beide laufen mit uv run build.py und produzieren sofort eine echte out.mp4. Lies sie zusammen mit diesem Skill — jedes unten beschriebene Muster wird dort in der Praxis gezeigt.
Abhängigkeiten. moviepy, Pillow und matplotlib sind in der root pyproject.toml deklariert und werden mit dem Einzeiler des Toolkits installiert: uv sync. Falls beim Ausführen eines Beispiels Missing dependency erscheint, führe diesen Befehl vom Repo-Root aus — die build.py-Dateien der Beispiele teilen dir dasselbe in ihrer Fehlermeldung mit und beenden sich sauber, statt einen rohen Traceback zu werfen.
Der Hauptanwendungsfall: Text auf KI-generierten Videos
Sowohl LTX-2 als auch SadTalker liefern reine Bilder:
- LTX-2 kann lesbaren Text nicht zuverlässig rendern (das Modell halluziniert Buchstabenformen — siehe das ltx2-Skill unter „Bad Prompts").
- SadTalker liefert einen sprechenden Kopf ohne Untertitel, Labels, Lower Thirds oder Kontext.
Der Fix besteht darin, das Bild sauber zu generieren und dann deterministisch Text mit moviepy zu überlagern. Dies ist das kanonische Muster in diesem Toolkit:
from moviepy import VideoFileClip, ImageClip, CompositeVideoClip
# 1. KI-generiertes Bild (LTX-2 oder SadTalker Output)
bg = VideoFileClip("lugh_ltx.mp4").without_audio()
# 2. Text via PIL gerendert → ImageClip (siehe „Textrendering" unten)
title = (
ImageClip("text_cache/intro_title.png")
.with_duration(2.0)
.with_start(0.5)
.with_position(("center", 880))
)
# 3. Zusammensetzen
final = CompositeVideoClip([bg, title], size=(1920, 1080))
final.write_videofile("lugh_with_caption.mp4", fps=30, codec="libx264")
Häufige Formen, die dies annimmt:
| Form | LTX-2 Verwendung | SadTalker Verwendung |
|---|---|---|
| Titelcard über Heldenmaterial | „INTRODUCING LONGARM" über einem filmischen LTX-2 B-Roll | n/a |
| Lower Third / Namensschild | n/a | „Lugh — Ancient Warrior God" unter einem sprechenden Kopf |
| Zitat-Untertitel | „I am going home." über einem LTX-2 Charakter-Cameo | Gleich, über einem SadTalker sprechenden Kopf |
| Markenattribution | Logo + URL Einblendung in der letzten Sekunde | Gleich |
| Farbiger Overlay für Kontrast | Dunkelmarineblaue halbtransparente Schicht hinter Text | Gleich |
Genres, in denen dies glänzt
Das Muster „KI-Visual + deterministischer Text-Overlay" ist die natürliche Produktionspipeline für verschiedene Videostile. Wenn die Anfrage einem dieser Genres entspricht, greife standardmäßig zu moviepy:
| Genre | Was überlagert wird | Warum moviepy die richtige Wahl ist |
|---|---|---|
| Nachrichten / Journalismus mit Sprecher | Sprecher-Namensschilder, Ortseinblendungen, Eilmeldungs-Banner, Quellenangaben, Pull Quotes | Namen müssen richtig geschrieben sein (redaktionell/rechtlich). Das volumenmäßig größte Genre. |
| Dokumentationssegmente | Interviewte Lower Thirds, Kapiteltitel, Archivquellen-Credits, Ortsstempel | Gleiches Vertrauenserfordernis wie Nachrichten. |
| Trailer / Promo-Spots | Titelcards, Credit-Overlays („FROM THE DIRECTOR OF…"), Datumseinblendungen, Zitatkarten, CTAs | Zeitlich genau, textlastig, jeder Frame zählt. Das q2-townhall-longarm-ad-Beispiel ist genau das. |
| Social Short-Form (Reels, TikTok, Shorts) | Wortgenaue Untertitel für stummgeschaltetes Ansehen, Hashtag-Overlays | Die meisten Social-Views sind stummgeschaltet; Untertitel sind unerlässlich. |
| Produktdemos mit Anmerkungen | Preisauszeichnungen, Feature-Labels, „Klicke hier"-Hinweise über Bildschirmaufnahmen, Vorher/Nachher-Labels | Preise und Produktnamen müssen exakt sein. |
| Tutorials / Erklärvideos | Schrittnummern-Overlays, Terminal-Befehl-Untertitel, Tastenkürzel-Hinweise | Schrittnummern müssen sequenziell sein, Befehle kopierbar. |
Weniger verbreitete, aber dennoch passende Anwendungen: Musikvideos (Lyric-Overlays), Reaktionsvideos (Quellenangaben), Sportzusammenfassungen (Score-Overlays), Immobilientouren (Preis/qm), Konferenzvorträge (Sprecher + Session-Platte).
Für vollständige SRT-gesteuerte Untertitelung (Langform, zeitcodiert, mehrsprachig) ist moviepy brauchbar, aber nicht ideal — greife zu ffmpeg mit dem subtitles-Filter oder einem dedizierten Untertitel-Tool. moviepy ist am besten für manuell platzierte Overlays, nicht für Massen-Untertitel-Spuren.
Textrendering — PIL verwenden, nicht TextClip
Kritisches Problem: moviepy 2.x TextClip(method='label') hat einen engen Bounding-Box-Bug, der Buchstaben-Oberlängen und -Unterlängen abschneidet (die Spitzen von Großbuchstaben, die Unterlängen von g/p/y). Auf Apple Silicon siehst du Zeichen mit abgeschnittenen Kanten und merkst stundenlang nicht, was falsch ist.
Der Workaround: Rendere Text als transparentes PNG via PIL und lade es dann als ImageClip. Cache das Ergebnis per Inhalts-Hash, sodass Neuerstellungen kostenlos sind.
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)
Die vollständige Hilfsfunktion (mit kwargs für fett, Position, Einblendungen und sauberere Ergonomie) befindet sich in examples/quick-spot/build.py — kopiere sie, anstatt sie neu zu implementieren.
Audio-verankertes Zeitachsenmuster
Für werbeähnliche Schnitte, bei denen jeder Frame zählt, generiere zuerst pro-Szene VO und verankere jedes Bild an bekannten absoluten Zeitstempeln. Dies eliminiert Timing-Drift vollständig. Siehe CLAUDE.md → Video Timing → Audio-Anchored Timelines für das vollständige Muster. Die Kurzversion:
# Audio-verankerte Zeitachse (25s):
# Szene 1 tired 0.3 → 3.74 (Audio 3.44s)
# Szene 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)
Häufige Rezepte
Text auf einem einzelnen KI-generierten Clip
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)
Lower Third über einem SadTalker sprechenden Kopf
from moviepy import VideoFileClip, ImageClip, ColorClip, CompositeVideoClip
talking = VideoFileClip("narrator_sadtalker.mp4")
W, H = talking.size
# Halbtransparenter Balken unten für Kontrast
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)
Getönter Overlay für Textkontrast über bewegten Aufnahmen
LTX-2 B-Roll ist oft zu visuell überladen für lesbaren Text. Lege eine halbtransparente marineblaue Schicht zwischen Video und Text:
from moviepy import ColorClip
tint = (
ColorClip((W, H), color=(20, 24, 38))
.with_duration(duration)
.with_opacity(0.55)
)
# Compositing-Reihenfolge: bg → tint → text
CompositeVideoClip([bg, tint, text_clip])
Side-by-Side-Komposition
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)
Mische pro-Szene VO mit geduckter Musik
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), # duck unter 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)
Fallstricke
- moviepy 2.x hat Methoden umbenannt. Verwende
subclipped(nichtsubclip),with_duration/with_start/with_position(nichtset_durationusw.),with_effects([...])statt.fadein()/.fadeout(). Viele Online-Tutorials zeigen noch 1.x-Syntax — sei skeptisch. TextClip(method='label')schneidet Ober-/Unterlängen ab. Verwende immer den PIL-Workaround oben.OffthreadVideoist nur für Remotion. moviepy verwendetVideoFileClip. Mische die beiden nicht.- Skalierung erfordert Pillow ≥ 10.0 für den LANCZOS-Resample. Bei
ANTIALIAS-Fehlern Pillow aktualisieren. ColorClipakzeptiert RGB-Tupel, keine Hex-Strings. Verwende(20, 24, 38), nicht"#141826".- Audio in
VideoFileClipwird standardmäßig geladen. Rufe.without_audio()auf, wenn du nur das Bild willst — Compositing mit unerwünschtem Audio führt zu stummen VO-Ausfällen inCompositeAudioClip. - Setze immer
size=(W, H)aufCompositeVideoClip. Ohne Angabe folgen die Ausgabemaße dem ersten Clip, was kleiner als dein Ziel sein kann.
Wann greife ich zu was
| Aufgabe | Werkzeug |
|---|---|
| Ein Standbild animieren | tools/ltx2.py --input |
| Sprechenden Kopf aus fotorealistischem Porträt | tools/sadtalker.py |
| Sprechenden Kopf aus stilisierter Figur | tools/ltx2.py --input (siehe ltx2-Skill) |
| Ein Label/Untertitel/Lower Third zu einem der obigen hinzufügen | moviepy + PIL (dieses Skill) |
| Vorhandene Datei konvertieren/komprimieren/skalieren | ffmpeg (siehe ffmpeg-Skill) |
| Langform-, designsystemgetriebenes Video | Remotion (siehe remotion-Skill) |
Referenzen
- Ausführbares Beispiel — kurzer Werbespot:
examples/quick-spot/build.py - Ausführbares Beispiel — Datenvisualisierung mit Text-Overlay:
examples/data-viz-chart/build.py - Audio-verankerte Zeitachsen:
CLAUDE.md → Video Timing → Audio-Anchored Timelines - Verwandte Skills:
ltx2,ffmpeg,remotion