사전 준비

이 단계는 한 번만 하면 됩니다. scene-studio는 외부 도구 의존이 가장 많은 제품이라, 이 단계가 다른 base보다 무겁습니다. 다만 본인이 쓸 트랙에 맞는 도구만 깔면 되니, 트랙부터 정하고 시작하면 가벼워집니다.

어느 트랙을 쓰나

먼저 본인이 쓸 트랙을 정합니다. 설치할 도구가 달라집니다.

생성형만 — ffmpeg, OPENAI_API_KEY, codex CLI
리믹스만 — ffmpeg, OPENAI_API_KEY, yt-dlp, whisper-cli(선택)
둘 다 — 위 전부

결정이 안 서면 둘 다 깔아도 됩니다. 다만 안 쓰는 트랙 도구는 나중에 그 트랙을 시작할 때 깔아도 늦지 않습니다.

운영체제별 차이

항목	macOS	Windows	Linux
사용하는 터미널	`Terminal.app` 또는 iTerm2	WSL2 위의 Ubuntu 권장	배포판이 제공하는 셸
검증 상태	검증됨	WSL2 먼저 깐 다음 그 안에서 모든 명령 실행	검증됨

Windows에서는 WSL2 설치 안내를 먼저 끝낸 다음 이쪽으로 돌아오세요.

1) ffmpeg — 두 트랙 공통

영상 합성에 쓰는 핵심 도구입니다. 두 트랙 다 필요합니다.

# macOS
brew install ffmpeg

# Linux와 WSL2
sudo apt update && sudo apt install -y ffmpeg

설치 검증

ffmpeg -version    # ffmpeg version ... 줄이 뜨면 정상

2) OPENAI_API_KEY — 두 트랙 공통

Codex 이미지 생성과 Whisper API에 씁니다. .env에 박지 말고 셸 시작 파일(~/.zshrc 등)에 export하거나, .env로 두되 git 추적에서 빠지게 합니다.

export OPENAI_API_KEY="sk-..."

이 줄을 ~/.zshrc에 넣고 새 터미널을 열면 다음부터 자동으로 잡힙니다.

3) 생성형 트랙 — codex CLI

생성형 트랙의 이미지 생성에 OpenAI Codex CLI가 필요합니다. 없으면 생성형 진입이 막힙니다. 설치 안내는 OpenAI Codex CLI 공식 문서를 따릅니다.

codex --version    # 버전이 뜨면 정상

REPLICATE_API_TOKEN과 FAL_KEY는 선택입니다. preview 모드의 빠른 이미지 백엔드용이라, 없으면 codex만 써서 조금 느립니다.

4) 리믹스 트랙 — yt-dlp와 whisper

리믹스 트랙은 원본 영상을 받고 전사합니다.

# yt-dlp (원본 다운로드)
brew install yt-dlp          # macOS
# Linux: pip install yt-dlp 또는 패키지 매니저

# whisper-cli (선택, 로컬 전사)
brew install whisper-cpp     # macOS, M 시리즈에서 빠름

whisper-cli가 없으면 OPENAI_API_KEY의 Whisper API로 폴백합니다. 로컬 모델을 쓰려면 모델 파일을 한 번 받습니다.

mkdir -p ~/.whisper/models
curl -L -o ~/.whisper/models/ggml-base.en.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin

5) Claude Code

공식 설치 안내는 docs.claude.com/ko/docs/claude-code/quickstart에 있습니다.

claude --version    # 버전 번호가 뜨면 준비 완료

Claude Code 대신 OpenAI Codex CLI를 진입점으로 써도 됩니다. 그 경우 저장소 루트의 AGENTS.md가 진입점입니다.

6) 폰트는 선택

자막에 한국어는 Pretendard, 영문은 Inter를 씁니다. 미설치 시 sans-serif로 자동 폴백되니 꼭 깔 필요는 없습니다. 자막을 깔끔하게 가려면 두 폰트를 시스템에 설치합니다.

본인 트랙에 맞는 도구가 자리를 잡았다면 clone-and-install로 갑니다.