자주 막히는 자리

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

설치와 환경

”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 버전)