몇 달 전, 저는 AI 채팅창에 YouTube 링크를 붙여넣고 "이 영상에서 무슨 일이 일어나나요?"라고 물었습니다.

AI는 즉각적으로, 그리고 자신 있게 대답했습니다. 하지만 그 내용은 완전히 _자막(transcript)_에 기반한 것이었습니다. 영상 중간에는 클립의 핵심 포인트인 시각적 유머(sight gag)가 있었지만, 모델은 단 한 프레임도 보여준 적이 없었기에 전혀 알지 못했습니다.

이 점이 너무 신경 쓰여서, 저는 어떤 영상이든 LLM이 실제로 읽을 수 있는 형태로 변환해 주는 작은 오픈 소스 CLI인 claude-real-video (crv)를 만들었습니다. 이 프로젝트는 Hacker News 메인 페이지에 올라갔고, 방금 GitHub 스타 1.6k를 돌파했습니다. 그래서 이제 이것이 내부적으로 어떻게 작동하는지 정리해 볼 때가 되었다고 생각했습니다.

단순한 접근 방식은 토큰 문제로 실패합니다

가장 뻔한 해결책은 "프레임을 추출해서 붙여넣는 것"입니다. 하지만 1 fps의 고정된 속도로 추출하면, 58초짜리 클립은 58개의 이미지가 됩니다. 대부분은 인접한 프레임과 거의 중복되는 이미지이며, 비전 토큰(vision tokens)은 비용이 많이 듭니다. 즉, 모델에게 똑같은 말하는 얼굴을 40번 보여주는 데 비용을 지불하게 되는 셈입니다.

고정 간격 샘플링(Fixed-interval sampling)은 반대의 실패 사례도 가집니다. 두 샘플 사이의 빠른 컷(cut)은 그냥 사라져 버립니다.

crv가 대신 하는 일

pip install "claude-real-video[whisper]"
crv "https://www.youtube.com/watch?v=..."
# → crv-out/frames/*.jpg + frames.json + transcript.txt/.json + MANIFEST.txt

모든 것은 로컬에서 실행됩니다. 핵심 경로를 위해 다운로드해야 할 ML 모델은 없습니다. ffmpeg가 힘든 일을 대신 수행합니다.

1. 고정된 할당량이 아닌 장면 전환 감지(Scene-change detection). 한 번의 ffmpeg 메타데이터 패스를 통해 모든 프레임에 대한 장면 점수(scene score)를 계산합니다. 콘텐츠가 실제로 변하는 지점의 프레임만 유지하므로, 동일한 58초 클립이 58개가 아닌 26개의 프레임으로 추출됩니다. 또한 장면 점수가 급증하는 지점이 바로 컷(cut)이기 때문에 어떤 컷도 놓치지 않습니다.

2. 슬라이딩 윈도우 중복 제거(Sliding-window dedup). 임계값을 통과한 거의 중복되는 이미지들은 슬라이딩 윈도우와 비교되어 제거됩니다. 남은 것은 서로 다른 최소한의 프레임 세트입니다.

3. 컨택트 시트 (Contact sheets). --grid는 살아남은 프레임들을 몇 개의 라벨이 붙은 그리드 이미지로 묶습니다. 26개의 프레임이 3개의 컨택트 시트로 변환됩니다. 이미지 수는 줄어들지만 정보량은 동일하며, 각 셀에 타임스탬프(timestamps)가 인쇄되어 모델이 "0:41에"와 같은 참조를 정확하게 수행할 수 있습니다.

4. 타임스탬프가 포함된 전사 (Timestamped transcript). 플랫폼에서 제공하는 경우 자막을 사용하고, 그렇지 않은 경우 Whisper를 사용합니다. 이는 일반 텍스트와 세그먼트별 타임스탬프가 포함된 transcript.json 형식 모두로 작성되어, 프레임과 단어가 하나의 타임라인 상에서 일치하게 됩니다.

출력물은 최상단에 MANIFEST.txt가 있는 하나의 폴더입니다. 이를 Claude, ChatGPT 또는 Gemini에 넣고 질문하면 됩니다.

실제 사용자들이 발견한 두 가지 실패 모드

고정된 장면 점수(scene-score) 임계값에는 사각지대가 있음이 밝혀졌으며, 두 가지 해결책 모두 GitHub 이슈를 통해 도출되었습니다.

느린 모핑(morphs)은 절대 급증하지 않습니다. 한 애니메이터는 2~3초간 지속되는 스쿼시 앤 스트레치(squash-and-stretch)가 단 하나의 프레임도 트리거하지 못한다고 보고했습니다. 즉, 개별 프레임이 이전 프레임과 충분히 다르지 않은 것입니다. --adaptive는 전역 상수 대신 각 프레임을 2초 이동 평균(rolling 2-second neighbourhood mean)과 비교하여 점수를 매김으로써 이 문제를 해결합니다. 느린 변화는 로컬 기준선(local baseline)에 대비하여 누적되므로 포착될 수 있습니다.

화자가 바뀔 때 슬라이드(slides)가 바뀌지 않습니다. 강의나 화면 녹화에서는 오디오가 세 가지 아이디어를 진행하는 동안 화면이 1분 동안 정지해 있을 수 있습니다. --text-anchors는 각 자막 큐 타임스탬프(초당 최대 1개로 제한)마다 하나의 추가 프레임을 강제로 삽입하여, 장면 탐지(scene detection)가 아무것도 감지하지 못할 때도 모든 발화 세그먼트에 일치하는 시각 자료가 있도록 합니다.

여기서 로컬(local)이 중요한 이유

모델은 비디오 파일 자체가 필요하지 않습니다. 모델에게 필요한 것은 '잔여물(residue)'입니다. 즉, 어떤 프레임이 변했는지, 무엇이 말해졌는지, 그리고 언제인지에 대한 정보입니다. 이 잔여물은 ffmpeg가 있는 어떤 노트북에서도 계산할 수 있을 만큼 충분히 작으므로, 비디오 파일 자체가 사용자의 기기를 떠날 필요가 없음을 의미합니다. 그 이후에 클라우드 LLM으로 전송되는 것은 오직 당신이 붙여넣기로 선택한 것뿐입니다.

Claude Code를 사용 중이라면, 리포지토리에 skill 폴더가 포함되어 있습니다. 이를 설치하면 에이전트가 링크를 붙여넣었을 때 스스로 영상을 시청합니다.

솔직한 각주

crv는 MIT 라이선스이며 계속해서 무료로 제공됩니다. 저는 크리에이터를 위해 카메라 움직임(camera-motion) 및 감정 타임라인(emotion-timeline) 분석 기능을 추가한 유료 애드온(crv Pro)을 통해 이 작업을 후원합니다. 무료 코어는 데모가 아닌 완전한 시청 파이프라인(watching pipeline)입니다.

Repo: https://github.com/HUANGCHIHHUNGLeo/claude-real-video
PyPI: https://pypi.org/project/claude-real-video/

— Leo Huang (黃志弘, LeoAido), AI 팀과 함께 1인 기업을 구축 중.