yt-dlp Supported Video Formats and Sources in the Claude-Video Repository

The Claude-Video skill leverages yt-dlp to support hundreds of video-hosting platforms including YouTube, Vimeo, TikTok, and X, while handling standard containers like MP4, MKV, and WebM through a Python wrapper that prioritizes caption extraction over full downloads.

The bradautomates/claude-video repository implements a robust video processing skill that delegates format handling and source compatibility to yt-dlp. This integration enables support for virtually any URL recognized by yt-dlp while maintaining strict container validation through a curated extension whitelist defined in the source code.

Supported Container Formats

The skill explicitly limits acceptable video containers to a predefined set that ffmpeg can decode. In skills/watch/scripts/download.py, the VIDEO_EXTS tuple defines the supported extensions:

• .mp4
• .mkv
• .webm
• .mov
• .m4v
• .avi
• .flv
• .wmv

When yt-dlp completes a download, the wrapper validates the output file against this whitelist before proceeding to frame extraction or transcription.

Supported Video Sources and Platforms

Rather than maintaining a custom list of supported sites, Claude-Video inherits yt-dlp’s comprehensive extractor library, which supports hundreds of video-hosting platforms.

Recognized Platforms

According to the repository's README and skill documentation, validated sources include:

• YouTube (standard videos, Shorts, and playlists)
• Vimeo
• TikTok
• X (Twitter)
• Instagram
• Loom
• Twitch (clips and VODs)

The skill documentation in skills/watch/SKILL.md explicitly states support for "anything yt-dlp supports," delegating platform detection to yt-dlp's internal URL matching logic.

The Download Workflow: Captions vs. Full Video

The implementation optimizes bandwidth by attempting caption extraction before downloading video data. In skills/watch/scripts/download.py, the wrapper constructs yt-dlp commands with specific subtitle flags:

yt-dlp --write-subs --write-auto-subs --sub-langs en.* --sub-format vtt --convert-subs vtt [URL]

If captions are available, the skill downloads only the VTT subtitle file and skips the video download entirely. When captions are unavailable, the skill falls back to downloading the full video (or audio-only stream) and processes it through ffmpeg and Whisper.

Safety Mechanisms and URL Validation

The wrapper implements security measures to prevent option injection attacks. Before invoking yt-dlp, the code validates URLs using an is_url() function that rejects strings beginning with - and requires a non-empty netloc.

When constructing the command line, the wrapper inserts a -- separator before the URL to ensure the argument is treated as a positional parameter rather than a command option:

# Conceptual implementation from download.py

cmd = ["yt-dlp", "--", url]

Audio-Only Extraction and Transcription Fallback

When yt-dlp cannot provide captions and the user only requires transcription, the skill supports an audio-only mode. In skills/watch/scripts/transcribe.py, the orchestration layer extracts audio using ffmpeg and sends it to Whisper (via Groq or OpenAI APIs) for speech-to-text conversion.

To download audio-only streams directly, the script accepts a --audio-only flag that invokes yt-dlp with the format selector -f ba/bestaudio:

python3 -m skills.watch.scripts.download https://example.com/video ./tmp --audio-only

Practical Usage Examples

Processing a YouTube Video with Captions

/watch https://youtu.be/dQw4w9WgXcQ summarize the key points

This command triggers caption extraction first. If English VTT subtitles exist, yt-dlp downloads only the subtitle metadata; otherwise, it retrieves the video file.

Direct Script Execution for Local Processing

python3 -m skills.watch.scripts.download https://vimeo.com/12345678 ./tmp

The script creates ./tmp/video.<ext> using one of the supported container formats and generates video.en.vtt when subtitles are available.

Local File Bypass

For previously downloaded content, the wrapper detects filesystem paths and bypasses yt-dlp entirely:

python3 -m skills.watch.scripts.download /home/user/lecture.mov ./tmp

The system validates the file extension against VIDEO_EXTS and proceeds directly to processing.

Summary

• Container Support: The skill restricts downloads to eight verified formats (MP4, MKV, WebM, MOV, M4V, AVI, FLV, WMV) defined in skills/watch/scripts/download.py.
• Source Compatibility: Any URL recognized by yt-dlp is supported, including major platforms like YouTube, TikTok, Vimeo, and X.
• Caption Priority: The workflow attempts VTT subtitle extraction before downloading video data, using --write-subs --sub-format vtt flags.
• Security: URL validation via is_url() and -- separator injection prevent command-line option attacks.
• Fallback Chain: When captions fail, the system extracts audio for Whisper transcription via skills/watch/scripts/transcribe.py.

Frequently Asked Questions

What video file formats does Claude-Video support?

The skill supports MP4, MKV, WebM, MOV, M4V, AVI, FLV, and WMV containers. These extensions are explicitly whitelisted in the VIDEO_EXTS tuple within skills/watch/scripts/download.py to ensure ffmpeg compatibility during subsequent processing.

Can I download videos from any website using this tool?

Yes, provided the site is supported by yt-dlp. The skill delegates platform detection to yt-dlp's extractor library, which recognizes hundreds of sites including YouTube, Vimeo, TikTok, Instagram, Loom, and Twitch. The README explicitly documents support for "anything yt-dlp supports."

How does the tool handle videos without subtitles?

When yt-dlp cannot retrieve captions, the skill falls back to downloading the audio stream or full video, then extracts audio using ffmpeg. This audio is sent to Whisper (via Groq or OpenAI) for transcription, as implemented in skills/watch/scripts/transcribe.py.

Is there a way to download only audio for transcription purposes?

Yes. Pass the --audio-only flag to the download script, which invokes yt-dlp with the -f ba/bestaudio format selector. This retrieves the best available audio stream without video data, optimizing for transcription workflows where visual content is unnecessary.

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