capcut-agent/SETUP.md

SETUP.md — 다른 PC 설치 · 환경 · 버전 명세

이 프로젝트(캡컷 에이전트 · 구간합치기 v2)를 다른 Windows PC에서 그대로 돌리기 위한 전체 스펙·버전 문서. 구현 세부는 ARCHITECTURE.md, 사용법은 README.md 참고. 아래 버전들은 현재 작동 중인 PC에서 실측한 값(2026-07 기준)이라, 이 조합이면 확실히 돕니다.

---

0. 30초 요약 체크리스트

다른 PC에서 이 6개만 맞추면 됩니다:

• Windows 10/11 (64-bit)
• Python 3.13 설치 + PATH 등록
• ffmpeg / ffprobe PATH 등록 (pip 아님)
• Node.js(또는 deno) PATH 등록 (yt-dlp JS 런타임)
• CapCut 설치 + (선택) 코트라 볼드체 1회 사용해 폰트 캐시 생성
• python -m pip install -r requirements.txt 실행

그다음 캡컷_에이전트_구간합치기.bat 더블클릭 → http://127.0.0.1:8001

---

1. 시스템 요구사항

항목	실측 버전	비고
OS	Windows 11 (10.0.26200)	Windows 10 64-bit 이상 권장. 콘솔 cp949라 한글 print 깨져 보여도 로직 무관
Python	3.13.0	3.10~3.13 범위면 대체로 OK. python.org 설치 시 "Add to PATH" 체크
아키텍처	x64	faster-whisper(ctranslate2)·onnxruntime가 x64 전제
디스크 여유	약 3~4GB	Whisper medium 모델(~1.5GB) + 패키지 + 다운로드 캐시
인터넷	최초 1회 필수	패키지·Whisper 모델·유튜브 다운로드에 필요

권장 사양 (쾌적하게 돌리려면)

병목은 자막 받아쓰기(ASR) 입니다. faster-whisper medium 모델을 CPU(int8) 로 돌리므로 CPU 성능·코어 수가 속도를 좌우합니다. (아래 GPU 항목 참고 — 현재 GPU는 안 씀.)

항목	최소	권장	비고
CPU	4코어	8코어 이상 (최신 Ryzen 5/7, Intel i5/i7)	ASR·ffmpeg 재인코딩이 CPU 바운드. 코어 많을수록 자막·병합 빠름
RAM	8GB	16GB	Whisper 모델 로드(~2~3GB) + ffmpeg 재인코딩 + 브라우저 동시
저장소	HDD 가능	SSD(NVMe 권장)	영상 재인코딩·프레임 추출 I/O가 많음. SSD면 체감 큰 차이
디스크 여유	4GB	10GB+	여러 영상 다운로드·ASR 캐시가 쌓임(.downloads .cache)
GPU	불필요	불필요	⚠ 현재 코드는 Whisper를 device="cpu" 로 고정 → GPU 있어도 이득 없음. CPU에 투자할 것
네트워크	—	안정적 유선/와이파이	유튜브 다운로드용. 구간 컷 속도는 회선보다 ffmpeg 8.0.1(§2-1)이 핵심

속도 감각: 붙여넣기 탭에서 ASR을 끄면 CPU 부담이 확 줄어 어떤 PC에서도 빠릅니다. 파일/유튜브 탭(자동 자막)은 CPU가 약하면 영상 길이에 비례해 ASR이 오래 걸립니다.

---

2. 시스템 의존성 (pip 아님 — 별도 설치 + PATH 필수)

이 3개는 파이썬 패키지가 아니라 OS에 따로 깔고 PATH에 잡혀야 합니다. 없으면 조용히 실패하거나 ffmpeg 크래시가 납니다.

2-1. ffmpeg / ffprobe ★필수 · ⭐버전 8.0.1 반드시 고정

항목	실측
버전	ffmpeg 8.0.1 (gyan.dev essentials_build) — ⭐이 버전으로 고정
확인	ffmpeg -version, ffprobe -version 둘 다 나와야 함

⚠️ 가장 중요 — 최신(8.1.x) 쓰지 말 것. ffmpeg 8.1.x는 --download-sections(유튜브 구간 컷) 경로에서 HTTP seek 회귀가 있어 10초 클립 다운로드가 90초+ 로 극단적으로 느려집니다. 8.0.1로 내리면 12~15초로 정상화. (전체 다운로드는 이 경로를 안 타서 멀쩡하므로, "일반 다운로드는 빠른데 구간 컷만 느리다"면 100% 이 문제입니다.)

• 다운로드(8.0.1 정확히): https://github.com/GyanD/codexffmpeg/releases/tag/8.0.1 → ffmpeg-8.0.1-essentials_build.7z
• 압축 해제 후 bin 폴더(= ffmpeg.exe, ffprobe.exe)를 시스템 PATH에 추가. 이미 8.1.x가 잡혀 있으면 그 경로를 지우고 8.0.1로 교체(또는 exe 2개 덮어쓰기).
• 터미널 새로 열고 ffmpeg -version이 8.0.1-essentials_build인지 확인.
• 용도: 구간 병합·재인코딩, 무음 감지, 장면분할, 오디오 추출, 프레임 추출.

속도 검증(셋업 후 10초 구간 컷이 몇 초 걸리는지):

yt-dlp --js-runtimes node --download-sections "*0:30-0:40" --force-keyframes-at-cuts -f "bv*[vcodec^=avc1]+ba[acodec^=mp4a]/b" --merge-output-format mp4 -o "%TEMP%/sec.%(ext)s" "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

→ 12~15초 = ✅ 정상 / 90초+ = ffmpeg가 아직 8.1.x (터미널 새로 열었는지 재확인).

2-2. JS 런타임 (Node.js 또는 deno) ★필수

항목	실측
Node.js	v22.17.0
deno	1.3.14 (있으면 우선 사용)

• 최신 유튜브는 JS 챌린지가 있어 런타임이 없으면 포맷 누락 → ffmpeg 크래시가 납니다.
• youtube.py가 deno → node → bun 순으로 자동 감지(--js-runtimes)하므로 셋 중 하나만 있으면 됨.
• 가장 쉬운 선택: Node.js LTS 설치 (https://nodejs.org) → node --version 확인.

2-3. CapCut ★필수

용도	필수 여부
드래프트 저장 위치 제공(%LOCALAPPDATA%/CapCut/...)	필수
완료 후 자동 열기(/open-capcut)	선택
코트라 볼드체 폰트 캐시	선택(없으면 기본 폰트로 안전 동작)

• CapCut 데스크톱(Windows) 설치. 드래프트는 아래 경로에 생성됨: %LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<드래프트명>\
• 폰트 캐시는 §6 참고.

---

3. Python 패키지 (pip)

3-1. 느슨한 설치 (requirements.txt — 최신으로 받음)

python -m pip install -r requirements.txt

requirements.txt 내용:

fastapi
uvicorn
python-multipart
pyCapCut
Pillow
pymediainfo
yt-dlp
faster-whisper

3-2. 버전 고정 (재현성 100% — 이 조합이 실제로 도는 버전)

다른 PC에서 최신 버전 충돌이 걱정되면 아래를 requirements.lock.txt로 저장해 python -m pip install -r requirements.lock.txt 로 설치하세요.

# ── 직접 의존성 ──────────────────────────────
fastapi==0.115.14
uvicorn==0.35.0
python-multipart==0.0.20
pyCapCut==0.0.3            # import 이름은 pycapcut
Pillow==10.4.0
pymediainfo==7.0.1
yt-dlp==2026.7.4
faster-whisper==1.2.1

# ── faster-whisper / fastapi 전이 의존성(자동 설치되지만 버전 고정용) ──
av==16.0.1
ctranslate2==4.6.2
onnxruntime==1.23.2
tokenizers==0.21.2
huggingface-hub==0.33.4
numpy==2.2.0
starlette==0.46.2
pydantic==2.11.7

참고

• yt-dlp는 pip로 깔면 yt-dlp 콘솔 스크립트가 PATH에 생겨 코드가 subprocess로 호출합니다. (유튜브는 자주 막히니 주기적으로 python -m pip install -U yt-dlp 업데이트 권장 — 버전 고정하지 말 것.)
• SSE(진행상황 스트림)는 FastAPI 내장 StreamingResponse 사용 → sse-starlette 불필요.
• Gemini 교정은 표준 라이브러리 urllib로 REST 직접 호출 → google-generativeai 패키지 불필요.
• pymediainfo는 내부적으로 MediaInfo DLL을 씀. 대개 wheel에 포함되나, 안 되면 https://mediaarea.net/en/MediaInfo 의 DLL을 PATH에 두면 됨.

---

4. 자동 다운로드되는 모델 (faster-whisper)

파일/유튜브 탭에서 자막 받아쓰기(ASR) 를 처음 실행할 때, HuggingFace에서 자동 다운로드됩니다.

항목	값
모델	Systran/faster-whisper-medium
크기	약 1.5GB
설정	medium / compute_type=int8 / device=cpu / 언어 ko
캐시 위치	%USERPROFILE%\.cache\huggingface\hub\models--Systran--faster-whisper-medium
ASR 결과 캐시	프로젝트 .cache\ (content-hash 기준)

• 최초 1회 인터넷 필요. 이후 오프라인 동작.
• 붙여넣기 탭만 쓰고 ASR(하단자막 자동생성)을 끄면 이 모델은 안 받아도 됨.
• 미리 받아두려면 아무 영상이나 파일 탭에 한 번 돌리면 캐시됨. (또는 다른 PC의 위 캐시 폴더를 통째로 복사해도 됨.)

---

5. (선택) Gemini 자막 글자 교정

자막 글자만 1:1 교정(시간 불변). 키 없으면 자동 스킵(Whisper 원문 유지)이라 필수는 아님.

항목	값
모델	gemini-2.5-flash (무료 티어 지원)
호출	REST(generativelanguage.googleapis.com) via urllib — 추가 패키지 없음
키 주입 방법 (둘 중 하나)	① 프로젝트 루트에 .gemini_key 파일(키 한 줄) ② 환경변수 GEMINI_API_KEY 또는 GOOGLE_API_KEY

• 키 발급: https://aistudio.google.com → API key
• 429(무료 한도 초과) 시 Whisper 원문으로 폴백.

---

6. 코트라 볼드체 폰트 (선택, 있으면 예쁨)

pycapcut FontType에 없어 저장 후 draft_content.json에 폰트 경로를 직접 주입합니다.

항목	값
캐시 경로	%LOCALAPPDATA%\CapCut\User Data\Cache\effect\7480846567709265157\782a91b14f1661b95e7e587be27f1af4\font.ttf
크기	약 642KB
경로 성격	PC 무관(CapCut 전역 폰트 ID라 어느 PC든 동일 경로)

• 이 파일이 있어야 자막/제목이 코트라 볼드체로 나옴. 없으면 주입을 자동 생략 → CapCut 기본 폰트로 안전 동작(에러 아님).
• 다른 PC에서 만들려면: 그 PC의 CapCut에서 코트라 볼드체를 한 번 사용(아무 텍스트에 적용)하면 캐시가 생성됨. 또는 위 font.ttf를 같은 경로에 복사.

---

7. 다른 PC 설치 순서 (처음부터)

# 1) Python 3.13 설치 (python.org, "Add Python to PATH" 체크)  → 확인
python --version

# 2) ffmpeg 설치 후 bin 폴더를 PATH 등록  → 확인
ffmpeg -version
ffprobe -version

# 3) Node.js LTS 설치  → 확인
node --version

# 4) CapCut 설치 (그리고 원하면 코트라 볼드체 1회 사용)

# 5) 프로젝트 폴더 통째로 복사한 뒤, 그 폴더에서:
python -m pip install -r requirements.txt

# 6) (선택) Gemini 키
#    .gemini_key 파일에 키 한 줄 저장  또는  환경변수 GEMINI_API_KEY 설정

# 7) 실행
캡컷_에이전트_구간합치기.bat

폴더를 복사할 때 .cache/, .downloads/ 같은 대용량 파생물은 빼도 됨(자동 재생성). .gemini_key는 개인 키라 공유 주의.

---

8. 실행 · 포트

항목	값
런처	캡컷_에이전트_구간합치기.bat (브라우저 자동 오픈)
직접 실행	python -m uvicorn server.app:app --port 8001
주소	http://127.0.0.1:8001
포트	8001 (형제 앱 v1 ../capcut은 8000 — 동시 실행 가능)

⚠️ 코드 수정 후엔 반드시 검은 창 닫고 .bat 재실행. uvicorn hot-reload 안 됨(가장 흔한 "안 돼요" 원인).

---

9. 설치 검증

# 파이썬 임포트 체인 확인 (에러 없이 통과해야 함)
python -c "from server import app; print('app OK')"
python -c "from capcut_agent import pipeline, draft, youtube, transcribe, correct; print('modules OK')"

# 외부 도구 확인
ffmpeg -version | head -1
node --version
yt-dlp --version

최종 검증은 실제로 짧은 유튜브 구간 하나를 돌려 CapCut에서 드래프트가 열리는지 확인.

---

10. 문제 해결 (다른 PC 이식 시 흔한 것)

증상	원인	해결
ffmpeg/ffprobe not found	PATH 미등록	ffmpeg bin을 시스템 PATH에 추가, 창 새로 열기
유튜브 다운로드가 ffmpeg 크래시(exit 3436169992)	JS 런타임 없음	Node.js 또는 deno 설치
"Video unavailable"	영상 자체 없음/지역제한	curl "https://www.youtube.com/oembed?url=<URL>&format=json" 404면 영상 문제
유튜브가 갑자기 다 실패	yt-dlp 구버전	python -m pip install -U yt-dlp
자막이 기본 폰트로 나옴	코트라 볼드체 캐시 없음	§6 — CapCut에서 1회 사용 or font.ttf 복사 (없어도 동작은 함)
ASR 첫 실행이 매우 느림/멈춘 듯	Whisper medium(1.5GB) 다운로드 중	최초 1회. 인터넷 확인, 기다리기
자막 교정이 안 됨	Gemini 키 없음/429	선택 기능. 없으면 Whisper 원문 사용(정상)
병합 시 Invalid argument(exit 4294967274)	(해결됨) 한글 경로 concat 버그	최신 youtube.py면 ASCII 임시링크로 자동 우회
드래프트 열면 영상이 흰띠·댓글 위로 삐짐	CapCut 편집 중 render_index 꼬임	최신 draft.py는 오버레이/제목 트랙 자동 잠금으로 예방
클립을 옮긴 뒤 확대하면 그 클립만 템플릿 밖으로 삐짐	CapCut이 옮긴 클립에 렌더순서를 새로(맨 위로) 매김 — 잠금으로 못 막음	캡컷에서 그 프로젝트를 닫고 → 웹 UI 하단 "🩹 레이어 수리" → 드래프트 선택 → 실행 → 캡컷에서 다시 열기
영상 중간에 초록 화면이 몇 초 나옴	yt-dlp가 키프레임 아닌 위치에서 잘라 참조 프레임이 없음	최신 youtube.py가 컷마다 자동 검증→재다운로드→정밀 재컷. 로그에 🩹 표시. 예전에 받은 영상은 다시 만들어야 함
컷 섹션에 🤖 배지가 하나도 없다 (⭐만 있거나 비어 있음)	Gemini 추천 실패 — 한도 초과(429)·타임아웃·응답 파싱. 컷 섹션 자체는 타임스탬프만으로 그대로 뜬다	분석 로그(진행 화면 아래)에 ⚠️ ID n AI 추천 실패 — 타임스탬프만으로 배정했습니다 가 있는지 확인. 한도 초과면 잠시 뒤 재분석. 프롬프트/댓글_추천.md를 고쳤다면 {cuts} {comments} {k} 가 남아 있는지 확인
컷 섹션이 아예 안 보이고 ⭐ + ➕ 두 덩어리만 뜬다	편집안에 컷 정보가 없어(hl.cuts 없음) 예전 화면으로 폴백	편집안 생성(Step 3)이 실패한 ID다. 로그에서 그 ID의 실패 사유 확인. 이 화면에서 고른 카드는 컷 배치 없이 전체 균등으로 깔린다
댓글이 엉뚱한 장면에 뜬다	컷 소속 없이 전체 균등 배치로 깔림(위 폴백 화면) 또는 추천 자체가 안 맞음	위 두 줄 확인. 컷 섹션이 보인다면 그 컷 섹션 안에서 카드를 갈아끼우면 그 컷 위로 옮겨진다
"컷별 댓글 추천"에서 오래 멈춰 보인다	하이라이트마다 Gemini 를 순차로 부른다(429 회피). 최악 5×90초	새로고침하지 말 것 — 분석이 통째로 날아간다. 로그에 ID n 컷별 댓글 추천 중… (i/N) 이 올라오면 정상 진행 중
콘솔에 한글 깨짐	Windows cp949	표시만 깨짐. 로직·결과와 무관

---

11. 한눈에 보는 버전 표 (복붙용)

OS              Windows 11 (10.0.26200), x64
Python          3.13.0
ffmpeg/ffprobe  8.0.1 (gyan.dev essentials)
Node.js         22.17.0   (또는 deno 1.3.14)
CapCut          데스크톱(Windows)

fastapi         0.115.14
uvicorn         0.35.0
python-multipart 0.0.20
pyCapCut        0.0.3   (import pycapcut)
Pillow          10.4.0
pymediainfo     7.0.1
yt-dlp          2026.7.4  (최신 유지 권장)
faster-whisper  1.2.1
  ├ av          16.0.1
  ├ ctranslate2 4.6.2
  ├ onnxruntime 1.23.2
  ├ tokenizers  0.21.2
  ├ huggingface-hub 0.33.4
  └ numpy       2.2.0
starlette       0.46.2
pydantic        2.11.7

ASR 모델        Systran/faster-whisper-medium (~1.5GB, int8/cpu)
Gemini(선택)    gemini-2.5-flash (REST/urllib, 키 선택)
포트            8001