Claude Video Vision

ffmpeg 프레임과 Whisper·Gemini 오디오를 결합해 Claude Code가 영상을 조사하게 하는 플러그인

/plugin marketplace add https://github.com/jordanrendric/claude-video-vision ; /plugin install claude-video-vision

로컬 영상 파일이나 YouTube URL에서 ffmpeg로 프레임을 추출하고 오디오를 전사해 Claude Code 세션에 시간 정보와 함께 전달하는 제3자 플러그인입니다. Gemini API, 로컬 whisper.cpp·openai-whisper, OpenAI Whisper API 중 오디오 백엔드를 고를 수 있고 영상 프레임은 항상 Claude가 이미지로 직접 봅니다. `video_analyze`로 장면 전환·무음·동결·흐림·동작 특성을 먼저 조사한 뒤 `video_watch`와 `video_detail`로 필요한 구간만 고해상도·가변 FPS로 읽는 흐름을 제공합니다. MCP 서버는 npm에서 첫 사용 시 자동 설치되며 6개 도구와 설정 마법사를 노출합니다. 긴 영상은 세션 캐시와 샘플링으로 컨텍스트 사용량을 줄일 수 있습니다.

판단

이럴 때 씁니다

  • 버그 재현 영상·제품 데모·강의를 Claude Code 구현 작업의 직접 근거로 쓰고 싶을 때
  • 긴 영상의 구조를 먼저 분석한 뒤 필요한 순간만 상세히 읽어 컨텍스트를 아끼고 싶을 때
  • 오디오 전사를 로컬 Whisper와 외부 API 사이에서 선택해야 할 때

이럴 땐 쓰지 마세요

  • Claude Code를 사용하지 않거나 MCP 서버 실행을 허용할 수 없는 환경
  • 영상·오디오가 외부 모델에 전달될 수 없는데 로컬 Whisper를 설치할 자원도 없는 경우
  • 저작권·서비스 약관상 다운로드나 프레임 추출 권한이 없는 영상

차별점

  • 프레임 추출과 오디오 전사를 병렬 처리하고 원본 영상 시간축에 맞춰 함께 전달합니다.
  • 장면 전환·무음·동결·흐림·SITI 같은 구조 분석을 먼저 수행해 긴 영상에서 볼 구간을 줄입니다.
  • Gemini API, OpenAI API와 완전 로컬 Whisper 중 비용·개인정보 조건에 맞는 오디오 백엔드를 고를 수 있습니다.
  • 세션별 프레임 캐시, 가변 구간 FPS, 균등 샘플로 이미지 컨텍스트 사용량을 제어합니다.

워크플로

  1. 01Claude Code 마켓플레이스에 공식 저장소를 추가하고 플러그인을 설치합니다.
  2. 02`/setup-video-vision`에서 ffmpeg와 Node.js를 확인하고 로컬 Whisper 또는 API 백엔드를 고릅니다.
  3. 03긴 영상은 `video_analyze`로 장면·무음·동작 구조와 전사를 먼저 얻습니다.
  4. 04질문과 관련된 구간만 `video_watch`·`video_detail`로 프레임과 오디오를 읽습니다.
  5. 05분석 근거의 타임스탬프와 전사 출처를 확인한 뒤 코드 수정·문서화 작업에 사용합니다.

주요 명령

명령설명
/setup-video-vision오디오 백엔드, Whisper, 프레임 옵션과 필수 프로그램을 대화형으로 설정합니다.
/watch-video path/to/video.mp4로컬 영상에서 질문에 맞는 프레임과 오디오를 분석합니다.
/watch-video https://www.youtube.com/watch?v=...yt-dlp가 있을 때 YouTube 영상을 가져와 분석합니다.
video_analyze프레임을 대량으로 보기 전에 장면·무음·동작 등 영상 구조를 검사하는 MCP 도구입니다.
video_detail특정 시간 구간을 다른 FPS·해상도로 다시 추출합니다.

설정

{"backend":"local","whisper_engine":"cpp","frame_format":"jpeg","max_frames":100,"enable_index":false}

함정

설치 전에 확인하세요

  • Gemini·OpenAI 백엔드를 고르면 오디오가 해당 API로 전송되고 사용량이 과금될 수 있습니다. 민감 영상은 로컬 Whisper 경로를 우선 검토하세요.
  • 프레임은 base64 이미지로 Claude 컨텍스트를 차지합니다. 긴 영상은 `video_analyze` 후 필요한 구간만 샘플링하고 `max_frames`를 제한해야 합니다.
  • Node.js 20과 ffmpeg가 필수이며 YouTube URL에는 yt-dlp가 추가로 필요합니다. 영상 다운로드 권한과 서비스 약관을 사용자가 확인해야 합니다.
  • 공식 README의 Status 문구는 초기 v1.0.0 설명이 남아 있지만 현재 정본 태그와 npm 서버 버전은 v1.3.2입니다.
  • 로컬 Whisper 모델은 처음 내려받을 때 저장 공간과 시간이 필요합니다. 현재 릴리스는 체크섬 검증을 하지만 다운로드 출처와 캐시 위치를 운영 정책에 포함하세요.

비교

Kimi Code가 터미널 에이전트 자체에서 영상 입력을 받는다면 Claude Video Vision은 기존 Claude Code에 ffmpeg·전사·MCP 지각 계층만 추가합니다. HyperFrames가 HTML·CSS에서 영상을 만드는 렌더러라면 이 도구는 이미 있는 영상을 분석하는 반대 방향의 파이프라인입니다.

최근 변경

v1.3.2에서 Windows의 lavfi 경로 이스케이프와 whisper.cpp VAD·JSON 처리를 고쳤습니다.

공식 변경 내역