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

> Process local video files like MP4 MOV MKV and WebM with Claude-video. Learn how it bypasses yt-dlp for direct file processing and transcription.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-10

---

**Claude-video supports local video files including .mp4, .mov, .mkv, and .webm by detecting local paths in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) and [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py).

### Argument Parsing and URL Detection

The main entry point in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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:

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

```

Processing an MKV with custom output directory and frame limits:

```bash
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):

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/download.py).
- The `is_url()` function in [`download.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.