Communitygithub.com

digitalsamba/claude-code-video-toolkit

Python 影片合成工具組,使用 moviepy 2.x 在 AI 生成影片(LTX-2、SadTalker)上疊加確定性文字、合成片段,並透過單一 build.py 檔案建立影片專案。適用於為 LTX-2 或 SadTalker 輸出添加標籤、字幕或下方三欄文字,無需 Remotion 即可用純 Python 建立短片廣告。

claude-code-video-toolkit 是什麼?

此技能提供了一個基於 moviepy 2.x 的 Python 影片合成工具組,專注於在 AI 生成影片(如 LTX-2 和 SadTalker)上疊加確定性文字。其核心原則是『可信文字』:任何需要文字精確、一致(法律、編輯或商業需求)的場景,都應避免使用 AI 生成框架內文字,而應採用 moviepy 疊加層來確保正確性。此技能支援多種影片製作類型,包括新聞、紀錄片、預告片、社交短片、產品示範和教學影片,並提供文字渲染(使用 PIL 而非 TextClip)、音訊錨定時間軸、半透明疊加層、並排合成等實用模式。支援的平台包括 Claude Code、Cursor 和 Codex 等 AI 代理環境,其範例檔案(如 `examples/quick-spot/build.py`)可直接執行,展示了從頭建立完整影片專案的流程。

相容平台✓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 生成影片上疊加確定性文字,以及在無需 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

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

相關技能