capcut-agent/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

이 프로젝트가 하는 일

유튜브 영상(URL/파일/LLM 편집안 JSON) → 다운로드·컷·자막·배경 템플릿을 자동 조립해 편집 가능한 CapCut 드래프트(draft_content.json)를 로컬 CapCut 프로젝트 폴더에 생성하는 FastAPI + 정적 HTML 로컬 웹앱. 포트 8001 (형제 앱 v1 ../capcut은 8000, 완전히 별개 코드베이스).

먼저 읽어야 할 문서

이 저장소에는 이미 깊은 명세 문서가 있다. 코드를 건드리기 전에 반드시 참고:

• ARCHITECTURE.md — 전체 구현 명세(좌표계, 파이프라인 단계별 동작, 드래프트 빌더 내부, yt-dlp 함정, 고정값 치트시트, "하지 말 것" 목록). 가장 정확하고 깊은 문서.
• README.md — 사용자용 요약, 붙여넣기 JSON 스키마, 다른 PC 설치법, 문제 해결표.

CLAUDE.md는 위 두 문서와 중복하지 않는다. 세부는 그쪽을 볼 것.

실행 / 개발 명령

# 서버 실행 (Windows 런처 — 브라우저 자동 오픈, 포트 8001)
캡컷_에이전트_구간합치기.bat

# 런처 없이 직접 실행
python -m uvicorn server.app:app --port 8001

# 의존성 설치
python -m pip install -r requirements.txt

# 파이썬 구문 검증 (수정 후 습관)
python -c "import ast; ast.parse(open('capcut_agent/pipeline.py', encoding='utf-8').read())"
python -c "from server import app"   # 임포트 체인 확인

시스템 의존성(pip 아님, PATH 필요): ffmpeg/ffprobe, Node.js 또는 deno(yt-dlp JS 런타임), CapCut(드래프트 열기 + 코트라 볼드체 폰트 캐시).

⚠️ 가장 중요한 규칙: 코드 수정 후 .bat 재시작 필수

파이썬 코드가 uvicorn 서버에 물려 있어 hot-reload 안 됨. 코드를 고쳤으면 반드시 검은 창을 닫고 .bat을 다시 실행해야 반영된다. 이것을 잊는 게 "안 돼요"의 가장 흔한 원인.

아키텍처 큰 그림

요청은 세 탭(파일 / 유튜브 구간 / 붙여넣기)에서 들어와 두 파이프라인 중 하나로 갈린다:

• server/app.py — FastAPI. 엔드포인트 4개(/upload /youtube /paste /open-capcut) + SSE 스트림(/stream/{job_id}). job은 메모리 dict JOBS[hash]에 저장(서버 재시작 시 소실). 폼 필드 → 파이프라인 인자 변환 담당.
• server/static/index.html — UI 전체(단일 파일, 탭 3개 + 옵션 + SSE 렌더).
• capcut_agent/pipeline.py — ★ 진입점 두 개:
  • process_bg_template() — 파일/유튜브 탭. download → silence → asr → [scene] → draft
  • process_paste() — 붙여넣기 탭. download(정밀 컷) → [remove_silence] → [asr_bottom] → [scene] → draft
• capcut_agent/draft.py — ★ build_bg_template_draft. pycapcut으로 드래프트 생성 후 draft_content.json을 직접 후처리(폰트·그림자 주입 등).
• 나머지 capcut_agent/*.py — youtube(다운로드/병합), paste(관대한 JSON 파서), silence, transcribe(faster-whisper), correct(Gemini 교정), scene, media, probe. 역할은 ARCHITECTURE.md §1.

절대 되돌리면 안 되는 핵심 설계 결정

• 자막 타이밍 = Whisper 단어 타임스탬프, 글자만 = Gemini 제자리 교정(시간 불변). 과거에 Gemini 오디오 전사 타임스탬프를 직접 쓰거나 글자수 기반 정렬을 시도했다가 누적 드리프트로 자막이 밀렸다. Gemini는 글자만 1:1 교정, 줄 수·순서·시간은 절대 건드리지 않는다.
• 붙여넣기 탭은 배치 시간을 입력받지 않는다 — 컷 순서대로 누적 자동 계산(LLM이 계산하면 오타).
• 같은 텍스트 트랙에 동시간 세그먼트 2개 금지 — CapCut SegmentOverlap 에러.
• 정답 파일은 draft_content.json (draft_info.json 아님).

좌표계 (draft.py 작업 시)

CapCut Y = transform_y × 1920 (canvas 1080×1920, 위가 +/아래가 −). 헬퍼 _ty(y_px) = (960 - y_px)/960. 확대(%) = scale 비율. 사용자가 "위치 −559로" 라고 하면 transform_y로 환산해 반영. 고정값은 ARCHITECTURE.md §9 치트시트.

검증 방식

이 프로젝트에 자동 테스트 스위트는 없다. 검증은:

1. 구문 파싱 + 임포트 체인 확인(위 명령).
2. 가능하면 실제 드래프트를 빌드해 draft_content.json 값을 열어 확인(테스트 드래프트는 확인 후 삭제).
3. 최종적으로 사용자가 CapCut에서 열어 확인.

테스트용 영상이 필요하면 .downloads/의 기존 mp4 재사용(네트워크 불필요). Windows 콘솔은 cp949라 한글/특수문자 print가 깨져 보일 수 있음(로직과 무관).