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는 관리형 Python(PEP 668)이 있는 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(단어_수 / 2.5) + 2로 추정합니다. 4단계에서 오디오를 생성한 후 이를 조정합니다.
3단계: 음성 대본 작성
projects/PROJECT_NAME/VOICEOVER-SCRIPT.md 생성:
## 장면 1: 제목 (9초, ~17단어)
AI로 동영상을 제작하세요. 제품 이름 툴킷이 쉽게 만들어줍니다.
## 장면 2: 문제 (14초, ~30단어)
문제 설명이 여기에 옵니다. 간결하고 공감되게 작성하세요.
장면당 단어 예산: (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 "1장의 음성 해설 텍스트입니다." \
--speaker Ryan --tone warm \
--output projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
--cloud modal
# 장면 02
python3 tools/qwen3_tts.py \
--text "2장의 음성 해설 텍스트입니다." \
--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에서 후속 클립은 더 빠릅니다.
- 생성된 오디오는 주변 음향(ambient)만 해당됩니다. 음성 및 음악은 음성 해설/음악 도구를 사용하세요.
- 생성물의 약 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)
4f. 이미지 편집 (선택 사항)
기존 이미지에서 장면 변형을 만듭니다:
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
4g. 업스케일링 (선택 사항)
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(실제_오디오_길이 + 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} = 30프레임 = 1초 at 30fps):
<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" | npm install이 올바른지 확인하거나 Remotion 패키지를 다시 설치 |