Watch Video

watch-video

Claude（または任意の MCP クライアント）に動画を視聴させます。ローカルファイルまたは URL（YouTube および yt-dlp 経由の 1,500 以上のサイト）を渡すと、タイムスタンプ付きの文字起こしと、シーンに応じて選ばれた数枚のキーフレームを取得し、必要なときだけ正確なフレームを詳しく確認します。クラウドでの文字起こしも、API キーも不要です。

> Watch https://www.youtube.com/watch?v=jNQXAC9IVRw and tell me what he says about the elephants.

$ video-cli overview https://www.youtube.com/watch?v=jNQXAC9IVRw --max-frames 8
# Me at the zoo
duration: 00:19
transcript: platform-subs:en, language=en, 6 segments, took 0.4s
keyframes: 3 scene-selected at 00:00, 00:05, 00:11
total time: 6.7s

## Transcript
[00:01] All right, so here we are, in front of the elephants
[00:05] the cool thing about these guys is that they have really... really really long trunks and that's cool
[00:16] and that's pretty much all there is to say
IMAGE: ~/.cache/video_mcp/Youtube_jNQXAC9IVRw/sheets_8/sheet_01.jpg

Claude: He stands in front of the elephants (00:01) and says the cool thing about them is
their really long trunks (00:05). That is the whole video (00:16).

このツールを選ぶ理由

	watch-video	クラウド動画 API（Gemini など）	文字起こしのみのツール
画面を認識する（コード、スライド、グラフ、UI）	はい：キーフレーム、高解像度フレーム、OCR	はい	いいえ
ローカルで実行され、アップロードされない	はい	いいえ：動画はプロバイダーに送信されます	さまざま
API キーまたはアカウント	不要	必須、使用ごとに課金	さまざま
字幕のない動画	ローカルの Parakeet / Whisper	はい	多くの場合、失敗します
映像解析にかかるトークンコスト	コンタクトシート約 20 フレーム分（画像約 1.5 枚分のコスト）	動画の長さに応じて課金	なし（映像なし）
プライベートな録画（会議、バグの再現動画）	安全：マシンの外に出ません	アップロードされます	さまざま

次の 2 つの要素で構成されています。

• video MCP サーバー：7 つのツールを提供します（以下を参照）。
• watch-video スキル：Claude に、まず概要を確認し、次にフレームを確認し、その後に範囲を確認する、コストを抑えたワークフローを教えます。

仕組み

手順	処理内容
文字起こし	動画に字幕があればプラットフォームの字幕（数秒）、なければ Parakeet TDT 0.6B v3（int8、CPU、ヨーロッパの 25 言語）、それ以外の言語では faster-whisper large-v3-turbo（GPU または language="auto"）を使用します。
キーフレーム	サムネイルサイズでキーフレームのみをデコードし、重複や静止スライドを除外してから、時間間隔が最も大きい箇所を埋めます。選択内容は動画の変化の度合い（画面録画かアクションか）に合わせて調整されます。
コンタクトシート	ラベル付きフレームをグリッドに並べます。フルサイズ画像 1.5 枚分のトークンコストで、約 20 フレームを確認できます。黒帯は自動的に切り抜かれます。
詳細確認	get_frames は正確なタイムスタンプにシークし、1280 px で取得します（コードやグラフを読み取れる解像度です）。URL の場合は、動画全体をダウンロードせずにストリーム内をシークします。

すべて ~/.cache/video_mcp にキャッシュされるため、再度呼び出すとすぐに結果が返ります。

中価格帯の CPU（i5-11400、GPU なし）での測定値：35.7 分のローカル動画の概要を約 2.6 分で生成、字幕付き YouTube 動画を約 7 秒で処理、詳細確認用のフレームを約 0.5 秒で取得。

インストール

要件：Python 3.10 以降、および PATH 上に ffmpeg（ffprobe を含む）。

Claude Code：プラグインを 1 つのコマンドでインストール

MCP サーバーとスキルをまとめてインストールします。uvx を使用するため、uv が必要です。

/plugin marketplace add marwanm7moud/watch-video
/plugin install watch-video@watch-video

任意のエージェント：パッケージ、サーバー、スキル

pipx install watch-video-mcp          # or: uv tool install watch-video-mcp / pip install watch-video-mcp
# optional extras: Whisper (non-European languages / GPU) and OCR (on-screen text as text)
pipx install "watch-video-mcp[whisper,ocr]"
# latest from GitHub instead of PyPI:
pip install git+https://github.com/marwanm7moud/watch-video

CLI はインストールせずに試せます：uvx --from watch-video-mcp video-cli hw。

ffmpeg は winget install Gyan.FFmpeg（Windows）、brew install ffmpeg（macOS）、または sudo apt install ffmpeg（Linux）でインストールします。初回の文字起こし時に Parakeet モデル（約 650 MB）がダウンロードされます。

MCP サーバーを登録する

Claude Code：

claude mcp add video --scope user -- video-mcp

Claude Desktop（claude_desktop_config.json）またはその他の MCP クライアント：

{ "mcpServers": { "video": { "command": "video-mcp" } } }

video-mcp が PATH 上にない場合は、実行ファイルのフルパスを指定するか、python -m video_mcp.server を使用してください。

スキルをインストールする

このスキルは MCP サーバーがあってもなくても動作します。サーバーがない場合は video-cli にフォールバックし、初回使用時にインストールします。 エージェントがツールを使用するタイミングと方法を認識できるように、スキルフォルダーをコピーしてください。

# macOS / Linux
mkdir -p ~/.claude/skills && cp -r skills/watch-video ~/.claude/skills/
# Windows (PowerShell)
Copy-Item -Recurse skills\watch-video $HOME\.claude\skills\

次に Claude に、「https://youtu.be/... を見て要約してください」、または 「ストップロスの説明はどのあたりですか。そのときグラフには何が表示されていますか？」 と依頼します。

ツール

ツール	用途
video_overview(source, max_frames=40, ocr=False)	まず実行します。メタデータ、チャプター、全トランスクリプト、コンタクトシートを取得します。ocr=True を指定すると、画面上のテキストも追加されます。
get_frames(source, timestamps, hi_res=True)	指定したフレームを取得します（"12:30"、"1:02:05" または秒数）。最大20件です。
scan_range(source, start, end, count=12)	範囲内のフレームを均等に抽出し、1枚のシートにまとめます。動きやデモの流れを追うのに使います。
find_cuts(source, start, end, threshold=0.2)	ハードカット（ショットや画面の切り替わり）と、1分あたりのカット数を検出します。
get_transcript(source, start, end)	トランスクリプトの一部を取得します。
search_transcript(source, query)	指定した単語を検索し、タイムスタンプ付きの該当箇所を返します。完全一致するフレーズが優先されます。さらに、ocr=True を指定した概要取得後は画面上のテキストも検索します。
check_hardware()	検出されたツール、GPU、使用中の文字起こしプロファイルを確認します。

コマンドライン

同じ操作はMCPを使わずに実行できます。

video-cli overview video.mp4 --max-frames 16
video-cli overview demo.mp4 --ocr          # also read code/slides on screen
video-cli frames https://youtu.be/... 12:30 13:05
video-cli range video.mp4 10:00 10:30 --count 12
video-cli cuts ad.mp4                       # hard cuts + cuts per minute
video-cli search video.mp4 "stop loss"
video-cli hw

設定

変数	デフォルト	効果
VIDEO_MCP_CACHE	~/.cache/video_mcp	キャッシュディレクトリです（空き容量を確保するには削除してください）。
VIDEO_MCP_LANG	en	デフォルトの文字起こし言語です。auto を指定すると、Whisperで言語を検出します。
VIDEO_MCP_THREADS	4 (CPU)	CPUでの文字起こしに使用するスレッド数です。
VIDEO_MCP_AVX512	未設定	1 を設定すると、WhisperでAVX-512を使用できます（高速ですが、非常に高い負荷が継続します）。

CPUでは、サーバーは通常より低い優先度で、負荷の高いジョブを一度に1つだけ実行し、Whisperの使用命令をAVX2に制限します。そのため、長時間の文字起こしでもデスクトップがフリーズしません。

制限事項

• language を指定しない場合、英語として処理されます。ParakeetはCPU上で25のヨーロッパ言語に対応しています（language="de"、 "fr"、"es" など）。その他の言語（アラビア語、中国語、日本語、ヒンディー語など）にはWhisperが必要ですが、CPUでは処理に時間がかかります。
• フレームはサンプリングされ、すべてのフレームが解析されるわけではありません。また、トランスクリプトでは名前や用語が誤認識される場合があります。このスキルは、Claudeにタイムスタンプを示し、画面上の正確なテキストを高解像度フレームで確認するよう指示します。
• アクセスおよび処理が許可されている動画にのみ使用してください。各サイトの利用規約と著作権を尊重してください。

開発

pip install -e ".[dev]"
ruff check .
pytest

ライセンス

MITです。LICENSEを参照してください。