How Claude Video Handles Different Video Sources: URLs vs Local Files

Claude Video automatically detects whether your input is a remote URL or local file path using is_url() and delegates to either yt-dlp for downloading or direct path resolution, providing a unified interface for both sources.

The bradautomates/claude-video repository implements a flexible video processing pipeline that accepts diverse input types through a single CLI argument. Understanding how Claude Video handles different video sources reveals the underlying architecture that seamlessly bridges remote content fetching and local file system operations.

Source Detection Logic

Claude Video determines the input type through a simple but effective validation check performed in the download utility module.

URL Detection with is_url()

In skills/watch/scripts/download.py, the is_url() function (lines 20-25) validates the source string by checking if it begins with http or https and contains a valid network location using Python's urlparse module. When this function returns True, Claude Video treats the input as a remote video URL requiring network access.

Local Path Resolution with resolve_local()

For non-URL inputs, the system delegates to resolve_local() (lines 27-42 in skills/watch/scripts/download.py). This function performs three critical operations: it expands the tilde (~) to the user's home directory, resolves the absolute path, and verifies file existence on disk. It returns a dictionary marking the video as not downloaded and supplying the resolved absolute path, signaling that the video is ready for processing without network retrieval.

Download Orchestration Architecture

The high-level coordination between network and local operations occurs in the download() function, which abstracts the complexity of source acquisition.

The download() Function Delegation

Located in skills/watch/scripts/download.py (lines 65-73), the download() function acts as a router. Based on the result of is_url(), it delegates to either download_url()—which invokes yt-dlp to fetch the video and subtitles—or resolve_local() for filesystem-based sources. This design ensures that local files never trigger unnecessary network operations.

URL Processing with yt-dlp

When processing remote URLs, Claude Video leverages yt-dlp within download_url() to handle video fetching and subtitle extraction. This external tool manages the complexities of various video hosting platforms while the wrapper script handles local storage and metadata generation.

Entry Point Workflow in watch.py

The main entry point in skills/watch/scripts/watch.py orchestrates the entire pipeline based on the detected source type.

Source Branching Logic

At lines 90-102, the script executes url_source = is_url(args.source) to determine the workflow branch. This boolean flag controls whether the system attempts caption fetching and video downloading or proceeds directly to local file processing.

URL Workflow Branch

For remote URLs, the system first attempts to fetch captions using fetch_captions(), then proceeds to download the video via the download() function unless the user specifies a transcript-only detail level using the --detail transcript flag.

Local File Workflow Branch

When processing local files, watch.py calls download() (lines 115-129) which immediately invokes resolve_local() without invoking yt-dlp. The video path is validated and returned for direct processing by the frame extraction and transcription pipelines.

Practical Usage Examples

Claude Video accepts the same watch command regardless of source type, demonstrating the unified interface:

# Remote URL -- Claude Video downloads the video using yt-dlp

watch https://www.youtube.com/watch?v=abcd1234

# Local file -- Claude Video resolves the path and skips downloading

watch /home/user/videos/my-lecture.mkv

# Transcript-only mode for remote URL (no video download)

watch https://vimeo.com/5678 --detail transcript

# Local file with specific timestamps for frame extraction

watch ./samples/clip.mp4 --timestamps 00:01,00:45,01:20

Summary

• Automatic detection: The is_url() function in skills/watch/scripts/download.py distinguishes URLs from file paths by checking for http/https schemes and network locations.
• Unified interface: Both source types use the same watch CLI command, with download() routing to download_url() or resolve_local() as appropriate.
• Local file optimization: Local paths bypass yt-dlp entirely through resolve_local(), which expands ~, resolves absolute paths, and verifies existence.
• URL handling: Remote sources trigger yt-dlp for video and subtitle fetching, with optional transcript-only mode to skip downloads.
• Entry point logic: skills/watch/scripts/watch.py uses the url_source boolean to determine whether to fetch captions and download videos or process local files directly.

Frequently Asked Questions

How does Claude Video detect whether a source is a URL or local file?

Claude Video uses the is_url() function in skills/watch/scripts/download.py (lines 20-25) to analyze the source string. It checks if the input starts with http or https and contains a valid network location using Python's urlparse module. If both conditions are met, the system treats the input as a remote URL; otherwise, it assumes a local file path.

What happens when I provide a local file path to Claude Video?

When a local path is detected, Claude Video invokes resolve_local() in skills/watch/scripts/download.py (lines 27-42), which expands the tilde (~) to the home directory, resolves the absolute path, and verifies the file exists. The function returns a dictionary indicating the video is not downloaded and provides the resolved path, allowing immediate processing without network operations.

Does Claude Video download videos automatically when given a URL?

Yes, unless you specify transcript-only mode. In skills/watch/scripts/watch.py (lines 115-129), URL sources trigger the download() function, which delegates to download_url() using yt-dlp to fetch both the video and subtitles. However, if you pass the --detail transcript flag, the system fetches only captions without downloading the video file.

Can Claude Video handle both YouTube URLs and direct video file links?

Yes. The download_url() function utilizes yt-dlp, which supports hundreds of video hosting platforms including YouTube, Vimeo, and direct MP4 links. The underlying detection mechanism in is_url() only validates the URL scheme and network location, making the system agnostic to specific hosting providers as long as yt-dlp supports the platform.

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