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