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

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 constant within 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 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:

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:

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), which constructs the yt-dlp command with appropriate flags:

# 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:

# 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) 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) 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.

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