Communitygithub.com

digitalsamba/claude-code-video-toolkit

Python-Videokomposition mit moviepy 2.x — deterministische Texteinblendung auf KI-generierten Videos (LTX-2, SadTalker), Zusammenfügen von Clips, single-file build.py-Videoprojekte.

Was ist claude-code-video-toolkit?

Dieses Skill-Paket für Claude Code bietet eine vollständige Python-basierte Videokompositionsumgebung mit moviepy 2.x, die speziell für die Überlagerung von deterministischem Text auf KI-generierten Videos entwickelt wurde. Es löst das grundlegende Problem, dass Modelle wie LTX-2 und SadTalker keine zuverlässigen Texteinblendungen erzeugen können – Namen, Preise und Quellenangaben müssen pixelgenau sein. Das Toolkit enthält zwei lauffähige Beispiele in `examples/`: ein 15-Sekunden-Werbespot (`quick-spot/build.py`) und einen animierten Zeitreihen-Chart (`data-viz-chart/build.py`), die beide mit `uv run build.py` sofort ein `out.mp4` produzieren. Es unterstützt Plattformen wie Cursor und Codex durch die Bereitstellung von strukturiertem, wiederverwendbarem Code. Die kritische Einschränkung von moviepy 2.x (`TextClip(method='label')` schneidet Buchstaben-Oberlängen ab) wird durch eine PIL-basierte Textrender-Funktion umgangen. Das Skill deckt ein breites Spektrum an Szenarien ab: von Nachrichten- und Dokumentarfilmen über Social-Media-Formate bis hin zu Produktdemos und Tutorials, und bietet bewährte Muster wie audio-verankerte Zeitachsen, getönte Overlays für besseren Kontrast und Side-by-Side-Kompositionen.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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 überlagernLange Sprint-Reviews oder Produktdemos erstellen
Kurze Werbespots unter 30s in einem einzigen build.py bauenMulti-Template, Multi-Brand, designintensive Arbeit
Datengetriebene Visuals komponieren (matplotlib FuncAnimation → mp4)Alles, was React-Komponenten oder Designsystem-Wiederverwendung benötigt
Einmalige Transformationen auf vorhandenen VideodateienAlles, bei dem der Projektlebenszyklus (Planung → Render) wichtig ist
Kein Node.js / kein React-Overhead gewünschtHot-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:

FormLTX-2 VerwendungSadTalker Verwendung
Titelcard über Heldenmaterial„INTRODUCING LONGARM" über einem filmischen LTX-2 B-Rolln/a
Lower Third / Namensschildn/a„Lugh — Ancient Warrior God" unter einem sprechenden Kopf
Zitat-Untertitel„I am going home." über einem LTX-2 Charakter-CameoGleich, über einem SadTalker sprechenden Kopf
MarkenattributionLogo + URL Einblendung in der letzten SekundeGleich
Farbiger Overlay für KontrastDunkelmarineblaue halbtransparente Schicht hinter TextGleich

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:

GenreWas überlagert wirdWarum moviepy die richtige Wahl ist
Nachrichten / Journalismus mit SprecherSprecher-Namensschilder, Ortseinblendungen, Eilmeldungs-Banner, Quellenangaben, Pull QuotesNamen müssen richtig geschrieben sein (redaktionell/rechtlich). Das volumenmäßig größte Genre.
DokumentationssegmenteInterviewte Lower Thirds, Kapiteltitel, Archivquellen-Credits, OrtsstempelGleiches Vertrauenserfordernis wie Nachrichten.
Trailer / Promo-SpotsTitelcards, Credit-Overlays („FROM THE DIRECTOR OF…"), Datumseinblendungen, Zitatkarten, CTAsZeitlich 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-OverlaysDie meisten Social-Views sind stummgeschaltet; Untertitel sind unerlässlich.
Produktdemos mit AnmerkungenPreisauszeichnungen, Feature-Labels, „Klicke hier"-Hinweise über Bildschirmaufnahmen, Vorher/Nachher-LabelsPreise und Produktnamen müssen exakt sein.
Tutorials / ErklärvideosSchrittnummern-Overlays, Terminal-Befehl-Untertitel, Tastenkürzel-HinweiseSchrittnummern 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 (nicht subclip), with_duration / with_start / with_position (nicht set_duration usw.), 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.
  • OffthreadVideo ist nur für Remotion. moviepy verwendet VideoFileClip. Mische die beiden nicht.
  • Skalierung erfordert Pillow ≥ 10.0 für den LANCZOS-Resample. Bei ANTIALIAS-Fehlern Pillow aktualisieren.
  • ColorClip akzeptiert RGB-Tupel, keine Hex-Strings. Verwende (20, 24, 38), nicht "#141826".
  • Audio in VideoFileClip wird 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 in CompositeAudioClip.
  • Setze immer size=(W, H) auf CompositeVideoClip. Ohne Angabe folgen die Ausgabemaße dem ersten Clip, was kleiner als dein Ziel sein kann.

Wann greife ich zu was

AufgabeWerkzeug
Ein Standbild animierentools/ltx2.py --input
Sprechenden Kopf aus fotorealistischem Porträttools/sadtalker.py
Sprechenden Kopf aus stilisierter Figurtools/ltx2.py --input (siehe ltx2-Skill)
Ein Label/Untertitel/Lower Third zu einem der obigen hinzufügenmoviepy + PIL (dieses Skill)
Vorhandene Datei konvertieren/komprimieren/skalierenffmpeg (siehe ffmpeg-Skill)
Langform-, designsystemgetriebenes VideoRemotion (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

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...

Verwandte Skills