Communitygithub.com

digitalsamba/claude-code-video-toolkit

使用 moviepy 2.x 进行 Python 视频合成——在 AI 生成的视频(LTX-2、SadTalker)上叠加确定性文本、合成片段、单文件 build.py 视频项目。适用于需要为 LTX-2 或 SadTalker 输出添加标签/字幕/底部三分之一、在纯 Python 中构建短广告风格片段而无需 Remotion、或执行程序化视频合成的场景。

claude-code-video-toolkit 是什么?

该技能提供了使用 moviepy 2.x 库在 AI 生成的视频上叠加确定性文本的完整工作流程。其核心理念是'可信任的文本'——任何文本必须可读、准确且一致的场景(如法律、编辑或商业用途)中,AI 生成的画内文本不可接受,而 moviepy 叠加步骤是自然解决方案。技能详细说明了何时使用 moviepy 与 Remotion 的对比、使用 PIL 而非 TextClip 进行文本渲染(避免字体裁剪 bug)、音频锚定的时间轴模式以及常见配方(包括单个 AI 片段文本叠加、讲话者底部三分之一、色调覆盖层、并排合成和场景音频混音)。支持 LTX-2 和 SadTalker 输出,并提供两个可运行示例(快速广告片段和数据可视化图表)作为参考。该技能适用于新闻/采访、纪录片片段、预告片/促销片、社交媒体短视频、带注释的产品演示和教程/讲解视频。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

moviepy 视频制作

moviepy 是该工具包中用于在 AI 生成的视频上叠加确定性文本以及构建短小、单文件 Python 视频项目(无需 Remotion 工具链)的首选库。

更深层次的原则是可信任的文本:任何文本必须可读、准确且一致(法律、编辑或商业用途)的类型,都是 AI 渲染的画内文本不可接受、而 moviepy 叠加步骤是自然修正的场景。名称必须拼写正确。价格必须精确无误。来源归属必须像素完美。AI 生成模型无法保证这些。

何时使用 moviepy 与 Remotion

使用 moviepy 的场景…使用 Remotion 的场景…
在 LTX-2 或 SadTalker 输出上叠加文本/标签构建长篇幅的冲刺回顾或产品演示
在单个 build.py 中构建 30 秒以下的广告风格片段多模板、多品牌、设计密集型工作
合成数据驱动的视觉元素(matplotlib FuncAnimation → mp4)需要 React 组件或设计系统复用的任何内容
对现有视频文件进行一次性转换项目生命周期(规划 → 渲染)重要的任何内容
零 Node.js / 无 React 心智负担在 Remotion Studio 中热重载预览

本技能的所有内容有两个可运行参考,位于 examples/:

  • examples/quick-spot/build.py — 15 秒广告风格片段。音频锚定的时间轴、文本叠加、可选的画外音 + 音乐闪避。开箱即可静音渲染,无需外部素材。
  • examples/data-viz-chart/build.py — 带确定性标题和来源归属的动画时间序列图表。演示了 matplotlib(数据) + moviepy(可信任文本)的分割。

两者都可通过 uv run build.py 运行,并立即生成真实的 out.mp4。请与本技能一起阅读——下面列出的每个模式都在这些示例中实际运行着。

依赖项。 moviepy、Pillow 和 matplotlib 在根目录的 pyproject.toml 中声明,并通过工具包的一行 Python 设置命令安装:uv sync。如果在运行示例时遇到 Missing dependency,请从仓库根目录运行该命令——示例的 build.py 文件会在错误消息中提示相同内容,并干净退出,而不是打印裸露的堆栈跟踪。

主要用例:AI 生成视频上的文本

LTX-2 和 SadTalker 都输出裸视觉内容:

  • LTX-2 无法可靠地渲染可读文本(模型会幻觉字母形状——请参阅 ltx2 技能的“不良提示”)。
  • SadTalker 输出一个说话的头像,没有字幕、标签、底部三分之一或上下文。

解决方法:先干净地生成视觉内容,然后用 moviepy 确定性地叠加文本。这是本工具包中的经典模式:

from moviepy import VideoFileClip, ImageClip, CompositeVideoClip

# 1. AI 生成的视觉内容(LTX-2 或 SadTalker 输出)
bg = VideoFileClip("lugh_ltx.mp4").without_audio()

# 2. 通过 PIL 渲染文本 → ImageClip(见下文“文本渲染”)
title = (
    ImageClip("text_cache/intro_title.png")
    .with_duration(2.0)
    .with_start(0.5)
    .with_position(("center", 880))
)

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

常见的形式:

形式LTX-2 用途SadTalker 用途
主角镜头上的标题卡片在电影般的 LTX-2 B 卷上显示“介绍 LONGARM”不适用
底部三分之一 / 姓名牌不适用在说话的头像下显示“Lugh — 古代战神”
引用字幕在 LTX-2 角色客串上显示“我要回家了。”同上,在 SadTalker 说话头像上
品牌归属最后几秒 Logo + URL 淡入同上
提高对比度的色调覆盖层文本后面的深海军蓝半透明层同上

此模式的闪光类型

“AI 视觉 + 确定性文本叠加”模式是几种视频风格的自然生产流程。如果请求匹配以下之一,则默认使用 moviepy:

类型叠加内容为什么 moviepy 是正确的选择
新闻 / 采访式新闻发言人名牌、地点栏、突发新闻横幅、来源归属、引语名称必须拼写正确(编辑/法律要求)。按数量计最大类别。
纪录片片段受访者底部三分之一、章节标题、档案来源版权、地点戳与新闻相同的信任要求。
预告片 / 促销片段标题卡片、信用叠加(“导演作品…”)、日期字符串、引语卡片、行动号召时间紧凑、文本密集、每一帧都重要。q2-townhall-longarm-ad 示例正是如此。
社交媒体短视频(Reels、TikTok、Shorts)针对无声观看的词准确字幕、标签叠加大多数社交观看是静音的;字幕是必不可少的。
带注释的产品演示价格标注、功能标签、屏幕录制上的“点击此处”指针、之前/之后标签价格和产品名称必须精确。
教程 / 讲解步骤编号叠加、终端命令字幕、键盘快捷键提示步骤编号必须连续,命令必须可复制粘贴。

较小但真实的应用:音乐视频(歌词叠加)、反应视频(来源归属)、体育集锦(比分叠加)、房地产游览(价格/面积)、会议演讲(演讲者 + 会话牌)。

对于完整的 SRT 驱动字幕(长篇、时间编码、多语言),moviepy 可行但不理想——请使用带 subtitles 过滤器的 ffmpeg 或专用字幕工具。moviepy 最适合手工放置的叠加层,而非批量字幕轨道。

文本渲染——使用 PIL,而非 TextClip

关键陷阱: moviepy 2.x 的 TextClip(method='label') 有一个紧缩边界框 bug,会裁剪字母上升部分和下降部分(大写字母的顶部、g/p/y 的尾部)。在 Apple Silicon 上,你会看到字符边缘被切割,而你可能在数小时内都不会意识到问题所在。

解决方法: 通过 PIL 将文本渲染为透明 PNG,然后将其作为 ImageClip 加载。按内容哈希缓存结果,使重新构建免费。

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)

完整辅助函数(带有粗体、位置、淡入淡出和更整洁人体工程学的 kwargs)位于 examples/quick-spot/build.py 中——请复制它,而不是重新实现。

音频锚定的时间轴模式

对于每一帧都重要的广告风格剪辑,首先生成每个场景的画外音,并将每个视觉元素锚定到已知的绝对时间戳。这完全消除了时间漂移。请参阅 CLAUDE.md → 视频时间轴 → 音频锚定时间轴 获取完整模式。简版如下:

# 音频锚定时间轴 (25 秒):
#   场景 1 tired      0.3 → 3.74  (音频 3.44 秒)
#   场景 2 worries    4.0 → 8.88  (音频 4.88 秒)

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)

常见配方

单个 AI 生成片段上的文本

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)

SadTalker 说话头像上的底部三分之一

from moviepy import VideoFileClip, ImageClip, ColorClip, CompositeVideoClip

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

# 底部半透明条带以增强对比度
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)

在繁忙素材上为文本对比度添加色调覆盖层

LTX-2 的 B 卷通常过于视觉繁忙,难以使文本清晰易读。在视频和文本之间放置一个半透明的深蓝色层:

from moviepy import ColorClip

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

并排合成

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)

混合场景画外音与闪避音乐

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),  # 在画外音下方闪避
    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)

陷阱

  • moviepy 2.x 重命名了方法。 使用 subclipped(而不是 subclip)、with_duration / with_start / with_position(而不是 set_duration 等)、with_effects([...]) 代替 .fadein()/.fadeout()。许多在线教程仍然显示 1.x 语法——请谨慎。
  • TextClip(method='label') 裁剪字母上升部分/下降部分。 始终使用上面的 PIL 解决方法。
  • OffthreadVideo 仅限 Remotion。 moviepy 使用 VideoFileClip。不要混用两者。
  • 调整大小需要 Pillow ≥ 10.0 才能使用 LANCZOS 重采样。如果看到 ANTIALIAS 错误,请升级 Pillow。
  • ColorClip 接受 RGB 元组,而不是十六进制字符串。 使用 (20, 24, 38),而不是 "#141826"。
  • VideoFileClip 中的音频默认加载。 如果只需要视觉内容,请调用 .without_audio()——组合你不想要的音频会导致 CompositeAudioClip 中画外音静音丢失。
  • 始终在 CompositeVideoClip 上设置 size=(W, H)。 不设置时,输出尺寸跟随第一个片段,可能小于目标尺寸。

何时使用何种工具

任务工具
动画化静态图像tools/ltx2.py --input
从逼真肖像生成说话头像tools/sadtalker.py
从风格化角色生成说话头像tools/ltx2.py --input(参见 ltx2 技能)
为上述任一内容添加标签/字幕/底部三分之一moviepy + PIL(本技能)
转换/压缩/调整现有文件大小ffmpeg(参见 ffmpeg 技能)
长篇、设计系统驱动的视频Remotion(参见 remotion 技能)

参考

  • 可运行示例——短广告风格片段:examples/quick-spot/build.py
  • 可运行示例——带文本叠加的数据可视化:examples/data-viz-chart/build.py
  • 音频锚定的时间轴:CLAUDE.md → 视频时间轴 → 音频锚定时间轴
  • 相关技能: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...

相关技能