Video Production을 위한 moviepy
moviepy는 AI 생성 비디오 위에 결정적 텍스트를 배치하고, Remotion 툴체인 없이 짧은 단일 파일 Python 비디오 프로젝트를 구축하기 위한 도구 키트의 핵심 라이브러리입니다.
더 깊은 원칙은 신뢰할 수 있는 텍스트입니다. 텍스트가 반드시 읽기 쉽고, 정확하고, 일관되어야 하는(법적, 편집적, 상업적 이유로) 장르는 AI가 프레임 안에 렌더링한 텍스트를 사용할 수 없으며, moviepy 오버레이 단계가 자연스러운 해결책입니다. 이름은 올바르게 철자되어야 합니다. 가격은 정확해야 합니다. 출처 표시는 픽셀 단위로 완벽해야 합니다. AI 생성 모델은 이 중 어떤 것도 보장할 수 없습니다.
moviepy vs 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초 광고 스타일 스팟. 오디오 중심 타임라인, 텍스트 오버레이, 선택적 VO + 덕킹된 음악. 외부 자산 없이 바로 무음으로 렌더링됩니다.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-롤 위에 "INTRODUCING LONGARM" | 해당 없음 |
| 로우어 서드 / 네임 플레이트 | 해당 없음 | 말하는 머리 아래 "Lugh — Ancient Warrior God" |
| 인용 캡션 | LTX-2 캐릭터 카메오 위에 "I am going home." | SadTalker 말하는 머리 위에 동일 |
| 브랜드 표시 | 마지막 1초에 로고 + URL 페이드인 | 동일 |
| 명암 대비를 위한 틴트 오버레이 | 텍스트 뒤에 짙은 네이비 반투명 레이어 | 동일 |
이 스킬이 빛나는 장르
"AI 비주얼 + 결정적 텍스트 오버레이" 패턴은 여러 비디오 스타일에 자연스러운 제작 파이프라인입니다. 요청이 다음 중 하나와 일치한다면 기본적으로 moviepy를 사용하세요:
| 장르 | 오버레이할 내용 | moviepy가 올바른 선택인 이유 |
|---|---|---|
| 뉴스 / 토크-헤드 저널리즘 | 발언자 이름 바, 위치 바, 속보 배너, 출처 표시, 인용문 | 이름이 올바르게 철자되어야 함(편집상/법적). 볼륨 기준 가장 큰 카테고리. |
| 다큐멘터리 세그먼트 | 인터뷰이 로우어 서드, 챕터 제목, 아카이브 출처 크레딧, 위치 스탬프 | 뉴스와 동일한 신뢰 요구 사항. |
| 트레일러 / 프로모 스팟 | 타이틀 카드, 크레딧 오버레이("FROM THE DIRECTOR OF…"), 날짜 스팅, 인용 카드, CTA | 시간이 빡빡하고, 텍스트가 많으며, 모든 프레임이 중요함. q2-townhall-longarm-ad 예제가 정확히 이것입니다. |
| 소셜 숏폼 (Reels, TikTok, Shorts) | 무음 시청을 위한 단어 정확한 캡션, 해시태그 오버레이 | 대부분의 소셜 시청은 음소거됨; 캡션은 필수. |
| 주석이 있는 제품 데모 | 가격 콜아웃, 기능 라벨, 화면 녹화 위 "click here" 포인터, 전후 라벨 | 가격과 제품명이 정확해야 함. |
| 튜토리얼 / 설명 영상 | 단계 번호 오버레이, 터미널 명령 캡션, 키보드 단축키 콜아웃 | 단계 번호가 순차적이어야 하고, 명령이 복사-붙여넣기 가능해야 함. |
덜하지만 실제로 맞는 경우: 뮤직 비디오(가사 오버레이), 리액션 비디오(출처 표시), 스포츠 요약(점수 오버레이), 부동산 투어(가격/평방피트), 컨퍼런스 강연(발언자 + 세션 플레이트).
전체 SRT 기반 자막 (긴 형식, 시간 코드, 다국어)의 경우 moviepy가 가능하지만 이상적이지는 않습니다 — ffmpeg의 subtitles 필터나 전용 자막 도구를 사용하세요. moviepy는 대량 캡션 트랙보다는 수동 배치 오버레이에 가장 적합합니다.
텍스트 렌더링 — TextClip 대신 PIL 사용
중요한 주의점: moviepy 2.x의 TextClip(method='label')에는 문자 어센더와 디센더(대문자의 윗부분, p/g/y의 꼬리)를 자르는 타이트-bbox 버그가 있습니다. 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, 위치, 페이드, 더 깔끔한 인체공학을 위한 kwargs 포함)는 examples/quick-spot/build.py에 있습니다 — 다시 구현하지 말고 복사하세요.
오디오-앵커드 타임라인 패턴
모든 프레임이 중요한 광고 스타일 편집의 경우, 먼저 장면별 VO를 생성하고 모든 비주얼을 알려진 절대 타임스탬프에 고정합니다. 이렇게 하면 타이밍 드리프트가 완전히 제거됩니다. 전체 패턴은 CLAUDE.md → Video Timing → Audio-Anchored Timelines를 참조하세요. 짧은 버전:
# 오디오-앵커드 타임라인 (25초):
# 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)
일반적인 레시피
단일 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)
장면별 VO와 덕킹된 음악 믹싱
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), # 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)
주의사항
- moviepy 2.x 메서드 이름이 변경됨.
subclipped(구subclip),with_duration/with_start/with_position(구set_duration등),.fadein()/.fadeout()대신with_effects([...])를 사용하세요. 많은 온라인 튜토리얼이 여전히 1.x 문법을 보여줍니다 — 신중하게 확인하세요. TextClip(method='label')가 어센더/디센더를 자릅니다. 항상 위의 PIL 해결책을 사용하세요.OffthreadVideo는 Remotion 전용입니다. moviepy는VideoFileClip을 사용합니다. 둘을 혼용하지 마세요.- 크기 조정에는 Pillow ≥ 10.0이 필요합니다. LANCZOS 리샘플을 위해.
ANTIALIAS오류가 보이면 Pillow를 업그레이드하세요. ColorClip은 RGB 튜플을 받고, 16진수 문자열을 받지 않습니다."#141826"대신(20, 24, 38)을 사용하세요.VideoFileClip의 오디오는 기본적으로 로드됩니다. 비주얼만 원한다면.without_audio()를 호출하세요 — 원하지 않는 오디오와 합성하면CompositeAudioClip에서 VO가 조용히 누락됩니다.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