LLM이 영상을 "진짜로" 보게 만드는 오픈소스 — claude-real-video 분석 (github.com)

한줄 요약

LLM에게 영상을 이해시키는 가장 현실적인 방법 — 장면 감지·중복 제거·로컬 처리까지 한 번에.

무엇이 달라지나?

LLM이 영상을 "본다"고 말할 때 실제로 일어나는 일은 대부분 기대와 다르다. ChatGPT에 YouTube 링크를 붙여넣으면 모델이 읽는 건 자막 텍스트지 화면이 아니다. Claude는 아예 영상 파일을 직접 받지 않는다. 네이티브 비디오 처리를 지원한다는 Gemini조차 기본 설정에서 초당 1프레임이라는 고정 간격으로 샘플링하기 때문에 빠르게 전환되는 장면은 통째로 건너뛰어진다.

claude-real-video는 이 문제를 완전히 다른 방식으로 푼다. 핵심은 두 가지다.

첫째, 프레임 선택 기준이 다르다. 고정 시간 간격이 아니라 장면 전환이 감지될 때마다 프레임을 뽑는다. 10분짜리 슬라이드 강의라면 거의 동일한 수백 장 대신 실제 슬라이드 변경 시점의 프레임만 추출되고, 빠른 컷 편집 영상이라면 놓치지 않고 각 컷을 잡아낸다.

둘째, 슬라이딩 윈도우 기반 중복 제거를 사용한다. A-B-A 순서로 화면이 전환될 때 A 장면이 두 번 들어가는 문제를 방지한다. 중복 판별은 퍼셉추얼 해시가 아니라 실제 픽셀 차이(다운스케일된 RGB 비교)를 쓴다. 퍼셉추얼 해시는 단색 배경이나 밝기가 같은 색상 변화에서 오판하는 사례가 있기 때문이다.

처리 결과물은 frames/*.jpg, transcript.txt, MANIFEST.txt 세 가지다. 이 폴더를 Claude, ChatGPT, Gemini 어디에든 그대로 첨부하면 된다. 영상 파일이 외부 서버로 전송되지 않고 로컬에서 전부 처리된다는 점도 실무 관점에서 중요하다.

오디오는 Whisper를 통해 전사하되, 로컬 파일에 이미 자막 파일(.srt/.vtt)이 있거나 임베디드 자막 트랙이 있으면 그쪽을 우선 사용한다. 재전사보다 빠르고 정확하다. --keep-audio 옵션을 쓰면 원본 사운드트랙 전체를 audio.m4a로 저장해 GPT-4o나 Gemini처럼 오디오를 직접 처리할 수 있는 모델에도 넘길 수 있다.

라이선스는 MIT이고 Python 3.10 이상, macOS·Windows·Linux 모두 지원한다.

---

실무에서 어떤 의미인가?

영상을 다루는 서비스를 개발하거나, 영상 콘텐츠를 AI로 분석하는 파이프라인을 구성할 때 이 도구가 해결하는 문제는 꽤 구체적이다.

컨텍스트 비용 문제. LLM API는 토큰 또는 첨부 파일 수에 따라 비용이 달라진다. 고정 간격 샘플링은 정적인 화면에서 거의 동일한 프레임을 수십 장씩 만들어낸다. 중복 제거 후 "더 적고 더 의미 있는" 프레임만 남기면 같은 이해 수준을 더 낮은 비용으로 얻을 수 있다.

프라이버시와 보안. 영상 내용이 민감한 경우 외부 클라우드로 파일을 올리는 것 자체가 문제가 된다. 로컬에서 전처리 후 텍스트와 이미지만 API에 전달하는 구조는 이 리스크를 줄이는 데 유효하다.

파이프라인 유연성. Python API(process() 함수)를 제공하기 때문에 단순 CLI 사용을 넘어 기존 백엔드 로직에 바로 붙일 수 있다. YouTube, Instagram, TikTok 등 yt-dlp가 지원하는 소스라면 URL만으로 처리가 가능하고, 로그인이 필요한 소스는 쿠키 파일을 넘기는 방식으로 처리한다.

외주 개발이나 AI 기능 통합 프로젝트에서 "영상 이해" 기능을 붙여야 할 때, 무거운 멀티모달 파이프라인을 새로 설계하기 전에 이 도구가 커버하는 범위를 먼저 확인해보는 게 현실적인 출발점이다.

도입 전 체크포인트

도구 자체는 단순하지만 실 서비스에 붙이기 전에 확인해야 할 항목들이 있다.

ffmpeg 의존성. pip 설치만으로 완결되지 않는다. ffmpeg와 ffprobe가 시스템 PATH에 잡혀 있어야 한다. 서버 환경이나 Docker 이미지 구성 시 이 단계를 빠뜨리면 런타임에서 실패한다.

Whisper 처리 시간. 로컬 Whisper 전사는 GPU 없이 긴 영상을 처리할 경우 상당한 시간이 걸릴 수 있다. 이미 자막이 있는 콘텐츠를 다룬다면 --no-transcribe로 건너뛰거나 사이드카 자막을 활용하는 쪽이 낫다.

프레임 수 상한. 기본 최대 프레임은 150장으로 하드캡이 걸려 있다. --max-frames 옵션으로 조정 가능하다. 영상 길이와 LLM 컨텍스트 한도를 고려해 적절한 값을 설정해야 한다.

저작권 주의. 도구가 기술적으로 다운로드를 지원한다고 해서 모든 영상에 적용해도 되는 건 아니다. 권한이 있는 콘텐츠에만 사용해야 하고, --cookies 옵션에 쓰는 인증 정보를 코드 저장소에 커밋하지 않도록 각별히 신경 써야 한다.