🎬 영상 자동 분석 파이프라인

영상 파일 하나를 업로드하면 음성 전사 → 자막 교정 → 장면 분할 → 장면별 분석을 자동으로 수행하고, 원본/교정 자막(SRT) 과 장면 메타데이터(JSON) 를 만들어 주는 웹 애플리케이션입니다.

온라인(OpenAI) / 오프라인(폐쇄망) 모드를 .env 설정 한 줄로 전환할 수 있습니다.

---

✨ 처리 단계 (6단계 파이프라인)

단계	작업	담당
①	오디오 추출	ffmpeg (로컬)
②	자막 전사	Whisper
③	자막 교정 (오타·띄어쓰기, 타임코드 보존)	GPT (LLM)
④	장면(컷) 감지 + 키프레임 추출	PySceneDetect (로컬)
⑤	장면별 분석 (설명·태그·분위기)	GPT Vision (VLM)
⑥	메타데이터 통합	로컬

출력물 3종: original.srt(원본 자막) · corrected.srt(교정 자막) · metadata.json(장면 메타데이터)

---

📦 설치

사전 요구 사항

• Python 3.10+
• ffmpeg (PATH 등록 필요 — ffmpeg, ffprobe)

  winget install Gyan.FFmpeg     # Windows

• OpenAI API 키 (온라인 모드일 때)

패키지 설치

pip install -r requirements.txt

환경 변수(.env) 설정

Copy-Item .env.example .env
notepad .env       # OPENAI_API_KEY=sk-... 입력

---

▶️ 실행

uvicorn app:app --host 127.0.0.1 --port 8000

브라우저에서 http://127.0.0.1:8000 접속.

---

📖 사용 방법

1단계 — 시작 화면

접속하면 업로드 화면이 나타납니다. 아직 파일이 없으면 분석 시작 버튼은 비활성화 상태입니다.

2단계 — 영상 선택

점선 영역을 클릭하거나 영상 파일을 끌어다 놓습니다. 파일명이 표시되고 분석 시작 버튼이 활성화됩니다.

3단계 — 분석 실행 & 결과 다운로드

분석 시작을 누르면 ①~⑥ 단계가 순서대로 진행됩니다(진행 막대 + 단계 표시). 완료되면 ✅ 분석 완료와 함께 세 개의 다운로드 버튼이 나타납니다.

• 원본 SRT (original.srt) — Whisper가 만든 자막
• 교정 SRT (corrected.srt) — GPT 교정본 (타임코드는 원본과 동일)
• 장면 메타데이터 (metadata.json) — 장면별 분석 결과

---

📤 출력물 예시

original.srt / corrected.srt (타임코드 보존)

1
00:00:00,000 --> 00:00:06,000
Hello. This is a test of the Video Analysis Pipeline.

2
00:00:06,000 --> 00:00:09,000
The weather today is sunny and clear.

metadata.json

{
  "source": { "filename": "test_video.mp4", "duration": 11.722 },
  "provider": "openai",
  "models": { "transcribe": "whisper-1", "correct": "gpt-4o-mini", "analyze": "gpt-4o" },
  "scene_count": 2,
  "scenes": [
    {
      "scene_id": 1,
      "start": "00:00:00,000",
      "end": "00:00:07,000",
      "subtitle": "Hello. This is a test of the Video Analysis Pipeline...",
      "analysis": {
        "description": "화려한 색상 막대와 숫자가 포함된 테스트 화면.",
        "tags": ["테스트 화면", "컬러 바", "비디오 테스트"],
        "mood": "중립",
        "on_screen_text": "3"
      },
      "keyframe": "keyframe_1.jpg"
    }
  ]
}

---

🔀 온라인 / 오프라인 모드

.env의 PROVIDER 값으로 전환합니다 (코드 변경 불필요).

모드	PROVIDER	전사(②)	교정(③)·분석(⑤)	인터넷
온라인	openai	Whisper API	OpenAI GPT	필요
오프라인	local	faster-whisper	Ollama(LLM/VLM)	불필요

폐쇄망(오프라인) 배포 절차는 OFFLINE_DEPLOY.md 참고.

---

⚠️ 주의 사항

• 타임코드 수정 금지 — 자막 교정은 텍스트만 고치고 타임코드는 보존합니다. 교정 후 코드로 검증(assert_timecodes_unchanged)합니다.
• API 키 보안 — 키는 .env에만 두며, .gitignore로 커밋에서 제외됩니다.
• 온라인 모드는 인터넷 필요 — ②③⑤가 api.openai.com을 호출합니다. 완전 오프라인은 local 모드 사용.
• Whisper API 25MB 제한 — 온라인 모드에서 큰 오디오는 자동 분할 전사합니다(타임코드 오프셋 보정).

---

📁 프로젝트 구조

hello/
├─ app.py                  # FastAPI: 업로드/상태/다운로드
├─ pipeline/
│  ├─ config.py            # 온/오프라인 토글
│  ├─ runner.py            # 6단계 오케스트레이션
│  ├─ audio.py             # ① 오디오 추출
│  ├─ transcribe.py        # ② 전사 (whisper-1 / faster-whisper)
│  ├─ correct.py           # ③ 자막 교정 (타임코드 보존)
│  ├─ scenes.py            # ④ 장면 감지 + 키프레임
│  ├─ analyze.py           # ⑤ 장면별 분석
│  ├─ metadata.py          # ⑥ 통합
│  ├─ srt_utils.py         # SRT 파싱/직렬화/타임코드 검증
│  ├─ gpt_utils.py         # GPT JSON 호출 (재시도)
│  └─ ffmpeg_utils.py      # ffmpeg/ffprobe 래퍼
├─ static/index.html       # 업로드 UI
├─ outputs/<job_id>/       # 작업별 결과물
├─ requirements.txt
├─ .env.example
├─ PLAN.md                 # 설계 문서
└─ OFFLINE_DEPLOY.md       # 폐쇄망 배포 절차서

---

🛠️ 기술 스택

영역	기술
백엔드	FastAPI · Uvicorn
전사	OpenAI Whisper API / faster-whisper
LLM·VLM	OpenAI GPT-4o / Ollama (Qwen2.5 등)
미디어	ffmpeg · PySceneDetect · OpenCV
프론트	단일 HTML/CSS/JS (의존성 없음)