Video Toolkit
텍스트 브리프로 전문적인 설명 동영상을 제작합니다. 이 툴킷은 음성 해설, 이미지 생성, 음악 및 토킹 헤드 애니메이션을 위해 클라우드 GPU(Modal 또는 RunPod)에서 오픈소스 AI 모델을 사용합니다. Remotion(React)이 합성과 렌더링을 담당합니다.
중요: 툴킷 경로
툴킷은 고정된 경로에 있습니다. 항상 도구 명령을 실행하기 전에 cd로 이 디렉토리로 이동하세요.
TOOLKIT=~/.openclaw/workspace/claude-code-video-toolkit
cd $TOOLKIT
프로젝트 디렉토리 내부에서 도구 명령을 절대 실행하지 마세요. 도구는 툴킷 루트 기준으로 경로를 확인합니다.
설정
1단계: 현재 상태 확인
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/verify_setup.py
모든 항목에 [x]가 표시되면 아래 "빠른 테스트"로 건너뛰세요. 그렇지 않으면 설정을 계속합니다.
2단계: Python 종속성 설치
cd ~/.openclaw/workspace/claude-code-video-toolkit
pip3 install --break-system-packages -r tools/requirements.txt
참고: --break-system-packages는 PEP 668로 관리되는 Python이 있는 Debian/Ubuntu에서 필요합니다. 컨테이너 내에서는 안전합니다.
3단계: 클라우드 GPU 엔드포인트 구성
툴킷은 .env 파일에 클라우드 GPU 엔드포인트 URL이 필요합니다. .env가 존재하고 Modal 엔드포인트가 있는지 확인하세요:
cat ~/.openclaw/workspace/claude-code-video-toolkit/.env | grep MODAL
Modal 엔드포인트가 구성되어 있으면 준비가 완료된 것입니다. 그렇지 않으면 사용자에게 Modal 엔드포인트 URL을 제공하거나 Modal을 설정하도록 요청하세요:
pip3 install --break-system-packages modal
python3 -m modal setup # 브라우저를 열어 인증
# 각 도구 배포 — 출력에서 엔드포인트 URL을 캡처
cd ~/.openclaw/workspace/claude-code-video-toolkit
modal deploy docker/modal-qwen3-tts/app.py
modal deploy docker/modal-flux2/app.py
modal deploy docker/modal-music-gen/app.py
modal deploy docker/modal-sadtalker/app.py
modal deploy docker/modal-image-edit/app.py
modal deploy docker/modal-upscale/app.py
modal deploy docker/modal-propainter/app.py
modal deploy docker/modal-ltx2/app.py # 필요: modal secret create huggingface-token HF_TOKEN=hf_...
LTX-2 사전 조건: LTX-2를 배포하기 전에 HuggingFace 시크릿을 생성하고 Gemma 3 라이선스에 동의하세요:
modal secret create huggingface-token HF_TOKEN=hf_your_read_access_token
각 URL을 .env에 추가하세요:
MODAL_QWEN3_TTS_ENDPOINT_URL=https://...modal.run
MODAL_FLUX2_ENDPOINT_URL=https://...modal.run
MODAL_MUSIC_GEN_ENDPOINT_URL=https://...modal.run
MODAL_SADTALKER_ENDPOINT_URL=https://...modal.run
MODAL_IMAGE_EDIT_ENDPOINT_URL=https://...modal.run
MODAL_UPSCALE_ENDPOINT_URL=https://...modal.run
MODAL_DEWATERMARK_ENDPOINT_URL=https://...modal.run
MODAL_LTX2_ENDPOINT_URL=https://...modal.run
선택 사항이지만 권장 — 안정적인 파일 전송을 위한 Cloudflare R2:
R2_ACCOUNT_ID=...
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=video-toolkit
4단계: 확인 및 빠른 테스트
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/verify_setup.py
모든 도구에 [x]가 표시되어야 합니다. 그런 다음 빠른 테스트를 실행하여 GPU 파이프라인이 작동하는지 확인하세요:
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/qwen3_tts.py --text "Hello, this is a test." --speaker Ryan --tone warm --output /tmp/video-toolkit-test.mp3 --cloud modal
유효한 .mp3 파일이 생성되면 설정이 완료된 것입니다. 실패하면 다음을 확인하세요:
.env에 올바른MODAL_QWEN3_TTS_ENDPOINT_URL이 있는지python3 tools/verify_setup.py --json을 실행하고modal_tools에서 누락된 엔드포인트 확인
비용: Modal은 월 $30 상당의 무료 컴퓨팅을 포함합니다. 일반적인 60초 비디오는 $1-3입니다.
비디오 만들기
1단계: 프로젝트 생성
cd ~/.openclaw/workspace/claude-code-video-toolkit
cp -r templates/product-demo projects/PROJECT_NAME
cd projects/PROJECT_NAME
npm install
템플릿: product-demo(마케팅/설명), sprint-review, sprint-review-v2(구성 가능한 장면).
2단계: 설정 작성
projects/PROJECT_NAME/src/config/demo-config.ts 편집:
export const demoConfig: ProductDemoConfig = {
product: {
name: 'My Product',
tagline: 'What it does in one line',
website: 'example.com',
},
scenes: [
{ type: 'title', durationSeconds: 9, content: { headline: '...', subheadline: '...' } },
{ type: 'problem', durationSeconds: 14, content: { headline: '...', problems: ['...', '...'] } },
{ type: 'solution', durationSeconds: 13, content: { headline: '...', highlights: ['...', '...'] } },
{ type: 'stats', durationSeconds: 12, content: { stats: [{value: '99%', label: '...'}, ...] } },
{ type: 'cta', durationSeconds: 10, content: { headline: '...', links: ['...'] } },
],
audio: {
backgroundMusicFile: 'audio/bg-music.mp3',
backgroundMusicVolume: 0.12,
},
};
장면 유형: title, problem, solution, demo, feature, stats, cta.
기간 규칙: durationSeconds를 ceil(word_count / 2.5) + 2로 추정합니다. 4단계에서 오디오를 생성한 후 이 값을 조정합니다.
3단계: 음성 해설 대본 작성
projects/PROJECT_NAME/VOICEOVER-SCRIPT.md 생성:
## 장면 1: 제목 (9초, ~17단어)
Build videos with AI. The product name toolkit makes it easy.
## 장면 2: 문제 (14초, ~30단어)
The problem statement goes here. Keep it punchy and relatable.
장면당 단어 예산: (durationSeconds - 2) * 2.5 단어. -2는 1초 오디오 지연 + 1초 여백을 의미합니다.
4단계: 에셋 생성
중요: 아래 모든 명령은 프로젝트 디렉토리가 아닌 툴킷 루트에서 실행해야 합니다.
cd ~/.openclaw/workspace/claude-code-video-toolkit
4a. 배경 음악
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/music_gen.py \
--preset corporate-bg \
--duration 90 \
--output projects/PROJECT_NAME/public/audio/bg-music.mp3 \
--cloud modal
프리셋: corporate-bg, upbeat-tech, ambient, dramatic, tension, hopeful, cta, lofi.
4b. 음성 해설 (장면별)
장면당 하나의 .mp3 파일을 생성하세요. 단일 음성 해설 파일을 생성하지 마세요.
cd ~/.openclaw/workspace/claude-code-video-toolkit
# 장면 01
python3 tools/qwen3_tts.py \
--text "The voiceover text for scene one." \
--speaker Ryan --tone warm \
--output projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
--cloud modal
# 장면 02
python3 tools/qwen3_tts.py \
--text "The voiceover text for scene two." \
--speaker Ryan --tone warm \
--output projects/PROJECT_NAME/public/audio/scenes/02.mp3 \
--cloud modal
# ... 각 장면에 대해 반복
화자: Ryan, Aiden, Vivian, Serena, Uncle_Fu, Dylan, Eric, Ono_Anna, Sohee
톤: neutral, warm, professional, excited, calm, serious, storyteller, tutorial
음성 복제의 경우 (참조 녹음 필요):
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/qwen3_tts.py \
--text "Text to speak" \
--ref-audio assets/voices/reference.m4a \
--ref-text "Exact transcript of the reference audio" \
--output projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
--cloud modal
4c. 장면 이미지
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/flux2.py \
--prompt "Dark tech background with blue geometric grid, cinematic lighting" \
--width 1920 --height 1080 \
--output projects/PROJECT_NAME/public/images/title-bg.png \
--cloud modal
이미지 프리셋 (--prompt --width --height 대신 --preset 사용):
title-bg, problem, solution, demo-bg, stats-bg, cta, thumbnail, portrait-bg
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/flux2.py \
--preset title-bg \
--output projects/PROJECT_NAME/public/images/title-bg.png \
--cloud modal
4d. 비디오 클립 — B-롤 및 애니메이션 배경 (선택사항)
B-롤 컷어웨이, 애니메이션 슬라이드 배경 또는 인트로/아웃트로 시퀀스를 위한 AI 비디오 클립을 생성하세요:
cd ~/.openclaw/workspace/claude-code-video-toolkit
# 텍스트로 B-롤 클립
python3 tools/ltx2.py \
--prompt "Aerial drone shot over a European city at golden hour, cinematic wide angle" \
--output projects/PROJECT_NAME/public/videos/broll-europe.mp4 \
--cloud modal
# 슬라이드/스크린샷 애니메이션 (이미지-비디오)
python3 tools/ltx2.py \
--prompt "Gentle particle effects, soft ambient light shifts, very slight camera drift" \
--input projects/PROJECT_NAME/public/images/title-bg.png \
--output projects/PROJECT_NAME/public/videos/animated-title.mp4 \
--cloud modal
# 추상 인트로/아웃트로 배경
python3 tools/ltx2.py \
--prompt "Dark moody abstract background with flowing blue light streaks, bokeh particles, cinematic" \
--output projects/PROJECT_NAME/public/videos/intro-bg.mp4 \
--cloud modal
Remotion 컴포지션에서 <OffthreadVideo>를 사용하세요:
<OffthreadVideo src={staticFile('videos/broll-europe.mp4')} />
LTX-2 규칙:
- 클립당 최대 ~8초 (24fps에서 193프레임). 기본값은 ~5초 (121프레임).
- 너비/높이는 64로 나누어 떨어져야 합니다. 기본값: 768x512.
- 클립당 약 $0.20-0.25, 생성 시간 약 2.5분.
- 콜드 스타트 약 60-90초. 웜 GPU에서 후속 클립은 더 빠릅니다.
- 생성된 오디오는 앰비언트 전용입니다. 음성 및 음악에는 음성 해설/음악 도구를 사용하세요.
- 생성물의 약 30%에서 학습 데이터 아티팩트(로고/텍스트)가 나타날 수 있습니다.
--seed로 다시 실행하여 다양화하세요.
4e. 토킹 헤드 내레이터 (선택사항)
발표자 초상화를 생성한 다음 장면별 클립을 애니메이션화하세요:
cd ~/.openclaw/workspace/claude-code-video-toolkit
# 1. 초상화 생성
python3 tools/flux2.py \
--prompt "Professional presenter portrait, clean style, dark background, facing camera, upper body" \
--width 1024 --height 576 \
--output projects/PROJECT_NAME/public/images/presenter.png \
--cloud modal
# 2. 장면별 내레이터 클립 생성 (장면당 하나, 하나의 긴 비디오가 아님)
python3 tools/sadtalker.py \
--image projects/PROJECT_NAME/public/images/presenter.png \
--audio projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
--preprocess full --still --expression-scale 0.8 \
--output projects/PROJECT_NAME/public/narrator-01.mp4 \
--cloud modal
# 내레이터가 필요한 각 장면에 대해 반복
SadTalker 규칙 — 다음을 정확히 따르세요:
- 항상
--preprocess full을 사용하세요 (기본값crop은 정사각형을 출력하여 종횡비가 잘못됨) - 항상
--still을 사용하세요 (머리 움직임을 줄여 프로페셔널하게 보임) - 항상 장면별 클립(각 6-15초)을 생성하고, 절대 하나의 긴 비디오를 만들지 마세요
- 처리: Modal A10G에서 오디오 10초당 약 3-4분
--expression-scale 0.8은 표정을 미묘하게 유지합니다 (범위 0.0-1.5)
4e. 이미지 편집 (선택사항)
기존 이미지에서 장면 변형을 만듭니다:
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/image_edit.py \
--input projects/PROJECT_NAME/public/images/title-bg.png \
--prompt "Make it darker with red tones, more ominous" \
--output projects/PROJECT_NAME/public/images/problem-bg.png \
--cloud modal
4f. 업스케일링 (선택사항)
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/upscale.py \
--input projects/PROJECT_NAME/public/images/some-image.png \
--output projects/PROJECT_NAME/public/images/some-image-4x.png \
--scale 4 --cloud modal
5단계: 타이밍 동기화
음성 해설을 생성한 후 항상 이 작업을 수행하세요. 오디오 길이는 추정치와 다릅니다.
cd ~/.openclaw/workspace/claude-code-video-toolkit
for f in projects/PROJECT_NAME/public/audio/scenes/*.mp3; do
echo "$(basename $f): $(ffprobe -v error -show_entries format=duration -of csv=p=0 "$f")s"
done
demo-config.ts에서 각 장면의 durationSeconds를 ceil(actual_audio_duration + 2)로 업데이트하세요.
예: 01.mp3가 6.8초이면 장면 1의 durationSeconds를 9로 설정합니다 (ceil(6.8 + 2) = 9).
6단계: 스틸 프레임 검토
cd ~/.openclaw/workspace/claude-code-video-toolkit/projects/PROJECT_NAME
npx remotion still src/index.ts ProductDemo --frame=100 --output=/tmp/review-scene1.png
npx remotion still src/index.ts ProductDemo --frame=400 --output=/tmp/review-scene2.png
확인할 사항: 텍스트 잘림, 애니메이션 타이밍, 내레이터 PiP 위치, 배경 대비.
7단계: 렌더링
cd ~/.openclaw/workspace/claude-code-video-toolkit/projects/PROJECT_NAME
npm run render
출력: out/ProductDemo.mp4
구성 패턴
장면별 오디오
1초 지연(from={30} = 30fps에서 30프레임 = 1초)으로 장면별 오디오 사용:
<Sequence from={30}>
<Audio src={staticFile('audio/scenes/01.mp3')} volume={1} />
</Sequence>
장면별 내레이터 PiP
<Sequence from={30}>
<OffthreadVideo
src={staticFile('narrator-01.mp4')}
style={{ width: 320, height: 180, objectFit: 'cover' }}
muted
/>
</Sequence>
항상 <OffthreadVideo>를 사용하고, 절대 <video>를 사용하지 마세요. Remotion은 프레임 정확한 렌더링을 위해 자체 컴포넌트가 필요합니다.
전환 효과
import { TransitionSeries, linearTiming } from '@remotion/transitions';
import { fade } from '@remotion/transitions/fade';
import { glitch } from '../../../lib/transitions/presentations/glitch';
import { lightLeak } from '../../../lib/transitions/presentations/light-leak';
lib/transitions 배럴에서 절대 임포트하지 마세요 — 사용자 정의 전환은 lib/transitions/presentations/에서 직접 임포트하세요.
오류 복구
| 문제 | 해결책 |
|---|---|
| 도구 명령 실패 "No module named..." | 툴킷 루트에서 pip3 install --break-system-packages -r tools/requirements.txt 실행 |
| "MODAL_*_ENDPOINT_URL not configured" | .env에 엔드포인트 URL이 있는지 확인. python3 tools/verify_setup.py 실행 |
| SadTalker 출력이 정사각형/잘림 | --preprocess full을 잊었습니다. 해당 플래그로 다시 실행 |
| 오디오가 장면에 비해 너무 짧거나 김 | 5단계(타이밍 동기화)를 다시 실행하고 설정 업데이트 |
npm run render 실패 | 프로젝트 디렉토리에 있는지 확인 (툴킷 루트가 아님). 먼저 npm install 실행 |
| Remotion에서 "Cannot find module" | Remotion 설정 및 가져오기 경로 확인 |