Claude에게 모든 영상을 시청할 수 있는 능력 부여하기

Claude에게 어떤 영상이든 시청할 수 있는 능력을 부여하세요.

Claude Code:

/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

claude.ai (web): watch.skill을 다운로드하여

Settings → Capabilities → Skills에 드롭하세요.

Codex / 일반적인 기술 (generic skills):

git clone https://github.com/bradautomates/claude-video.git ~/.codex/skills/watch

설정 없이 바로 시작 가능 — yt-dlp와

ffmpeg를

첫 실행 시 brew를 통해 설치합니다.

macOS 기준 (Linux/Windows의 경우 정확한 명령어를 출력합니다). 자막(Captions)은 대부분의 공개 영상을 무료로 커버합니다. Whisper API 키는 영상에 자막이 없는 경우에만 필요합니다.

Claude는 웹페이지를 읽고, 스크립트를 실행하며, 저장소(repo)를 탐색할 수 있습니다. 하지만 기본 상태(out of the box)에서 할 수 없는 것은 바로 영상을 시청하는 것입니다. YouTube 링크를 붙여넣으면 Claude는 제목을 통해 추측하거나, 화면에 나오는 내용의 90%가 누락된 스크립트를 가져와야만 합니다.

Claude Video /watch를 사용하면

URL이나 로컬 경로를 붙여넣고 질문을 던질 수 있습니다. 그러면 Claude는 영상을 다운로드하고, 자동 스케일링된 비율로 프레임(frames)을 추출하며, 타임스탬프가 찍힌 스크립트를 가져오고 (자막이 있는 경우 무료 자막 사용, 실패 시 Whisper API를 대체제로 사용), 모든 프레임을 이미지로서 읽습니다 (Read).

Claude가 답변을 할 때쯤이면, 이미 영상을 보고 오디오를 들은 상태가 됩니다.

/watch https://youtu.be/dQW4w9WgXcQ 30초 지점에 어떤 일이 일어나나요?

저는 콘텐츠를 따라잡기 위해 끊임없이 영상을 사용하기 때문에 이것을 만들었습니다. 화제가 되고 있는 YouTube 영상을 보면, 제작자가 후크(hook)를 어떻게 구성했는지 — 처음 3초 동안 화면에 무엇이 나오는지, 무엇을 말했는지, 왜 효과적이었는지 알고 싶습니다. 예전에는 메모장을 들고 직접 영상을 시청해야 했습니다. 이제는 그냥 URL을 붙여넣고 질문하면 됩니다.

나머지 절반은 요약(summarization)입니다. 대부분의 YouTube 영상은 제 주의력을 20분 동안이나 쏟을 가치가 없습니다. URL을 Claude에게 전달하면, Claude가 스크립트를 가져와 실제로 어떤 일이 일어났는지 알려줍니다. 시각적 요소가 중요하다면 프레임도 함께 제공됩니다. 팟캐스트나 토킹 헤드(talking head) 형식이라면 스크립트만으로도 충분합니다.

Claude는 읽고 종합하는 능력이 뛰어나지만, 지금까지 비디오는 제가 전달할 수 없었던 유일한 입력 방식이었습니다. YouTube 링크를 붙여넣어도 유용한 결과는 얻을 수 없었습니다. /watch가 그 간극을 메워줍니다.

타인의 콘텐츠 분석하기. /watch https://youtu.be/<viral-video> 어떤 훅(hook)으로 시작했나요?

Claude는 첫 프레임들을 살펴보고, 오프닝 스크립트(transcript)를 읽으며, 구조를 분석합니다. 광고 크리에이티브, 경쟁사의 출시 제품, 팟캐스트 인트로 등 '무엇(what)'만큼이나 '어떻게(how)'가 중요한 모든 경우에 동일하게 적용됩니다.

비디오를 통한 버그 진단. 누군가 고장 난 화면을 녹화한 영상을 보냅니다. /watch bug-repro.mov 무엇이 잘못되었나요?

Claude는 녹화 영상을 시청하고, 문제가 발생하는 프레임을 찾아내며, 화면에 무엇이 있는지 설명합니다. 사용자가 파일을 직접 열어보지 않고도 원인을 잡아내는 경우가 많습니다.

비디오 요약하기. /watch https://youtu.be/<long-thing> 이것을 요약해줘

당연한 일을 수행합니다. 구조, 핵심 순간, 실제로 말하고 보여준 내용을 추출합니다. 2배속으로 시청하는 것보다 빠릅니다.

비디오와 질문을 함께 붙여넣기. URL(yt-dlp가 지원하는 모든 것 — YouTube, Loom, TikTok, X, Instagram 및 수백 개 더 포함) 또는 로컬 경로(.mp4, .mov, .mkv, .webm)를 입력합니다. URL의 경우 임시 작업 디렉토리로 다운로드합니다. 로컬 파일의 경우 다운로드 없이 제자리에서 탐색(probed)합니다. yt-dlp가 이를 다운로드합니다. 프레임 예산(frame budget)은 길이에 따라 달라집니다: 30초 이하는 약 30프레임, 3060초는 약 40프레임, 13분은 약 60프레임, 3~10분은 약 80프레임, 그보다 길면 100프레임을 드문드문 추출합니다. 엄격한 상한선은 초당 2프레임(2 fps), 총 100프레임입니다. 기본적으로 가로 512px 크기의 JPEG를 사용하며, Claude가 화면상의 텍스트를 읽어야 하는 경우 ffmpeg를 사용하여 --resolution 1024로 해상도를 높여 프레임을 자동 스케일링된 비율로 추출합니다.

스크립트(transcript)는 두 곳 중 한 곳에서 가져옵니다.
첫 번째 시도: yt-dlp가 소스에서 네이티브 자막(수동 또는 자동 생성)을 가져옵니다. 무료이며, 즉각적이고, 어느 정도 정확합니다.
대체 방법(Fallback): 모노 16 kHz 오디오 클립을 추출하여 Whisper로 전송합니다. Groq의 whisper-large-v3(권장 — 더 저렴하고 빠름) 또는 OpenAI의 whisper-1을 사용합니다.

.프레임(Frames) + 전사(transcript)가 Claude에게 전달됩니다. 스크립트는 t=MM:SS 마커가 포함된 프레임 경로와 타임스탬프가 포함된 전사 내용을 출력합니다. Claude는 각 프레임을 병렬로 읽습니다(Read) — JPEG 파일은 컨텍스트 내에서 이미지로 직접 렌더링됩니다.

Claude는 화면에 실제로 나타나는 내용과 오디오에 기반하여 답변합니다. "설명에 기반하여" 또는 "제목에 따르면"이 아닙니다. Claude는 프레임을 보았고, 전사를 들었습니다. 영상을 직접 시청한 사람과 같은 방식으로 답변합니다.

정리(Cleanup). 스크립트는 마지막에 작업 디렉토리를 출력합니다. 추가 질문을 하지 않는 경우, Claude가 이를 삭제합니다.

토큰 비용은 프레임에 의해 좌우됩니다. 모든 프레임은 이미지이며, 이미지 토큰은 빠르게 누적됩니다. 스크립트의 자동 FPS(auto-fps) 로직은 30분짜리 영상의 희소한 스캔(sparse scan)에 컨텍스트 예산을 낭비하지 않도록 하기 위해 존재합니다. 집중적인 30초 구간이 더 나은 답변을 줄 수 있기 때문입니다.

지속 시간	기본 프레임 예산	제공 내용
≤30초	~30 프레임	밀도 높음 — 기본적으로 모든 주요 순간
...

사용자가 특정 순간을 지정하면 ("2:30 부근", "마지막 30초", "0:45부터 1:00까지"), --start / --end를 전달합니다. 집중 모드(Focused mode)는 초당 예산이 더 밀도 있게 할당되며, 최대 2 fps로 제한됩니다. 전체 영상을 희소하게 훑는 것보다 훨씬 유용합니다.

환경	설치 방법
Claude Code	/plugin marketplace add bradautomates/claude-video 실행 후 /plugin install watch@claude-video
claude.ai (웹)	watch.skill 다운로드 → Settings → Capabilities → Skills → +
Codex	git clone https://github.com/bradautomates/claude-video.git ~/.codex/skills/watch
수동 / 개발자	git clone https://github.com/bradautomates/claude-video.git ~/.claude/skills/watch

/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

나중에 /plugin update watch@claude-video로 업데이트하세요.

• 최신 릴리스에서 watch.skill을 다운로드합니다. - Settings → Capabilities → Skills로 이동합니다.
• +를 클릭하고 파일을 드롭합니다.

먼저 Capabilities (기능) 항목에서 "Code execution and file creation" (코드 실행 및 파일 생성)을 활성화해야 합니다. 이 스킬은 ffmpeg와 yt-dlp를 외부 명령어로 호출하므로, 해당 도구들이 없으면 실행되지 않습니다.

git clone https://github.com/bradautomates/claude-video.git ~/.codex/skills/watch

git clone https://github.com/bradautomates/claude-video.git ~/.claude/skills/watch

첫 번째 /watch 호출 시, 스킬은 scripts/setup.py --check를 실행합니다. 만약 ffmpeg / yt-dlp가 PATH (경로)에 없거나, Whisper API 키가 설정되어 있지 않다면 문제를 해결할 수 있도록 안내합니다.

macOS— brew install ffmpeg yt-dlp를 자동으로 실행합니다.
Linux— 정확한 apt / dnf / pipx 명령어를 출력합니다.
Windows— winget / pip 명령어를 출력합니다.
API key— GROQ_API_KEY (권장) 및 OPENAI_API_KEY를 위한 주석 처리된 플레이스홀더가 포함된 ~/.config/watch/.env (모드 0600) 파일을 생성합니다.

설정 후 사전 점검 (preflight)은 조용히 지나가며, /watch가 즉시 작동합니다. 점검은 100ms 미만의 조회 작업이므로 이후 실행 시 속도를 저하시키지 않습니다.

자막은 대부분의 공개 영상을 무료로 커버합니다. Whisper 폴백 (fallback)은 영상에 실제로 자막 트랙이 없는 경우에만 작동합니다. 일반적으로 로컬 파일, TikTok, 일부 Vimeo, 그리고 간혹 자막이 없는 YouTube 업로드 영상이 이에 해당합니다.

기능 (Capability)	필요한 사항	비용
다운로드 + 기본 자막	yt-dlp + ffmpeg	무료
Whisper 폴백 (권장)	Groq API 키 — whisper-large-v3	저렴하고 빠름
Whisper 폴백 (대안)	OpenAI API 키 — whisper-1	표준 가격
Whisper 완전히 비활성화	--no-whisper	무료, 자막이 없을 때 프레임만 사용

/watch https://youtu.be/dQw4w9WgXcQ 30초 지점에 무슨 일이 일어나나요?
/watch https://www.tiktok.com/@user/video/123 이것을 요약해줘
/watch ~/Movies/screen-recording.mp4 UI가 언제 깨지나요?
...

특정 섹션에 집중 — 더 밀도 높은 프레임 예산, 더 낮은 토큰 비용:

/watch https://youtu.be/abc --start 2:15 --end 2:45
/watch video.mp4 --start 50 --end 60
/watch "$URL" --start 1:12:00 # 1시간 12분부터 끝까지

기타 옵션 (scripts/watch.py로 전달됨):

--max-frames N
— 토큰 예산을 타이트하게 관리하기 위해 프레임 상한선을 낮춥니다.

--resolution W
— Claude가 화면상의 텍스트(슬라이드, 터미널, 코드)를 읽어야 할 때 프레임 너비를 1024 px로 높입니다.

--fps F
— 자동 FPS (frames per second) 계산을 무시하고 설정합니다 (여전히 2 fps로 제한됨).

--whisper groq|openai
— 특정 Whisper 백엔드를 강제합니다.

--no-whisper
— 전사 (transcription) 기능을 완전히 비활성화합니다; 프레임만 사용합니다.

--out-dir DIR
— 작업 파일을 특정 위치에 보관합니다 (기본값: 자동 생성된 tmp 디렉토리).

최상의 정확도: 10분 미만.
10분이 넘어가면 스크립트가 "sparse scan" 경고를 출력합니다. 이 경우 --start 또는 --end를 사용하여 실제로 관심 있는 부분에 집중하여 다시 실행하세요.

강제 제한 사항: 2 fps, 100 프레임.
프레임 수는 토큰 비용을 결정합니다. 스크립트는 자동 FPS 계산 결과가 더 높더라도 이 제한을 강제합니다.

Whisper 업로드 제한: 25 MB.
모노 16 kHz 기준 약 50분 분량의 오디오입니다. 더 긴 영상은 자막을 사용하거나 --start / --end를 사용하여 더 짧은 구간을 지정해야 합니다.

비공개 플랫폼 사용 불가.
이 기능은 어떤 서비스에도 로그인하지 않습니다. 공개 URL 및 로컬 파일만 가능합니다. yt-dlp가 인증 없이 접근할 수 없다면 /watch 도구도 접근할 수 없습니다.

.
├── SKILL.md # skill contract — 세 가지 인터페이스 모두에서 로드됨
├── scripts/
...

# claude.ai 업로드 번들 빌드:
bash scripts/build-skill.sh # → dist/watch.skill

릴리스: vX.Y.Z 태그를 생성하고 태그를 푸시(push)하세요. 워크플로우가 dist/watch.skill을 빌드하고 이를 GitHub 릴리스에 첨부합니다.

버전 기록은 CHANGELOG.md를 참조하세요.

MIT 라이선스.

yt-dlp, ffmpeg, 그리고 Claude의 멀티모달 Read 도구를 기반으로 구축되었습니다. Whisper 전사는 Groq 또는 OpenAI를 통해 수행됩니다.