# Video Formats and Platforms Supported by yt-dlp for claude-video Downloads

> Discover video formats and platforms supported by yt-dlp for claude-video downloads. claude-video downloads from any yt-dlp supported platform, ensuring MP4 output or original audio.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: api-reference
- Published: 2026-08-04

---

**The claude-video project downloads from any platform yt-dlp supports, forcing MP4 output for videos and preserving original audio codecs for audio-only mode, while accepting local files with extensions in `.mp4, .mkv, .webm, .mov, .m4v, .avi, .flv, .wmv`.**

The claude-video repository leverages yt-dlp as its download backend for the `/watch` slash command. Understanding what video formats and platforms are supported by yt-dlp for claude-video downloads helps you know exactly what content you can process and how it will be delivered.

## Output Formats: Video vs. Audio-Only

The download behavior in `claude-video` differs based on whether you request full video or audio-only extraction. This logic resides in [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py).

### Video Downloads: Forced MP4 Container

When `audio_only=False` (the default), the script explicitly merges outputs into **MP4** format:

```python

# From skills/watch/scripts/download.py, lines 31-33

cmd = [
    "yt-dlp",
    "--merge-output-format", "mp4",
    ...
]

```

This `--merge-output-format mp4` flag ensures that regardless of the source site's native container (WebM, MKV, FLV, etc.), the final file delivered to claude-video is always MP4. The script also applies `-S "vcodec:h264,res:720,acodec:aac"` to prioritize **H.264 video** and **AAC audio** within that MP4 container for maximum compatibility.

### Audio-Only Downloads: Preserved Source Codecs

When the `--audio-only` flag is passed, the script selects the best available audio stream without container conversion:

```python

# From skills/watch/scripts/download.py, lines 26-27

fmt = "ba/bestaudio"  # best audio / fallback to bestaudio

```

The resulting file retains yt-dlp's default audio extraction format, which varies by site:
- **m4a** (AAC in MP4 container) — most common from YouTube
- **opus** — YouTube WebM audio streams
- **mp3, ogg, flac** — depending on source platform availability

No `--audio-format` conversion is applied, preserving the original codec quality.

## Supported Platforms: The Full yt-dlp Ecosystem

The `claude-video` project does **not** implement any platform restrictions. The `download_url` function in [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) forwards URLs directly to yt-dlp without validation, meaning **any site supported by yt-dlp** works automatically.

This includes major platforms such as:
- **YouTube** — videos, Shorts, playlists, livestreams
- **Vimeo** — standard and On Demand content
- **Twitch** — VODs and clips
- **TikTok** — videos and trending feeds
- **Instagram Reels** — single posts and stories
- **Facebook** — videos and live replays
- **Reddit** — hosted and embedded videos
- **Dailymotion** — standard and licensed content

The complete, up-to-date list of supported sites is maintained by the yt-dlp project at [github.com/yt-dlp/yt-dlp/blob/master/README.md#supported-sites](https://github.com/yt-dlp/yt-dlp/blob/master/README.md#supported-sites).

## Local File Support: VIDEO_EXTS Fallback

When a filesystem path is provided instead of a URL, the script validates against a hardcoded extension list. The `VIDEO_EXTS` constant in [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) (lines 17-18) defines accepted formats:

```python
VIDEO_EXTS = {".mp4", ".mkv", ".webm", ".mov", ".m4v", ".avi", ".flv", ".wmv"}

```

These eight extensions cover the most common container formats across consumer and professional video workflows. Files matching any of these extensions bypass yt-dlp entirely and proceed directly to claude-video's frame extraction pipeline.

## Practical Usage Examples

### Download YouTube Video as MP4

```bash
python -m skills.watch.scripts.download \
    https://www.youtube.com/watch?v=dQw4w9WgXcQ \
    ./output_folder

```

Result: `dQw4w9WgXcQ.mp4` (H.264/AAC, 720p max)

### Extract Audio Only (Preserves Source Codec)

```bash
python -m skills.watch.scripts.download \
    https://www.youtube.com/watch?v=dQw4w9WgXcQ \
    ./output_folder \
    --audio-only

```

Result: `dQw4w9WgXcQ.m4a` or `dQw4w9WgXcQ.opus` (depending on best available stream)

### Process Local MKV File

```bash
python -m skills.watch.scripts.download \
    /Users/brad/movies/documentary.mkv \
    ./output_folder

```

Result: Frame extraction proceeds without network download.

## Key Source Files

Understanding the architecture helps when debugging format issues:

| File | Purpose |
|------|---------|
| [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) | Core yt-dlp wrapper; handles format selection, subtitle embedding, and local file resolution |
| [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) | Orchestrates the full pipeline: download → frame extraction → transcription |
| [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) | Defines the `/watch` slash command interface exposed to Claude |
| [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) | High-level usage documentation for the watch skill |

## Summary

- **Video output format**: Always **MP4** (H.264/AAC preferred) via `--merge-output-format mp4`
- **Audio output format**: **Original codec preserved** (m4a, opus, mp3, etc.) when `--audio-only` is used
- **Supported platforms**: **Any site yt-dlp supports** — no restrictions in claude-video
- **Local file formats**: **`.mp4`, `.mkv`, `.webm`, `.mov`, `.m4v`, `.avi`, `.flv`, `.wmv`** accepted
- **Core implementation**: [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) manages all format logic

## Frequently Asked Questions

### Can claude-video download from Netflix, Spotify, or other subscription services?

No. While yt-dlp supports many platforms, claude-video inherits yt-dlp's limitations. DRM-protected services like Netflix, Spotify, Disney+, and Amazon Prime Video cannot be downloaded. The script forwards URLs directly to yt-dlp without authentication handling for paid services.

### Why does my audio-only download have a different extension than MP3?

The [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) script uses yt-dlp's `ba/bestaudio` format selector without specifying `--audio-format`. This preserves the highest-quality audio stream in its native container — often m4a (AAC) or opus from YouTube — rather than re-encoding to MP3. This avoids quality loss from transcoding.

### Can I force a different video resolution or codec than 720p H.264?

Not through command-line flags in the current implementation. The `-S "vcodec:h264,res:720,acodec:aac"` sorting preference is hardcoded in [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py). To modify this behavior, you would need to edit the script's `cmd` list construction around lines 29-36 to adjust or remove the `-S` parameter.

### What happens if I provide a URL from an unsupported site?

yt-dlp will attempt extraction and fail with an `UnsupportedError` if no extractor matches. The error propagates through [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) and surfaces in Claude's response. Since claude-video adds no pre-validation, the failure message comes directly from yt-dlp's diagnostic output.