# Essential Mix 파이프라인 — 1시간 mix + essential 시각 스타일 + UX 강화 설계

> 작성일: 2026-05-09
> 관련 spec:
> - `2026-05-07-music-youtube-pipeline-design.md` (본 파이프라인의 베이스)
> - `2026-05-09-gpu-video-offload-design.md` (Windows GPU 인코딩)

---

## 1. 배경

현재 파이프라인은 **단일 트랙 → 단일 영상**(커버 + 가장자리 파형)만 지원. 사용자는 YouTube essential 채널처럼 **1시간 이상의 음악 mix + 차분한 배경 + 중앙 비주얼라이저** 영상을 원함.

또한 진행 중 산출물(커버·썸네일·영상)을 NAS 파일시스템에서 직접 확인하는 게 번거로워, 진행 탭에서도 미리보기 가능했으면 함.

---

## 2. 비목표

- 사용자 직접 업로드 사진/영상 (P3로 미룸)
- 360° 정확한 방사형 비주얼라이저 (ffmpeg 단독으로 한계 — `showfreqs` + ring overlay로 근사)
- Mix 자동 큐레이션(곡 자동 선택) — 기존 컴파일 탭의 수동 선택 그대로 활용
- AI 검토 가중치 자동 튜닝 (Mix와 단일 트랙의 다른 기준 등 — P3)
- 텔레그램 사진 첨부 — 본 작업의 PipelineDetailModal로 우선 해결, 차후 P3

---

## 3. 사용자 흐름

### 3-1. Mix 영상 만들기

```
[사용자] Compile 탭에서 트랙 N개 선택 → crossfade 설정 → 컴파일 시작
   → 컴파일 완료 (1시간+ mp3 생성, 기존 흐름)
   → 컴파일 카드에 [🎬 영상 만들기] 버튼 클릭
   → 백엔드: POST /api/music/pipeline { compile_job_id, visual_style: 'essential' }
   → 진행 탭으로 자동 이동, 새 카드 생성
   → 단계별 텔레그램 승인 (기존과 동일):
       cover (또는 background_video) → video → thumbnail → metadata → AI 검토 → 발행
   → YouTube 비공개 영상 1편
```

### 3-2. 단일 트랙 영상 만들기 (기존)

진행 탭 모달에 라디오 "단일 트랙 / Mix" 추가. 단일 선택 시 기존 흐름 그대로.

### 3-3. 산출물 미리보기

진행 탭 카드의 cover/thumbnail 미니 썸네일 → 카드 클릭 → 상세 모달 → 큰 이미지 + 영상 플레이어 + 메타·검토 JSON.

---

## 4. 데이터 모델 변경

### 4-1. `video_pipelines` 테이블 확장

신규 컬럼:
```sql
ALTER TABLE video_pipelines ADD COLUMN compile_job_id INTEGER NULL REFERENCES compile_jobs(id);
ALTER TABLE video_pipelines ADD COLUMN visual_style TEXT NOT NULL DEFAULT 'essential';
ALTER TABLE video_pipelines ADD COLUMN background_mode TEXT NOT NULL DEFAULT 'static';
ALTER TABLE video_pipelines ADD COLUMN background_keyword TEXT;
```

| 컬럼 | 의미 |
|------|------|
| `track_id` (기존) | 단일 트랙 입력 시 |
| `compile_job_id` (신규) | Mix 입력 시 — `track_id` XOR `compile_job_id` |
| `visual_style` | `single` / `essential` |
| `background_mode` | `static` (사진) / `video_loop` (영상) |
| `background_keyword` | Pexels 검색용 (예: "rainy window cafe"). 비어있으면 장르 기반 자동 |

마이그레이션: `ADD COLUMN`은 SQLite에서 안전. 기존 행은 NULL 또는 default 값 부여.

### 4-2. `youtube_setup.visual_defaults` JSON 확장

기존:
```json
{"resolution": "1920x1080", "style": "visualizer", "background": "ai_cover"}
```

신규:
```json
{
  "resolution": "1920x1080",
  "default_visual_style": "essential",
  "default_background_mode": "static",
  "default_background_keyword": "",
  "background_image_source": "ai",      // ai | pexels (Mix는 default ai)
  "subtitle_track_titles": true          // Mix에서 곡명 자막 표시
}
```

기존 클라이언트 호환을 위해 미설정 키는 default로 fallback.

---

## 5. API 변경

### 5-1. `POST /api/music/pipeline` 요청 body 확장

```json
{
  "track_id": 13,
  // 또는
  "compile_job_id": 5,
  // 옵션 (default는 setup에서)
  "visual_style": "essential",            // single | essential
  "background_mode": "static",            // static | video_loop
  "background_keyword": "rainy cafe"
}
```

검증:
- `track_id` XOR `compile_job_id` 정확히 하나만 — 둘 다거나 둘 다 없으면 400
- `compile_job_id`인 경우 `compile_jobs` 테이블에서 status='succeeded' 확인 — 아니면 400
- `visual_style` 미지정 시 `youtube_setup.visual_defaults.default_visual_style`
- `background_mode` 미지정 시 `youtube_setup.visual_defaults.default_background_mode`

응답:
```json
{
  "id": 7,
  "track_id": null,
  "compile_job_id": 5,
  "visual_style": "essential",
  "background_mode": "static",
  "state": "created",
  ...
}
```

### 5-2. `GET /api/music/pipeline/{id}` 응답 확장

신규 필드: `compile_job_id`, `visual_style`, `background_mode`, `background_keyword`, `tracks` (Mix면 트랙 리스트, 단일이면 단일 트랙 1개)

`tracks` 형식:
```json
[
  {"id": 13, "title": "Lo-Fi Drive", "start_offset_sec": 0, "duration_sec": 176},
  {"id": 14, "title": "Midnight Cafe", "start_offset_sec": 173, "duration_sec": 200},
  ...
]
```

`start_offset_sec`은 컴파일 시 acrossfade 적용을 고려한 누적 시작 시각 (=영상 자막 트리거 타이밍).

### 5-3. 변경 없음

`/feedback`, `/cancel`, `/publish`, `/setup`, `/youtube/*` 모두 그대로.

---

## 6. 백엔드 — NAS music-lab

### 6-1. `pipeline/orchestrator.py` 변경

`run_step`에 입력 audio 결정 로직 추가:

```python
def _resolve_input(p: dict) -> dict:
    """파이프라인 입력 = 단일 트랙 또는 컴파일 결과.

    반환: {"audio_path": str, "duration_sec": int, "tracks": list[dict],
           "title": str, "genre": str, "moods": list, ...}
    """
    if p.get("compile_job_id"):
        job = db.get_compile_job(p["compile_job_id"])
        if not job or job["status"] != "succeeded":
            raise ValueError(f"compile job {p['compile_job_id']} not ready")
        # 누적 offset 계산 (acrossfade 고려)
        tracks = []
        offset = 0.0
        crossfade = job["crossfade_sec"]
        for tid in job["track_ids"]:
            t = db.get_track_by_id(tid)
            tracks.append({
                "id": tid, "title": t["title"],
                "start_offset_sec": offset,
                "duration_sec": t["duration_sec"],
            })
            offset += t["duration_sec"] - crossfade  # acrossfade overlap만큼 차감
        return {
            "audio_path": job["audio_path"],         # /app/data/compiles/{id}.mp3
            "duration_sec": int(offset + crossfade), # 마지막 트랙은 풀 길이
            "tracks": tracks,
            "title": job["title"] or "Mix",
            "genre": "mix",
            "moods": [],
        }
    else:
        t = db.get_track_by_id(p["track_id"])
        return {
            "audio_path": t["file_path"],
            "duration_sec": t["duration_sec"],
            "tracks": [{"id": t["id"], "title": t["title"],
                        "start_offset_sec": 0, "duration_sec": t["duration_sec"]}],
            "title": t["title"], "genre": t["genre"], "moods": t.get("moods", []),
        }
```

각 step runner는 `_resolve_input(p)` 결과를 사용:
- `_run_cover`: `genre`, `moods`, `title` 활용 (Mix면 `genre="mix"` → "mix" 키 prompt 또는 default)
- `_run_video`: `audio_path`, `duration_sec`, `tracks` 모두 Windows로 전달
- `_run_meta`: `tracks` 리스트를 메타 prompt에 포함
- `_run_review`: `tracks` 리스트를 검토 prompt에 포함 (트랙 수, 다양한 장르 등)

### 6-2. `pipeline/cover.py` Pexels 폴백/대안

```python
async def generate(*, pipeline_id: int, genre: str, prompt_template: str,
                   mood: str = "", track_title: str = "", feedback: str = "",
                   image_source: str = "ai") -> dict:
    """image_source: 'ai' (DALL·E) | 'pexels' (스톡 검색)."""
    if image_source == "pexels":
        return await _generate_with_pexels(pipeline_id, genre, mood, track_title)
    # 기존 AI 흐름 그대로
    ...
    # AI 실패 시 — 그라데이션 폴백 대신 Pexels 시도 (config 옵션)
    ...
```

신규 `_generate_with_pexels`:
- Pexels API: `GET https://api.pexels.com/v1/search?query={keyword}&per_page=10`
- 결과 1번째 큰 사진 다운로드 → `/app/data/videos/{id}/cover.jpg`
- API key 미설정/실패 시 그라데이션 폴백

### 6-3. 신규 `pipeline/background.py` (video_loop 모드)

```python
async def fetch_video_loop(pipeline_id: int, keyword: str) -> dict:
    """Pexels Video API로 5–15초 루프 영상 받아옴.

    /app/data/videos/{id}/loop.mp4 저장.
    """
    # GET https://api.pexels.com/videos/search?query=...&per_page=5
    # SD/HD 720p 중에서 골라 다운로드
    ...
    return {"path": "/app/data/videos/{id}/loop.mp4", "duration_sec": ...}
```

오케스트레이터에서 `background_mode == "video_loop"` 분기 시 cover step 대신 또는 보조로 호출 (디자인 결정: cover step을 두 모드의 공통 입력 준비 단계로 통합 — 정적이면 cover.jpg, 영상이면 loop.mp4).

### 6-4. `pipeline/metadata.py` Mix 지원

`generate(*, track, template, trend_keywords, feedback="", tracks=None)` 시그니처 확장. `tracks` 있으면 Claude prompt에 다음 추가:

```
이 영상은 {len(tracks)}개 트랙의 mix입니다. 트랙 리스트:
1. [00:00] Lo-Fi Drive — lo-fi
2. [03:00] Midnight Cafe — lo-fi
...
설명에는 트랙 리스트를 타임스탬프와 함께 포함하세요.
```

응답 description은 자동으로 트랙리스트 포함됨. 이는 YouTube에서 챕터로 자동 인식.

### 6-5. `pipeline/video.py` (NAS측, 변경 작음)

기존 함수에 추가 파라미터 전달:

```python
def generate(*, pipeline_id, audio_path, cover_path, genre, duration_sec,
             resolution="1920x1080", style="essential",
             background_mode="static", background_path=None,
             tracks=None) -> dict:
    payload = {
        "audio_path_nas": ..., "cover_path_nas": ...,
        "output_path_nas": ...,
        "resolution": resolution,
        "duration_sec": duration_sec,
        "style": style,                     # NEW: single | essential
        "background_mode": background_mode, # NEW: static | video_loop
        "background_path_nas": ...,         # NEW: video_loop일 때 loop.mp4 경로
        "tracks": tracks,                   # NEW: Mix면 트랙 리스트 (자막용)
    }
    ...
```

### 6-6. `db.py` 변경

신규 컬럼 추가 마이그레이션 + `get_compile_job(id)` (없으면 추가) + `get_track_by_id(id)` 활용.

---

## 7. 백엔드 — Windows music_ai

### 7-1. `/encode_video` 요청 확장

```json
{
  "audio_path_nas": "...",
  "cover_path_nas": "...",
  "output_path_nas": "...",
  "resolution": "1920x1080",
  "duration_sec": 3600,
  "style": "essential",                    // NEW
  "background_mode": "static",             // NEW
  "background_path_nas": "...",            // NEW: video_loop면 loop.mp4
  "tracks": [                              // NEW: 자막용
    {"start_offset_sec": 0, "title": "Lo-Fi Drive"},
    {"start_offset_sec": 173, "title": "Midnight Cafe"}
  ]
}
```

### 7-2. `video_encoder.py` 분기 로직

```python
def encode_video(*, ..., style="essential", background_mode="static",
                  background_path_nas=None, tracks=None):
    if style == "single":
        cmd = build_single_track_cmd(...)
    else:  # essential
        if background_mode == "static":
            cmd = build_essential_static_cmd(cover, audio, out, w, h, tracks)
        else:
            bg = translate_path(background_path_nas)
            cmd = build_essential_video_loop_cmd(bg, audio, out, w, h, tracks)
    ...
```

### 7-3. Essential 정적 ffmpeg 명령

핵심 filter_complex 구조:

```
[0:v]scale=1920:1080,format=yuv420p[bg];           # 정적 배경 사진
[1:a]showfreqs=s=400x200:mode=bar:cmode=combined:colors=0xFFFFFF@0.9[bars];  # 중앙 막대
[2:v]format=rgba[ring];                            # 데코 ring PNG (사전 제작 1장)
[bg][bars]overlay=(W-w)/2:(H-h)/2[mid];           # 막대 정중앙 배치
[mid][ring]overlay=(W-w)/2:(H-h)/2[viz];          # ring 데코 같은 위치
[viz]drawtext=...:enable='between(t,0,5)+between(t,173,178)+...'[final]
```

- `showfreqs s=400x200 mode=bar` — 가로 막대 (방사형 근사 1차 버전)
- `ring.png` — 사전 제작된 투명 PNG (`music_ai/assets/visualizer_ring.png`, 단순 흰색 원 + 외곽 점선)
- `drawtext` — 트랙 리스트 순회하며 enable expression 동적 생성

향후(V2): `showcqt`나 `showspectrum` 시도 + 진짜 360° 방사형은 외부 도구(예: SuperCollider, butterchurn) 검토.

### 7-4. Essential 영상 루프 ffmpeg 명령

```
[0:v]scale=1920:1080,setpts=PTS-STARTPTS[bg_loop];
loop=loop=-1:size=N         # 루프 영상 무한 반복
[1:a]showfreqs=...[bars];
[bg_loop][bars]overlay=center[mid];
[mid][ring]overlay=center[viz];
... drawtext 동일
```

루프는 `-stream_loop -1 -i loop.mp4` 입력 옵션 + `-shortest` 출력으로 audio 길이만큼 반복.

### 7-5. 자막(곡명) drawtext

```python
def build_drawtext_filter(tracks, total_duration):
    expressions = []
    for tr in tracks:
        start = tr["start_offset_sec"]
        end = start + 5  # 5초 표시
        # alpha fade in/out
        text = tr["title"].replace(":", r"\:").replace("'", r"\'")
        expressions.append(
            f"drawtext=fontfile='Arial Bold':text='{text}'"
            f":fontcolor=white:fontsize=36:x=(w-text_w)/2:y=h-100"
            f":alpha='if(between(t,{start},{end}),"
            f"  if(lt(t-{start},1), t-{start},"      # 0~1s fade in
            f"     if(gt(t-{start},4), {end}-t, 1)), 0)'"   # 4~5s fade out
        )
    return ",".join(expressions)  # 체인으로 연결
```

폰트는 Windows에 기본 설치된 Arial 또는 NanumGothic 사용. 한글 트랙명 지원 위해 NanumGothic 권장.

### 7-6. 신규 자산 파일

`music_ai/assets/visualizer_ring.png` — 1920×1080 캔버스 정중앙 400×400 영역에 그려진 흰색 원형 (외곽선 + 옅은 inner glow). 사전 제작 1장 — Pillow로 자동 생성도 가능 (서버 시작 시 없으면 생성).

---

## 8. 프론트엔드 변경

### 8-1. `CompileTab.jsx` — 영상 만들기 버튼

완료된 compile job 카드에 버튼 추가:

```jsx
{job.status === 'succeeded' && (
    <button onClick={() => handleVideoFromCompile(job.id)}>
        🎬 영상 만들기
    </button>
)}
```

`handleVideoFromCompile`:
```js
async (compileJobId) => {
    const p = await createPipeline({ compile_job_id: compileJobId });
    await startPipeline(p.id);
    // 진행 탭으로 이동 (router push 또는 setTab + setOpenPipelineFor 패턴)
};
```

### 8-2. `PipelineStartModal.jsx` 확장

```jsx
const [inputType, setInputType] = useState('track');  // 'track' | 'compile'
const [compileJobs, setCompileJobs] = useState([]);

useEffect(() => {
    if (inputType === 'compile') getCompileJobs().then(setCompileJobs);
}, [inputType]);

return (
    <div className="modal-body">
        <h3>새 파이프라인 시작</h3>

        <fieldset>
            <legend>입력</legend>
            <label><input type="radio" checked={inputType==='track'}
                onChange={() => setInputType('track')}/> 단일 트랙</label>
            <label><input type="radio" checked={inputType==='compile'}
                onChange={() => setInputType('compile')}/> Mix (컴파일 결과)</label>
        </fieldset>

        {inputType === 'track' && (
            <select>{library.map(...)}</select>
        )}
        {inputType === 'compile' && (
            <select>{compileJobs.filter(j=>j.status==='succeeded').map(j =>
                <option key={j.id} value={j.id}>{j.title} ({j.tracks_count}곡, {fmtDuration(j.duration_sec)})</option>
            )}</select>
        )}

        {/* 시각 모드 override */}
        <details>
            <summary>고급 옵션</summary>
            <select>visual_style: single | essential</select>
            <select>background_mode: static | video_loop</select>
            <input>background_keyword</input>
        </details>

        {/* ... 기존 시작/취소 버튼 */}
    </div>
);
```

### 8-3. `PipelineCard.jsx` — 미리보기 inline

```jsx
return (
    <div className="pipeline-card" onClick={() => setShowDetail(true)}>
        <div className="pipeline-card__head">
            <h4>{pipeline.track_title || pipeline.compile_title || `Pipeline #${pipeline.id}`}</h4>
            <span className="pipeline-style-badge">{pipeline.visual_style}</span>
            ...
        </div>

        {/* 미니 미리보기 */}
        <div className="pipeline-previews">
            {pipeline.cover_url && <img src={pipeline.cover_url} alt="" className="pipeline-preview-mini" />}
            {pipeline.thumbnail_url && <img src={pipeline.thumbnail_url} alt="" className="pipeline-preview-mini" />}
            {pipeline.video_url && <span className="pipeline-video-icon">▶</span>}
        </div>

        {/* 진행도 바 + 현재 상태 (기존) */}
        ...
    </div>
);
```

### 8-4. `PipelineDetailModal.jsx` (신규)

```jsx
export default function PipelineDetailModal({ pipeline, onClose }) {
    return (
        <div className="modal-overlay" onClick={onClose}>
            <div className="modal-body modal-body--lg" onClick={e=>e.stopPropagation()}>
                <header>
                    <h3>{pipeline.compile_title || pipeline.track_title}</h3>
                    <span className="badge">{pipeline.visual_style}</span>
                    <button onClick={onClose}>×</button>
                </header>

                {/* 큰 미리보기 그리드 */}
                <div className="pdm-grid">
                    {pipeline.cover_url && (
                        <figure>
                            <img src={pipeline.cover_url} alt="cover" />
                            <figcaption>커버 (배경)</figcaption>
                        </figure>
                    )}
                    {pipeline.thumbnail_url && (
                        <figure>
                            <img src={pipeline.thumbnail_url} alt="thumbnail" />
                            <figcaption>썸네일</figcaption>
                        </figure>
                    )}
                </div>

                {/* 영상 플레이어 */}
                {pipeline.video_url && (
                    <div className="pdm-video">
                        <video src={pipeline.video_url} controls width="100%" />
                    </div>
                )}

                {/* 메타데이터 */}
                {pipeline.metadata && (
                    <section className="pdm-meta">
                        <h4>메타데이터</h4>
                        <p><strong>제목:</strong> {pipeline.metadata.title}</p>
                        <details>
                            <summary>설명</summary>
                            <pre>{pipeline.metadata.description}</pre>
                        </details>
                        <p><strong>태그:</strong> {pipeline.metadata.tags?.join(', ')}</p>
                    </section>
                )}

                {/* AI 검토 */}
                {pipeline.review && (
                    <section className="pdm-review">
                        <h4>AI 검토 — <span className="badge">{pipeline.review.verdict}</span> ({pipeline.review.weighted_total}/100)</h4>
                        <table>
                            <tbody>
                                <tr><td>메타데이터 품질</td><td>{pipeline.review.metadata_quality.score}</td></tr>
                                <tr><td>콘텐츠 정책</td><td>{pipeline.review.policy_compliance.score}</td></tr>
                                <tr><td>시청 경험</td><td>{pipeline.review.viewer_experience.score}</td></tr>
                                <tr><td>트렌드 정렬</td><td>{pipeline.review.trend_alignment.score}</td></tr>
                            </tbody>
                        </table>
                        <p><em>{pipeline.review.summary}</em></p>
                    </section>
                )}

                {/* 트랙 리스트 (Mix일 때) */}
                {pipeline.tracks && pipeline.tracks.length > 1 && (
                    <section className="pdm-tracks">
                        <h4>트랙 리스트 ({pipeline.tracks.length})</h4>
                        <ol>
                            {pipeline.tracks.map(t => (
                                <li key={t.id}>
                                    [{fmtTimestamp(t.start_offset_sec)}] {t.title} ({fmtDuration(t.duration_sec)})
                                </li>
                            ))}
                        </ol>
                    </section>
                )}

                {/* 피드백 히스토리 */}
                {pipeline.feedback && pipeline.feedback.length > 0 && (
                    <section className="pdm-feedback">
                        <h4>피드백 ({pipeline.feedback.length})</h4>
                        <ul>
                            {pipeline.feedback.map(f => (
                                <li key={f.id}>
                                    <code>[{f.step}]</code> {f.feedback_text}
                                    <small>{f.received_at}</small>
                                </li>
                            ))}
                        </ul>
                    </section>
                )}

                {/* YouTube 링크 */}
                {pipeline.youtube_video_id && (
                    <a href={`https://youtu.be/${pipeline.youtube_video_id}`}
                       target="_blank" rel="noreferrer" className="pdm-youtube">
                        🎬 YouTube에서 보기
                    </a>
                )}
            </div>
        </div>
    );
}
```

### 8-5. `SetupTab.jsx` 확장

영상 비주얼 기본값 카드 확장:
- **default_visual_style** 드롭다운: `single` / `essential`
- **default_background_mode** 드롭다운: `static` / `video_loop`
- **default_background_keyword** 텍스트 입력 (예: "lofi cafe")
- **background_image_source** 드롭다운: `ai` / `pexels`
- **subtitle_track_titles** 체크박스: Mix에서 곡명 자막 표시

---

## 9. 환경변수 (NAS측)

신규 — 이미 `.env`에 있을 가능성 높음:
```env
PEXELS_API_KEY=xxx     # 이미 있음 (현재 미사용)
```

신규 (Windows측 — music_ai/.env):
```env
# 한글 자막용 폰트 경로 (선택)
SUBTITLE_FONT=C:\Windows\Fonts\malgun.ttf
```

---

## 10. 에러 처리

| 시나리오 | 결과 |
|---------|------|
| compile_job 미완료 (status != succeeded) | POST /pipeline 시 400 |
| compile_job 삭제됨 | get_pipeline에서 `compile_title=null`, 진행 탭에 "삭제됨" 배지 |
| Pexels API 실패 (image) | AI 폴백 |
| Pexels API 실패 (video) | 단색 폴백 + 텔레그램에 "Pexels 실패" 명시 |
| drawtext 자막 한글 폰트 누락 | 자막 없이 인코딩 + 경고 로그 |
| 1시간 NVENC timeout | 영상 단계 timeout 600s → 그래도 부족하면 failed (보통 NVENC면 5분 내) |

---

## 11. 테스트 전략

### 11-1. 단위 테스트 (NAS music-lab)

| 대상 | 테스트 |
|------|--------|
| `orchestrator._resolve_input` | track_id 분기 / compile_job_id 분기 / 둘 다 / 둘 다 없음 / compile not ready |
| `cover.generate` `image_source='pexels'` | Pexels API mock + 다운로드 + 파일 저장 |
| `background.fetch_video_loop` | Pexels Video API mock + mp4 다운로드 |
| `metadata.generate` `tracks=[...]` | 트랙 리스트가 prompt에 포함되는지, 응답 description에 chapter 포맷 |
| API `POST /pipeline { compile_job_id }` | 정상 / not ready 400 / 둘 다 400 / 단일은 기존 작동 |
| DB 마이그레이션 | 새 컬럼 default 값 |

### 11-2. 단위 테스트 (Windows music_ai)

| 대상 | 테스트 |
|------|--------|
| `build_essential_static_cmd` | filter_complex 문자열 검증 (showfreqs, overlay 위치 등) |
| `build_drawtext_filter` | 트랙 N개 → enable expression N개 생성, alpha fade 검증 |
| `encode_video` `style='essential'` | 새 분기 호출됨 |
| `encode_video` `style='single'` | 기존 단일 트랙 명령 그대로 |
| 자산 ring.png 자동 생성 | 서버 시작 시 없으면 PIL로 생성 |

### 11-3. 통합 테스트

`test_essential_pipeline_flow.py`:
- compile job 생성 → 파이프라인 시작 (compile_job_id) → 모든 단계 mock → published → tracks 리스트가 metadata description에 포함됐는지

### 11-4. 수동 E2E

- [ ] 컴파일 탭에서 3-5분 mix 컴파일
- [ ] "🎬 영상 만들기" 클릭 → 진행 탭 카드 생성, visual_style=essential
- [ ] cover 단계 → 텔레그램 알림 + 카드에 cover 미니 썸네일 표시
- [ ] 카드 클릭 → 상세 모달 → cover 큰 이미지, 메타·검토 영역 표시 (해당 단계 진행 시)
- [ ] 모든 단계 승인 → 발행 → YouTube 비공개 영상에 essential 시각 + 챕터 자동 인식 확인
- [ ] 1시간 mix로 동일 흐름 — Windows NVENC 인코딩 시간 5분 미만 확인
- [ ] background_mode=video_loop로 시도 — Pexels 영상 다운로드 + 루프 인코딩

---

## 12. 마이그레이션 + 배포

### 12-1. DB 마이그레이션

`init_db()` 신규 컬럼 `ALTER TABLE` (SQLite는 idempotent: 컬럼 존재 확인 후 추가):
```python
def _add_column_if_missing(cursor, table, column, ddl):
    cursor.execute(f"PRAGMA table_info({table})")
    cols = [r[1] for r in cursor.fetchall()]
    if column not in cols:
        cursor.execute(f"ALTER TABLE {table} ADD COLUMN {column} {ddl}")
```

### 12-2. 자산 파일

`music_ai/assets/visualizer_ring.png`은 git에 커밋 (small, ~30KB). Windows 측이므로 사용자가 수동 배포 (이미 music_ai는 로컬 전용).

또는 **서버 시작 시 자동 생성** (PIL로 단순 ring 그리기) — 권장. assets 디렉토리도 자동 생성.

### 12-3. 환경변수

NAS `.env` 변경 없음 (PEXELS_API_KEY 이미 있음).
Windows `.env`에 `SUBTITLE_FONT` 추가 (선택).

---

## 13. 산출물

| 영역 | 파일 |
|------|------|
| Spec/Plan | 본 문서 + plan |
| NAS music-lab | `db.py` (마이그레이션), `pipeline/orchestrator.py` (resolve_input), `pipeline/cover.py` (Pexels 분기), `pipeline/background.py` (신규), `pipeline/metadata.py` (tracks 옵션), `pipeline/video.py` (style/background 파라미터), `app/main.py` (POST /pipeline body 확장) |
| Windows music_ai | `video_encoder.py` (style 분기, drawtext, ring), `server.py` (요청 schema 확장), `assets/visualizer_ring.png` (자동 생성), Pillow 이미 있음 |
| Frontend | `CompileTab.jsx` (영상 만들기 버튼), `PipelineStartModal.jsx` (라디오), `PipelineCard.jsx` (미리보기 inline), `PipelineDetailModal.jsx` (신규), `SetupTab.jsx` (visual_defaults 확장), `api.js` 헬퍼 추가, `MusicStudio.css` 스타일 |
| 테스트 | NAS 단위 6+ / Windows 단위 5+ / 통합 1 / 수동 E2E |

---

## 14. 후속 (P3)

- 사용자 직접 사진/영상 업로드
- 텔레그램에 cover/thumbnail 사진 첨부
- 360° 진짜 방사형 visualizer (외부 도구 또는 GPU shader)
- AI 검토 가중치 mix vs 단일 자동 분리
- Pexels 검색 미리보기 UI (구성 탭에서 "이 키워드로 검색해보기" 버튼)

---