Initial commit: YouTube transcript formatter

YouTube 영상의 자막을 추출하고 포맷팅하는 도구

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,17 @@
+# OpenAI API 키 (https://platform.openai.com/api-keys 에서 발급)
+OPENAI_API_KEY=sk-proj-여기에_키를_입력하세요
+
+# 기본 변환 모드 (api 또는 local)
+DEFAULT_MODE=api
+
+# 로컬 Whisper 모델 크기 (tiny, base, small, medium, large)
+DEFAULT_MODEL=base
+
+# MD 포맷팅용 API 키 (사용하는 LLM만 설정하면 됩니다)
+# Google Gemini (https://aistudio.google.com/app/apikey)
+GOOGLE_API_KEY=여기에_키를_입력하세요
+# Anthropic Claude (https://console.anthropic.com/)
+ANTHROPIC_API_KEY=여기에_키를_입력하세요
+
+# 웹 서버 포트
+PORT=8000

.gitignore

@@ -0,0 +1,27 @@
+# 환경 변수 (API 키 포함)
+.env
+
+# 출력물
+output/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Claude Code 로컬 설정
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Whisper 모델 캐시
+*.pt
+
+# 임시 파일
+*.tmp
+temp/

README.md

@@ -0,0 +1,116 @@
+# 🎬 YouTube Script Extractor
+
+YouTube 영상에서 스크립트를 추출하고, AI로 깔끔하게 정리하는 도구입니다.
+
+## ✨ 주요 기능
+
+- **자동 스크립트 추출** — YouTube URL만 입력하면 음성을 텍스트로 변환
+- **AI 마크다운 정리** — LLM이 스크립트를 구조화된 마크다운으로 정리
+- **다국어 번역** — 14개 언어 지원 (한국어, 영어, 일본어 등)
+- **키프레임 분석 (CV)** — 영상의 핵심 장면을 추출하고 Vision AI로 분석
+- **Smart Mix** — 파이프라인 단계별로 다른 LLM을 지정 가능
+- **웹 UI + CLI** — 브라우저 기반 UI와 커맨드라인 모두 지원
+
+## 🤖 지원 LLM
+
+| 모델 | 가격 | Vision | 비고 |
+|------|------|--------|------|
+| Ollama (로컬) | 무료 | ❌ | 인터넷 불필요 |
+| Gemini 2.5 Flash-Lite | $0.10/1M토큰 | ✅ | ⭐ 최저가 |
+| Gemini 3.1 Flash-Lite | $0.25/1M토큰 | ✅ | 최신 모델 |
+| GPT-4o-mini | $0.15/1M토큰 | ✅ | OpenAI |
+| Claude Sonnet 4.6 | $3/1M토큰 | ✅ | 고품질 |
+| Claude Opus 4.6 | $5/1M토큰 | ✅ | 최고 품질 |
+
+## 🚀 빠른 시작
+
+### 1. 설치
+
+```bash
+git clone https://huggingface.co/spaces/YOUR_USERNAME/youtube-script-extractor
+cd youtube-script-extractor
+
+# ffmpeg 설치 (macOS)
+brew install ffmpeg
+
+# Python 의존성 설치
+pip install -r requirements.txt
+```
+
+### 2. API 키 설정
+
+```bash
+cp .env.example .env
+# .env 파일을 열어 사용할 LLM의 API 키를 입력하세요
+```
+
+### 3. 실행
+
+```bash
+# 웹 UI (추천)
+chmod +x run
+./run
+
+# 또는 직접 실행
+python3 web.py
+```
+
+브라우저에서 `http://localhost:8000` 접속
+
+### CLI 모드
+
+```bash
+./run "https://www.youtube.com/watch?v=VIDEO_ID"
+./run "https://www.youtube.com/watch?v=VIDEO_ID" --mode local --format srt
+```
+
+## ⚙️ 설정
+
+`.env` 파일에서 설정합니다:
+
+```env
+# 필수: Whisper API용
+OPENAI_API_KEY=sk-proj-...
+
+# 선택: 사용하는 LLM만 설정
+GOOGLE_API_KEY=...        # Gemini
+ANTHROPIC_API_KEY=...     # Claude
+
+# 기본 설정
+DEFAULT_MODE=api          # api 또는 local
+DEFAULT_MODEL=base        # Whisper 모델 (tiny/base/small/medium/large)
+PORT=8000
+```
+
+## 📁 프로젝트 구조
+
+```
+├── run                 # 실행 스크립트 (설치 + 실행)
+├── web.py              # FastAPI 웹 서버
+├── cli.py              # CLI 인터페이스
+├── transcriber.py      # 음성 추출 + STT + 키프레임 추출
+├── formatter.py        # LLM 호출 + 마크다운 정리 + 번역
+├── templates/
+│   └── index.html      # 웹 UI
+├── requirements.txt    # Python 의존성
+├── .env.example        # 환경 변수 템플릿
+└── output/             # 추출 결과물 (git 제외)
+```
+
+## 🔧 Smart Mix (단계별 LLM 선택)
+
+웹 UI의 ⚙ 버튼으로 파이프라인 단계별 LLM을 설정할 수 있습니다:
+
+- **MD 정리** — 스크립트를 마크다운으로 구조화 (저렴한 모델 OK)
+- **번역** — 다국어 번역 (저렴한 모델 OK)
+- **키프레임 분석** — Vision AI로 화면 분석 (Vision 지원 모델 필요)
+
+## 📋 요구사항
+
+- Python 3.9+
+- ffmpeg
+- API 키 (사용하려는 LLM에 따라)
+
+## 📄 License
+
+MIT

cli.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""YouTube Script Extractor - CLI."""
+
+import argparse
+import os
+import sys
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from transcriber import process_video
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="YouTube 영상에서 음성인식으로 스크립트를 추출합니다.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+사용 예시:
+  # Whisper API 사용 (빠르고 정확)
+  python cli.py "https://www.youtube.com/watch?v=..." --mode api
+
+  # 로컬 Whisper 사용 (무료)
+  python cli.py "https://www.youtube.com/watch?v=..." --mode local --model base
+
+  # SRT 자막만 생성
+  python cli.py "https://www.youtube.com/watch?v=..." --format srt
+
+  # 출력 디렉토리 지정
+  python cli.py "https://www.youtube.com/watch?v=..." --output ./my_scripts
+        """,
+    )
+
+    parser.add_argument("url", help="YouTube 영상 URL")
+    parser.add_argument(
+        "--mode",
+        choices=["api", "local"],
+        default=os.environ.get("DEFAULT_MODE", "api"),
+        help="변환 모드 (기본: api)",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=None,
+        help="OpenAI API 키 (미지정 시 OPENAI_API_KEY 환경변수 사용)",
+    )
+    parser.add_argument(
+        "--model",
+        default=os.environ.get("DEFAULT_MODEL", "base"),
+        choices=["tiny", "base", "small", "medium", "large"],
+        help="로컬 Whisper 모델 크기 (기본: base)",
+    )
+    parser.add_argument(
+        "--format",
+        default="txt,srt",
+        help="출력 형식, 쉼표로 구분 (기본: txt,srt)",
+    )
+    parser.add_argument(
+        "--output",
+        default="./output",
+        help="출력 디렉토리 (기본: ./output)",
+    )
+
+    args = parser.parse_args()
+
+    # API 키 처리
+    api_key = args.api_key or os.environ.get("OPENAI_API_KEY")
+    if args.mode == "api" and not api_key:
+        print("오류: API 모드에서는 OpenAI API 키가 필요합니다.")
+        print("  --api-key 인자를 사용하거나 OPENAI_API_KEY 환경변수를 설정하세요.")
+        sys.exit(1)
+
+    formats = [f.strip() for f in args.format.split(",")]
+
+    def on_progress(msg: str):
+        print(f"  → {msg}")
+
+    print(f"YouTube Script Extractor")
+    print(f"  URL: {args.url}")
+    print(f"  모드: {'Whisper API' if args.mode == 'api' else f'로컬 Whisper ({args.model})'}")
+    print(f"  출력: {', '.join(formats)}")
+    print()
+
+    try:
+        result = process_video(
+            url=args.url,
+            mode=args.mode,
+            api_key=api_key,
+            model_size=args.model,
+            output_dir=args.output,
+            formats=formats,
+            on_progress=on_progress,
+        )
+
+        print()
+        print(f"제목: {result['title']}")
+        print(f"감지된 언어: {result['language']}")
+        print(f"생성된 파일:")
+        for fmt, path in result["files"].items():
+            print(f"  [{fmt.upper()}] {path}")
+
+    except KeyboardInterrupt:
+        print("\n중단되었습니다.")
+        sys.exit(130)
+    except Exception as e:
+        print(f"\n오류 발생: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

formatter.py

@@ -0,0 +1,687 @@
+"""LLM을 사용하여 Whisper 추출 텍스트를 마크다운 정리/번역하는 모듈."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import time
+from typing import Callable, List, Optional
+
+# ── LLM 정보 (가격순 정렬) ──────────────────────────────────
+LLM_MODELS = {
+    "ollama": {
+        "name": "Ollama (로컬, 무료)",
+        "model": "llama3.2",
+        "version": "llama3.2",
+        "price_rank": 0,
+        "quality_rank": 5,
+        "needs_key": False,
+        "env_key": None,
+        "supports_vision": False,
+        "description": "로컬 실행, 무료, 인터넷 불필요",
+    },
+    "gemini-flash-lite": {
+        "name": "Gemini 2.5 Flash-Lite",
+        "model": "gemini-2.5-flash-lite",
+        "version": "2.5-flash-lite",
+        "price_rank": 1,
+        "quality_rank": 4,
+        "needs_key": True,
+        "env_key": "GOOGLE_API_KEY",
+        "supports_vision": True,
+        "description": "⭐ 최저가, $0.10/1M토큰, 빠르고 안정적",
+    },
+    "gemini-flash": {
+        "name": "Gemini 3.1 Flash-Lite (Preview)",
+        "model": "gemini-3.1-flash-lite-preview",
+        "version": "3.1-flash-lite",
+        "price_rank": 2,
+        "quality_rank": 3,
+        "needs_key": True,
+        "env_key": "GOOGLE_API_KEY",
+        "supports_vision": True,
+        "description": "최신 모델, $0.25/1M토큰, 향상된 성능",
+    },
+    "gpt-4o-mini": {
+        "name": "GPT-4o-mini (OpenAI)",
+        "model": "gpt-4o-mini",
+        "version": "4o-mini",
+        "price_rank": 3,
+        "quality_rank": 2,
+        "needs_key": True,
+        "env_key": "OPENAI_API_KEY",
+        "supports_vision": True,
+        "description": "빠르고 저렴, $0.15/1M토큰",
+    },
+    "claude-sonnet": {
+        "name": "Claude Sonnet 4.6 (Anthropic)",
+        "model": "claude-sonnet-4-6",
+        "version": "sonnet-4.6",
+        "price_rank": 4,
+        "quality_rank": 1,
+        "needs_key": True,
+        "env_key": "ANTHROPIC_API_KEY",
+        "supports_vision": True,
+        "description": "Anthropic, 빠르고 고품질 ($3/1M토큰)",
+    },
+    "claude-opus": {
+        "name": "Claude Opus 4.6 (Anthropic)",
+        "model": "claude-opus-4-6",
+        "version": "opus-4.6",
+        "price_rank": 5,
+        "quality_rank": 0,
+        "needs_key": True,
+        "env_key": "ANTHROPIC_API_KEY",
+        "supports_vision": True,
+        "description": "Anthropic 최고 모델, 구조화 능력 최고 ($5/1M토큰)",
+    },
+}
+
+# ── 번역 지원 언어 ────────────────────────────────────────
+LANGUAGES = {
+    "ko": "한국어",
+    "en": "English",
+    "ja": "日本語",
+    "zh-CN": "中文(简体)",
+    "zh-TW": "中文(繁體)",
+    "es": "Español",
+    "fr": "Français",
+    "de": "Deutsch",
+    "pt": "Português",
+    "ru": "Русский",
+    "vi": "Tiếng Việt",
+    "th": "ภาษาไทย",
+    "ar": "العربية",
+    "hi": "हिन्दी",
+}
+
+
+def get_models_sorted(sort_by: str = "price") -> list:
+    """정렬된 LLM 모델 리스트를 반환한다."""
+    key = "price_rank" if sort_by == "price" else "quality_rank"
+    return sorted(
+        [{"id": k, **v} for k, v in LLM_MODELS.items()],
+        key=lambda x: x[key],
+    )
+
+
+def get_languages() -> list:
+    """지원되는 번역 언어 목록을 반환한다."""
+    return [{"code": k, "name": v} for k, v in LANGUAGES.items()]
+
+
+def make_llm_config(
+    global_llm: Optional[str] = None,
+    global_api_key: Optional[str] = None,
+    global_ollama_model: str = "llama3.2",
+    format_llm: Optional[str] = None,
+    format_api_key: Optional[str] = None,
+    translate_llm: Optional[str] = None,
+    translate_api_key: Optional[str] = None,
+    keyframe_llm: Optional[str] = None,
+    keyframe_api_key: Optional[str] = None,
+) -> dict:
+    """단계별 LLM 설정 딕셔너리를 생성한다.
+
+    per-step 값이 없으면 global 값으로 fallback.
+    반환: {"format": {...}, "translate": {...}, "keyframe": {...}}
+    """
+    def _resolve(step_llm, step_key):
+        llm = step_llm or global_llm
+        api_key = step_key or global_api_key
+        return {
+            "llm": llm,
+            "api_key": api_key,
+            "ollama_model": global_ollama_model,
+        }
+
+    return {
+        "format": _resolve(format_llm, format_api_key),
+        "translate": _resolve(translate_llm, translate_api_key),
+        "keyframe": _resolve(
+            keyframe_llm or "gemini-flash-lite",
+            keyframe_api_key,
+        ),
+    }
+
+
+# ── 프롬프트 ──────────────────────────────────────────────
+
+FORMAT_SYSTEM_PROMPT = """You are an expert document formatter. Your task is to transform raw speech-to-text transcriptions into clean, well-structured Markdown documents.
+
+Rules:
+- Detect the content's language and write the output in the SAME language
+- Add a clear title as # heading
+- Write a brief 2-3 sentence summary at the top
+- Divide content into logical sections with ## headings
+- Clean up filler words, repetitions, and stutters
+- Fix obvious grammar/punctuation errors
+- Keep the original meaning and tone intact
+- Use bullet points or numbered lists where appropriate
+- Add --- horizontal rules between major sections
+- Do NOT add information that wasn't in the original text
+- Output ONLY the formatted Markdown, no explanations"""
+
+FORMAT_USER_TEMPLATE = """Here is a raw speech-to-text transcription from a YouTube video titled "{title}".
+Please format it into a clean, readable Markdown document.
+
+---
+{text}
+---"""
+
+FORMAT_SYSTEM_PROMPT_WITH_KEYFRAMES = """You are an expert document formatter. Your task is to transform raw speech-to-text transcriptions into clean, well-structured Markdown documents, enhanced with visual context from video keyframes.
+
+Rules:
+- Detect the content's language and write the output in the SAME language
+- Add a clear title as # heading
+- Write a brief 2-3 sentence summary at the top
+- Divide content into logical sections with ## headings
+- Clean up filler words, repetitions, and stutters
+- Fix obvious grammar/punctuation errors
+- Keep the original meaning and tone intact
+- Use bullet points or numbered lists where appropriate
+- Add --- horizontal rules between major sections
+- KEYFRAME CONTEXT: You are also given timestamped descriptions of visual keyframes.
+  Insert relevant visual descriptions as blockquotes (> 🖼 [timestamp] description) at
+  appropriate positions in the transcript where they add context.
+- Only include keyframe descriptions that add meaningful value (skip redundant ones)
+- Do NOT add information that wasn't in the original text or keyframes
+- Output ONLY the formatted Markdown, no explanations"""
+
+FORMAT_USER_TEMPLATE_WITH_KEYFRAMES = """Here is a raw speech-to-text transcription from a YouTube video titled "{title}".
+Please format it into a clean, readable Markdown document.
+
+---
+TRANSCRIPT:
+{text}
+---
+
+VISUAL KEYFRAME DESCRIPTIONS (timestamped):
+{keyframe_descriptions}
+---"""
+
+KEYFRAME_ANALYSIS_SYSTEM_PROMPT = """You are a visual content analyst. Analyze the provided video keyframes and describe what is shown.
+
+Rules:
+- Describe each frame concisely (1-3 sentences)
+- Include any visible text (OCR) exactly as shown
+- Note visual elements: diagrams, charts, code, slides, people, scenes
+- Focus on informational content, not aesthetic quality
+- For each frame, output one line in the format: [MM:SS] description
+- Keep descriptions factual and relevant to the video content
+- Output ONLY the descriptions, no extra commentary"""
+
+KEYFRAME_ANALYSIS_USER_TEMPLATE = """Analyze these keyframes from a video. For each image, describe what is shown and extract any visible text.
+The timestamps for each frame are provided as labels."""
+
+TRANSLATE_SYSTEM_PROMPT = """You are a professional translator. Translate the given text accurately into {target_lang}.
+
+Rules:
+- Maintain the original meaning, tone, and nuance
+- If the text uses Markdown formatting, preserve the Markdown structure
+- Translate naturally and idiomatically, not word-by-word
+- Keep proper nouns, brand names, and technical terms appropriately
+- Do NOT add explanations, notes, or commentary
+- Output ONLY the translated text"""
+
+TRANSLATE_USER_TEMPLATE = """Translate the following text into {target_lang}:
+
+---
+{text}
+---"""
+
+
+# ── LLM 호출 함수들 (범용) ────────────────────────────────
+
+def _call_openai(system_prompt: str, user_prompt: str, api_key: str) -> str:
+    """OpenAI GPT-4o-mini 호출."""
+    from openai import OpenAI
+
+    client = OpenAI(api_key=api_key)
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+        temperature=0.3,
+    )
+    return response.choices[0].message.content
+
+
+def _call_gemini(system_prompt: str, user_prompt: str, api_key: str,
+                  model: str = "gemini-2.5-flash-lite") -> str:
+    """Google Gemini 호출."""
+    import google.generativeai as genai
+
+    genai.configure(api_key=api_key)
+    gmodel = genai.GenerativeModel(model)
+
+    prompt = system_prompt + "\n\n" + user_prompt
+    response = gmodel.generate_content(prompt)
+    return response.text
+
+
+def _call_ollama(system_prompt: str, user_prompt: str, model_name: str = "llama3.2") -> str:
+    """Ollama 로컬 모델 호출."""
+    import urllib.request
+
+    payload = json.dumps({
+        "model": model_name,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+        "stream": False,
+        "options": {"temperature": 0.3},
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        "http://localhost:11434/api/chat",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=300) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+            return data["message"]["content"]
+    except Exception as e:
+        if "Connection refused" in str(e):
+            raise RuntimeError(
+                "Ollama가 실행 중이 아닙니다. "
+                "'ollama serve' 명령으로 먼저 시작해주세요. "
+                "(설치: brew install ollama && ollama pull llama3.2)"
+            )
+        raise
+
+
+def _call_claude(system_prompt: str, user_prompt: str, api_key: str, model: str = "claude-sonnet-4-6") -> str:
+    """Anthropic Claude 호출."""
+    import anthropic
+
+    client = anthropic.Anthropic(api_key=api_key)
+    response = client.messages.create(
+        model=model,
+        max_tokens=8192,
+        system=system_prompt,
+        messages=[
+            {"role": "user", "content": user_prompt},
+        ],
+    )
+    return response.content[0].text
+
+
+# ── Vision LLM 호출 함수들 ───────────────────────────────
+
+def _call_gemini_vision(
+    system_prompt: str,
+    user_prompt: str,
+    images: List[dict],
+    api_key: str,
+    model: str = "gemini-2.5-flash-lite",
+) -> str:
+    """Google Gemini Vision 호출."""
+    import google.generativeai as genai
+    from PIL import Image
+
+    genai.configure(api_key=api_key)
+    gmodel = genai.GenerativeModel(model)
+
+    parts = [system_prompt + "\n\n" + user_prompt]
+    for img_info in images:
+        img = Image.open(img_info["path"])
+        parts.append(img)
+        parts.append(f"[Timestamp: {img_info['timestamp']}]")
+
+    response = gmodel.generate_content(parts)
+    return response.text
+
+
+def _call_openai_vision(
+    system_prompt: str,
+    user_prompt: str,
+    images: List[dict],
+    api_key: str,
+) -> str:
+    """OpenAI GPT-4o-mini Vision 호출."""
+    from openai import OpenAI
+
+    client = OpenAI(api_key=api_key)
+    content = [{"type": "text", "text": user_prompt}]
+    for img_info in images:
+        with open(img_info["path"], "rb") as f:
+            b64 = base64.b64encode(f.read()).decode()
+        content.append({
+            "type": "image_url",
+            "image_url": {"url": f"data:image/jpeg;base64,{b64}"},
+        })
+        content.append({"type": "text", "text": f"[Timestamp: {img_info['timestamp']}]"})
+
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": content},
+        ],
+        temperature=0.3,
+    )
+    return response.choices[0].message.content
+
+
+def _call_claude_vision(
+    system_prompt: str,
+    user_prompt: str,
+    images: List[dict],
+    api_key: str,
+    model: str = "claude-sonnet-4-6",
+) -> str:
+    """Anthropic Claude Vision 호출."""
+    import anthropic
+
+    client = anthropic.Anthropic(api_key=api_key)
+    content = []
+    for img_info in images:
+        with open(img_info["path"], "rb") as f:
+            b64 = base64.b64encode(f.read()).decode()
+        content.append({
+            "type": "image",
+            "source": {"type": "base64", "media_type": "image/jpeg", "data": b64},
+        })
+        content.append({"type": "text", "text": f"[Timestamp: {img_info['timestamp']}]"})
+    content.append({"type": "text", "text": user_prompt})
+
+    response = client.messages.create(
+        model=model,
+        max_tokens=8192,
+        system=system_prompt,
+        messages=[{"role": "user", "content": content}],
+    )
+    return response.content[0].text
+
+
+def _call_vision_llm(
+    system_prompt: str,
+    user_prompt: str,
+    images: List[dict],
+    llm_provider: str,
+    api_key: Optional[str] = None,
+) -> str:
+    """Vision LLM 호출 디스패처 (Rate limit 자동 재시도 포함)."""
+    def _do_call():
+        if llm_provider in ("gemini-flash", "gemini-flash-lite"):
+            key = api_key or os.environ.get("GOOGLE_API_KEY", "")
+            if not key:
+                raise ValueError("Google API 키가 필요합니다. (GOOGLE_API_KEY)")
+            model_id = LLM_MODELS[llm_provider]["model"]
+            return _call_gemini_vision(system_prompt, user_prompt, images, key, model=model_id)
+
+        elif llm_provider == "gpt-4o-mini":
+            key = api_key or os.environ.get("OPENAI_API_KEY", "")
+            if not key:
+                raise ValueError("OpenAI API 키가 필요합니다.")
+            return _call_openai_vision(system_prompt, user_prompt, images, key)
+
+        elif llm_provider in ("claude-sonnet", "claude-opus"):
+            key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+            if not key:
+                raise ValueError("Anthropic API 키가 필요합니다. (ANTHROPIC_API_KEY)")
+            model_id = LLM_MODELS[llm_provider]["model"]
+            return _call_claude_vision(system_prompt, user_prompt, images, key, model=model_id)
+
+        elif llm_provider == "ollama":
+            raise ValueError("Ollama는 Vision(이미지 분석)을 지원하지 않습니다.")
+
+        else:
+            raise ValueError(f"지원하지 않는 Vision LLM: {llm_provider}")
+
+    return _retry_on_rate_limit(_do_call)
+
+
+# ── Rate Limit 재시도 로직 ────────────────────────────────
+
+def _is_rate_limit_error(error: Exception) -> bool:
+    """429 Rate Limit 에러인지 확인한다."""
+    err_str = str(error).lower()
+    err_type = type(error).__name__
+    return (
+        "rate_limit" in err_str
+        or "rate limit" in err_str
+        or "429" in err_str
+        or "resource_exhausted" in err_str
+        or "quota" in err_str
+        or err_type == "RateLimitError"
+    )
+
+
+def _parse_retry_after(error: Exception) -> float:
+    """에러 메시지에서 대기 시간(초)을 추출한다."""
+    err_str = str(error)
+    # "Please try again in 2.129s" 같은 패턴
+    match = re.search(r"try again in (\d+\.?\d*)s", err_str)
+    if match:
+        return float(match.group(1))
+    # "Retry-After: 5" 헤더 패턴
+    match = re.search(r"retry.?after:?\s*(\d+)", err_str, re.IGNORECASE)
+    if match:
+        return float(match.group(1))
+    return 0.0
+
+
+def _retry_on_rate_limit(func, *args, max_retries: int = 3, **kwargs):
+    """Rate limit 에러 시 exponential backoff으로 재시도한다."""
+    for attempt in range(max_retries + 1):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            if not _is_rate_limit_error(e) or attempt >= max_retries:
+                raise
+            # 에러에서 대기 시간 추출, 없으면 exponential backoff
+            wait = _parse_retry_after(e)
+            if wait <= 0:
+                wait = (2 ** attempt) * 2  # 2초, 4초, 8초
+            wait = min(wait + 0.5, 60)  # 여유 0.5초 추가, 최대 60초
+            print(f"⏳ Rate limit 초과, {wait:.1f}초 후 재시도... ({attempt + 1}/{max_retries})")
+            time.sleep(wait)
+
+
+# ── 텍스트 LLM 호출 디스패처 ─────────────────────────────
+
+def _call_llm(
+    system_prompt: str,
+    user_prompt: str,
+    llm_provider: str,
+    api_key: Optional[str] = None,
+    ollama_model: str = "llama3.2",
+) -> str:
+    """텍스트 LLM 호출 디스패처 (Rate limit 자동 재시도 포함)."""
+    def _do_call():
+        if llm_provider == "gpt-4o-mini":
+            key = api_key or os.environ.get("OPENAI_API_KEY", "")
+            if not key:
+                raise ValueError("OpenAI API 키가 필요합니다.")
+            return _call_openai(system_prompt, user_prompt, key)
+
+        elif llm_provider in ("gemini-flash", "gemini-flash-lite"):
+            key = api_key or os.environ.get("GOOGLE_API_KEY", "")
+            if not key:
+                raise ValueError("Google API 키가 필요합니다. (GOOGLE_API_KEY)")
+            model_id = LLM_MODELS[llm_provider]["model"]
+            return _call_gemini(system_prompt, user_prompt, key, model=model_id)
+
+        elif llm_provider == "ollama":
+            return _call_ollama(system_prompt, user_prompt, ollama_model)
+
+        elif llm_provider in ("claude-sonnet", "claude-opus"):
+            key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+            if not key:
+                raise ValueError("Anthropic API 키가 필요합니다. (ANTHROPIC_API_KEY)")
+            model_id = LLM_MODELS[llm_provider]["model"]
+            return _call_claude(system_prompt, user_prompt, key, model=model_id)
+
+        else:
+            raise ValueError(f"지원하지 않는 LLM: {llm_provider}")
+
+    return _retry_on_rate_limit(_do_call)
+
+
+# ── 키프레임 분석 ─────────────────────────────────────────
+
+def analyze_keyframes(
+    keyframe_paths: List[dict],
+    llm_provider: str = "gemini-flash-lite",
+    api_key: Optional[str] = None,
+    on_progress: Optional[Callable] = None,
+    batch_size: int = 10,
+) -> str:
+    """Vision LLM으로 키프레임 이미지를 분석한다.
+
+    keyframe_paths: [{"path": str, "timestamp": str}, ...]
+    반환: 타임스탬프별 설명 텍스트
+    """
+    def _notify(percent: int, detail: str):
+        if on_progress:
+            on_progress({"step": "keyframe_analysis", "percent": percent, "detail": detail})
+
+    model_info = LLM_MODELS.get(llm_provider, {})
+    model_name = model_info.get("name", llm_provider)
+
+    total = len(keyframe_paths)
+    _notify(5, f"{total}개 키프레임을 {model_name}으로 분석 준비 중...")
+
+    all_descriptions = []
+    batches = [keyframe_paths[i:i + batch_size] for i in range(0, total, batch_size)]
+
+    for idx, batch in enumerate(batches):
+        pct = int(10 + (idx / len(batches)) * 80)
+        _notify(pct, f"배치 {idx + 1}/{len(batches)} 분석 중 ({len(batch)}프레임)...")
+
+        try:
+            result = _call_vision_llm(
+                system_prompt=KEYFRAME_ANALYSIS_SYSTEM_PROMPT,
+                user_prompt=KEYFRAME_ANALYSIS_USER_TEMPLATE,
+                images=batch,
+                llm_provider=llm_provider,
+                api_key=api_key,
+            )
+            all_descriptions.append(result.strip())
+        except Exception as e:
+            _notify(pct, f"배치 {idx + 1} 분석 오류: {str(e)}")
+            raise
+
+    _notify(100, f"{total}개 키프레임 분석 완료")
+    return "\n".join(all_descriptions)
+
+
+# ── 메인 함수들 ───────────────────────────────────────────
+
+def _truncate_text(text: str, max_chars: int = 100000) -> tuple:
+    """텍스트가 너무 길면 잘라낸다. (text, truncated) 반환."""
+    if len(text) > max_chars:
+        return text[:max_chars], True
+    return text, False
+
+
+def format_as_markdown(
+    text: str,
+    title: str,
+    llm_provider: str = "gpt-4o-mini",
+    api_key: Optional[str] = None,
+    ollama_model: str = "llama3.2",
+    on_progress: Optional[Callable] = None,
+    keyframe_descriptions: Optional[str] = None,
+) -> str:
+    """Whisper 추출 텍스트를 LLM으로 마크다운으로 정리한다.
+
+    keyframe_descriptions가 주어지면 키프레임 설명을 MD에 통합한다.
+    """
+    def _notify(percent: int, detail: str):
+        if on_progress:
+            on_progress({"step": "format", "percent": percent, "detail": detail})
+
+    model_info = LLM_MODELS.get(llm_provider, {})
+    model_name = model_info.get("name", llm_provider)
+
+    has_keyframes = bool(keyframe_descriptions and keyframe_descriptions.strip())
+    extra = " + 키프레임 컨텍스트" if has_keyframes else ""
+    _notify(10, f"{model_name}에 텍스트{extra} 전송 중...")
+
+    text, truncated = _truncate_text(text)
+    if truncated:
+        _notify(15, f"텍스트가 길어서 앞부분만 정리합니다 ({len(text)}자)")
+
+    _notify(30, f"{model_name} 처리 중...")
+
+    # 키프레임 설명이 있으면 통합 프롬프트 사용
+    if has_keyframes:
+        sys_prompt = FORMAT_SYSTEM_PROMPT_WITH_KEYFRAMES
+        usr_prompt = FORMAT_USER_TEMPLATE_WITH_KEYFRAMES.format(
+            title=title, text=text, keyframe_descriptions=keyframe_descriptions,
+        )
+    else:
+        sys_prompt = FORMAT_SYSTEM_PROMPT
+        usr_prompt = FORMAT_USER_TEMPLATE.format(title=title, text=text)
+
+    try:
+        result = _call_llm(
+            system_prompt=sys_prompt,
+            user_prompt=usr_prompt,
+            llm_provider=llm_provider,
+            api_key=api_key,
+            ollama_model=ollama_model,
+        )
+    except Exception as e:
+        _notify(0, f"LLM 오류: {str(e)}")
+        raise
+
+    if truncated:
+        result += "\n\n---\n> ⚠️ 원본 텍스트가 길어서 일부만 정리되었습니다.\n"
+
+    _notify(100, f"{model_name} 정리 완료")
+    return result
+
+
+def translate_text(
+    text: str,
+    target_lang: str,
+    llm_provider: str = "gpt-4o-mini",
+    api_key: Optional[str] = None,
+    ollama_model: str = "llama3.2",
+    on_progress: Optional[Callable] = None,
+) -> str:
+    """텍스트를 지정 언어로 번역한다."""
+    def _notify(percent: int, detail: str):
+        if on_progress:
+            on_progress({"step": "translate", "percent": percent, "detail": detail})
+
+    lang_name = LANGUAGES.get(target_lang, target_lang)
+    model_info = LLM_MODELS.get(llm_provider, {})
+    model_name = model_info.get("name", llm_provider)
+
+    _notify(10, f"{lang_name}로 번역 준비 중...")
+
+    text, truncated = _truncate_text(text)
+    if truncated:
+        _notify(15, f"텍스트가 길어서 앞부분만 번역합니다 ({len(text)}자)")
+
+    _notify(30, f"{model_name}으로 {lang_name} 번역 중...")
+
+    try:
+        result = _call_llm(
+            system_prompt=TRANSLATE_SYSTEM_PROMPT.format(target_lang=lang_name),
+            user_prompt=TRANSLATE_USER_TEMPLATE.format(target_lang=lang_name, text=text),
+            llm_provider=llm_provider,
+            api_key=api_key,
+            ollama_model=ollama_model,
+        )
+    except Exception as e:
+        _notify(0, f"번역 오류: {str(e)}")
+        raise
+
+    if truncated:
+        result += f"\n\n---\n> ⚠️ 원본 텍스트가 길어서 일부만 번역되었습니다.\n"
+
+    _notify(100, f"{lang_name} 번역 완료")
+    return result

requirements.txt

@@ -0,0 +1,15 @@
+pytubefix>=6.0.0
+openai-whisper>=20231117
+openai>=1.0.0
+fastapi>=0.104.0
+uvicorn>=0.24.0
+jinja2>=3.1.0
+python-multipart>=0.0.6
+pydub>=0.25.1
+python-dotenv>=1.0.0
+# MD 포맷팅용 (선택적, 사용하는 LLM만 설치하면 됨)
+google-generativeai>=0.3.0
+anthropic>=0.18.0
+# 키프레임 분석용 (선택적)
+opencv-python>=4.8.0
+Pillow>=10.0.0

run

@@ -0,0 +1,68 @@
+#!/bin/bash
+# YouTube Script Extractor 실행 스크립트
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$DIR"
+
+# 첫 실행: .env 파일이 없으면 자동 설정
+if [ ! -f .env ]; then
+    echo "=== YouTube Script Extractor 초기 설정 ==="
+    echo ""
+
+    read -p "OpenAI API Key를 입력하세요 (sk-...): " api_key
+    if [ -n "$api_key" ]; then
+        cat > .env << EOF
+OPENAI_API_KEY=$api_key
+DEFAULT_MODE=api
+DEFAULT_MODEL=base
+PORT=8000
+EOF
+        echo ""
+        echo ".env 파일이 생성되었습니다."
+    else
+        cp .env.example .env
+        echo ".env.example을 복사했습니다. 나중에 .env 파일을 직접 수정해주세요."
+    fi
+    echo ""
+fi
+
+# ffmpeg 체크
+if ! command -v ffmpeg &>/dev/null; then
+    echo "ffmpeg이 필요합니다. 설치합니다..."
+    brew install ffmpeg || { echo "ffmpeg 설치 실패. 'brew install ffmpeg'을 직접 실행해주세요."; exit 1; }
+    echo ""
+fi
+
+# Python 의존성 체크
+if ! python3 -c "import yt_dlp" 2>/dev/null; then
+    echo "Python 의존성을 설치합니다..."
+    python3 -m pip install -r requirements.txt || { echo "설치 실패. python3와 pip이 설치되어 있는지 확인해주세요."; exit 1; }
+    echo ""
+fi
+
+# 실행 모드 선택
+case "${1:-}" in
+    web|w)
+        echo "웹 서버를 시작합니다..."
+        python3 web.py
+        ;;
+    "")
+        # URL 없이 실행하면 웹 서버
+        echo "웹 서버를 시작합니다..."
+        python3 web.py
+        ;;
+    http*|www.*)
+        # URL이 주어지면 CLI 모드
+        python3 cli.py "$@"
+        ;;
+    *)
+        echo "사용법:"
+        echo "  ./run                       웹 서버 시작"
+        echo "  ./run web                   웹 서버 시작"
+        echo "  ./run <YouTube URL>         CLI로 스크립트 추출"
+        echo ""
+        echo "CLI 옵션:"
+        echo "  ./run <URL> --mode local    로컬 Whisper 사용"
+        echo "  ./run <URL> --format srt    SRT만 생성"
+        ;;
+esac

templates/index.html

@@ -0,0 +1,1448 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>YouTube Script Extractor</title>
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: #0f0f0f;
+            color: #e1e1e1;
+            min-height: 100vh;
+        }
+
+        .container {
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 40px 20px;
+        }
+
+        h1 {
+            text-align: center;
+            font-size: 28px;
+            margin-bottom: 8px;
+            color: #fff;
+        }
+
+        .subtitle {
+            text-align: center;
+            color: #888;
+            margin-bottom: 40px;
+            font-size: 14px;
+        }
+
+        .card {
+            background: #1a1a1a;
+            border: 1px solid #333;
+            border-radius: 12px;
+            padding: 24px;
+            margin-bottom: 20px;
+        }
+
+        .form-group { margin-bottom: 16px; }
+
+        label {
+            display: block;
+            font-size: 13px;
+            color: #aaa;
+            margin-bottom: 6px;
+            font-weight: 500;
+        }
+
+        input[type="text"], select {
+            width: 100%;
+            padding: 10px 14px;
+            background: #0f0f0f;
+            border: 1px solid #333;
+            border-radius: 8px;
+            color: #fff;
+            font-size: 14px;
+            outline: none;
+            transition: border-color 0.2s;
+        }
+
+        input[type="text"]:focus, select:focus { border-color: #ff4444; }
+
+        .row { display: flex; gap: 12px; }
+        .row .form-group { flex: 1; }
+
+        .checkbox-group {
+            display: flex;
+            gap: 16px;
+            align-items: center;
+        }
+
+        .checkbox-group label {
+            display: flex;
+            align-items: center;
+            gap: 6px;
+            cursor: pointer;
+            color: #e1e1e1;
+            font-size: 14px;
+        }
+
+        input[type="checkbox"] {
+            accent-color: #ff4444;
+            width: 16px;
+            height: 16px;
+        }
+
+        .btn {
+            width: 100%;
+            padding: 12px;
+            background: #ff4444;
+            color: #fff;
+            border: none;
+            border-radius: 8px;
+            font-size: 16px;
+            font-weight: 600;
+            cursor: pointer;
+            transition: background 0.2s;
+        }
+
+        .btn:hover { background: #e03030; }
+        .btn:disabled {
+            background: #333;
+            color: #666;
+            cursor: not-allowed;
+        }
+
+        .mode-note {
+            font-size: 12px;
+            color: #666;
+            margin-top: 4px;
+        }
+
+        /* ========= 진행 상태 ========= */
+        #progress-section { display: none; }
+
+        .steps { display: flex; flex-direction: column; gap: 0; }
+
+        .step {
+            padding: 16px 0;
+            border-bottom: 1px solid #222;
+            color: #555;
+            transition: color 0.3s;
+        }
+
+        .step:last-child { border-bottom: none; }
+        .step.active { color: #fff; }
+        .step.done { color: #4caf50; }
+        .step.error { color: #ff4444; }
+
+        .step-header {
+            display: flex;
+            align-items: center;
+            gap: 12px;
+        }
+
+        .step-icon {
+            width: 28px;
+            height: 28px;
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-size: 14px;
+            flex-shrink: 0;
+            background: #222;
+            color: #555;
+            transition: all 0.3s;
+        }
+
+        .step.active .step-icon {
+            background: #ff4444;
+            color: #fff;
+        }
+
+        .step.done .step-icon {
+            background: #4caf50;
+            color: #fff;
+        }
+
+        .step-title { font-size: 14px; font-weight: 500; }
+
+        .step-percent {
+            margin-left: auto;
+            font-size: 13px;
+            font-weight: 600;
+            font-family: 'SF Mono', Menlo, monospace;
+            color: #555;
+            min-width: 40px;
+            text-align: right;
+        }
+
+        .step.active .step-percent { color: #ff4444; }
+        .step.done .step-percent { color: #4caf50; }
+
+        /* 프로그레스 바 */
+        .step-progress {
+            height: 4px;
+            background: #222;
+            border-radius: 2px;
+            margin: 10px 0 0 40px;
+            overflow: hidden;
+        }
+
+        .step-progress-bar {
+            height: 100%;
+            background: #ff4444;
+            border-radius: 2px;
+            width: 0%;
+            transition: width 0.4s ease;
+        }
+
+        .step.done .step-progress-bar {
+            background: #4caf50;
+            width: 100%;
+        }
+
+        .step-progress-bar.indeterminate {
+            width: 30%;
+            animation: indeterminate 1.5s ease-in-out infinite;
+        }
+
+        @keyframes indeterminate {
+            0% { margin-left: 0%; }
+            50% { margin-left: 70%; }
+            100% { margin-left: 0%; }
+        }
+
+        /* 상세 정보 */
+        .step-detail {
+            font-size: 12px;
+            color: #555;
+            margin: 6px 0 0 40px;
+            min-height: 16px;
+            transition: color 0.3s;
+        }
+
+        .step.active .step-detail { color: #999; }
+        .step.done .step-detail { color: #4caf5099; }
+
+        /* 타이머 + 팁 */
+        .progress-footer {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-top: 20px;
+            padding-top: 16px;
+            border-top: 1px solid #222;
+        }
+
+        .elapsed {
+            font-size: 13px;
+            color: #888;
+            font-family: 'SF Mono', Menlo, monospace;
+        }
+
+        .tip {
+            font-size: 12px;
+            color: #666;
+            font-style: italic;
+            max-width: 60%;
+            text-align: right;
+            animation: fadeInOut 6s ease-in-out infinite;
+        }
+
+        @keyframes fadeInOut {
+            0%, 100% { opacity: 0.4; }
+            50% { opacity: 1; }
+        }
+
+        /* ========= 결과 ========= */
+        #result-section { display: none; }
+
+        .result-banner {
+            background: #1a2e1a;
+            border: 1px solid #2d5a2d;
+            border-radius: 8px;
+            padding: 16px;
+            margin-bottom: 16px;
+            display: flex;
+            align-items: center;
+            gap: 12px;
+        }
+
+        .result-banner-icon { font-size: 24px; flex-shrink: 0; }
+
+        .result-banner-text { flex: 1; }
+
+        .result-banner-title {
+            font-size: 15px;
+            font-weight: 600;
+            color: #4caf50;
+            margin-bottom: 4px;
+        }
+
+        .result-banner-info { font-size: 13px; color: #888; }
+
+        .result-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 12px;
+        }
+
+        .result-title { font-size: 16px; font-weight: 600; color: #fff; }
+
+        .result-lang {
+            font-size: 12px;
+            background: #333;
+            color: #aaa;
+            padding: 4px 10px;
+            border-radius: 12px;
+        }
+
+        .result-text {
+            background: #0f0f0f;
+            border-radius: 8px;
+            padding: 16px;
+            font-size: 14px;
+            line-height: 1.7;
+            max-height: 400px;
+            overflow-y: auto;
+            white-space: pre-wrap;
+            word-break: break-word;
+            color: #ccc;
+        }
+
+        .download-buttons { display: flex; gap: 10px; margin-top: 16px; }
+
+        .btn-download {
+            flex: 1;
+            padding: 12px;
+            background: #1a3a1a;
+            border: 1px solid #2d5a2d;
+            border-radius: 8px;
+            color: #4caf50;
+            font-size: 14px;
+            font-weight: 600;
+            cursor: pointer;
+            text-align: center;
+            text-decoration: none;
+            transition: background 0.2s;
+        }
+
+        .btn-download:hover { background: #2d5a2d; color: #fff; }
+
+        .save-path {
+            font-size: 12px;
+            color: #666;
+            margin-top: 12px;
+            font-family: 'SF Mono', Menlo, monospace;
+            padding: 8px 12px;
+            background: #111;
+            border-radius: 6px;
+        }
+
+        .error-msg {
+            color: #ff4444;
+            padding: 12px;
+            font-size: 14px;
+            background: #2a1515;
+            border-radius: 8px;
+            border: 1px solid #4a2020;
+        }
+
+        .btn-new {
+            width: 100%;
+            padding: 10px;
+            background: transparent;
+            border: 1px solid #444;
+            border-radius: 8px;
+            color: #aaa;
+            font-size: 14px;
+            cursor: pointer;
+            margin-top: 12px;
+            transition: all 0.2s;
+        }
+
+        .btn-new:hover { border-color: #888; color: #fff; }
+
+        /* ========= LLM 옵션 (MD/번역 공용) ========= */
+        .llm-options {
+            display: none;
+            margin-top: 12px;
+            padding: 16px;
+            background: #111;
+            border-radius: 8px;
+            border: 1px solid #2a2a2a;
+        }
+
+        .llm-options.visible { display: block; }
+
+        .llm-options .form-group { margin-bottom: 12px; }
+        .llm-options .form-group:last-child { margin-bottom: 0; }
+
+        .llm-select-desc {
+            font-size: 12px;
+            color: #888;
+            margin-top: 4px;
+        }
+
+        /* ========= 설정 버튼 ========= */
+        .llm-header { display: flex; gap: 8px; align-items: stretch; }
+        .llm-header > div { flex: 1; }
+
+        .btn-settings {
+            padding: 8px 14px;
+            background: #222;
+            border: 1px solid #333;
+            border-radius: 8px;
+            color: #aaa;
+            font-size: 16px;
+            cursor: pointer;
+            transition: all 0.2s;
+            flex-shrink: 0;
+            position: relative;
+        }
+        .btn-settings:hover { background: #333; color: #fff; border-color: #555; }
+        .settings-dot {
+            display: none;
+            position: absolute;
+            top: 4px; right: 4px;
+            width: 8px; height: 8px;
+            border-radius: 50%;
+            background: #4caf50;
+        }
+        .settings-dot.active { display: block; }
+        .workflow-summary {
+            font-size: 12px;
+            color: #4caf50;
+            margin-top: 6px;
+            line-height: 1.5;
+        }
+
+        /* ========= 워크플로우 설정 모달 ========= */
+        .modal-overlay {
+            position: fixed;
+            top: 0; left: 0; right: 0; bottom: 0;
+            background: rgba(0,0,0,0.7);
+            z-index: 1000;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            backdrop-filter: blur(4px);
+        }
+        .modal {
+            background: #1a1a1a;
+            border: 1px solid #333;
+            border-radius: 16px;
+            padding: 28px;
+            width: 540px;
+            max-width: 90vw;
+            max-height: 85vh;
+            overflow-y: auto;
+        }
+        .modal-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 8px;
+        }
+        .modal-header h3 { color: #fff; font-size: 18px; margin: 0; }
+        .modal-close {
+            background: none;
+            border: none;
+            color: #666;
+            font-size: 24px;
+            cursor: pointer;
+            padding: 4px 8px;
+            border-radius: 6px;
+            transition: all 0.2s;
+            line-height: 1;
+        }
+        .modal-close:hover { background: #333; color: #fff; }
+        .modal-desc {
+            color: #888;
+            font-size: 13px;
+            margin-bottom: 20px;
+            line-height: 1.5;
+        }
+        .modal-step-row {
+            border: 1px solid #2a2a2a;
+            border-radius: 10px;
+            padding: 16px;
+            margin-bottom: 12px;
+            background: #111;
+        }
+        .modal-step-label {
+            display: flex;
+            align-items: center;
+            gap: 10px;
+            margin-bottom: 10px;
+        }
+        .modal-step-name {
+            font-size: 14px;
+            font-weight: 600;
+            color: #e1e1e1;
+        }
+        .modal-step-badge {
+            font-size: 11px;
+            padding: 2px 8px;
+            border-radius: 10px;
+            background: #222;
+            color: #666;
+        }
+        .modal-step-badge.custom {
+            background: #1a3a1a;
+            color: #4caf50;
+        }
+        .modal-step-fields { display: flex; flex-direction: column; gap: 8px; }
+        .modal-step-fields select,
+        .modal-step-fields input[type="text"] {
+            width: 100%;
+            padding: 8px 12px;
+            background: #0f0f0f;
+            border: 1px solid #333;
+            border-radius: 6px;
+            color: #fff;
+            font-size: 13px;
+            outline: none;
+        }
+        .modal-step-fields select:focus,
+        .modal-step-fields input[type="text"]:focus { border-color: #ff4444; }
+        .modal-step-sub {
+            margin-top: 10px;
+            padding-top: 10px;
+            border-top: 1px solid #222;
+        }
+        .modal-step-sub label {
+            font-size: 12px;
+            color: #888;
+            margin-bottom: 4px;
+        }
+        .modal-step-sub select,
+        .modal-step-sub input[type="text"] {
+            width: 100%;
+            padding: 6px 10px;
+            background: #0f0f0f;
+            border: 1px solid #333;
+            border-radius: 6px;
+            color: #fff;
+            font-size: 12px;
+            outline: none;
+            margin-bottom: 6px;
+        }
+        .modal-save-btn {
+            margin-top: 8px;
+            padding: 10px;
+            font-size: 14px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>YouTube Script Extractor</h1>
+        <p class="subtitle">YouTube 영상의 음성을 텍스트로 변환합니다</p>
+
+        <div class="card" id="form-section">
+            <div class="form-group">
+                <label>YouTube URL</label>
+                <input type="text" id="url" placeholder="https://www.youtube.com/watch?v=..." onkeydown="if(event.key==='Enter') startTranscription()">
+            </div>
+
+            <div class="row">
+                <div class="form-group">
+                    <label>변환 모드</label>
+                    <select id="mode" onchange="toggleApiKey()">
+                        <option value="api">Whisper API (빠르고 정확)</option>
+                        <option value="local">로컬 Whisper (무료)</option>
+                    </select>
+                </div>
+                <div class="form-group" id="model-group" style="display:none;">
+                    <label>모델 크기</label>
+                    <select id="model_size">
+                        <option value="tiny">tiny (39MB, 가장 빠름)</option>
+                        <option value="base" selected>base (74MB, 균형)</option>
+                        <option value="small">small (244MB, 좋음)</option>
+                        <option value="medium">medium (769MB, 높음)</option>
+                        <option value="large">large (1.5GB, 최고)</option>
+                    </select>
+                </div>
+            </div>
+
+            <div class="form-group" id="api-key-group">
+                <label>OpenAI API Key</label>
+                <input type="text" id="api_key" placeholder="sk-...">
+                <p class="mode-note">서버에 OPENAI_API_KEY 환경변수가 설정되어 있으면 비워둬도 됩니다.</p>
+            </div>
+
+            <div class="form-group">
+                <label>출력 형식</label>
+                <div class="checkbox-group">
+                    <label><input type="checkbox" id="fmt_txt" checked> TXT (텍스트)</label>
+                    <label><input type="checkbox" id="fmt_srt" checked> SRT (자막)</label>
+                    <label><input type="checkbox" id="fmt_md" onchange="toggleLlmOptions()"> MD (AI 정리)</label>
+                    <label><input type="checkbox" id="fmt_translate" onchange="toggleLlmOptions()"> 번역</label>
+                    <label><input type="checkbox" id="fmt_keyframes" onchange="toggleLlmOptions()"> 키프레임 분석</label>
+                </div>
+            </div>
+
+            <!-- LLM 옵션 (MD/번역 공용) -->
+            <div class="llm-options" id="llm-options">
+                <div class="form-group">
+                    <label>기본 LLM <span style="color:#666; font-weight:400;">(모든 AI 단계에 적용)</span></label>
+                    <div class="llm-header">
+                        <div>
+                            <select id="llm-select" onchange="onLLMChange()">
+                                <option value="">로딩 중...</option>
+                            </select>
+                        </div>
+                        <button type="button" class="btn-settings" id="btn-settings" onclick="openSettingsModal()" title="워크플로우 설정">⚙<span class="settings-dot" id="settings-dot"></span></button>
+                    </div>
+                    <p class="llm-select-desc" id="llm-select-desc"></p>
+                    <p class="workflow-summary" id="workflow-summary" style="display:none;"></p>
+                </div>
+                <div class="form-group" id="md-api-key-group" style="display:none;">
+                    <label id="md-api-key-label">LLM API Key</label>
+                    <input type="text" id="md_api_key" placeholder="API 키 입력...">
+                    <p class="mode-note" id="md-api-key-note"></p>
+                </div>
+                <div class="form-group" id="md-ollama-group" style="display:none;">
+                    <label>Ollama 모델</label>
+                    <input type="text" id="md_ollama_model" value="llama3.2" placeholder="llama3.2">
+                    <p class="mode-note">ollama pull &lt;모델명&gt; 으로 먼저 다운로드 필요</p>
+                </div>
+                <div class="form-group" id="translate-lang-group" style="display:none;">
+                    <label>번역 언어</label>
+                    <select id="translate-lang">
+                        <option value="">로딩 중...</option>
+                    </select>
+                </div>
+            </div>
+
+            <div class="form-group">
+                <label>저장 경로</label>
+                <input type="text" id="output_dir" placeholder="./output" value="./output">
+                <p class="mode-note">비워두면 기본 경로(./output)에 저장됩니다. 절대 경로도 사용 가능합니다 (예: /Users/이름/Desktop)</p>
+            </div>
+
+            <button class="btn" id="submit-btn" onclick="startTranscription()">스크립트 추출 시작</button>
+        </div>
+
+        <!-- 진행 상태 -->
+        <div class="card" id="progress-section">
+            <div class="steps">
+                <div class="step" id="step-download" data-step="download">
+                    <div class="step-header">
+                        <div class="step-icon">1</div>
+                        <div class="step-title">오디오 다운로드</div>
+                        <div class="step-percent" id="pct-download"></div>
+                    </div>
+                    <div class="step-progress"><div class="step-progress-bar" id="bar-download"></div></div>
+                    <div class="step-detail" id="detail-download">YouTube에서 오디오를 추출합니다</div>
+                </div>
+                <div class="step" id="step-keyframe_extract" data-step="keyframe_extract" style="display:none;">
+                    <div class="step-header">
+                        <div class="step-icon">2</div>
+                        <div class="step-title">키프레임 추출</div>
+                        <div class="step-percent" id="pct-keyframe_extract"></div>
+                    </div>
+                    <div class="step-progress"><div class="step-progress-bar" id="bar-keyframe_extract"></div></div>
+                    <div class="step-detail" id="detail-keyframe_extract">영상에서 주요 장면을 추출합니다</div>
+                </div>
+                <div class="step" id="step-keyframe_analysis" data-step="keyframe_analysis" style="display:none;">
+                    <div class="step-header">
+                        <div class="step-icon">3</div>
+                        <div class="step-title">키프레임 분석</div>
+                        <div class="step-percent" id="pct-keyframe_analysis"></div>
+                    </div>
+                    <div class="step-progress"><div class="step-progress-bar" id="bar-keyframe_analysis"></div></div>
+                    <div class="step-detail" id="detail-keyframe_analysis">Vision AI로 화면을 분석합니다</div>
+                </div>
+                <div class="step" id="step-transcribe" data-step="transcribe">
+                    <div class="step-header">
+                        <div class="step-icon">2</div>
+                        <div class="step-title">음성 인식</div>
+                        <div class="step-percent" id="pct-transcribe"></div>
+                    </div>
+                    <div class="step-progress"><div class="step-progress-bar" id="bar-transcribe"></div></div>
+                    <div class="step-detail" id="detail-transcribe">Whisper로 음성을 텍스트로 변환합니다</div>
+                </div>
+                <div class="step" id="step-format" data-step="format" style="display:none;">
+                    <div class="step-header">
+                        <div class="step-icon">3</div>
+                        <div class="step-title">AI 마크다운 정리</div>
+                        <div class="step-percent" id="pct-format"></div>
+                    </div>
+                    <div class="step-progress"><div class="step-progress-bar" id="bar-format"></div></div>
+                    <div class="step-detail" id="detail-format">LLM으로 텍스트를 구조화합니다</div>
+                </div>
+                <div class="step" id="step-translate" data-step="translate" style="display:none;">
+                    <div class="step-header">
+                        <div class="step-icon">4</div>
+                        <div class="step-title">번역</div>
+                        <div class="step-percent" id="pct-translate"></div>
+                    </div>
+                    <div class="step-progress"><div class="step-progress-bar" id="bar-translate"></div></div>
+                    <div class="step-detail" id="detail-translate">선택한 언어로 번역합니다</div>
+                </div>
+                <div class="step" id="step-save" data-step="save">
+                    <div class="step-header">
+                        <div class="step-icon" id="icon-save">3</div>
+                        <div class="step-title">파일 저장</div>
+                        <div class="step-percent" id="pct-save"></div>
+                    </div>
+                    <div class="step-progress"><div class="step-progress-bar" id="bar-save"></div></div>
+                    <div class="step-detail" id="detail-save">결과 파일을 생성합니다</div>
+                </div>
+            </div>
+            <div class="progress-footer">
+                <div class="elapsed" id="elapsed"></div>
+                <div class="tip" id="tip"></div>
+            </div>
+        </div>
+
+        <!-- 결과 -->
+        <div class="card" id="result-section">
+            <div class="result-banner">
+                <div class="result-banner-icon">&#10003;</div>
+                <div class="result-banner-text">
+                    <div class="result-banner-title">스크립트 추출 완료</div>
+                    <div class="result-banner-info" id="result-info"></div>
+                </div>
+            </div>
+            <div class="result-header">
+                <span class="result-title" id="result-title"></span>
+                <span class="result-lang" id="result-lang"></span>
+            </div>
+            <div class="result-text" id="result-text"></div>
+            <div class="download-buttons" id="download-buttons"></div>
+            <div class="save-path" id="save-path"></div>
+            <button class="btn-new" onclick="resetForm()">새 영상 추출하기</button>
+        </div>
+
+        <!-- 에러 -->
+        <div class="card" id="error-section" style="display:none;">
+            <div class="error-msg" id="error-msg"></div>
+            <button class="btn-new" onclick="resetForm()">다시 시도하기</button>
+        </div>
+    </div>
+
+    <!-- 워크플로우 설정 모달 -->
+    <div class="modal-overlay" id="settings-modal" style="display:none;" onclick="if(event.target===this)closeSettingsModal()">
+        <div class="modal">
+            <div class="modal-header">
+                <h3>워크플로우 설정</h3>
+                <button class="modal-close" onclick="closeSettingsModal()">&times;</button>
+            </div>
+            <p class="modal-desc">각 단계별로 다른 LLM을 지정할 수 있습니다.<br>비워두면 기본 LLM(<strong id="modal-global-llm-name" style="color:#e1e1e1;">—</strong>)을 사용합니다.</p>
+
+            <!-- MD 정리 -->
+            <div class="modal-step-row">
+                <div class="modal-step-label">
+                    <span class="modal-step-name">MD 정리</span>
+                    <span class="modal-step-badge" id="badge-format">기본 LLM</span>
+                </div>
+                <div class="modal-step-fields">
+                    <select id="modal-format-llm" onchange="onModalLLMChange('format')">
+                        <option value="">기본 LLM 사용</option>
+                    </select>
+                    <input type="text" id="modal-format-api-key" placeholder="API Key (비워두면 환경변수 사용)" style="display:none;">
+                </div>
+            </div>
+
+            <!-- 번역 -->
+            <div class="modal-step-row">
+                <div class="modal-step-label">
+                    <span class="modal-step-name">번역</span>
+                    <span class="modal-step-badge" id="badge-translate">기본 LLM</span>
+                </div>
+                <div class="modal-step-fields">
+                    <select id="modal-translate-llm" onchange="onModalLLMChange('translate')">
+                        <option value="">기본 LLM 사용</option>
+                    </select>
+                    <input type="text" id="modal-translate-api-key" placeholder="API Key (비워두면 환경변수 사용)" style="display:none;">
+                </div>
+            </div>
+
+            <!-- 키프레임 분석 -->
+            <div class="modal-step-row">
+                <div class="modal-step-label">
+                    <span class="modal-step-name">키프레임 분석</span>
+                    <span class="modal-step-badge" id="badge-keyframe">기본 LLM</span>
+                </div>
+                <div class="modal-step-fields">
+                    <select id="modal-keyframe-llm" onchange="onModalLLMChange('keyframe')">
+                        <option value="">기본 LLM 사용 (Vision 지원 필요)</option>
+                    </select>
+                    <input type="text" id="modal-keyframe-api-key" placeholder="API Key (비워두면 환경변수 사용)" style="display:none;">
+                </div>
+                <div class="modal-step-sub">
+                    <label>추출 방식</label>
+                    <select id="keyframe-method" onchange="onKeyframeMethodChange()">
+                        <option value="scene">장면 전환 감지 (추천)</option>
+                        <option value="interval">고정 간격</option>
+                    </select>
+                    <div id="keyframe-interval-group" style="display:none;">
+                        <label>간격 (초)</label>
+                        <input type="text" id="keyframe-interval" value="30" placeholder="30">
+                    </div>
+                </div>
+            </div>
+
+            <button class="btn modal-save-btn" onclick="saveModalSettings()">설정 저장</button>
+        </div>
+    </div>
+
+    <script>
+        let timerInterval = null;
+        let startTime = null;
+        let tipInterval = null;
+        let selectedLLM = 'gpt-4o-mini';
+        let llmModels = [];
+        let languages = [];
+        let llmLoaded = false;
+        let langLoaded = false;
+        let visionModels = [];
+        let visionLoaded = false;
+
+        // 단계별 LLM 설정 (모달에서 관리)
+        let perStepConfig = {
+            format:    { llm: '', apiKey: '' },
+            translate: { llm: '', apiKey: '' },
+            keyframe:  { llm: '', apiKey: '', method: 'scene', interval: 30 },
+        };
+
+        const TIPS = [
+            "Whisper는 90개 이상의 언어를 자동으로 감지합니다",
+            "SRT 파일은 대부분의 동영상 플레이어에서 자막으로 사용할 수 있습니다",
+            "영상이 길수록 변환 시간이 오래 걸립니다",
+            "API 모드는 로컬 모드보다 보통 5~10배 빠릅니다",
+            "TXT 파일은 텍스트 편집기에서 바로 열 수 있습니다",
+            "추출된 스크립트는 ./output 폴더에 저장됩니다",
+            "로컬 모드는 인터넷 없이도 사용 가능합니다",
+            "Whisper API 비용은 1분당 약 $0.006입니다",
+            "MD 출력은 LLM이 텍스트를 깔끔하게 구조화합니다",
+            "Ollama는 로컬에서 무료로 LLM을 실행할 수 있습니다",
+            "번역 기능으로 원본과 번역본을 동시에 생성할 수 있습니다",
+            "키프레임 분석으로 발표 슬라이드나 화면 내용을 MD에 포함할 수 있습니다",
+            "워크플로우 설정에서 단계별로 다른 LLM을 지정할 수 있습니다",
+            "키프레임 분석에 Gemini Flash를 사용하면 무료입니다",
+        ];
+
+        // 다운로드 버튼 라벨 매핑
+        const FMT_LABELS = {
+            'txt': 'TXT',
+            'srt': 'SRT',
+            'md': 'MD',
+        };
+
+        let STEP_ORDER = ['download', 'transcribe', 'save'];
+
+        function getStepOrder() {
+            const useMd = document.getElementById('fmt_md').checked;
+            const useTranslate = document.getElementById('fmt_translate').checked;
+            const useKeyframes = document.getElementById('fmt_keyframes').checked;
+            const order = ['download'];
+            if (useKeyframes) {
+                order.push('keyframe_extract');
+                order.push('keyframe_analysis');
+            }
+            order.push('transcribe');
+            if (useMd) order.push('format');
+            if (useTranslate) order.push('translate');
+            order.push('save');
+            return order;
+        }
+
+        function needsLLM() {
+            return document.getElementById('fmt_md').checked ||
+                   document.getElementById('fmt_translate').checked ||
+                   document.getElementById('fmt_keyframes').checked;
+        }
+
+        function toggleApiKey() {
+            const mode = document.getElementById('mode').value;
+            document.getElementById('api-key-group').style.display = mode === 'api' ? '' : 'none';
+            document.getElementById('model-group').style.display = mode === 'local' ? '' : 'none';
+        }
+
+        function toggleLlmOptions() {
+            const opts = document.getElementById('llm-options');
+            const translateChecked = document.getElementById('fmt_translate').checked;
+            const keyframesChecked = document.getElementById('fmt_keyframes').checked;
+
+            if (needsLLM()) {
+                opts.classList.add('visible');
+                if (!llmLoaded) loadLLMModels();
+                if (translateChecked && !langLoaded) loadLanguages();
+                if (keyframesChecked && !visionLoaded) loadVisionModels();
+            } else {
+                opts.classList.remove('visible');
+            }
+
+            // 번역 언어 선택 표시/숨기기
+            document.getElementById('translate-lang-group').style.display =
+                translateChecked ? '' : 'none';
+        }
+
+        async function loadLLMModels() {
+            try {
+                const res = await fetch('/api/llm-models?sort=price');
+                const data = await res.json();
+                llmModels = data.models;
+                llmLoaded = true;
+                renderLLMDropdown();
+            } catch (e) {
+                console.error('LLM 모델 로딩 실패:', e);
+            }
+        }
+
+        async function loadLanguages() {
+            try {
+                const res = await fetch('/api/languages');
+                const data = await res.json();
+                languages = data.languages;
+                langLoaded = true;
+                renderLanguageDropdown();
+            } catch (e) {
+                console.error('언어 목록 로딩 실패:', e);
+            }
+        }
+
+        function renderLLMDropdown() {
+            const select = document.getElementById('llm-select');
+            select.innerHTML = '';
+            llmModels.forEach(model => {
+                const opt = document.createElement('option');
+                opt.value = model.id;
+                opt.textContent = model.version
+                    ? `${model.name}  [${model.version}]`
+                    : model.name;
+                if (model.id === selectedLLM) opt.selected = true;
+                select.appendChild(opt);
+            });
+            onLLMChange();
+        }
+
+        function renderLanguageDropdown() {
+            const select = document.getElementById('translate-lang');
+            select.innerHTML = '';
+            languages.forEach(lang => {
+                const opt = document.createElement('option');
+                opt.value = lang.code;
+                opt.textContent = `${lang.name} (${lang.code})`;
+                select.appendChild(opt);
+            });
+        }
+
+        function onLLMChange() {
+            const select = document.getElementById('llm-select');
+            selectedLLM = select.value;
+            const model = llmModels.find(m => m.id === selectedLLM);
+            if (!model) return;
+
+            // 설명 텍스트 업데이트
+            document.getElementById('llm-select-desc').textContent = model.description;
+
+            // API 키 / Ollama 모델 UI 업데이트
+            const keyGroup = document.getElementById('md-api-key-group');
+            const ollamaGroup = document.getElementById('md-ollama-group');
+
+            if (selectedLLM === 'ollama') {
+                keyGroup.style.display = 'none';
+                ollamaGroup.style.display = '';
+            } else if (model.needs_key) {
+                keyGroup.style.display = '';
+                ollamaGroup.style.display = 'none';
+                const envKey = model.env_key || '';
+                document.getElementById('md-api-key-label').textContent = model.name + ' API Key';
+                document.getElementById('md-api-key-note').textContent =
+                    envKey ? `서버에 ${envKey} 환경변수가 설정되어 있으면 비워둬도 됩니다.` : '';
+            } else {
+                keyGroup.style.display = 'none';
+                ollamaGroup.style.display = 'none';
+            }
+
+            // 워크플로우 요약 업데이트 (기본 LLM 변경 시 "기본 LLM 사용" 뱃지도 갱신)
+            updateWorkflowSummary();
+        }
+
+        function startTimer() {
+            startTime = Date.now();
+            timerInterval = setInterval(() => {
+                const sec = Math.floor((Date.now() - startTime) / 1000);
+                const min = Math.floor(sec / 60);
+                const s = sec % 60;
+                document.getElementById('elapsed').textContent =
+                    min > 0 ? `${min}분 ${s}초 경과` : `${s}초 경과`;
+            }, 1000);
+        }
+
+        function stopTimer() {
+            if (timerInterval) clearInterval(timerInterval);
+            if (tipInterval) clearInterval(tipInterval);
+        }
+
+        function startTips() {
+            let tipIdx = Math.floor(Math.random() * TIPS.length);
+            const tipEl = document.getElementById('tip');
+            tipEl.textContent = TIPS[tipIdx];
+            tipInterval = setInterval(() => {
+                tipIdx = (tipIdx + 1) % TIPS.length;
+                tipEl.style.opacity = '0';
+                setTimeout(() => {
+                    tipEl.textContent = TIPS[tipIdx];
+                    tipEl.style.opacity = '';
+                }, 300);
+            }, 6000);
+        }
+
+        function updateStep(step, percent, detail) {
+            const stepEl = document.getElementById('step-' + step);
+            const barEl = document.getElementById('bar-' + step);
+            const pctEl = document.getElementById('pct-' + step);
+            const detailEl = document.getElementById('detail-' + step);
+
+            if (!stepEl) return;
+
+            // 현재 스텝을 active로
+            const stepIdx = STEP_ORDER.indexOf(step);
+            STEP_ORDER.forEach((s, i) => {
+                const el = document.getElementById('step-' + s);
+                if (!el) return;
+                const icon = el.querySelector('.step-icon');
+                if (i < stepIdx) {
+                    el.className = 'step done';
+                    icon.innerHTML = '&#10003;';
+                } else if (i === stepIdx) {
+                    el.className = 'step active';
+                    icon.textContent = String(i + 1);
+                }
+            });
+
+            // 프로그레스 바
+            if (percent < 0) {
+                barEl.className = 'step-progress-bar indeterminate';
+                barEl.style.width = '';
+                pctEl.textContent = '';
+            } else {
+                barEl.className = 'step-progress-bar';
+                barEl.style.width = percent + '%';
+                pctEl.textContent = percent + '%';
+            }
+
+            if (detail) {
+                detailEl.textContent = detail;
+            }
+
+            if (percent >= 100) {
+                stepEl.className = 'step done';
+                stepEl.querySelector('.step-icon').innerHTML = '&#10003;';
+                pctEl.textContent = '100%';
+            }
+        }
+
+        function setAllStepsDone() {
+            STEP_ORDER.forEach(step => {
+                const el = document.getElementById('step-' + step);
+                if (!el) return;
+                el.className = 'step done';
+                el.querySelector('.step-icon').innerHTML = '&#10003;';
+                document.getElementById('bar-' + step).style.width = '100%';
+                document.getElementById('bar-' + step).className = 'step-progress-bar';
+                document.getElementById('pct-' + step).textContent = '100%';
+            });
+        }
+
+        function resetForm() {
+            document.getElementById('form-section').style.display = 'block';
+            document.getElementById('progress-section').style.display = 'none';
+            document.getElementById('result-section').style.display = 'none';
+            document.getElementById('error-section').style.display = 'none';
+            document.getElementById('submit-btn').disabled = false;
+            document.getElementById('submit-btn').textContent = '스크립트 추출 시작';
+            stopTimer();
+            document.getElementById('elapsed').textContent = '';
+            document.getElementById('tip').textContent = '';
+
+            // 선택적 스텝 숨기기
+            document.getElementById('step-format').style.display = 'none';
+            document.getElementById('step-translate').style.display = 'none';
+            document.getElementById('step-keyframe_extract').style.display = 'none';
+            document.getElementById('step-keyframe_analysis').style.display = 'none';
+
+            const allSteps = ['download', 'keyframe_extract', 'keyframe_analysis', 'transcribe', 'format', 'translate', 'save'];
+            allSteps.forEach((step, i) => {
+                const el = document.getElementById('step-' + step);
+                if (!el) return;
+                el.className = 'step';
+                el.querySelector('.step-icon').textContent = String(i + 1);
+                document.getElementById('bar-' + step).style.width = '0%';
+                document.getElementById('bar-' + step).className = 'step-progress-bar';
+                document.getElementById('pct-' + step).textContent = '';
+            });
+            document.getElementById('detail-download').textContent = 'YouTube에서 오디오를 추출합니다';
+            document.getElementById('detail-keyframe_extract').textContent = '영상에서 주요 장면을 추출합니다';
+            document.getElementById('detail-keyframe_analysis').textContent = 'Vision AI로 화면을 분석합니다';
+            document.getElementById('detail-transcribe').textContent = 'Whisper로 음성을 텍스트로 변환합니다';
+            document.getElementById('detail-format').textContent = 'LLM으로 텍스트를 구조화합니다';
+            document.getElementById('detail-translate').textContent = '선택한 언어로 번역합니다';
+            document.getElementById('detail-save').textContent = '결과 파일을 생성합니다';
+        }
+
+        function getDownloadLabel(fmt) {
+            // txt_ko → "TXT (한국어)", md_zhcn → "MD (中文(简体))"
+            if (fmt.includes('_')) {
+                const parts = fmt.split('_');
+                const baseFmt = parts[0].toUpperCase();
+                const langCode = parts.slice(1).join('_');
+                // 언어 코드를 원래 형태로 복원 시도 (zhcn → zh-CN 등)
+                const langEntry = languages.find(l =>
+                    l.code.replace('-', '').toLowerCase() === langCode.toLowerCase()
+                );
+                const langName = langEntry ? langEntry.name : langCode.toUpperCase();
+                return `${baseFmt} (${langName})`;
+            }
+            return (FMT_LABELS[fmt] || fmt.toUpperCase());
+        }
+
+        async function startTranscription() {
+            const url = document.getElementById('url').value.trim();
+            if (!url) { alert('YouTube URL을 입력해주세요.'); return; }
+
+            const mode = document.getElementById('mode').value;
+            const apiKey = document.getElementById('api_key').value.trim();
+            const modelSize = document.getElementById('model_size').value;
+            const outputDir = document.getElementById('output_dir').value.trim() || './output';
+            const formats = [];
+            if (document.getElementById('fmt_txt').checked) formats.push('txt');
+            if (document.getElementById('fmt_srt').checked) formats.push('srt');
+            if (document.getElementById('fmt_md').checked) formats.push('md');
+
+            const useTranslate = document.getElementById('fmt_translate').checked;
+            const translateLang = useTranslate ? document.getElementById('translate-lang').value : '';
+            const enableKeyframes = document.getElementById('fmt_keyframes').checked;
+
+            if (formats.length === 0 && !useTranslate) {
+                alert('출력 형식을 하나 이상 선택해주세요.');
+                return;
+            }
+
+            // LLM 파라미터 (MD 또는 번역 사용 시)
+            const useLlm = needsLLM();
+            const mdLlm = useLlm ? selectedLLM : '';
+            const mdApiKey = useLlm ? document.getElementById('md_api_key').value.trim() : '';
+            const mdOllamaModel = useLlm ? document.getElementById('md_ollama_model').value.trim() || 'llama3.2' : 'llama3.2';
+
+            // STEP_ORDER를 동적으로 설정
+            STEP_ORDER = getStepOrder();
+
+            // 선택적 스텝 표시/숨기기 + 아이콘 번호 조정
+            const formatStep = document.getElementById('step-format');
+            const translateStep = document.getElementById('step-translate');
+            const keyExtStep = document.getElementById('step-keyframe_extract');
+            const keyAnalStep = document.getElementById('step-keyframe_analysis');
+            const useMd = formats.includes('md');
+
+            formatStep.style.display = useMd ? '' : 'none';
+            translateStep.style.display = useTranslate ? '' : 'none';
+            keyExtStep.style.display = enableKeyframes ? '' : 'none';
+            keyAnalStep.style.display = enableKeyframes ? '' : 'none';
+
+            // 스텝 번호 재배정
+            STEP_ORDER.forEach((s, i) => {
+                const el = document.getElementById('step-' + s);
+                if (el) el.querySelector('.step-icon').textContent = String(i + 1);
+            });
+
+            const btn = document.getElementById('submit-btn');
+            btn.disabled = true;
+            btn.textContent = '처리 중...';
+
+            document.getElementById('form-section').style.display = 'none';
+            document.getElementById('progress-section').style.display = 'block';
+            document.getElementById('result-section').style.display = 'none';
+            document.getElementById('error-section').style.display = 'none';
+
+            startTimer();
+            startTips();
+
+            try {
+                const res = await fetch('/api/transcribe', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        url, mode, api_key: apiKey, model_size: modelSize,
+                        formats, output_dir: outputDir,
+                        md_llm: mdLlm, md_api_key: mdApiKey, md_ollama_model: mdOllamaModel,
+                        translate_lang: translateLang,
+                        // Per-step LLM overrides (모달 설정)
+                        format_llm: perStepConfig.format.llm,
+                        format_api_key: perStepConfig.format.apiKey,
+                        translate_llm: perStepConfig.translate.llm,
+                        translate_api_key: perStepConfig.translate.apiKey,
+                        keyframe_llm: perStepConfig.keyframe.llm,
+                        keyframe_api_key: perStepConfig.keyframe.apiKey,
+                        // 키프레임 옵션
+                        enable_keyframes: enableKeyframes,
+                        keyframe_method: perStepConfig.keyframe.method,
+                        keyframe_interval: parseInt(perStepConfig.keyframe.interval) || 30,
+                    }),
+                });
+                const data = await res.json();
+
+                if (data.error) {
+                    showError(data.error);
+                    return;
+                }
+
+                const jobId = data.job_id;
+                const eventSource = new EventSource(`/api/stream/${jobId}`);
+
+                eventSource.onmessage = (event) => {
+                    const msg = JSON.parse(event.data);
+
+                    if (msg.type === 'progress') {
+                        if (msg.step && msg.percent !== undefined) {
+                            updateStep(msg.step, msg.percent, msg.detail || '');
+                        }
+                    } else if (msg.type === 'completed') {
+                        eventSource.close();
+                        stopTimer();
+                        setAllStepsDone();
+                        setTimeout(() => showResult(msg.result), 500);
+                    } else if (msg.type === 'error') {
+                        eventSource.close();
+                        stopTimer();
+                        showError(msg.message);
+                    }
+                };
+
+                eventSource.onerror = () => {
+                    eventSource.close();
+                    stopTimer();
+                    showError('서버 연결이 끊어졌습니다. 서버가 실행 중인지 확인해주세요.');
+                };
+            } catch (err) {
+                stopTimer();
+                showError(`요청 실패: ${err.message}`);
+            }
+        }
+
+        function showError(message) {
+            document.getElementById('progress-section').style.display = 'none';
+            document.getElementById('error-section').style.display = 'block';
+            document.getElementById('error-msg').textContent = message;
+        }
+
+        function showResult(result) {
+            document.getElementById('progress-section').style.display = 'none';
+            document.getElementById('result-section').style.display = 'block';
+
+            const elapsed = Math.floor((Date.now() - startTime) / 1000);
+            const min = Math.floor(elapsed / 60);
+            const sec = elapsed % 60;
+            const timeStr = min > 0 ? `${min}분 ${sec}초` : `${sec}초`;
+
+            document.getElementById('result-info').textContent =
+                `감지 언어: ${result.language} | 소요 시간: ${timeStr}`;
+            document.getElementById('result-title').textContent = result.title;
+            document.getElementById('result-lang').textContent = result.language;
+            document.getElementById('result-text').textContent = result.text;
+
+            const downloadBtns = document.getElementById('download-buttons');
+            downloadBtns.innerHTML = '';
+            const filenames = [];
+            const dirParam = result.output_dir_raw ? `?dir=${encodeURIComponent(result.output_dir_raw)}` : '';
+            for (const [fmt, filename] of Object.entries(result.files)) {
+                filenames.push(filename);
+                const a = document.createElement('a');
+                a.href = `/api/download/${encodeURIComponent(filename)}${dirParam}`;
+                a.className = 'btn-download';
+                a.download = filename;
+                a.textContent = `${getDownloadLabel(fmt)} 다운로드`;
+                downloadBtns.appendChild(a);
+            }
+
+            const dir = result.output_dir || './output';
+            document.getElementById('save-path').textContent =
+                '저장 위치: ' + filenames.map(f => dir + '/' + f).join(', ');
+        }
+        // ========= Vision 모델 로딩 =========
+        async function loadVisionModels() {
+            try {
+                const res = await fetch('/api/vision-models?sort=price');
+                const data = await res.json();
+                visionModels = data.models;
+                visionLoaded = true;
+            } catch (e) {
+                console.error('Vision 모델 로딩 실패:', e);
+            }
+        }
+
+        // ========= 워크플로우 설정 모달 =========
+        function openSettingsModal() {
+            // 모달 열기 전 모델 데이터 로딩 확인
+            if (!llmLoaded) loadLLMModels().then(() => populateModalDropdowns());
+            if (!visionLoaded) loadVisionModels().then(() => populateModalDropdowns());
+            populateModalDropdowns();
+            restoreModalFromConfig();
+            // 기본 LLM 이름 표시
+            const globalModel = llmModels.find(m => m.id === selectedLLM);
+            document.getElementById('modal-global-llm-name').textContent =
+                globalModel ? globalModel.name : selectedLLM;
+            document.getElementById('settings-modal').style.display = 'flex';
+        }
+
+        function closeSettingsModal() {
+            document.getElementById('settings-modal').style.display = 'none';
+        }
+
+        function populateModalDropdowns() {
+            const globalModel = llmModels.find(m => m.id === selectedLLM);
+            const globalName = globalModel ? globalModel.name : '기본 LLM';
+
+            // MD 정리 / 번역 드롭다운 (전체 LLM)
+            ['format', 'translate'].forEach(step => {
+                const select = document.getElementById(`modal-${step}-llm`);
+                const currentVal = select.value;
+                select.innerHTML = `<option value="">기본 LLM 사용 (${globalName})</option>`;
+                llmModels.forEach(model => {
+                    const opt = document.createElement('option');
+                    opt.value = model.id;
+                    opt.textContent = model.version
+                        ? `${model.name}  [${model.version}]`
+                        : model.name;
+                    select.appendChild(opt);
+                });
+                select.value = currentVal || '';
+            });
+
+            // 키프레임 드롭다운 (Vision 지원 모델만)
+            const kfSelect = document.getElementById('modal-keyframe-llm');
+            const kfVal = kfSelect.value;
+            const isGlobalVision = globalModel && globalModel.supports_vision !== false;
+            kfSelect.innerHTML = isGlobalVision
+                ? `<option value="">기본 LLM 사용 (${globalName})</option>`
+                : `<option value="">선택 필요 (기본 LLM이 Vision 미지원)</option>`;
+            visionModels.forEach(model => {
+                const opt = document.createElement('option');
+                opt.value = model.id;
+                opt.textContent = model.version
+                    ? `${model.name}  [${model.version}]`
+                    : model.name;
+                kfSelect.appendChild(opt);
+            });
+            kfSelect.value = kfVal || '';
+
+            updateModalBadges();
+        }
+
+        function restoreModalFromConfig() {
+            document.getElementById('modal-format-llm').value = perStepConfig.format.llm;
+            document.getElementById('modal-format-api-key').value = perStepConfig.format.apiKey;
+            document.getElementById('modal-translate-llm').value = perStepConfig.translate.llm;
+            document.getElementById('modal-translate-api-key').value = perStepConfig.translate.apiKey;
+            document.getElementById('modal-keyframe-llm').value = perStepConfig.keyframe.llm;
+            document.getElementById('modal-keyframe-api-key').value = perStepConfig.keyframe.apiKey;
+            document.getElementById('keyframe-method').value = perStepConfig.keyframe.method;
+            document.getElementById('keyframe-interval').value = perStepConfig.keyframe.interval;
+
+            onKeyframeMethodChange();
+            ['format', 'translate', 'keyframe'].forEach(s => onModalLLMChange(s));
+            updateModalBadges();
+        }
+
+        function onModalLLMChange(step) {
+            const select = document.getElementById(`modal-${step}-llm`);
+            const apiKeyInput = document.getElementById(`modal-${step}-api-key`);
+            const val = select.value;
+
+            if (val && val !== 'ollama') {
+                // 선택한 모델의 needs_key 확인
+                const allModels = step === 'keyframe' ? visionModels : llmModels;
+                const model = allModels.find(m => m.id === val);
+                if (model && model.needs_key) {
+                    apiKeyInput.style.display = '';
+                    apiKeyInput.placeholder = model.env_key
+                        ? `API Key (${model.env_key} 환경변수가 있으면 생략 가능)`
+                        : 'API Key 입력...';
+                } else {
+                    apiKeyInput.style.display = 'none';
+                }
+            } else {
+                apiKeyInput.style.display = 'none';
+            }
+            updateModalBadges();
+        }
+
+        function updateModalBadges() {
+            const globalModel = llmModels.find(m => m.id === selectedLLM);
+            const globalName = globalModel ? globalModel.name : '기본';
+
+            ['format', 'translate', 'keyframe'].forEach(step => {
+                const select = document.getElementById(`modal-${step}-llm`);
+                const badge = document.getElementById(`badge-${step}`);
+                if (select.value) {
+                    const allModels = step === 'keyframe' ? visionModels : llmModels;
+                    const model = allModels.find(m => m.id === select.value);
+                    badge.textContent = model ? model.name : select.value;
+                    badge.className = 'modal-step-badge custom';
+                } else {
+                    badge.textContent = globalName;
+                    badge.className = 'modal-step-badge';
+                }
+            });
+        }
+
+        function onKeyframeMethodChange() {
+            const method = document.getElementById('keyframe-method').value;
+            document.getElementById('keyframe-interval-group').style.display =
+                method === 'interval' ? '' : 'none';
+        }
+
+        function saveModalSettings() {
+            perStepConfig.format.llm = document.getElementById('modal-format-llm').value;
+            perStepConfig.format.apiKey = document.getElementById('modal-format-api-key').value.trim();
+            perStepConfig.translate.llm = document.getElementById('modal-translate-llm').value;
+            perStepConfig.translate.apiKey = document.getElementById('modal-translate-api-key').value.trim();
+            perStepConfig.keyframe.llm = document.getElementById('modal-keyframe-llm').value;
+            perStepConfig.keyframe.apiKey = document.getElementById('modal-keyframe-api-key').value.trim();
+            perStepConfig.keyframe.method = document.getElementById('keyframe-method').value;
+            perStepConfig.keyframe.interval = parseInt(document.getElementById('keyframe-interval').value) || 30;
+
+            updateWorkflowSummary();
+            closeSettingsModal();
+        }
+
+        function updateWorkflowSummary() {
+            const dot = document.getElementById('settings-dot');
+            const summary = document.getElementById('workflow-summary');
+
+            // 오버라이드가 있는지 확인
+            const overrides = [];
+            const getModelName = (id, models) => {
+                const m = models.find(x => x.id === id);
+                return m ? m.name : id;
+            };
+
+            if (perStepConfig.format.llm) {
+                overrides.push(`MD정리 → ${getModelName(perStepConfig.format.llm, llmModels)}`);
+            }
+            if (perStepConfig.translate.llm) {
+                overrides.push(`번역 → ${getModelName(perStepConfig.translate.llm, llmModels)}`);
+            }
+            if (perStepConfig.keyframe.llm) {
+                overrides.push(`키프레임 → ${getModelName(perStepConfig.keyframe.llm, visionModels)}`);
+            }
+
+            if (overrides.length > 0) {
+                dot.className = 'settings-dot active';
+                summary.style.display = '';
+                summary.textContent = '⚙ 단계별 설정: ' + overrides.join(' | ');
+            } else {
+                dot.className = 'settings-dot';
+                summary.style.display = 'none';
+                summary.textContent = '';
+            }
+        }
+    </script>
+</body>
+</html>

transcriber.py

@@ -0,0 +1,565 @@
+"""YouTube 영상에서 음성을 추출하고 텍스트로 변환하는 핵심 모듈."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import tempfile
+from typing import Callable, List, Optional
+from pathlib import Path
+
+from pytubefix import YouTube
+from pydub import AudioSegment
+
+
+def download_audio(
+    url: str,
+    output_dir: Optional[str] = None,
+    on_progress: Optional[Callable] = None,
+) -> dict:
+    """YouTube URL에서 오디오를 다운로드한다."""
+    if output_dir is None:
+        output_dir = tempfile.mkdtemp()
+
+    def _notify(percent: int, detail: str):
+        if on_progress:
+            on_progress({"step": "download", "percent": percent, "detail": detail})
+
+    _notify(0, "영상 정보를 가져오는 중...")
+
+    # pytubefix 다운로드 진행 콜백
+    def _download_cb(stream, chunk, bytes_remaining):
+        total = stream.filesize
+        downloaded = total - bytes_remaining
+        pct = min(int(downloaded / total * 80), 80)  # 0~80%: 다운로드
+        dl_mb = downloaded / (1024 * 1024)
+        total_mb = total / (1024 * 1024)
+        _notify(pct, f"다운로드 중... {dl_mb:.1f}MB / {total_mb:.1f}MB")
+
+    yt = YouTube(url, on_progress_callback=_download_cb)
+    title = yt.title
+    duration = yt.length
+
+    _notify(5, f"'{title}' 오디오 스트림 선택 중...")
+
+    audio_stream = yt.streams.filter(only_audio=True).order_by("abr").desc().first()
+    if not audio_stream:
+        raise RuntimeError("오디오 스트림을 찾을 수 없습니다.")
+
+    # 다운로드 (m4a/webm)
+    downloaded = audio_stream.download(output_path=output_dir)
+
+    # mp3로 변환 (80~100%)
+    _notify(85, "MP3로 변환 중...")
+    mp3_path = os.path.join(output_dir, Path(downloaded).stem + ".mp3")
+    audio = AudioSegment.from_file(downloaded)
+    audio.export(mp3_path, format="mp3", bitrate="192k")
+
+    if downloaded != mp3_path and os.path.exists(downloaded):
+        os.remove(downloaded)
+
+    file_mb = os.path.getsize(mp3_path) / (1024 * 1024)
+    _notify(100, f"다운로드 완료 ({file_mb:.1f}MB, {duration}초)")
+
+    return {"audio_path": mp3_path, "title": title, "duration": duration}
+
+
+def download_video(
+    url: str,
+    output_dir: Optional[str] = None,
+    on_progress: Optional[Callable] = None,
+    max_resolution: int = 720,
+) -> str:
+    """키프레임 추출을 위해 YouTube 영상을 다운로드한다 (720p 이하)."""
+    if output_dir is None:
+        output_dir = tempfile.mkdtemp()
+
+    def _notify(percent: int, detail: str):
+        if on_progress:
+            on_progress({"step": "download", "percent": percent, "detail": detail})
+
+    _notify(50, "키프레임용 영상 다운로드 중...")
+
+    def _download_cb(stream, chunk, bytes_remaining):
+        total = stream.filesize
+        downloaded = total - bytes_remaining
+        pct = min(50 + int(downloaded / total * 45), 95)
+        dl_mb = downloaded / (1024 * 1024)
+        total_mb = total / (1024 * 1024)
+        _notify(pct, f"영상 다운로드 중... {dl_mb:.1f}MB / {total_mb:.1f}MB")
+
+    yt = YouTube(url, on_progress_callback=_download_cb)
+
+    # progressive 스트림 (오디오+비디오 합본, 작은 파일)
+    stream = (
+        yt.streams.filter(progressive=True, file_extension="mp4")
+        .filter(res=f"{max_resolution}p")
+        .first()
+    )
+    if not stream:
+        # 해상도 제한 없이 가장 낮은 progressive 시도
+        stream = (
+            yt.streams.filter(progressive=True, file_extension="mp4")
+            .order_by("resolution")
+            .first()
+        )
+    if not stream:
+        raise RuntimeError("영상 스트림을 찾을 수 없습니다.")
+
+    video_path = stream.download(output_path=output_dir, filename_prefix="video_")
+    _notify(98, "영상 다운로드 완료")
+    return video_path
+
+
+def extract_keyframes(
+    video_path: str,
+    output_dir: Optional[str] = None,
+    method: str = "scene",
+    interval_seconds: int = 30,
+    max_frames: int = 50,
+    on_progress: Optional[Callable] = None,
+) -> List[dict]:
+    """영상에서 키프레임을 추출한다 (OpenCV).
+
+    method="scene": 히스토그램 비교로 장면 전환 감지.
+    method="interval": N초 간격으로 추출.
+    반환: [{"path": str, "timestamp": "MM:SS"}, ...]
+    """
+    import cv2
+
+    def _notify(percent: int, detail: str):
+        if on_progress:
+            on_progress({"step": "keyframe_extract", "percent": percent, "detail": detail})
+
+    if output_dir is None:
+        output_dir = tempfile.mkdtemp()
+    os.makedirs(output_dir, exist_ok=True)
+
+    cap = cv2.VideoCapture(video_path)
+    if not cap.isOpened():
+        raise RuntimeError(f"영상 파일을 열 수 없습니다: {video_path}")
+
+    fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    total_seconds = total_frames / fps
+
+    _notify(5, f"영상 분석 시작 ({total_seconds:.0f}초, {fps:.0f}fps)")
+
+    keyframes = []
+    prev_hist = None
+    frame_idx = 0
+    threshold = 0.6  # 장면 전환 감지 임계값
+
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+
+        current_seconds = frame_idx / fps
+        pct = min(int(5 + (frame_idx / total_frames) * 85), 90)
+
+        should_save = False
+
+        if method == "scene":
+            # HSV 히스토그램 비교로 장면 전환 감지
+            hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)
+            hist = cv2.calcHist([hsv], [0, 1], None, [50, 60], [0, 180, 0, 256])
+            cv2.normalize(hist, hist, 0, 1, cv2.NORM_MINMAX)
+
+            if prev_hist is not None:
+                score = cv2.compareHist(prev_hist, hist, cv2.HISTCMP_CORREL)
+                if score < threshold:
+                    should_save = True
+            else:
+                # 첫 프레임은 항상 저장
+                should_save = True
+
+            prev_hist = hist
+        else:
+            # interval 모드: N초 간격
+            if frame_idx == 0 or (frame_idx % int(fps * interval_seconds) == 0):
+                should_save = True
+
+        if should_save and len(keyframes) < max_frames:
+            mins = int(current_seconds // 60)
+            secs = int(current_seconds % 60)
+            timestamp = f"{mins:02d}:{secs:02d}"
+            frame_path = os.path.join(output_dir, f"keyframe_{len(keyframes) + 1:03d}.jpg")
+            cv2.imwrite(frame_path, frame, [cv2.IMWRITE_JPEG_QUALITY, 85])
+            keyframes.append({"path": frame_path, "timestamp": timestamp})
+
+            if len(keyframes) % 5 == 0:
+                _notify(pct, f"{len(keyframes)}개 키프레임 추출됨 ({timestamp})")
+
+        if len(keyframes) >= max_frames:
+            break
+
+        frame_idx += 1
+
+    cap.release()
+    _notify(100, f"키프레임 추출 완료: {len(keyframes)}개")
+    return keyframes
+
+
+def _split_audio(audio_path: str, max_size_mb: int = 24) -> List[str]:
+    """오디오 파일을 Whisper API 제한(25MB)에 맞게 분할한다."""
+    file_size = os.path.getsize(audio_path)
+    max_bytes = max_size_mb * 1024 * 1024
+
+    if file_size <= max_bytes:
+        return [audio_path]
+
+    audio = AudioSegment.from_mp3(audio_path)
+    total_ms = len(audio)
+
+    num_chunks = (file_size // max_bytes) + 1
+    chunk_ms = total_ms // num_chunks
+
+    chunks = []
+    base = Path(audio_path)
+    for i in range(num_chunks):
+        start = i * chunk_ms
+        end = min((i + 1) * chunk_ms, total_ms)
+        chunk = audio[start:end]
+        chunk_path = str(base.parent / f"{base.stem}_part{i}{base.suffix}")
+        chunk.export(chunk_path, format="mp3")
+        chunks.append(chunk_path)
+
+    return chunks
+
+
+def transcribe_api(
+    audio_path: str,
+    api_key: str,
+    on_progress: Optional[Callable] = None,
+) -> dict:
+    """OpenAI Whisper API로 음성을 텍스트로 변환한다."""
+    from openai import OpenAI
+
+    def _notify(percent: int, detail: str):
+        if on_progress:
+            on_progress({"step": "transcribe", "percent": percent, "detail": detail})
+
+    _notify(0, "오디오 파일 분석 중...")
+
+    client = OpenAI(api_key=api_key)
+    chunks = _split_audio(audio_path)
+    total_chunks = len(chunks)
+    all_segments = []
+    full_text_parts = []
+    detected_language = None
+    time_offset = 0.0
+
+    if total_chunks > 1:
+        _notify(5, f"파일이 커서 {total_chunks}개로 분할하여 처리합니다")
+
+    for i, chunk_path in enumerate(chunks):
+        chunk_pct_start = int(i / total_chunks * 90)
+        chunk_pct_end = int((i + 1) / total_chunks * 90)
+
+        if total_chunks > 1:
+            _notify(chunk_pct_start, f"청크 {i + 1}/{total_chunks} Whisper API 전송 중...")
+        else:
+            _notify(10, "Whisper API로 전송 중...")
+
+        with open(chunk_path, "rb") as f:
+            response = client.audio.transcriptions.create(
+                model="whisper-1",
+                file=f,
+                response_format="verbose_json",
+                timestamp_granularities=["segment"],
+            )
+
+        if detected_language is None:
+            detected_language = response.language
+
+        full_text_parts.append(response.text)
+
+        if total_chunks > 1:
+            _notify(chunk_pct_end, f"청크 {i + 1}/{total_chunks} 완료")
+        else:
+            _notify(85, "응답 처리 중...")
+
+        if response.segments:
+            for seg in response.segments:
+                _get = (lambda k: seg[k]) if isinstance(seg, dict) else (lambda k: getattr(seg, k))
+                all_segments.append(
+                    {
+                        "start": _get("start") + time_offset,
+                        "end": _get("end") + time_offset,
+                        "text": _get("text"),
+                    }
+                )
+
+        if chunks[-1] != chunk_path:
+            audio = AudioSegment.from_mp3(chunk_path)
+            time_offset += len(audio) / 1000.0
+
+    # 분할된 임시 파일 정리
+    for chunk_path in chunks:
+        if chunk_path != audio_path and os.path.exists(chunk_path):
+            os.remove(chunk_path)
+
+    _notify(100, f"변환 완료 (언어: {detected_language}, 세그먼트: {len(all_segments)}개)")
+
+    return {
+        "text": " ".join(full_text_parts),
+        "segments": all_segments,
+        "language": detected_language or "unknown",
+    }
+
+
+def transcribe_local(
+    audio_path: str,
+    model_size: str = "base",
+    on_progress: Optional[Callable] = None,
+) -> dict:
+    """로컬 Whisper 모델로 음성을 텍스트로 변환한다."""
+    import whisper
+
+    def _notify(percent: int, detail: str):
+        if on_progress:
+            on_progress({"step": "transcribe", "percent": percent, "detail": detail})
+
+    _notify(0, f"Whisper {model_size} 모델 로딩 중...")
+    model = whisper.load_model(model_size)
+
+    _notify(20, "음성 분석 중... (영상 길이에 따라 시간이 걸립니다)")
+    result = model.transcribe(audio_path)
+
+    _notify(90, "결과 정리 중...")
+    segments = []
+    for seg in result.get("segments", []):
+        segments.append(
+            {"start": seg["start"], "end": seg["end"], "text": seg["text"]}
+        )
+
+    lang = result.get("language", "unknown")
+    _notify(100, f"변환 완료 (언어: {lang}, 세그먼트: {len(segments)}개)")
+
+    return {
+        "text": result["text"],
+        "segments": segments,
+        "language": lang,
+    }
+
+
+def _format_srt_time(seconds: float) -> str:
+    """초를 SRT 타임스탬프 형식으로 변환한다."""
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = int(seconds % 60)
+    millis = int((seconds % 1) * 1000)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"
+
+
+def save_txt(result: dict, output_path: str) -> str:
+    """텍스트 파일로 저장한다."""
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(result["text"].strip())
+    return output_path
+
+
+def save_srt(result: dict, output_path: str) -> str:
+    """SRT 자막 파일로 저장한다."""
+    with open(output_path, "w", encoding="utf-8") as f:
+        for i, seg in enumerate(result["segments"], 1):
+            f.write(f"{i}\n")
+            f.write(
+                f"{_format_srt_time(seg['start'])} --> {_format_srt_time(seg['end'])}\n"
+            )
+            f.write(f"{seg['text'].strip()}\n\n")
+    return output_path
+
+
+def _sanitize_filename(title: str) -> str:
+    """파일명에 사용할 수 없는 문자를 제거한다."""
+    sanitized = re.sub(r'[<>:"/\\|?*]', "", title)
+    sanitized = sanitized.strip(". ")
+    return sanitized[:100] if sanitized else "untitled"
+
+
+def process_video(
+    url: str,
+    mode: str = "api",
+    api_key: Optional[str] = None,
+    model_size: str = "base",
+    output_dir: str = "./output",
+    formats: Optional[List[str]] = None,
+    on_progress: Optional[Callable] = None,
+    # LLM 옵션 (전역 기본값, 하위 호환)
+    md_llm: Optional[str] = None,
+    md_api_key: Optional[str] = None,
+    md_ollama_model: str = "llama3.2",
+    # 번역 옵션
+    translate_lang: Optional[str] = None,
+    # 단계별 LLM 오버라이드
+    format_llm: Optional[str] = None,
+    format_api_key: Optional[str] = None,
+    translate_llm: Optional[str] = None,
+    translate_api_key: Optional[str] = None,
+    keyframe_llm: Optional[str] = None,
+    keyframe_api_key: Optional[str] = None,
+    # 키프레임 옵션
+    enable_keyframes: bool = False,
+    keyframe_method: str = "scene",
+    keyframe_interval: int = 30,
+    keyframe_max_frames: int = 50,
+) -> dict:
+    """전체 파이프라인: 다운로드 → (키프레임) → 변환 → (AI 정리) → (번역) → 저장."""
+    from formatter import make_llm_config, format_as_markdown, translate_text, analyze_keyframes
+
+    if formats is None:
+        formats = ["txt", "srt"]
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    def progress(data):
+        if on_progress:
+            on_progress(data)
+
+    # 단계별 LLM 설정 빌드
+    llm_cfg = make_llm_config(
+        global_llm=md_llm, global_api_key=md_api_key,
+        global_ollama_model=md_ollama_model,
+        format_llm=format_llm, format_api_key=format_api_key,
+        translate_llm=translate_llm, translate_api_key=translate_api_key,
+        keyframe_llm=keyframe_llm, keyframe_api_key=keyframe_api_key,
+    )
+
+    # 1. 오디오 다운로드
+    audio_info = download_audio(url, on_progress=on_progress)
+    audio_path = audio_info["audio_path"]
+    title = audio_info["title"]
+
+    video_path = None
+    keyframe_dir = None
+
+    try:
+        # 2. 키프레임용 영상 다운로드 (선택 시)
+        if enable_keyframes:
+            video_path = download_video(url, on_progress=on_progress)
+
+        # 3. 키프레임 추출 (선택 시)
+        keyframe_descriptions = None
+        if enable_keyframes and video_path:
+            keyframe_dir = tempfile.mkdtemp()
+            keyframes = extract_keyframes(
+                video_path, output_dir=keyframe_dir,
+                method=keyframe_method,
+                interval_seconds=keyframe_interval,
+                max_frames=keyframe_max_frames,
+                on_progress=on_progress,
+            )
+
+            # 4. 키프레임 Vision LLM 분석
+            if keyframes:
+                kf_cfg = llm_cfg["keyframe"]
+                keyframe_descriptions = analyze_keyframes(
+                    keyframe_paths=keyframes,
+                    llm_provider=kf_cfg["llm"],
+                    api_key=kf_cfg["api_key"],
+                    on_progress=on_progress,
+                )
+
+        # 5. 음성 → 텍스트 변환
+        if mode == "api":
+            if not api_key:
+                raise ValueError("API 모드에서는 OpenAI API 키가 필요합니다.")
+            result = transcribe_api(audio_path, api_key, on_progress=on_progress)
+        else:
+            result = transcribe_local(audio_path, model_size, on_progress=on_progress)
+
+        # 6. AI 마크다운 정리 (MD 선택 시)
+        md_content = None
+        fmt_cfg = llm_cfg["format"]
+        if "md" in formats and fmt_cfg["llm"]:
+            md_content = format_as_markdown(
+                text=result["text"],
+                title=title,
+                llm_provider=fmt_cfg["llm"],
+                api_key=fmt_cfg["api_key"],
+                ollama_model=fmt_cfg["ollama_model"],
+                on_progress=on_progress,
+                keyframe_descriptions=keyframe_descriptions,
+            )
+
+        # 7. 번역 (선택 시)
+        translated_txt = None
+        translated_md = None
+        tr_cfg = llm_cfg["translate"]
+        if translate_lang and tr_cfg["llm"]:
+            translated_txt = translate_text(
+                text=result["text"],
+                target_lang=translate_lang,
+                llm_provider=tr_cfg["llm"],
+                api_key=tr_cfg["api_key"],
+                ollama_model=tr_cfg["ollama_model"],
+                on_progress=on_progress,
+            )
+
+            if md_content:
+                translated_md = translate_text(
+                    text=md_content,
+                    target_lang=translate_lang,
+                    llm_provider=tr_cfg["llm"],
+                    api_key=tr_cfg["api_key"],
+                    ollama_model=tr_cfg["ollama_model"],
+                    on_progress=on_progress,
+                )
+
+        # 8. 파일 저장
+        progress({"step": "save", "percent": 0, "detail": "파일 저장 중..."})
+        safe_title = _sanitize_filename(title)
+        saved_files = {}
+
+        if "txt" in formats:
+            txt_path = os.path.join(output_dir, f"{safe_title}.txt")
+            save_txt(result, txt_path)
+            saved_files["txt"] = txt_path
+
+        if "srt" in formats:
+            srt_path = os.path.join(output_dir, f"{safe_title}.srt")
+            save_srt(result, srt_path)
+            saved_files["srt"] = srt_path
+
+        if "md" in formats and md_content:
+            md_path = os.path.join(output_dir, f"{safe_title}.md")
+            with open(md_path, "w", encoding="utf-8") as f:
+                f.write(md_content)
+            saved_files["md"] = md_path
+
+        # 번역 파일 저장
+        if translated_txt:
+            lang_suffix = translate_lang.replace("-", "").lower()
+            tr_txt_path = os.path.join(output_dir, f"{safe_title}_{lang_suffix}.txt")
+            with open(tr_txt_path, "w", encoding="utf-8") as f:
+                f.write(translated_txt)
+            saved_files[f"txt_{lang_suffix}"] = tr_txt_path
+
+        if translated_md:
+            lang_suffix = translate_lang.replace("-", "").lower()
+            tr_md_path = os.path.join(output_dir, f"{safe_title}_{lang_suffix}.md")
+            with open(tr_md_path, "w", encoding="utf-8") as f:
+                f.write(translated_md)
+            saved_files[f"md_{lang_suffix}"] = tr_md_path
+
+        fmt_str = ", ".join(f.upper() for f in saved_files.keys())
+        progress({"step": "save", "percent": 100, "detail": f"{fmt_str} 파일 저장 완료"})
+
+        return {
+            "title": title,
+            "language": result["language"],
+            "text": result["text"],
+            "segments": result["segments"],
+            "files": saved_files,
+        }
+    finally:
+        # 임시 파일 정리
+        if os.path.exists(audio_path):
+            os.remove(audio_path)
+        if video_path and os.path.exists(video_path):
+            os.remove(video_path)
+        if keyframe_dir and os.path.exists(keyframe_dir):
+            shutil.rmtree(keyframe_dir, ignore_errors=True)

web.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""YouTube Script Extractor - Web Server."""
+
+import asyncio
+import json
+import os
+import uuid
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, HTMLResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+
+from transcriber import process_video
+from formatter import LLM_MODELS, get_models_sorted, get_languages
+
+app = FastAPI(title="YouTube Script Extractor")
+templates = Jinja2Templates(directory="templates")
+
+OUTPUT_DIR = "./output"
+os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+# 진행 중인 작업 추적
+jobs: dict[str, dict] = {}
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index(request: Request):
+    return templates.TemplateResponse("index.html", {"request": request})
+
+
+@app.get("/api/llm-models")
+async def get_llm_models(sort: str = "price"):
+    """LLM 모델 목록을 정렬하여 반환한다."""
+    models = get_models_sorted(sort_by=sort)
+    return {"models": models}
+
+
+@app.get("/api/languages")
+async def get_supported_languages():
+    """번역 지원 언어 목록을 반환한다."""
+    return {"languages": get_languages()}
+
+
+@app.get("/api/vision-models")
+async def get_vision_models(sort: str = "price"):
+    """Vision 지원 LLM 모델 목록을 반환한다."""
+    key = "price_rank" if sort == "price" else "quality_rank"
+    models = [
+        {"id": k, **v} for k, v in LLM_MODELS.items()
+        if v.get("supports_vision", False)
+    ]
+    return {"models": sorted(models, key=lambda x: x[key])}
+
+
+@app.post("/api/transcribe")
+async def start_transcription(request: Request):
+    body = await request.json()
+    url = body.get("url", "").strip()
+    mode = body.get("mode", "api")
+    api_key = body.get("api_key", "") or os.environ.get("OPENAI_API_KEY", "")
+    model_size = body.get("model_size", "base")
+    formats = body.get("formats", ["txt", "srt"])
+    output_dir = body.get("output_dir", "").strip() or OUTPUT_DIR
+
+    # LLM 옵션 (전역 기본값)
+    md_llm = body.get("md_llm", "")
+    md_api_key = body.get("md_api_key", "")
+    md_ollama_model = body.get("md_ollama_model", "llama3.2")
+    translate_lang = body.get("translate_lang", "")
+
+    # 단계별 LLM 오버라이드
+    format_llm = body.get("format_llm", "")
+    format_api_key = body.get("format_api_key", "")
+    translate_llm = body.get("translate_llm", "")
+    translate_api_key = body.get("translate_api_key", "")
+    keyframe_llm = body.get("keyframe_llm", "")
+    keyframe_api_key = body.get("keyframe_api_key", "")
+
+    # 키프레임 옵션
+    enable_keyframes = body.get("enable_keyframes", False)
+    keyframe_method = body.get("keyframe_method", "scene")
+    keyframe_interval = body.get("keyframe_interval", 30)
+
+    if not url:
+        return {"error": "YouTube URL을 입력해주세요."}
+
+    if mode == "api" and not api_key:
+        return {"error": "API 모드에서는 OpenAI API 키가 필요합니다."}
+
+    job_id = str(uuid.uuid4())[:8]
+    jobs[job_id] = {"status": "started", "progress": [], "result": None, "error": None}
+
+    asyncio.create_task(
+        _run_transcription(
+            job_id, url, mode, api_key, model_size, formats, output_dir,
+            md_llm=md_llm, md_api_key=md_api_key, md_ollama_model=md_ollama_model,
+            translate_lang=translate_lang,
+            format_llm=format_llm, format_api_key=format_api_key,
+            translate_llm=translate_llm, translate_api_key=translate_api_key,
+            keyframe_llm=keyframe_llm, keyframe_api_key=keyframe_api_key,
+            enable_keyframes=enable_keyframes,
+            keyframe_method=keyframe_method, keyframe_interval=keyframe_interval,
+        )
+    )
+
+    return {"job_id": job_id}
+
+
+async def _run_transcription(
+    job_id: str,
+    url: str,
+    mode: str,
+    api_key: str,
+    model_size: str,
+    formats: list[str],
+    output_dir: str = OUTPUT_DIR,
+    md_llm: str = "",
+    md_api_key: str = "",
+    md_ollama_model: str = "llama3.2",
+    translate_lang: str = "",
+    format_llm: str = "",
+    format_api_key: str = "",
+    translate_llm: str = "",
+    translate_api_key: str = "",
+    keyframe_llm: str = "",
+    keyframe_api_key: str = "",
+    enable_keyframes: bool = False,
+    keyframe_method: str = "scene",
+    keyframe_interval: int = 30,
+):
+    def on_progress(msg: str):
+        jobs[job_id]["progress"].append(msg)
+
+    try:
+        result = await asyncio.to_thread(
+            process_video,
+            url=url,
+            mode=mode,
+            api_key=api_key,
+            model_size=model_size,
+            output_dir=output_dir,
+            formats=formats,
+            on_progress=on_progress,
+            md_llm=md_llm or None,
+            md_api_key=md_api_key or None,
+            md_ollama_model=md_ollama_model,
+            translate_lang=translate_lang or None,
+            format_llm=format_llm or None,
+            format_api_key=format_api_key or None,
+            translate_llm=translate_llm or None,
+            translate_api_key=translate_api_key or None,
+            keyframe_llm=keyframe_llm or None,
+            keyframe_api_key=keyframe_api_key or None,
+            enable_keyframes=enable_keyframes,
+            keyframe_method=keyframe_method,
+            keyframe_interval=keyframe_interval,
+        )
+        jobs[job_id]["status"] = "completed"
+        # 절대 경로로 변환하여 저장 위치를 정확히 표시
+        abs_output = os.path.abspath(output_dir)
+        jobs[job_id]["result"] = {
+            "title": result["title"],
+            "language": result["language"],
+            "text": result["text"],
+            "files": {
+                fmt: os.path.basename(path) for fmt, path in result["files"].items()
+            },
+            "output_dir": abs_output,
+            "output_dir_raw": output_dir,
+        }
+    except Exception as e:
+        jobs[job_id]["status"] = "error"
+        jobs[job_id]["error"] = str(e)
+
+
+@app.get("/api/status/{job_id}")
+async def get_status(job_id: str):
+    job = jobs.get(job_id)
+    if not job:
+        return {"error": "작업을 찾을 수 없습니다."}
+    return job
+
+
+@app.get("/api/stream/{job_id}")
+async def stream_status(job_id: str):
+    async def event_generator():
+        seen = 0
+        while True:
+            job = jobs.get(job_id)
+            if not job:
+                yield f"data: {json.dumps({'type': 'error', 'message': '작업을 찾을 수 없습니다.'})}\n\n"
+                break
+
+            # 새 진행 메시지 전송
+            while seen < len(job["progress"]):
+                msg = job["progress"][seen]
+                if isinstance(msg, dict):
+                    yield f"data: {json.dumps({'type': 'progress', **msg})}\n\n"
+                else:
+                    yield f"data: {json.dumps({'type': 'progress', 'message': msg})}\n\n"
+                seen += 1
+
+            if job["status"] == "completed":
+                yield f"data: {json.dumps({'type': 'completed', 'result': job['result']})}\n\n"
+                break
+            elif job["status"] == "error":
+                yield f"data: {json.dumps({'type': 'error', 'message': job['error']})}\n\n"
+                break
+
+            await asyncio.sleep(0.5)
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+@app.get("/api/download/{filename}")
+async def download_file(filename: str, dir: str = ""):
+    base_dir = dir if dir else OUTPUT_DIR
+    file_path = os.path.join(base_dir, filename)
+    if not os.path.exists(file_path):
+        return {"error": "파일을 찾을 수 없습니다."}
+    return FileResponse(file_path, filename=filename)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    port = int(os.environ.get("PORT", 8000))
+    print("YouTube Script Extractor 웹 서버")
+    print(f"  http://localhost:{port}")
+    print()
+    uvicorn.run(app, host="0.0.0.0", port=port)