How to Process Local Video Files with Claude-Video: MP4, MOV, MKV, and WebM Support

Claude-video supports local video files including .mp4, .mov, .mkv, and .webm by detecting local paths in watch.py and bypassing yt-dlp to process them directly through the frame extraction and transcription pipeline.

The bradautomates/claude-video repository provides a versatile video analysis tool that works with both remote URLs and local file paths. Whether you need to analyze downloaded footage or private video files, Claude-video handles local video files seamlessly without requiring external hosting or cloud uploads.

Supported Local Video Formats

In skills/watch/scripts/download.py, the constant VIDEO_EXTS defines exactly which containers the utility accepts:

• .mp4
• .mov
• .mkv
• .webm

When you supply a path with one of these extensions, Claude-video treats it as a local file and skips the URL-based download logic entirely.

How Local File Detection Works

The pipeline distinguishes between remote URLs and local paths through a specific detection flow implemented across watch.py and download.py.

Argument Parsing and URL Detection

The main entry point in skills/watch/scripts/watch.py defines the positional argument source as accepting "Video URL or local file path" (lines 30-31). The download.py.is_url() function checks if the input string matches URL patterns; if not, the utility assumes a local file path (lines 20-25).

Local Path Validation

Once detected as local, download.py.resolve_local() validates that the file exists on disk, verifies the extension against VIDEO_EXTS, and returns a dictionary containing the absolute video_path (lines 27-41). This occurs without invoking yt-dlp or any network downloader.

Frame Extraction and Transcription

The validated video_path feeds directly into frames.py for keyframe extraction and scene-aware frame generation, while the transcription module handles audio processing. This local workflow mirrors the remote URL pipeline exactly, ensuring consistent output regardless of source.

Running Claude-Video with Local Files

Use the module path skills.watch.scripts.watch followed by your local file path. The tool accepts standard arguments like --out-dir and --max-frames regardless of whether the source is remote or local.

Basic processing of an MP4 file:

python -m skills.watch.scripts.watch /path/to/video.mp4

Processing an MKV with custom output directory and frame limits:

python -m skills.watch.scripts.watch /path/to/video.mkv \
    --out-dir ./my_report \
    --max-frames 50

Frame-only mode for a MOV file (skipping Whisper transcription):

python -m skills.watch.scripts.watch /path/to/video.mov \
    --detail transcript \
    --no-whisper

Summary

• Claude-video accepts local video files in .mp4, .mov, .mkv, and .webm formats as defined by the VIDEO_EXTS constant in download.py.
• The is_url() function in download.py automatically detects local paths, triggering resolve_local() to validate file existence and extension compatibility.
• Local files bypass yt-dlp entirely and proceed directly to frame extraction (frames.py) and optional transcription.
• Command-line usage remains identical between local files and remote URLs, requiring only a valid file path instead of a URL.

Frequently Asked Questions

Does Claude-video require internet access for local video files?

No. When processing local video files, Claude-video does not initiate network connections through yt-dlp. The resolve_local() function handles file validation entirely offline, though transcription via Whisper may require model downloads on first use if not already cached.

What happens if I try to process an unsupported video format?

If the file extension is not listed in VIDEO_EXTS (defined in skills/watch/scripts/download.py), the resolve_local() function issues a warning but typically attempts to process the file anyway, depending on FFmpeg's capabilities. However, for guaranteed compatibility, stick to .mp4, .mov, .mkv, or .webm.

Can I process multiple local videos in a single command?

The current implementation in watch.py processes a single source argument per invocation. To batch process multiple local video files, you must run the command separately for each file or wrap the invocation in a shell loop that iterates over your video directory.

Does Claude-video preserve the original video file during processing?

Yes. Claude-video only reads from the specified local path. Frame extraction generates new image files in your output directory (or the default location), leaving the original video file unchanged and unmodified.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}