영어 유튜브 학습을 위한 AI 스크립트 추출 파이프라인

유튜브 URL을 입력하면 자막을 먼저 확보하고, 자막이 없으면 로컬 ASR로 전사한 뒤 다음 결과를 생성하는 로컬 AI 파이프라인입니다.

• transcript.txt — 전체 스크립트
• Study Snapshot — 한 줄 개요
• Study Notes — 복습용 요약
• Highlight Timeline — 타임스탬프 기반 하이라이트
• Key Expressions — 핵심 표현 및 키워드
• window_notes.json, diagnostics, timing

빠르게 보기

항목	내용
입력	유튜브 URL
대상 언어	영어
처리 방식	자막 우선, 실패 시 로컬 ASR fallback
실행 환경	로컬 Python 환경
출력	transcript, study notes, highlights, expressions, JSON

핵심 특징

• 자막 우선 처리로 속도와 품질을 동시에 확보
• 자막 실패에 대비한 로컬 ASR fallback
• 영어 스크립트 정제와 학습용 출력 후처리
• fast, quality, best 모드 분리
• diagnostics, timing, quality metadata 제공

시스템 흐름

flowchart LR
    A["입력: YouTube URL"] --> B["RunConfig 생성"]
    B --> C["Video ID 추출"]
    C --> D["Transcript Cache 조회"]
    D -->|"cache hit"| E["정제 가능한 segment 확보"]
    D -->|"cache miss"| F["자막 수집 시도"]
    F -->|"성공"| E
    F -->|"실패"| G["오디오 다운로드"]
    G --> H["로컬 ASR 전사"]
    H --> I["ASR confidence filtering"]
    I --> E
    E --> J["Transcript Cleaning / Section Labeling"]
    J --> K["Window 생성"]
    K --> L["Summary Backend 선택"]
    L --> M["전체 요약 생성"]
    K --> N["Highlight 선택"]
    N --> O["Highlight 요약 생성"]
    M --> P["Payload 조립"]
    O --> P
    P --> Q["CLI 출력"]
    P --> R["result.json / transcript.txt 저장"]

Loading

5개 계층으로 구성됩니다.

계층	책임	대표 파일
Entry Layer	CLI 입력, 인터랙션, 실행 옵션 결정	app/main.py, app/runtime.py
Acquisition Layer	자막 수집, 오디오 다운로드, 캐시 재사용	app/backends/transcript/, app/pipeline/download_audio.py, app/pipeline/transcript_cache.py
Processing Layer	전사, 정제, confidence filtering, windowing	app/pipeline/asr.py, app/pipeline/text_clean.py, app/pipeline/segment.py
Understanding Layer	요약, 하이라이트, 키워드, 품질 선택	app/pipeline/summarize.py, app/pipeline/highlight.py, app/pipeline/quality_selection.py
Presentation Layer	CLI 출력, JSON payload, 결과 파일 정리	app/pipeline/output.py, app/pipeline/result_builder.py

자세한 아키텍처는 documents/02-시스템-아키텍처.md를 참고하세요.

데모

문서

문서	설명
documents/README.md	전체 문서 인덱스
documents/01-프로젝트-소개.md	문제 정의, 목표, 범위
documents/02-시스템-아키텍처.md	전체 구조, 데이터 흐름, 실패 경로
documents/03-구현-상세.md	코드 단위 설명과 설계 이유
documents/04-실행-가이드.md	설치, 실행, 옵션 설명
documents/06-한계-및-개선방향.md	한계, 리스크, 개선 우선순위
examples/sample_cli_output.md	CLI 결과 예시
examples/sample_result.json	JSON 결과 예시

바로 실행하기

공통 설치:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

기본 실행:

python -m app.main

인터랙티브 방식으로 URL, 실행 모드, 쿠키 전략, ASR 백엔드, 최대 길이, 타이밍 출력 여부를 순서대로 선택합니다.

URL과 옵션을 직접 넘기는 방식도 지원합니다.

python -m app.main "https://www.youtube.com/watch?v=VIDEO_ID"

품질 우선 실행 예시:

python -m app.main "https://www.youtube.com/watch?v=VIDEO_ID" --quality-mode --log-timing

쿠키 파일 사용:

python -m app.main "https://www.youtube.com/watch?v=VIDEO_ID" \
  --quality-mode \
  --cookies-file /absolute/path/to/cookies.txt \
  --log-timing

저장소 구조

app/
  backends/
    asr/
    summarizer/
    transcript/
  pipeline/
  quality/
  tools/
  diagnostics.py
  main.py
  models.py
  runtime.py
documents/
examples/

결과 폴더 규칙

runs/
  cache/
    transcripts/
      <video_id>.json
  results/
    <video_id>/
      <YYYYMMDD-HHMMSS>-<mode>/
        result.json
        transcript.txt
        window_notes.json
        downloads/

• --out: 결과 루트 폴더 (기본값 ./runs)
• cache/transcripts/: transcript 캐시 (재사용 가능)
• results/<video_id>/: 실행 이력 누적
• 실행 폴더 이름 형식: 실행시각-모드 (예: 20260307-214530-quality)
• downloads/: ASR fallback 시에만 생성

실행 종료 후 콘솔의 결과 파일 표에서 run_dir를 확인하면 가장 빠릅니다.