# yt-dlp Video Formats and Download Requirements in Claude-Video

> Discover yt-dlp video formats MP4 MKV WebM M4A MP3 Opus supported by Claude-Video. Learn download requirements for full video or audio-only streams.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-07-09

---

**The Claude-Video skill supports standard container formats including MP4, MKV, and WebM for video, and M4A, MP3, and Opus for audio, utilizing yt-dlp format selectors to download either height-bounded video with merged audio or audio-only streams depending on the `audio_only` flag.**

The `bradautomates/claude-video` repository implements a video processing skill that leverages **yt-dlp** for media retrieval and processing. Understanding which **yt-dlp video formats** are explicitly supported and how the skill handles full versus audio-only download requirements is essential for configuring output behavior and ensuring system compatibility.

## Supported Video and Audio Extensions

The skill defines accepted file extensions in the [`VIDEO_EXTS`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) constant within [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py). These extensions determine both the local video detection capabilities and the expected output formats from yt-dlp operations.

**Video container formats supported:**

- **.mp4**
- **.mkv**
- **.webm**
- **.mov**
- **.m4v**
- **.avi**
- **.flv**
- **.wmv**

**Audio-only formats (when downloading without video):**

- **.m4a**
- **.mp3**
- **.opus**

## Full Video vs. Audio-Only Download Logic

The `download_url()` function in [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) implements two distinct yt-dlp format selection strategies based on the `audio_only` parameter.

**Full Video Downloads (≤720p):**

When `audio_only=False`, the skill passes a complex format selector to yt-dlp:

```python
fmt = "bv*[height<=720]+ba/b[height<=720]/bv+ba/b"

```

This selector instructs yt-dlp to:
1. Select the best video stream with height ≤ 720 pixels
2. Combine it with the best available audio stream
3. Fall back to the best 720p combined format or best overall if exact match unavailable

The command includes `--merge-output-format mp4` to ensure the final output is a unified MP4 file regardless of the source container.

**Audio-Only Downloads:**

When `audio_only=True`, the format selector simplifies to:

```python
fmt = "ba/bestaudio"

```

This requests only the best quality audio stream available, preserving the native extension (typically `.m4a`, `.mp3`, or `.opus`) without video content or merging operations.

## System Requirements and Prerequisites

Both download paths require **yt-dlp** to be installed and discoverable on the system `$PATH`. The script explicitly verifies this using `shutil.which("yt-dlp")` and aborts with an error message if the binary is missing.

**Full video downloads impose an additional requirement:**

- **ffmpeg must be available** on the system to handle the `--merge-output-format mp4` operation that combines separate video and audio streams into a single container file. While the script does not explicitly check for ffmpeg, yt-dlp will fail during the merge phase if it is not present.

## Implementation Details in download.py

The core download logic resides in [[`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py)](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py), which constructs the yt-dlp command with appropriate flags:

```python

# Full video download with height constraint and merging

cmd = [
    "yt-dlp",
    "-f", "bv*[height<=720]+ba/b[height<=720]/bv+ba/b",
    "--merge-output-format", "mp4",
    "-o", output_path,
    url
]

```

For audio-only retrieval, the command construction omits the merge flag and uses the simplified audio selector:

```python

# Audio-only download

cmd = [
    "yt-dlp",
    "-f", "ba/bestaudio",
    "-o", output_path,
    url
]

```

The [[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) entry point coordinates these download operations with subsequent frame extraction and transcription workflows, while [[`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) defines the user-facing contract for the `/watch` slash command.

## Summary

- The skill recognizes **eight video extensions** (MP4, MKV, WebM, MOV, M4V, AVI, FLV, WMV) and **three audio extensions** (M4A, MP3, Opus).
- **Full video downloads** use the format selector `bv*[height<=720]+ba/b[height<=720]/bv+ba/b` with `--merge-output-format mp4` and require **ffmpeg** for stream merging.
- **Audio-only downloads** use the selector `ba/bestaudio` and do not require merging.
- Both modes require **yt-dlp** to be installed and available on the system `$PATH`.

## Frequently Asked Questions

### Which video formats does yt-dlp support in the Claude-Video skill?

The skill explicitly handles video files with extensions `.mp4`, `.mkv`, `.webm`, `.mov`, `.m4v`, `.avi`, `.flv`, and `.wmv` as defined in the `VIDEO_EXTS` constant. While yt-dlp itself supports numerous additional formats, the skill's local processing pipeline is optimized for these standard containers.

### How do I download only audio using the skill?

Set the `audio_only` parameter to `True` when calling the download function. This switches the yt-dlp format selector to `ba/bestaudio`, retrieving only the highest quality audio stream without video content. The output file will retain its native audio extension such as `.m4a` or `.opus`.

### Why is ffmpeg required for full video downloads but not audio-only?

Full video downloads utilize the `--merge-output-format mp4` flag to combine separate video and audio streams into a single MP4 container. This post-processing step requires ffmpeg to be installed on the system. Audio-only downloads consist of a single stream that does not require merging, eliminating the ffmpeg dependency.

### What is the maximum video resolution supported by the skill?

The format selector explicitly limits video height to **720 pixels** using the expression `[height<=720]`. This ensures downloads are optimized for processing efficiency while maintaining standard HD quality. Users requiring higher resolutions would need to modify the format selector string in [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py).