# Task: 음성 타이밍 기반 숏폼 영상 생성 모듈

## Task ID: task-350-p2
## Project: ThreadAuto (`/home/jay/projects/ThreadAuto/`)
## Priority: HIGH
## Phase: 2/3 (Phase 1 Edge TTS 완료)

---

## 배경
Phase 1에서 Edge TTS 2인 대화 합성 모듈이 완성됨 (`audio/edge_tts_dialogue.py`).
이제 생성된 음성에 맞춰 텍스트 슬라이드가 표시되는 숏폼 영상(MP4)을 만드는 모듈이 필요하다.

## 기존 코드 참조
- Edge TTS 모듈: `audio/edge_tts_dialogue.py` — `synthesize_dialogue()` 함수
- edge-tts는 자막 타임스탬프(SubMaker)를 지원함. 이를 활용할 것.

## 목표
음성 + 텍스트 슬라이드 → MP4 숏폼 영상 자동 생성 모듈을 개발한다.

## 상세 요구사항

### 1. 모듈 위치
- `/home/jay/projects/ThreadAuto/pipeline/video_composer.py`

### 2. 핵심 기능

#### 2-1. 자막/타이밍 추출
- edge-tts의 SubMaker를 활용하여 각 문장/단어의 시작-종료 타이밍을 추출
- 또는 각 화자별 TTS 파일의 duration을 pydub으로 측정하여 타이밍 계산
- 출력: `[{"speaker": "호스트", "text": "...", "start_ms": 0, "end_ms": 3500}, ...]`

#### 2-2. 텍스트 슬라이드 이미지 생성
- 각 발화 구간에 표시할 텍스트 슬라이드를 이미지로 생성 (Pillow 사용)
- 세로형 (1080x1920) — Threads/Instagram Reels 숏폼 규격
- 디자인:
  - 배경: 단색 또는 그라디언트 (파라미터화)
  - 화자 이름 표시 (상단)
  - 핵심 텍스트 큰 글씨 (중앙)
  - 폰트: NotoSansCJKkr (서버에 설치됨: `~/.local/share/fonts/NotoSansCJKkr-Regular.otf`, `NotoSansCJKkr-Bold.otf`)
- 텍스트가 길면 자동 줄바꿈

#### 2-3. MP4 영상 합성
- ffmpeg를 사용하여 이미지 시퀀스 + 음성 → MP4 합성
- 각 슬라이드의 표시 시간 = 해당 발화의 duration
- 출력: H.264 MP4, AAC 오디오

### 3. 인터페이스
```python
async def compose_video(
    script: list[dict],        # [{"speaker": "호스트", "text": "...", "start_ms": 0, "end_ms": 3500}, ...]
    audio_path: str,           # 합성된 대화 음성 MP3 경로
    output_path: str,          # 출력 MP4 경로
    width: int = 1080,
    height: int = 1920,
    bg_color: str = "#1a1a2e", # 배경색
    host_color: str = "#e94560",    # 호스트 강조색
    guest_color: str = "#0f3460",   # 게스트 강조색
    font_size: int = 60,
) -> str:  # returns output file path
```

### 4. 통합 파이프라인 함수
- `audio/edge_tts_dialogue.py`의 synthesize_dialogue와 video_composer를 한번에 실행하는 통합 함수
```python
async def create_dialogue_video(
    script_text: str,          # 평문 대화 대본
    output_path: str,          # 출력 MP4 경로
    **kwargs,
) -> str:
    # 1. 대본 파싱
    # 2. Edge TTS 음성 합성 (+ 타이밍 추출)
    # 3. 슬라이드 이미지 생성
    # 4. MP4 합성
```

### 5. CLI 진입점
- `python -m pipeline.video_composer --script <text_file> --output <output.mp4>`
- `--audio <audio.mp3>` 기존 오디오 사용 옵션

### 6. 테스트
- `pipeline/tests/test_video_composer.py`
- 슬라이드 이미지 생성 테스트
- 타이밍 계산 테스트
- 전체 파이프라인 통합 테스트 (짧은 2턴 대화 → MP4)

## 기술 스택
- Pillow (이미지 생성) — 필요 시 설치
- ffmpeg (`/home/jay/.local/bin/ffmpeg` 또는 시스템 ffmpeg)
- pydub (duration 측정)
- edge-tts SubMaker (타이밍 추출, 선택)

## 한글 폰트 경로
- Regular: `~/.local/share/fonts/NotoSansCJKkr-Regular.otf`
- Bold: `~/.local/share/fonts/NotoSansCJKkr-Bold.otf`

## 품질 기준
- pyright 타입 체크 에러 0건
- 테스트 전체 PASS
- 실제 보험 대화 샘플로 MP4 생성 확인
- 영상 길이 = 오디오 길이 (동기화 확인)

## 완료 조건
1. `pipeline/video_composer.py` 모듈 완성
2. 통합 파이프라인 함수 동작
3. CLI 실행 가능
4. 테스트 코드 작성 + PASS
5. 보험 대화 샘플 → 실제 MP4 생성하여 `/home/jay/projects/ThreadAuto/output/sample_dialogue_video.mp4`에 저장