자주 부딪히는 증상

영상을 만드는 동안 흔히 부딪히는 증상을 모았습니다. 외부 도구가 많은 제품이라 설치 단계에서 막히는 경우가 잦습니다. 증상으로 찾아 해당 항목만 보면 됩니다.

설치와 환경

”command not found: ffmpeg”

ffmpeg가 설치되지 않은 상태입니다. macOS는 brew install ffmpeg로, Linux와 WSL2는 sudo apt install -y ffmpeg로 설치합니다. 설치한 다음 ffmpeg -version으로 확인합니다.

OPENAI_API_KEY가 잡히지 않음

echo $OPENAI_API_KEY로 확인합니다. 빈 값이면 셸 시작 파일(~/.zshrc 등)에 export OPENAI_API_KEY="sk-..."를 넣고 새 터미널을 엽니다. .env에만 적어 두면 셸에서 잡히지 않을 수 있습니다.

”command not found: codex”

생성형 트랙에 필요한 Codex CLI가 설치되지 않은 상태입니다. OpenAI Codex CLI 공식 안내를 따라 설치합니다. 리믹스만 쓸 예정이면 codex 없이도 됩니다.

리믹스 도구

yt-dlp 다운로드 실패

원본 URL을 받지 못하는 경우입니다. yt-dlp --version으로 설치를 확인하고, URL이 지원되는 플랫폼(youtube, tiktok, instagram, vimeo, x 등)인지 확인합니다. yt-dlp가 오래된 버전이면 플랫폼 변경을 따라가지 못할 수 있으니 최신 버전으로 갱신합니다.

Whisper 모델이 없음

whisper-cli를 쓰는데 로컬 모델이 없으면 전사가 진행되지 않습니다. ~/.whisper/models/에 모델 파일을 내려받거나, whisper-cli 없이 OPENAI_API_KEY를 쓰는 Whisper API로 대체되도록 둡니다. prerequisites의 리믹스 항목에 모델을 내려받는 명령이 있습니다.

라이선스 게이트

리믹스가 라이선스 라벨이 없다며 멈춤

의도된 정지입니다. 원본 라이선스가 불명확한 상태입니다. 라이선스가 명확한 원본으로 바꾸거나, 명시적으로 책임을 수락합니다. 자세한 설명은 when-ai-gets-stuck에 있습니다.

영상 전환

엉뚱한 영상을 작업하고 있음

활성 영상(active_slug)이 의도와 다른 영상을 가리키는 상태입니다. “지금 어느 영상 작업 중이야?”라고 물어 확인하고, “영상 X로 이어서”라고 말해 옮깁니다.

이미지와 속도

캐릭터가 장면마다 다른 얼굴로 나옴

캐릭터 시트가 만들어지지 않은 상태입니다. “이 캐릭터 시트 먼저 만들어줘”라고 말해 시트를 만든 다음 다시 생성합니다. when-ai-gets-stuck의 이미지 항목을 함께 봅니다.

영상 생성이 너무 느림

final 모드로 실행되고 있을 수 있습니다. “preview로 돌려줘”라고 말해 빠른 모드로 돌아갑니다. REPLICATE_API_TOKEN을 설정하면 preview 이미지가 더 빨라집니다.

”Permission denied” 스크립트 실행 에러

스크립트에 실행 권한이 없는 상태입니다. chmod +x로 권한을 준 다음 다시 시도합니다.

그래도 안 풀리면

GitHub 이슈를 열거나 팀 Slack에 올립니다. 세 가지를 같이 적습니다.

• 어디서 막혔는지 적습니다 (어느 트랙, 어느 게이트).
• 에러 메시지 전체를 붙여 넣습니다.
• 환경 정보를 적습니다 (운영체제, ffmpeg 버전).