Communitygithub.com

digitalsamba/claude-code-video-toolkit

Python 비디오 합성용 도구 키트 (moviepy 2.x 기반) — AI 생성 비디오(LTX-2, SadTalker) 위에 결정적 텍스트 오버레이, 클립 합성, 단일 파일 build.py 비디오 프로젝트를 제공합니다.

claude-code-video-toolkit란 무엇인가요?

이 스킬은 moviepy 2.x를 활용하여 AI 생성 비디오(LTX-2, SadTalker) 위에 텍스트(라벨, 캡션, 로우어 서드 등)를 정확하게 오버레이하거나, 여러 클립을 합성하고, 단일 build.py 파일로 짧은 광고 스타일 비디오를 제작하는 Python 비디오 합성 도구 키트입니다. LTX-2는 텍스트를 왜곡하거나 환각하는 특성이 있고, SadTalker는 머리만 움직이는 영상에 추가 정보가 전혀 없으므로, 신뢰할 수 있는 텍스트(이름, 가격, 출처 등)가 필요한 모든 장르(뉴스, 다큐멘터리, 트레일러, 소셜 숏폼, 튜토리얼 등)에서 AI의 불확정적 텍스트 렌더링을 PIL 기반의 결정적 렌더링으로 대체합니다. 사용자는 복잡한 Remotion 툴체인 없이 순수 Python만으로 제어 가능한 오버레이를 구현할 수 있으며, 예제 폴더(quick-spot, data-viz-chart)에서 실제 실행 가능한 build.py를 바로 확인할 수 있습니다. 주요 패턴으로는 텍스트 오버레이(PIL→ImageClip), 오디오 기반 타임라인(각 장면의 VO에 정확히 정렬), 틴트 오버레이(텍스트 가독성 향상), 사이드바이사이드 합성, 음악+VO 믹싱 등이 포함됩니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/digitalsamba/claude-code-video-toolkit/tree/HEAD/.claude/skills/moviepy

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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

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

관련 스킬