# 캡컷 에이전트 · 구간합치기 (v2)

유튜브 영상 → **무음컷 · 자막 · 배경 템플릿**이 박힌 **편집 가능한 CapCut 드래프트**를 자동 생성하는 로컬 웹앱.
특히 **한 URL의 여러 구간을 이어붙이고**, LLM이 만든 편집안(컷+자막)을 **JSON 붙여넣기**로 한 번에 처리합니다.

---

## 1. 처음 실행 (이 PC)

1. `캡컷_에이전트_구간합치기.bat` 더블클릭
2. 잠시 후 브라우저가 http://127.0.0.1:8001 로 자동으로 열림
3. **이 검은 창은 켜두세요** (닫으면 서버가 꺼짐)

> 코드를 수정했으면 **반드시 창을 닫고 .bat 을 다시 실행**해야 반영됩니다.

---

## 2. 세 가지 입력 방법 (탭)

### 📋 붙여넣기 (기본 탭) — 추천
LLM이 만든 편집안 JSON을 붙여넣으면 컷·자막을 **그대로** 사용합니다. (무음컷·받아쓰기 없음)

### ▶ 유튜브 구간
한 URL + 여러 구간(＋ 구간 추가) → 이어붙여 **무음컷 + 자동 자막(Whisper)**.

### 📁 파일
로컬 영상 파일 → **무음컷 + 자동 자막**.

세 방법 모두 아래 **영상 옵션**을 함께 적용합니다.

---

## 3. 붙여넣기 JSON 형식 (핵심)

아래 **JSON 하나**만 붙여넣으면 됩니다. 배치 시간·SRT 타임코드는 **넣지 마세요** — 앱이 컷을 순서대로 이어붙이며 자동 계산합니다.

```json
{
  "url": "https://www.youtube.com/watch?v=영상ID",
  "title_top": "서브제목",
  "title_main": "메인제목",
  "channel": "@채널명",
  "cuts": [
    {"start":"0:01.0","end":"0:03.5","bottom":"하단 자막 윗줄\n하단 자막 아랫줄","effect":"효과자막"},
    {"start":"2:33.5","end":"2:36.5","bottom":"다음 컷 자막","effect":"공포의통계"}
  ]
}
```

| 필드 | 설명 |
|------|------|
| `url` | **실제 영상 주소** (브라우저에서 열리는 것). LLM이 지어낸 가짜 ID 금지 |
| `cuts[].start` / `end` | 원본 영상 타임스탬프. `분:초.밀리` 또는 `시:분:초.밀리` (밀리초 생략 가능) |
| `cuts[].bottom` | 하단 자막. `\n` 이 있으면 **같은 자리에서 시간을 반씩 나눠** 윗줄→아랫줄 순서로 표시 |
| `cuts[].effect` | 중앙 효과 자막(녹색). 짧게 |
| `title_top` / `title_main` / `channel` | 선택. 비우면 안 들어감(채널은 유튜브에서 자동) |

### LLM 에게 요청할 때 (이대로 복사)

> 아래 스키마의 **JSON 하나로만** 출력해. 설명·마크다운 금지.
> - `url` 은 내가 준 이 주소를 **그대로** 써라(임의 생성 금지): `여기에_실제_URL`
> - `start`/`end` 는 원본 영상 타임스탬프(`분:초.밀리`).
> - **배치 시간은 계산하지 마라.** 앱이 순서대로 이어붙인다.
> - `bottom` 은 2줄(`\n`), `effect` 는 짧은 한 마디.
> - 모든 컷은 `start < end`.

> 💡 자막이 안 쪼개지고 `\n` 글자가 그대로 보여도 앱이 알아서 처리합니다(`\n`·`\\n` 모두 인식).

---

## 4. 영상 옵션 (공통)

- **영상 확대** — 기본 144%. 슬라이더로 조절(캡컷에서 다시 조정 가능)
- **좌우반전(미러)** — 영상만 좌우 뒤집기
- **장면분할** — 화면이 확 바뀌는 지점마다 컷 자동 분할(캡컷에서 개별 편집 가능). 시간이 더 걸림
- **완료되면 CapCut 자동 실행** — 체크 시 결과 후 캡컷 자동 오픈

자막 위치·색은 코드 기본값(하단자막 CapCut Y=-559, 효과자막 Y=866·녹색 `#0dff63`).

---

## 5. 다른 PC 에서 실행

이 `capcut2` 폴더를 통째로 복사한 뒤(`.downloads`·`.cache`·`.uploads` 캐시는 빼도 됨 — 자동 생성):

1. **Python 3.10+** 설치 — https://python.org (설치 시 **Add to PATH** 체크)
2. 이 폴더에서 패키지 설치:
   ```
   python -m pip install -r requirements.txt
   ```
3. **ffmpeg / ffprobe** 설치(PATH 필요) — `winget install Gyan.FFmpeg`
4. **Node.js** 설치 — https://nodejs.org (yt-dlp 유튜브 추출용 JS 런타임)
5. **CapCut** 설치
6. `캡컷_에이전트_구간합치기.bat` 실행

> **코트라 볼드체**: 새 PC의 CapCut 에서 그 폰트를 한 번 사용하면 캐시가 생겨 자동 적용됩니다. 없으면 기본 폰트로 나옵니다(에러 아님).
> **드래프트 저장 위치**: 그 PC의 CapCut 프로젝트 폴더를 자동 인식합니다.
> **.gemini_key**: '파일'·'유튜브 구간' 탭 자막 교정용. 붙여넣기 탭만 쓰면 없어도 됩니다.

---

## 6. 문제 해결

| 증상 | 해결 |
|------|------|
| 수정한 게 반영 안 됨 | 검은 창 닫고 **.bat 재시작** |
| `python not found` | Python 재설치 시 PATH 체크 후 재부팅 |
| 유튜브 `Video unavailable` | 영상이 실제 공개인지 확인 → `python -m pip install -U yt-dlp` |
| 다운로드가 자꾸 깨짐 | `python -m pip install -U yt-dlp` (유튜브가 가끔 바뀜) |
| 자막이 밀림 | 붙여넣기 탭은 컷·자막을 그대로 쓰므로 안 밀림. 파일/유튜브 탭은 Whisper 타이밍 사용 |
| 자막 `\n` 이 글자로 박힘 | .bat 재시작하면 해결(앱이 `\n`·`\\n` 자동 분할) |
| 폰트가 다르게 나옴 | CapCut 에서 코트라 볼드체 한 번 사용해 캐시 생성 |

---

## 7. 폴더 구조 (참고)

```
capcut2/
├─ 캡컷_에이전트_구간합치기.bat   실행 파일(포트 8001)
├─ 배경.png                      배경 템플릿(검정-흰-검정)
├─ requirements.txt              파이썬 패키지 목록
├─ .gemini_key                   (선택) Gemini 키
├─ server/
│  ├─ app.py                     FastAPI 서버 (/upload /youtube /paste /stream)
│  └─ static/index.html          웹 UI
└─ capcut_agent/
   ├─ pipeline.py                처리 파이프라인(다운로드→컷→자막→드래프트)
   ├─ youtube.py                 유튜브 구간/다중/정밀 다운로드·병합
   ├─ paste.py                   붙여넣기 JSON 파서
   ├─ draft.py                   CapCut 드래프트 생성(pycapcut)
   ├─ scene.py                   장면전환 감지·분할
   ├─ silence.py                 무음 감지
   ├─ transcribe.py              Whisper 받아쓰기(파일/유튜브 탭)
   ├─ correct.py                 Gemini 자막 교정(선택)
   ├─ highlight.py               자막 청킹
   ├─ media.py                   프레임/오디오 처리
   └─ probe.py                   영상 메타 조회
```