# task-385.1 완료 보고서: 영상 생성 성능 개선

## 작업 요약
카드뉴스 7장 → 21초 영상 생성 시 **360초(6분) → 52.4초로 6.9배 성능 개선** (목표 3배 이상 달성)

## 변경 파일

- `video/config.py`: FFMPEG_PRESET = "fast" 설정 추가
- `video/video_generator.py`: FFMPEG_PRESET import + write_videofile에 ffmpeg_params 추가 (`-pix_fmt yuv420p -preset fast`)
- `video/effects.py`:
  - **ken_burns()**: 매 프레임 MoviePy resized → 사전 확대(1회) + numpy 크롭 + PIL BILINEAR 방식으로 변경
  - **fade_transition()**: `concatenate_videoclips(method="compose")` 제거 → 겹침 구간만 CompositeVideoClip 사용 (진짜 병목 해결)
- `video/tests/test_effects.py`: mock 업데이트 (w/h/fps/get_frame/subclipped 속성 추가, VideoClip/CompositeVideoClip 패치)

## 핵심 발견사항

원래 작업 지시는 ken_burns의 매 프레임 resize가 6분의 주범이라고 분석했으나, 실측 결과 **fade_transition의 `method="compose"`가 진짜 병목**임을 발견:

- 단순 concat (7클립): **4.9초**
- fade_transition 1회 (2클립): **21.7초**
- 7클립 + 6 fade_transition: **506초**

원인: `concatenate_videoclips(method="compose")`는 전체 duration에 걸쳐 CompositeVideoClip을 생성하여, 겹치지 않는 구간에서도 불필요한 합성 연산 수행.

수정: slide_transition과 동일한 패턴으로 겹침 구간(0.5초)만 CompositeVideoClip 사용.

## 테스트 결과

- 단위 테스트: **199/199 PASS** (integration 5개 제외)
- 성능 테스트: **52.4초** (목표 120초 이내, 6.9배 개선)
- 출력 영상: yuv420p, h264 High, 1080x1920, 30fps, 18초, 정상 재생
- pyright: 0 errors
- black + isort: PASS
- tdd_check: PASS

## QC 자동 검증 결과

```json
{
  "pyright_check": "PASS",
  "style_check": "PASS",
  "tdd_check": "PASS",
  "data_integrity": "PASS"
}
```

WARN: test_runner timeout (QC 60초 제한 초과, 수동 실행 시 55.5초에 199 PASS)

## 커밋 내역

- `491dd7b` [task-385.1] config.py에 FFMPEG_PRESET 설정 추가
- `b3c9e91` [task-385.1] write_videofile에 pix_fmt yuv420p + preset fast 적용
- `7519ac7` [task-385.1] effects.py ken_burns 함수를 사전 확대+크롭 방식으로 최적화
- `c09a18b` [task-385.1] test_effects.py TestKenBurns에 VideoClip 패치 및 fps 설정 추가
- `65b2a98` [task-385.1] fade_transition method=compose 병목 해결 + ken_burns 사전확대 최적화

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-385.1-dev2
- **워크트리 경로**: /home/jay/projects/ThreadAuto/.worktrees/task-385.1-dev2
- **머지 의견**: 199개 테스트 전부 PASS, 성능 6.9배 개선(52.4초), 출력 영상 품질 정상. API 시그니처 변경 없음 (내부 구현만 변경). 충돌 가능성 낮음. 머지 추천.