강의 영상을 로컬에서 전사하고, AI로 타임라인·학습 노트를 구조화해 제공하는 시스템
Why this project?
긴 강의 영상을 시청하며 직접 노트를 작성하는 것은 비효율적입니다. 기존 요약 서비스는 클라우드 전사에 의존하여 분당 $0.006의 비용이 발생하고, 한국어 전문 용어 처리가 미흡했습니다. 로컬 전사(완전 무료) + AI 요약(1시간 강의 기준 $0.002~0.005)으로 비용 효율적인 학습 노트를 자동 생성하되, 사용자가 개발 환경을 직접 설치할 필요 없이 바로 사용할 수 있어야 했습니다.
Key Features
비디오 선택 → yt-dlp 동영상 다운로드 → FFmpeg 음성 추출(32kbps 16kHz MP3) → 20MB 초과 시 자동 분할 → Faster-Whisper 로컬 전사(타임스탬프 세그먼트) → GPT-4o-mini 내용 분석(도메인 감지, 전문 용어 교정) → 3탭 HTML 노트 생성(스크립트/타임라인/학습 요약). 각 단계가 독립 모듈로 구현되어, 한 단계의 실패가 다른 단계에 전파되지 않는 실패 격리 구조입니다.
Content Script에서 YouTube URL과 DOM <video> 요소를 자동 감지하고, MediaSource/Blob URL도 캡처를 시도합니다. Manifest v3 Service Worker가 메시지 브로커 역할을 하며, Extension → Node.js API 서버 간 통신을 중계합니다. SSE 기반 실시간 진행도를 Extension popup에 표시하여 처리 상태를 시각적으로 확인할 수 있습니다.
PerformanceTracker 클래스가 세션 ID 기반으로 7단계 각각의 시작/종료 시간을 자동 측정하고, 단계별 소요 시간과 비율(%)을 JSON으로 직렬화합니다. PerformanceLogger가 최대 200개 세션 이력을 보관하며, 과거 데이터 기반 로그 회귀 모델로 영상 길이 대비 예상 처리 시간을 산출하여 사용자에게 예측값을 제공합니다.
build-portable.ps1 스크립트로 Python·Node.js·FFmpeg·Whisper 모델을 모두 포함한 Portable ZIP을 생성합니다. 첫 실행 시 setup_script.py가 의존성을 자동 설치하고, pystray 기반 Windows 시스템 트레이 앱으로 원클릭 서버 제어(시작/중지), 상태 아이콘(idle/running/error), 웹 대시보드 열기를 지원합니다.
Tech Decisions
Chrome Extension(UI), Node.js(오케스트레이션), Python(ML 전사)은 각각의 런타임과 역할이 뚜렷하므로 분리하여 독립 배포·확장이 가능하도록 했습니다.
클라우드 전사 비용이 분당 $0.006인 반면, 로컬 Faster-Whisper는 완전 무료입니다. 1시간 강의 전체 비용이 $0.002~0.005(GPT 요약만)로 절감됩니다.
사용자가 Python, Node.js, FFmpeg 등을 직접 설치하는 것은 높은 진입장벽입니다. 모든 의존성을 포함한 무설치 패키지로 사용자 경험을 최우선합니다.
Problem Solving
Problem
Whisper 모델 로드 시 사용자 시스템의 메모리 부족으로 로드가 실패하거나, Portable 환경에서 모델 캐시 경로가 표준 경로와 달라 모델 파일을 찾지 못하는 문제가 반복적으로 발생했습니다. 로컬 ML 추론이라는 특성상, 다양한 사용자 환경에서의 안정적인 모델 관리가 필수적이었습니다.
Approach
이 문제를 "모델 생명주기 관리"와 "환경 적응"이라는 두 측면으로 분리했습니다. 모델 관리는 FastAPI의 lifespan 이벤트를 활용하여 서버 시작 시 모델 로드, 종료 시 언로드를 자동화하고, 로드 실패 시 최대 3회 재시도하는 복원 로직을 구현했습니다. 환경 적응은 Portable 빌드에서 모델 캐시 경로를 실행 파일 기준 상대 경로로 자동 탐지하도록 하여, 표준 설치 환경과 Portable 환경 모두에서 동일하게 동작하도록 했습니다.
Result
다양한 시스템 환경(메모리 2GB~16GB)에서 안정적으로 모델을 로드하고, 실패 시 graceful 복구가 가능합니다.
Problem
1시간 이상의 긴 강의를 전사할 때, 추출된 오디오 파일이 수백 MB에 달하면서 Whisper 모델의 메모리 한계를 초과하는 상황이 발생했습니다. 전사 프로세스가 OOM(Out of Memory)으로 강제 종료되어, 긴 강의의 전사 자체가 불가능했습니다.
Approach
전사 프로세스에 오디오 전체를 한 번에 넘기는 것이 아니라, 파이프라인에 "음성 분할" 단계를 추가하는 것이 근본적인 해결책이라고 판단했습니다. 20MB 초과 시 FFmpeg로 오디오를 자동 분할하고, 각 청크를 순차 전사한 후 타임스탬프를 오프셋 보정하여 매끄럽게 병합하는 로직을 구현했습니다. 분할 기준은 무음 구간(silence detection)을 우선 탐색하되, 무음 구간이 없으면 시간 기반으로 균등 분할합니다.
Result
1시간 이상의 긴 강의도 메모리 제한 없이 안정적으로 처리되며, 분할점의 타임스탬프 불일치 없이 연속적인 전사 결과를 생성합니다.
Outcomes
Links