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

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.

Video Downloads: Forced MP4 Container

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

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

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

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 (lines 17-18) defines accepted formats:

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

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)

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

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	Core yt-dlp wrapper; handles format selection, subtitle embedding, and local file resolution
skills/watch/scripts/watch.py	Orchestrates the full pipeline: download → frame extraction → transcription
skills/watch/SKILL.md	Defines the /watch slash command interface exposed to Claude
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 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 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. 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 and surfaces in Claude's response. Since claude-video adds no pre-validation, the failure message comes directly from yt-dlp's diagnostic output.

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