TL;DR

이 레포는 Claude에 영상 '보기' 권한을 부여하는 스킬과 도구 모음으로, URL이나 로컬 파일을 받아 캡션을 우선 조회하고 필요 시 오디오를 Whisper로 전송해 전사를 확보한 뒤 ffmpeg로 장면 기반 또는 키프레임 기반 후보를 추출해 Claude에 프레임과 전사를 함께 전달한다. 프레임 추출은 `efficient`, `balanced`, `token-burner` 같은 모드로 속도와 시각 커버리지를 교환하며 예시 실험에서 `efficient`는 약 0.5초, `balanced`는 약 20.9초의 추출 시간을 기록했고 프레임당 이미지 토큰 추정치가 명시되어 토큰 비용 추산이 가능하다. 프레임 중복 제거와 프레임 예산 설계로 비용을 통제하면서 특정 타임스탬프에 대한 고밀도 샘플링이 가능하도록 해 요약·버그 진단·콘텐츠 분석 워크플로에 실용적인 대안을 제시하지만, 긴 영상에서는 기본 캡 모드가 희박한 스캔을 유발할 수 있어 집중 구간 재실행이나 uncapped 모드 선택이 필요한 한계가 있다.

주요 기능

• 캡션 우선 검색과 필요시 오디오 기반 전사를 수행해 텍스트 전사 결과를 확보한다. yt-dlp로 가능한 캡션 트랙을 먼저 확인하고 캡션이 없을 때만 오디오를 추출해 Whisper 백엔드로 전송하므로 불필요한 다운로드를 줄인다. 이 전략으로 `transcript` 모드는 거의 즉시 텍스트만으로 전체 영상의 내용을 다룰 수 있다.
• 프레임 추출에서 세 가지 모드(transcript|efficient|balanced|token-burner)를 제공해 속도와 시각 커버리지를 조절한다. `efficient`는 키프레임 기반으로 빠르게 추출해 예시에서 약 0.5초로 전체 범위를 커버했고 `balanced`와 `token-burner`는 장면 변화 기반 후보를 디코딩해 더 많은 프레임을 확보하되 시간이 더 소요되었다. 모드별 샘플링은 전체 구간에서 균등하게 분포되도록 설계되어 마지막 프레임이 항상 포함된다.
• 프레임 중복 제거를 기본으로 적용해 동일하거나 거의 동일한 장면을 자동으로 감축한다. 16×16 그레이스케일 썸네일을 만들고 평균 절대 밝기 차이(mean absolute difference)를 계산해 임계값 이하이면 드롭하는 방식으로, 느린 페이드나 장시간 고정 화면에서 중복을 효과적으로 제거한다. 중복 제거가 적용된 후에 프레임 예산이 집행되므로 토큰 비용이 불필요하게 증가하지 않는다.
• Claude에 프레임 파일 경로와 타임스탬프가 포함된 전사 텍스트를 함께 전달해 이미지와 텍스트를 결합한 근거 기반 응답을 생성한다. 각 프레임은 JPEG로 제공되어 Claude의 `Read` 멀티모달 컨텍스트에서 병렬로 렌더링되며, 질문자가 특정 타임스탬프를 지정하면 해당 구간의 고밀도 샘플링으로 더 정밀한 응답을 얻을 수 있다. 작업 완료 시 자동으로 작업 디렉토리를 정리해 후속 호출에서 잡음이 남지 않도록 관리한다.

어떻게 동작하는가

사용자가 URL이나 로컬 경로와 질의를 입력하면 yt-dlp가 먼저 캡션을 확인하고 캡션이 없을 때만 필요한 미디어를 내려받는 흐름으로 동작한다. ffmpeg는 선택한 디테일 모드에 따라 키프레임 또는 장면 분리 후보를 디코딩해 JPEG 프레임을 생성하고, 파이썬 표준 라이브러리 기반의 경량 전처리로 16×16 썸네일을 만들어 mean absolute difference 기준으로 중복을 제거한다. 확보된 타임스탬프 전사와 프레임 경로를 Claude에 전달해 Claude의 `Read` 멀티모달 처리로 시각·청각 근거에 기반한 응답을 산출한다.

해결 문제

영상의 텍스트 설명이나 제목만으로는 포착하기 어려운 화면상의 정보와 음성 내용을 결합해 질의응답과 요약을 가능하게 했다. 긴 영상을 전부 재생하지 않고도 캡션과 선택된 프레임만으로 핵심 순간을 찾거나 버그 발생 장면을 pinpoint하는 과제를 해결했다. 또한 프레임 예산과 중복 제거로 이미지 토큰 비용을 통제해 실용적인 비용-정확도 균형을 제공한다.

지금 주목받는 이유

레포는 Claude 멀티모달 인터랙션을 영상까지 확장하는 실용적 기능을 제공하며 GitHub에서 수천 개의 스타를 얻어 사용자 관심을 입증했다. 다양한 에이전트 호스트에 손쉽게 설치 가능한 스킬 형식을 채택해 실무 도입 장벽을 낮춘 점이 주목을 받았다. 또한 캡션 우선 전략과 Whisper 기반의 조건부 전사로 비용과 속도 측면에서 현실적인 대안을 제시한 점이 인기를 끌었다.

차별점

• Claude 플랫폼과의 직접적인 스킬 형태 통합으로 설치 대상 호스트(Claude Code, Codex, Cursor, Copilot, Gemini CLI 등)에서 동일한 SKILL.md 기반 런타임을 복사하거나 심볼릭 링크로 작동하게 했다. 이 구조는 스킬이 호스트별 런타임 환경에 맞춰 독립적으로 실행되면서도 동일한 동작을 보장한다. README에 명시된 설치 플로우와 marketplace 연동은 여러 에코시스템에서 일관된 사용성을 제공한 점에서 차별화된다.
• 프레임 예산 제어와 모드별 후보 소스 분리를 통해 속도와 토큰 비용을 명확히 조절할 수 있게 했다. `efficient`는 키프레임 전용으로 매우 빠른 추출을 제공하고 `balanced`/`token-burner`는 장면분리 후보를 디코딩해 더 정밀한 시각 커버리지를 제공하며, 모든 모드는 후보를 고르게 샘플링해 구간 끝이 항상 포함되도록 설계되었다. 이 접근은 단순히 프레임 수를 줄이는 것이 아니라 어떤 기준으로 샘플링하고 어떤 트레이드오프가 발생하는지 명확히 제어한다.
• 프레임 중복 제거를 썸네일 기반의 평균 밝기 차이로 구현해 이미지 라이브러리 의존성을 피하면서도 느린 페이드와 같은 케이스에서 실제로 중복을 잡아내도록 설계되었다. 중복 기준이 '이전에 보관된 프레임'과 비교하도록 되어 있어 연속된 낙차가 누적되어도 동일 장면 판단이 유지된다. 이로 인해 화면이 거의 고정된 녹화물에서 불필요한 토큰 소비를 크게 줄일 수 있다.

사용 사례

• 바이럴 영상이나 경쟁사 발표의 구조와 훅을 빠르게 파악해 콘텐츠 전략에 반영할 수 있다. 레포의 흐름은 영상의 초기 프레임과 타임스탬프 전사를 조합해 오프닝 훅과 메시지 전개를 분해하도록 설계되어 긴 영상을 빠르게 분석하는 데 유리하다. 이 과정은 수동으로 2배속 시청하는 것보다 핵심을 빠르게 추출하도록 토큰과 프레임 예산을 활용한다.
• 화면 녹화로 전달된 버그 재현 영상을 자동으로 검사해 문제 발생 시점을 찾아낼 수 있다. 시스템은 프레임과 전사를 동시에 검토해 오류가 화면에 처음 드러난 프레임을 식별하고 그 프레임 주변의 대화 내용을 근거로 원인을 짐작할 수 있게 했다. 결과적으로 디버깅에서 재현과 원인 규명을 위한 최초 조사 시간을 단축한다.
• 교육용 강의나 코스 재생목록을 각 동영상별 요약 노트로 전환해 검색 가능한 문서 모음으로 만들 수 있다. 레포는 재생목록을 순회하며 각 영상의 구조와 주요 발언, 화면 예시를 추출해 노트 항목으로 정리하는 워크플로를 지원하도록 설계되어 콘텐츠 소비 비용을 낮춘다. 이 방식은 학습 자료를 빠르게 색인화하여 반복 학습의 효율을 높인다.
• 제품 출시나 발표 영상에서 실질적으로 새로워진 기능만 골라내는 용도로 활용할 수 있다. 스크립트는 영상 전체를 훑은 뒤 '실제'로 보이는 시각적 증거와 발언을 결합해 과장된 소개 문구를 걸러내고 핵심 변경 사항을 요약한다. 이는 마케팅 과대포장과 기술적 개선을 구분해 의사결정 자료로 쓰기 적합하다.

시작하기

가장 간단한 시작법은 Claude Code 환경에서 `/plugin marketplace add bradautomates/claude-video` 후 `/plugin install watch@claude-video`를 실행하는 것이다. Agent Skills 생태계에서는 `npx skills add bradautomates/claude-video -g`로 전역 설치하거나 소스 코드를 클론해 `skills/watch` 디렉토리를 호스트의 스킬 폴더에 심볼릭 링크하면 된다. 첫 실행 시 `yt-dlp`와 `ffmpeg`가 없으면 자동으로 설치를 안내하거나 macOS에서는 `brew`로 자동 설치하고, Whisper 키가 필요한 경우 `~/.config/watch/.env`에 템플릿을 생성한다.

요구사항

• Python 3가 필요하며 스크립트는 표준 라이브러리와 pytest(테스트용)를 사용한다.
• ffmpeg와 yt-dlp가 PATH에 있어야 하며 첫 실행에서 자동 설치 안내가 제공된다.
• 선택적으로 Groq 또는 OpenAI Whisper API 키가 필요하며 키는 `~/.config/watch/.env`에 설정한다.
• Claude 플랫폼 또는 호환 에이전트 호스트(Claude Code, Codex, Cursor, Copilot, Gemini CLI 등)가 필요하다.

벤치마크