digitalsamba/claude-code-video-toolkit

moviepy

Python video composition with moviepy 2.x — overlaying deterministic text on AI-generated video (LTX-2, SadTalker), compositing clips, single-file build.py video projects.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/digitalsamba/claude-code-video-toolkit --skill moviepy

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

moviepy for Video Production

moviepy is the toolkit's go-to library for putting deterministic text on top of AI-generated video and for building short, single-file Python video projects without a Remotion toolchain.

The deeper principle is trustworthy text: any genre where text has to be readable, accurate, and consistent (legally, editorially, or commercially) is a genre where AI-rendered in-frame text is unacceptable and a moviepy overlay step is the natural fix. Names must be spelled right. Prices must be exact. Source attributions must be pixel-perfect. AI generation models cannot guarantee any of that.

When to use moviepy vs. Remotion

Use moviepy when…Use Remotion when…
Overlaying text/labels on an LTX-2 or SadTalker outputBuilding long-form sprint reviews or product demos
Building sub-30s ad-style spots in a single build.pyMulti-template, multi-brand, design-heavy work
Compositing data-driven visuals (matplotlib FuncAnimation → mp4)Anything needing React components or design system reuse
One-off transformations on existing video filesAnything where the project lifecycle (planning → render) matters
You want zero Node.js / no React mental overheadYou want hot-reload preview in Remotion Studio

Two runnable references for everything in this skill live in examples/:

  • `examples/quick-spot/build.py` — 15-second ad-style spot. Audio-anchored timeline, text overlay, optional VO + ducked music. Renders silent out of the box with zero external assets.
  • `examples/data-viz-chart/build.py` calls the shared tools/data_video.py renderer with chart.json. It accepts CSV/JSON specs and a brand, spaces dated lines by calendar time, labels bar periods, and overlays author-written text with Pillow through MoviePy. The bundled headline fades in at the spec's time. See the example README for spec fields.

Both run with uv run build.py and produce a real out.mp4 immediately. Read them alongside this skill — every pattern below is shown working there.

Dependencies. moviepy, Pillow, and matplotlib are declared in the root pyproject.toml and installed with the toolkit's one-line Python setup: uv sync. If you hit Missing dependency when running an example, run that command from the repo root — the examples' build.py files will tell you the same thing in their error message and exit cleanly rather than printing a bare traceback.

The main use case: text on AI-generated video

Both LTX-2 and SadTalker output bare visuals:

  • LTX-2 cannot reliably render readable text (the model hallucinates letterforms — see the ltx2 skill's "Bad Prompts").
  • SadTalker outputs a talking head with no captions, labels, lower thirds, or context.

The fix is to generate the visual cleanly, then composite text over it deterministically with moviepy. This is the canonical pattern in this toolkit:

python
from moviepy import VideoFileClip, ImageClip, CompositeVideoClip

# 1. AI-generated visual (LTX-2 or SadTalker output)
bg = VideoFileClip("lugh_ltx.mp4").without_audio()

# 2. Text rendered via PIL → ImageClip (see "Text rendering" below)
title = (
    ImageClip("text_cache/intro_title.png")
    .with_duration(2.0)
    .with_start(0.5)
    .with_position(("center", 880))
)

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

Common shapes this takes:

ShapeLTX-2 useSadTalker use
Title card over hero footage"INTRODUCING LONGARM" over a cinematic LTX-2 b-rolln/a
Lower third / name platen/a"Lugh — Ancient Warrior God" under a talking head
Quote caption"I am going home." over an LTX-2 character cameoSame, over a SadTalker talking head
Brand attributionLogo + URL fade-in over the last secondSame
Tinted overlay for contrastDark navy semi-transparent layer behind textSame

Genres where this shines

The "AI-visual + deterministic text overlay" pattern is the natural production pipeline for several styles of video. If the request matches one of these, reach for moviepy by default:

GenreWhat you overlayWhy moviepy is the right call
News / talking-head journalismSpeaker name plates, location bars, breaking-news banners, source attribution, pull quotesNames must be spelled right (editorial / legal). The biggest category by volume.
Documentary segmentsInterviewee lower thirds, chapter titles, archival source credits, location stampsSame trust requirement as news.
Trailers / promo spotsTitle cards, credit overlays ("FROM THE DIRECTOR OF…"), date stings, quote cards, CTAsTightly timed, text-heavy, every frame matters. The q2-townhall-longarm-ad example is exactly this.
Social short-form (Reels, TikTok, Shorts)Word-accurate captions for sound-off viewing, hashtag overlaysMost social viewing is muted; captions are non-negotiable.
Product demos with annotationsPricing callouts, feature labels, "click here" pointers over screen recordings, before/after labelsPrices and product names must be exact.
Tutorials / explainersStep number overlays, terminal-command captions, keyboard-shortcut calloutsStep numbers must be sequential, commands must be copy-pasteable.

Lesser-but-real fits: music videos (lyric overlays), reaction videos (source attribution), sports recaps (score overlays), real-estate tours (price / sqft), conference talks (speaker + session plate).

For full SRT-driven subtitling (long-form, time-coded, multilingual) moviepy is workable but not ideal — reach for ffmpeg with subtitles filter or a dedicated subtitle tool. moviepy is best for hand-placed overlays, not bulk caption tracks.

Text rendering — use PIL, not TextClip

Critical gotcha: moviepy 2.x's TextClip(method='label') has a tight-bbox bug that clips letter ascenders and descenders (the tops of capitals, the tails of g/p/y). On Apple Silicon you'll see characters with sliced edges and not realise what's wrong for hours.

The workaround: render text to a transparent PNG via PIL, then load it as an ImageClip. Cache the result by content hash so re-builds are free.

python
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)

The full helper (with kwargs for bold, position, fades, and cleaner ergonomics) is in examples/quick-spot/build.py — copy it rather than re-implementing.

Audio-anchored timeline pattern

For ad-style edits where every frame matters, generate per-scene VO first and anchor every visual to known absolute timestamps. This eliminates timing drift entirely. See CLAUDE.md → Video Timing → Audio-Anchored Timelines for the full pattern. The short version:

python
# Audio-anchored timeline (25s):
#   Scene 1 tired      0.3 → 3.74  (audio 3.44s)
#   Scene 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)

Common recipes

Text on a single AI-generated clip

python
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 over a SadTalker talking head

python
from moviepy import VideoFileClip, ImageClip, ColorClip, CompositeVideoClip

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

# Semi-transparent bar across the bottom for contrast
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)

Tinted overlay for text contrast over busy footage

LTX-2 b-roll is often too visually busy for legible text. Drop a semi-transparent navy layer between the video and the text:

python
from moviepy import ColorClip

tint = (
    ColorClip((W, H), color=(20, 24, 38))
    .with_duration(duration)
    .with_opacity(0.55)
)
# Composite order: bg → tint → text
CompositeVideoClip([bg, tint, text_clip])

Side-by-side composite

python
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)

Mix per-scene VO with ducked music

python
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 under 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)

Gotchas

  • moviepy 2.x renamed methods. Use subclipped (not subclip), with_duration / with_start / with_position (not set_duration etc.), with_effects([...]) instead of .fadein()/.fadeout(). Many tutorials online still show 1.x syntax — be skeptical.
  • `TextClip(method='label')` clips ascenders/descenders. Always use the PIL workaround above.
  • `OffthreadVideo` is Remotion-only. moviepy uses VideoFileClip. Don't mix the two.
  • Resizing requires Pillow ≥ 10.0 for the LANCZOS resample. If you see ANTIALIAS errors, upgrade Pillow.
  • `ColorClip` takes RGB tuples, not hex strings. Use (20, 24, 38), not "#141826".
  • Audio in `VideoFileClip` is loaded by default. Call .without_audio() if you only want the visual — composing with audio you don't want will cause silent VO drops in CompositeAudioClip.
  • Always set `size=(W, H)` on `CompositeVideoClip`. Without it, output dimensions follow the first clip, which can be smaller than your target.

When to reach for what

TaskTool
Animate a still imagetools/ltx2.py --input
Talking head from photoreal portraittools/sadtalker.py
Talking head from stylized charactertools/ltx2.py --input (see ltx2 skill)
Add a label/caption/lower third to either of the abovemoviepy + PIL (this skill)
Convert / compress / resize an existing fileffmpeg (see ffmpeg skill)
Long-form, design-system-driven videoRemotion (see remotion skill)

References

  • Runnable example — short ad-style spot: examples/quick-spot/build.py
  • Spec-driven charts with author-written overlays: examples/data-viz-chart/README.md; build.py delegates to tools/data_video.py
  • Audio-anchored timelines: CLAUDE.md → Video Timing → Audio-Anchored Timelines
  • Related skills: ltx2, ffmpeg, remotion
aus demselben Repository

Weitere Skills

Alle Skills
digitalsamba
Community

video-design

Visual design for videos - colour by act, type scale, chart and layout rules for 16:9 and 9:16 scenes, a design.md handoff that any design skill can fill, and a contact-sheet critique of the render. Use when designing or refining how a video looks (title cards, data scenes, slides, a whole video's palette), when a scene looks generic or busy, when choosing colours for a video, or when /design or /scene-review asks for visual work. Works on its own with a brand, or takes direction from a design s

Installationen / 1h
2
GitHub Stars
2651
Aktualisiert
17. Nov.
digitalsamba
Community

acestep

AI music generation with ACE-Step 1.5 — background music, vocal tracks, covers, stem extraction, audio repainting, and continuation for video production. Use when generating music, soundtracks, jingles, or working with audio stems. Triggers include background music, soundtrack, jingle, music generation, stem extraction, cover, style transfer, repaint, continuation, or musical composition tasks.

Installationen / 1h
4
GitHub Stars
2627
Aktualisiert
17. Nov.
digitalsamba
Community

blender

3D scenes, character acting and product shots from a shot spec, rendered in Blender, as a finished film, as clips for any other build (moviepy, a video job, an editor), or as elements of a Remotion video (transparent characters over a scene, a Remotion render on a 3D laptop, phone or floating card that the camera pulls back from, an imported 3D model on a studio stage), or a brand's opening and closing ident built from its SVG logo. A rigged cartoon cast described in JSON (build, face, hair, clo

Installationen / 1h
4
GitHub Stars
2627
Aktualisiert
17. Nov.
digitalsamba
Community

elevenlabs

Generate AI voiceovers, sound effects, and music using ElevenLabs APIs. Use when creating audio content for videos, podcasts, or games. Triggers include generating voiceovers, narration, dialogue, sound effects from descriptions, background music, soundtrack generation, voice cloning, or any audio synthesis task.

Installationen / 1h
4
GitHub Stars
2627
Aktualisiert
17. Nov.