claude-real-video: 장면 인식 프레임 추출을 통한 LLM의 비디오 시청 기능 구현

claude-real-video: 장면 인식 프레임 추출을 통한 LLM의 비디오 시청 기능 구현

개요

claude-real-video는 Claude, ChatGPT, Gemini와 같은 대규모 언어 모델(LLM)이 비디오를 쉽게 소화할 수 있는 형식으로 변환하여 비디오를 "시청"할 수 있도록 설계된 오픈 소스 도구입니다. 단순히 트랜스크립트나 고정된 간격의 프레임 샘플링에 의존하는 많은 AI 도구와 달리, claude-real-video는 장면 변화와 주요 시각적 변화와 같이 중요한 프레임만을 추출하고 이를 트랜스크립트와 결합하며, 이 모든 과정을 사용자의 로컬 환경에서 실행합니다.

고정 간격 샘플링의 한계 해결

Gemini의 기본 비디오 처리 기능을 포함하여 대부분의 기존 비디오-to-LLM 파이프라인은 일반적으로 고정된 간격(예: 초당 1프레임)으로 프레임을 샘플링합니다. 이 방식은 두 가지 주요 비효율성을 초래합니다:

  1. 정적 콘텐츠의 과잉 샘플링: 10분 동안 정지된 화면의 스크린캐스트는 거의 동일한 프레임 600개를 생성하여 컨텍스트 윈도우 공간을 낭비하고 비용을 증가시킵니다.
  2. 빠른 컷의 과소 샘플링: 고정된 샘플 지점 사이에서 발생하는 급격한 시각적 변화를 완전히 놓칠 수 있습니다.

claude-real-video는 장면 변화 감지와 **밀도 하한선(density floor)**을 결합하여 이 문제를 해결합니다. 이를 통해 모든 시각적 전환을 포착하는 동시에, 비디오의 긴 구간이 무시되지 않도록 최소 프레임 빈도( --fps-floor로 정의됨)를 유지합니다.

주요 기술적 특징

지능형 프레임 중복 제거

컨텍스트 윈도우를 더욱 최적화하기 위해, 이 도구는 슬라이딩 윈도우 중복 제거 프로세스를 사용합니다. 단순한 지각적 해시를 사용하는 대신, 다운스케일된 RGB 픽셀 차이를 사용하여 프레임이 고유한지 판단합니다.

새로운 프레임을 마지막 몇 개의 유지된 프레임 슬라이딩 윈도우( --dedup-window로 제어됨)와 비교함으로써, 도구는 비디오가 A-B-A 컷어웨이를 사용하더라도 동일한 샷이 LLM에 여러 번 전송되는 것을 방지합니다. 사용자는 --dedup-threshold 플래그를 사용하여 이 프로세스의 민감도를 조정할 수 있습니다.

멀티모달 데이터 추출

시각적 요소 외에도, claude-real-video는 LLM을 위한 종합적인 데이터 패키지를 제공합니다:

  • 트랜스크립트: 도구는 정확도를 극대화하기 위해 먼저 기존 자막(SRT/VTT) 사용을 시도합니다. 자막이 없는 경우, 로컬 오디오 트랜스크립션을 위해 OpenAI의 Whisper를 사용합니다.
  • 오디오 추출: --keep-audio 플래그를 사용하면 전체 사운드트랙을 audio.m4a 파일로 저장하여, 오디오 기능이 있는 모델(예: GPT-4o 또는 Gemini)이 톤과 음악을 분석할 수 있게 합니다.
  • 매니페스트 파일: 추출된 콘텐츠를 요약하는 MANIFEST.txt 파일이 생성되어 LLM에게 비디오 구성 요소의 구조화된 지도를 제공합니다.

로컬 처리 및 개인정보 보호

데이터 가져오기, 추출, 중복 제거를 포함한 모든 처리는 로컬에서 이루어집니다. 이 도구는 URL 처리를 위해 yt-dlp를 사용하고 프레임 및 오디오 추출을 위해 ffmpeg를 사용하므로, 비디오 데이터가 전처리를 위해 클라우드 서비스로 업로드되지 않음을 보장합니다.

설치 및 사용법

시스템 요구 사항

claude-real-video는 Python 3.10+ 및 시스템 경로에 설치된 ffmpeg가 필요합니다.

설치

사용자는 핵심 기능 또는 트랜스크립션을 포함한 전체 제품군을 설치할 수 있습니다:

# 핵심 프레임 및 중복 제거
pip install claude-real-video

# 오디오 트랜스크립션을 포함한 전체 제품군
pip install "claude-real-video[whisper]"

기본 명령어

  • URL로부터: crv "https://www.youtube.com/watch?v=..."
  • 로컬 파일로부터: crv lecture.mp4 -o out --lang en
  • 프레임만: crv clip.mp4 --no-transcribe
  • 로그인 제한 콘텐츠: crv "https://..." --cookies cookies.txt

설정 옵션 요약

Flag Default Description
--scene 0.30 장면 변화 감지 민감도 (낮을수록 = 더 많은 프레임)
--fps-floor 1.0 최소 프레임 캡처 빈도 (N초마다 한 프레임)
--max-frames 150 추출할 최대 총 프레임 수
--dedup-threshold 8 새로운 프레임으로 간주하기 위해 필요한 픽셀 변화율
--dedup-window 4 중복 제거를 위해 비교할 이전 프레임 수
--report off 유지/삭제 결정을 시각화하기 위해 report.html 생성

Sources