moviepy 影片製作
moviepy 是此工具組的核心函式庫,用於在 AI 生成影片上疊加確定性文字,以及在無需 Remotion 工具鏈的情況下,建立單一 Python 檔案的影片專案。
更深層的原則是可信文字:任何文字必須可讀、準確且一致(法律、編輯或商業需求)的類型,都是 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 用途 |
|---|---|---|
| 英雄素材上的標題卡 | 在 cinematic LTX-2 b-roll 上顯示「INTRODUCING LONGARM」 | n/a |
| 下方三欄文字 / 名牌 | n/a | 說話頭像下方顯示「Lugh — Ancient Warrior God」 |
| 引述字幕 | 在 LTX-2 角色客串上疊加「I am going home.」 | 相同,疊加在 SadTalker 說話頭像上 |
| 品牌歸屬 | 最後一秒淡入 Logo + URL | 相同 |
| 提高對比度的色調疊加 | 文字後方的深海軍藍半透明圖層 | 相同 |
此技能脫穎而出的類型
「AI 視覺 + 確定性文字疊加」模式是數種影片風格的自然製作流程。如果請求符合以下任一項,預設應使用 moviepy:
| 類型 | 疊加的內容 | 為何 moviepy 是正確選擇 |
|---|---|---|
| 新聞 / 談話頭像新聞報導 | 演講者名牌、位置列、突發新聞橫幅、來源歸屬、引用 | 名稱必須拼寫正確(編輯/法律需求)。按數量計是最大類別。 |
| 紀錄片片段 | 受訪者下方三欄文字、章節標題、檔案來源致謝、位置標記 | 與新聞相同的信任要求。 |
| 預告片 / 宣傳片段 | 標題卡、致謝疊加(「FROM THE DIRECTOR OF…」)、日期字串、引述卡、行動呼籲 | 時間控制嚴格、文字密集、每個畫面都很重要。q2-townhall-longarm-ad 範例正是如此。 |
| 社群短片(Reels、TikTok、Shorts) | 無聲觀看的逐字字幕、主題標籤疊加 | 大多數社群觀看是靜音的;字幕是不可妥協的。 |
| 附有註解的產品示範 | 價格標註、功能標籤、螢幕錄影上的「點擊此處」指標、前後對比標籤 | 價格和產品名稱必須精確。 |
| 教學 / 講解 | 步驟編號疊加、終端機命令字幕、鍵盤快捷鍵標註 | 步驟編號必須連續、命令必須可複製貼上。 |
較小但仍然合適的應用:音樂影片(歌詞疊加)、反應影片(來源歸屬)、運動回顧(分數疊加)、房地產導覽(價格/坪數)、會議演講(演講者 + 場次名牌)。
對於完整的 SRT 驅動字幕(長篇、時間碼、多語言),moviepy 可行但非理想 — 請使用 ffmpeg 搭配 subtitles 篩選器或專用字幕工具。moviepy 最適合手動放置的疊加層,而非大量字幕軌。
文字渲染 — 使用 PIL,而非 TextClip
關鍵陷阱: moviepy 2.x 的 TextClip(method='label') 存在 tight-bbox 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)
完整的輔助函式(包含 bold、position、fades 參數和更佳的人體工學設計)位於 examples/quick-spot/build.py — 請直接複製而非重新實作。
音訊錨定時間軸模式
對於每個畫面都很重要的廣告風格剪輯,請先為每個場景生成旁白,然後將每個視覺元素錨定到已知的絕對時間戳記。這完全消除了時間漂移。完整模式請參閱 CLAUDE.md → Video Timing → Audio-Anchored Timelines。簡短版本如下:
# 音訊錨定時間軸(25 秒):
# 場景 1 疲倦 0.3 → 3.74 (音訊 3.44 秒)
# 場景 2 擔憂 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-roll 通常視覺上過於繁雜,無法讓文字清晰可讀。在影片和文字之間放置一個半透明的海軍藍圖層:
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 → Video Timing → Audio-Anchored Timelines - 相關技能:
ltx2、ffmpeg、remotion