How the claude-video Download Module Differentiates URLs from Local File Paths

The download module uses the is_url helper function to validate whether a source string uses an http or https scheme with a network location, routing valid URLs to download_url and treating all other inputs as local file paths handled by resolve_local.

The claude-video repository provides a unified interface for processing video content from both remote sources and local storage. Located in skills/watch/scripts/download.py, the download module eliminates the need for separate handling logic by automatically detecting the source type at runtime. This design allows the same download() function to fetch YouTube videos via yt-dlp or verify existing local files without additional user configuration.

Detecting URLs with the is_url Helper

The core detection mechanism resides in the is_url function defined at lines 20–25 of skills/watch/scripts/download.py. This helper applies three specific validation rules to determine if a string represents a remote resource:

def is_url(source: str) -> bool:
    if source.startswith("-"):
        return False
    parsed = urlparse(source)
    return parsed.scheme in ("http", "https") and bool(parsed.netloc)

The function executes the following logic:

• Rejects CLI flags: Strings beginning with a hyphen are immediately classified as command-line options rather than URLs or paths.
• Parses the string: It uses urllib.parse.urlparse to decompose the source into components.
• Validates scheme and location: Returns True only if the scheme is http or https and the netloc (network location) component is non-empty.

This approach reliably excludes local file paths like /home/user/video.mp4 or relative paths like ./assets/clip.mov, while correctly identifying remote URLs including those with query parameters or fragment identifiers.

Branching Logic in the Main Download Function

The primary entry point download (lines 65–73) leverages the boolean result from is_url to select the appropriate processing branch:

def download(source: str, out_dir: Path, audio_only: bool = False) -> dict:
    if is_url(source):
        return download_url(source, out_dir, audio_only=audio_only)
    return resolve_local(source)

Two distinct execution paths emerge:

• Remote handling (download_url): When is_url returns True, the module invokes yt-dlp to fetch the video and extract subtitles, storing results in the specified out_dir.
• Local handling (resolve_local): When is_url returns False, the module verifies the file exists on the filesystem and constructs a result dictionary referencing the original path, bypassing all network operations.

Both paths return a standardized dictionary containing video_path and subtitle_path keys, ensuring consistency for downstream processing regardless of the source origin.

Practical Code Examples

Downloading a remote video:

from pathlib import Path
from skills.watch.scripts.download import download

result = download(
    "https://www.youtube.com/watch?v=abc123",
    Path("/tmp/watch-output"),
    audio_only=False
)
print(result["video_path"])      # → "/tmp/watch-output/video.mp4"

print(result["subtitle_path"])   # → "/tmp/watch-output/video.en.vtt"

Processing a local video file:

from pathlib import Path
from skills.watch.scripts.download import download

result = download(
    "/home/user/videos/lecture.mkv",
    Path("/tmp/watch-output")
)
print(result["video_path"])      # → "/home/user/videos/lecture.mkv"

print(result["subtitle_path"])   # → None

Note that local files return None for subtitles since the module does not attempt to fetch external caption files for existing media.

Key Source Files and Architecture

The download system spans several files within the bradautomates/claude-video repository:

• skills/watch/scripts/download.py: Contains the is_url validator, download dispatcher, and implementation of download_url and resolve_local.
• skills/watch/scripts/watch.py: Orchestrates the complete workflow, invoking the download module based on parsed command-line arguments.
• skills/watch/scripts/setup.py: Ensures runtime dependencies including yt-dlp and ffmpeg are available before attempting remote downloads.
• tests/test_download.py: Validates both URL detection heuristics and local file resolution logic.

Summary

• The is_url function at lines 20–25 of download.py validates HTTP/HTTPS schemes and non-empty network locations to identify remote sources.
• The download function branches execution at lines 65–73, sending URLs to download_url for fetching and local paths to resolve_local for verification.
• Both paths return identical dictionary structures, containing video_path and subtitle_path keys for consistent downstream processing.
• Local file processing bypasses network operations entirely, while URL processing requires yt-dlp and ffmpeg availability.

Frequently Asked Questions

What happens if a local path looks like a URL?

If a local path contains http or https but lacks a proper network location (e.g., a file named https-video.mp4), the is_url function will return False because urlparse will not detect a valid netloc component. The module treats it as a local file and passes it to resolve_local for filesystem verification.

Does the download module support FTP or other protocols?

No. According to the source code in skills/watch/scripts/download.py, the is_url function explicitly checks for schemes of only http or https. FTP, SFTP, or other protocols are treated as local paths and will fail during the resolve_local check unless a matching file exists on the filesystem.

How does the module handle command-line flags or options?

The is_url function explicitly rejects any string starting with a hyphen (-), returning False immediately. This prevents the module from attempting to parse CLI arguments like --help or -o output.mp4 as URLs, ensuring these arguments are handled by the argument parser rather than the download logic.

Why do local files return None for subtitles?

The resolve_local function only validates the existence of the specified video file and returns its absolute path. Unlike download_url, which invokes yt-dlp to extract caption tracks, the local path resolver does not search for or associate external subtitle files automatically, resulting in a None value for subtitle_path.

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