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

> Discover how claude-video's download module distinguishes URLs from local file paths using the is_url helper function. Learn how it routes downloads efficiently.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-07-14

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py). This helper applies three specific validation rules to determine if a string represents a remote resource:

```python
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:

```python
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:**

```python
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:**

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)**: Orchestrates the complete workflow, invoking the download module based on parsed command-line arguments.
- **[`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py)**: Ensures runtime dependencies including `yt-dlp` and `ffmpeg` are available before attempting remote downloads.
- **[`tests/test_download.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`.