claude-real-video: 어떤 LLM이든 영상을 실제로 '볼 수' 있게 해주는 도구

Who Should Read

LLM에게 영상 내용을 분석시키고 싶은 개발자, 특히 프레젠테이션·튜토리얼·리뷰 영상을 AI로 자동 처리하려는 사람.

Core Mechanics

• Claude는 영상 파일 자체를 입력으로 받지 못하고, ChatGPT는 YouTube 링크를 넣으면 자막(텍스트)만 읽으며, Gemini는 고정 1fps로 프레임을 샘플링해 빠른 컷은 놓치고 정적인 화면은 중복 과다 추출하는 문제가 있다.
• claude-real-video는 고정 간격 대신 '장면 변화 감지(scene-change detection)' 방식으로 프레임을 추출한다. 즉 화면이 실제로 바뀔 때만 프레임을 저장하고, 최소 밀도 하한선(density floor)을 둬서 너무 드물게 추출되는 것도 방지한다.
• A-B-A 인터뷰 컷어웨이처럼 같은 장면이 반복될 때 중복 프레임이 계속 저장되는 문제를 막기 위해 '슬라이딩 윈도우 픽셀 차분 알고리즘(sliding-window pixel-diff dedup)'을 사용한다. 16x16 RGB 썸네일로 직전 N개 보존 프레임과 픽셀 차이를 비교해 중복을 걸러낸다.
• 10분짜리 프레젠테이션 기준으로 고정 간격 샘플링이면 약 600개 프레임이 나오는데, 이 도구를 쓰면 5~15개의 의미 있는 키프레임으로 압축된다. 90% 이상 토큰 절감 효과를 기대할 수 있다.
• 음성 처리도 포함된다. 영상에 내장된 자막이 있으면 그걸 우선 사용하고, 없으면 Whisper로 음성을 전사한다. 언어 자동 감지도 지원한다.
• 출력 결과는 `crv-out/frames/*.jpg`, `crv-out/transcript.txt`, `crv-out/MANIFEST.txt` 세 가지다. 이 파일들을 Claude, ChatGPT, Gemini 등 어느 LLM 채팅 인터페이스에든 그대로 드래그해서 질문할 수 있다.
• YouTube URL(yt-dlp 사용)과 로컬 파일 모두 입력으로 받는다. 모든 처리가 로컬에서 실행되어 영상 원본 자체는 외부로 전송되지 않는다. 단, 추출한 프레임을 Claude 등에 붙여넣으면 그건 당연히 해당 서비스 서버로 전송된다.
• `--report` 옵션을 쓰면 각 프레임마다 보존/드롭 결정과 픽셀 차이 퍼센트를 보여주는 독립 실행형 HTML 리포트가 생성된다. 임계값(threshold)을 시각적으로 튜닝하는 데 유용하다.

Evidence

• 'Where the video goes: stays on your machine'이라는 홍보 문구에 대해, 추출된 프레임을 Claude에 업로드하면 결국 Anthropic 서버로 전송되는 것 아니냐는 지적이 있었다. 로컬 처리는 영상 원본에 한정된 이야기이고, 분석 결과물을 LLM에 보내는 순간 클라우드로 간다는 점은 명확히 해야 한다는 의견이다.
• 도구 이름에 'Claude'가 들어간 것에 대해, 실제로는 어떤 LLM에도 쓸 수 있는 범용 도구인데 특정 제품명을 붙이면 혼란스럽다는 이유로 이름을 바꾸는 게 낫겠다는 의견이 여러 명에게서 나왔다.
• 비슷한 도구를 직접 만들어봤다는 댓글에서, 모션 디자인 영상의 경우 LLM이 프레임만 보고 구체적인 애니메이션을 추론하는 건 잘 안 됐고, 여러 프레임을 그리드 이미지 하나로 합쳐서 보여줬을 때 어느 정도 작동했지만 세밀한 디테일은 여전히 놓쳤다는 경험이 공유됐다. 결국 직접 텍스트로 설명하는 게 제일 잘 됐다고.
• 키프레임은 영상이 아니기 때문에 LLM이 이미지 셋만으로 모션, 물체 연속성(object permanence) 같은 시간적 정보를 추론하는 데는 근본적인 한계가 있다는 비판도 있었다. 영상의 시각적 내용 파악에는 유용하지만 동작 분석에는 적합하지 않다는 지적이다.
• 충전 장비 테스트 시나리오로 활용 가능성을 언급한 댓글이 있었다. 전압계와 온도계를 카메라로 찍고 이 도구에 돌리면 배터리 충전 속도, 온도 변화 같은 데이터를 LLM이 자동으로 정리해줄 수 있겠다는 구체적 사용 아이디어였다.

How to Apply

• 긴 프레젠테이션이나 강의 영상을 LLM으로 요약하고 싶을 때, `pip install claude-real-video && crv 'https://youtube.com/watch?v=...' --report` 한 줄로 키프레임과 자막을 뽑아 Claude나 ChatGPT에 붙여넣으면 600개짜리 프레임 대신 5~15개만 쓰게 되어 API 비용을 대폭 줄일 수 있다.
• 프레임 추출 임계값을 조정하고 싶으면 `--report` 옵션으로 HTML 리포트를 생성해 각 보존/드롭 결정과 픽셀 차이 퍼센트를 시각적으로 확인한 다음 threshold 파라미터를 영상 유형에 맞게 튜닝하면 된다.
• 사내 회의 녹화나 제품 데모 영상처럼 외부로 올리면 안 되는 영상을 분석해야 할 때, 이 도구로 로컬에서 프레임을 추출한 뒤 사내 LLM이나 로컬 모델(예: Ollama)에 넘기면 영상 원본 자체는 외부로 나가지 않는 흐름을 구성할 수 있다.
• 영상에서 측정 기기 수치나 화면 변화를 자동으로 기록해야 하는 경우(예: 충전 테스트, UI 변화 추적), 카메라로 촬영한 영상을 이 도구로 처리하면 변화가 생길 때마다 프레임이 캡처되므로 LLM에게 수치 변화 차트 생성을 요청하는 파이프라인을 만들 수 있다.

Code Example

# 설치
pip install claude-real-video

# YouTube URL 처리 (기본)
crv "https://www.youtube.com/watch?v=..."
# 출력: crv-out/frames/*.jpg + crv-out/transcript.txt + crv-out/MANIFEST.txt

# HTML 리포트 포함 (keep/drop 결정 시각화)
crv "https://youtube.com/watch?v=..." --report

# 로컬 파일도 지원
crv ./my_video.mp4

Terminology

관련 논문

• LLM을 활용한 Single/Multi Truth Data Fusion

  여러 소스의 충돌하는 데이터를 GPT-4o-mini 프롬프트로 병합하면 기존 비지도 방법보다 일관되게 F1 점수가 높다.

• 다국어 Reasoning Cascade는 더 많은 Context가 필요하다

  번역 cascade 파이프라인에서 원본 질문을 마지막까지 유지하면 추가 학습 없이 다국어 성능이 크게 오른다.

• Back-and-Forth를 줄여라: Structured Prompting 비교 연구

  체크리스트 형식으로 프롬프트를 구조화하면 LLM 답변 품질도 높아지고 토큰도 적게 쓴다.

• Training-Free Cultural Alignment: Persona 불일치를 활용한 LLM 문화적 정렬

  재학습 없이 각 나라의 도덕적 가치관에 맞게 LLM 출력을 조정하는 추론 시점 기법 DISCA 제안

• Claude Code에서 HTML을 출력 포맷으로 쓰는 이유: Markdown보다 나은 점들

  Claude Code 팀이 Markdown 대신 HTML을 LLM 출력 포맷으로 선호하기 시작한 이유와 그 실용적 장점을 정리한 글로, AI와 함께 문서/스펙/대시보드를 만드는 워크플로우에 직접적인 영향을 준다.

• 언제 투표하고 언제 다시 쓸까: Disagreement 기반 Test-Time Scaling 전략 라우팅

  모델 출력이 얼마나 일치하는지 보고 쉬운 문제엔 majority voting, 어려운 문제엔 문제 rewriting을 자동으로 선택해 정확도 3~7% 올리고 샘플링 비용도 줄이는 학습 불필요 프레임워크.

• Less Is More: Android 앱에 On-Device Small Language Model 통합할 때 실제로 겪는 엔지니어링 문제들

Related Resources

• claude-real-video GitHub 레포지토리 (MIT 라이선스)