# What Types of YouTube Links Can Pyutube Detect?

> Pyutube detects standard videos Shorts playlists and raw video IDs. Learn how Pyutube classifies YouTube links efficiently.

- Repository: [Ebraheem Alhetari/pyutube](https://github.com/hetari/pyutube)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Pyutube detects four categories of YouTube links—standard videos, Shorts, playlists, and raw 11-character video IDs—using the `URLHandler` class in [`pyutube/handlers/URLHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/URLHandler.py) to classify each input as "video", "short", or "playlist" before processing.**

The `hetari/pyutube` library provides robust URL validation to ensure users can download content from various YouTube formats. Understanding what types of YouTube links Pyutube can detect helps developers and CLI users input compatible URLs without guesswork.

## How Pyutube Validates YouTube URLs

At the core of link detection is the **`URLHandler`** class located in [`pyutube/handlers/URLHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/URLHandler.py). When instantiated with a URL string or raw video ID, the class processes the input through its **`validate()`** method, which sequentially runs private detection methods to determine the link category. This architecture ensures that whether you paste a standard watch link, a shareable Short, or a playlist URL, Pyutube correctly identifies the resource type before initiating the download workflow.

## The Four Link Categories Detected by Pyutube

The validation logic distinguishes between four primary input types, each handled by specific private methods within the `URLHandler` class.

### Standard Video URLs

The **`__is_youtube_video()`** method recognizes multiple video URL formats, returning the classification **"video"** upon successful match. Supported patterns include:

- Standard watch URLs: `https://www.youtube.com/watch?v=...`
- Shortened links: `https://youtu.be/...`
- Embed URLs: `.../embed/...`
- Live-stream URLs: `.../live/...`
- Share-style URLs: `.../watch?feature=share&v=...`

### YouTube Shorts

Content hosted on YouTube Shorts is identified by the **`__is_youtube_shorts()`** method. Any URL containing the `/shorts/` path segment (for example, `https://www.youtube.com/shorts/abc123XYZ`) is classified as **"short"**, allowing Pyutube to apply specific handling for vertical short-form content.

### Playlist URLs

The **`__is_youtube_playlist()`** method detects both dedicated playlist pages and video URLs that include playlist parameters. This includes:

- Playlist-only URLs: `https://www.youtube.com/playlist?list=...`
- Watch URLs with list parameters: `https://www.youtube.com/watch?v=...&list=...`

Both patterns return the type **"playlist"**, enabling batch download operations.

### Raw Video IDs

Pyutube accepts bare 11-character video IDs through the **`__is_youtube_video_id()`** method. When a string matching the pattern (letters, digits, underscores, or hyphens) is provided, the handler automatically prepends the standard YouTube watch URL prefix before validation, effectively treating it as **"video"** type.

## Implementation Details in URLHandler.py

The validation sequence follows a strict order within `validate()`: video detection runs first, followed by Shorts, playlists, and finally raw ID checks. If none of these patterns match, the program invokes the **`error_console`** from [`pyutube/utils.py`](https://github.com/hetari/pyutube/blob/main/pyutube/utils.py) to display an error message and exits immediately. This early validation prevents invalid network requests and provides immediate feedback to users interacting with the CLI entry point in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py).

## Code Examples

The following examples demonstrate how to instantiate `URLHandler` and validate different YouTube link types:

```python
from pyutube.handlers.URLHandler import URLHandler

# Example 1 – regular video link

handler = URLHandler("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
valid, kind = handler.validate()
print(valid, kind)          # → True video

# Example 2 – YouTube Shorts

handler = URLHandler("https://www.youtube.com/shorts/abc123XYZ")
valid, kind = handler.validate()
print(valid, kind)          # → True short

# Example 3 – Playlist URL

handler = URLHandler("https://www.youtube.com/playlist?list=PL1234567890ABCDEF")
valid, kind = handler.validate()
print(valid, kind)          # → True playlist

# Example 4 – Raw video ID (auto‑converted to a watch link)

handler = URLHandler("dQw4w9WgXcQ")
valid, kind = handler.validate()
print(valid, kind)          # → True video

```

## Summary

- **Pyutube detects four distinct YouTube link types**: standard videos, Shorts, playlists, and raw video IDs.
- **The `URLHandler` class** in [`pyutube/handlers/URLHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/URLHandler.py) orchestrates validation through the `validate()` method.
- **Private detection methods** (`__is_youtube_video()`, `__is_youtube_shorts()`, `__is_youtube_playlist()`, `__is_youtube_video_id()`) classify inputs into "video", "short", or "playlist" categories.
- **Invalid URLs trigger immediate program termination** via error handling utilities in [`pyutube/utils.py`](https://github.com/hetari/pyutube/blob/main/pyutube/utils.py).

## Frequently Asked Questions

### Does Pyutube support shortened youtu.be links?

Yes. The `__is_youtube_video()` method explicitly handles shortened URLs in the `youtu.be` domain, classifying them as standard **"video"** types before processing begins.

### Can Pyutube download YouTube Shorts?

Yes. URLs containing the `/shorts/` path are detected by `__is_youtube_shorts()` and classified as **"short"**, enabling Pyutube to handle vertical short-form content appropriately.

### What happens if I provide an invalid URL or malformed ID?

If the input fails all validation checks in `URLHandler.validate()`, Pyutube outputs an error message using `error_console` from [`pyutube/utils.py`](https://github.com/hetari/pyutube/blob/main/pyutube/utils.py) and exits the program immediately without attempting network requests.

### Can I use a raw video ID instead of a full URL?

Yes. Pyutube accepts 11-character video IDs (containing letters, digits, underscores, or hyphens) through `__is_youtube_video_id()`, automatically converting them to full watch URLs and classifying them as **"video"** type.