# How Claude Video Handles Different Video Sources: URLs vs Local Files > Learn how Claude Video seamlessly handles video sources, automatically detecting URLs for yt-dlp downloads or local files for direct use. Simplify your video processing workflow. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: how-to-guide - Published: 2026-08-01 --- **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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) The main entry point in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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: ```bash # Remote URL -- Claude Video downloads the video using yt-dlp watch https://www.youtube.com/watch?v=abcd1234 ``` ```bash # Local file -- Claude Video resolves the path and skips downloading watch /home/user/videos/my-lecture.mkv ``` ```bash # Transcript-only mode for remote URL (no video download) watch https://vimeo.com/5678 --detail transcript ``` ```bash # 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.