What Types of YouTube Links Can Pyutube Detect?

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 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. 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 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.

Code Examples

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

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 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.

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 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.

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