Core Command Flow for Pyutube Downloads: From CLI Argument to Local File

When you run pyutube download <URL>, the tool executes a ten-step pipeline that parses CLI arguments via Typer, validates connectivity and URLs through URLHandler, delegates to a DownloadService orchestrator, and branches into audio-only, video, or playlist workflows before streaming content to disk via FileService.

The hetari/pyutube repository implements a streamlined command-line interface for YouTube content acquisition. Understanding the core command flow for Pyutube downloads reveals precisely how the tool coordinates CLI parsing, service instantiation, and media processing to deliver files reliably.

CLI Entry Point and Argument Parsing

The download sequence initiates in pyutube/cli.py, where Typer constructs the command interface and ingests the YouTube URL, target path, and boolean flags (--audio, --footage, --version).

Before any network activity occurs, the code performs two guard checks. If the user passes --version, the program prints the version string and exits immediately via sys.exit(). If the URL argument is omitted, Typer raises an error and halts execution. Subsequently, check_internet_connection() validates network availability, aborting early when no connection is detected to prevent wasted cycles.

URL Validation and Classification

Once input sanity is confirmed, the flow delegates to URLHandler (defined in pyutube/handlers/URLHandler.py). This utility expands bare video IDs into full canonical URLs and classifies the link type into one of three categories: video, short, or playlist.

Invalid links trigger an immediate exit with an error message. Valid links return a structured handler object that downstream services query to determine which download strategy to invoke.

Service Orchestration and Download Branching

With a validated URL, the program instantiates a single DownloadService object (from pyutube/services/DownloadService.py) to act as the central orchestrator. This service maintains state for the target URL, destination folder, and quality preferences.

The DownloadService evaluates flags and URL type to branch into four distinct execution paths:

• --audio flag: Forces download_service.is_audio to True. The service calls download_preparing() to fetch video metadata via pytubefix.YouTube, then executes download_audio() to write the audio stream directly.

• --footage flag or short links: Resolves the requested quality, obtains the video stream through VideoService.get_video_streams(), and invokes download_video(). This path fetches the video track and, if necessary, a separate audio track, then merges them using ffmpeg_merge_video_audio.

• Plain video links: Invokes asking_video_or_audio() to prompt the user interactively for their preferred format (audio or video), then proceeds along the respective branch listed above.

• Playlist links: Calls DownloadService.get_playlist_links() to transfer control to PlaylistHandler (in pyutube/handlers/PlaylistHandler.py). The handler prompts the user for audio/video preference, enumerates all playlist items concurrently, presents a selection interface, optionally enforces ordered filenames (prefixing indices), and iterates over selected IDs by invoking download() for each item while preserving the initially selected quality.

Stream Preparation and File Writing

Regardless of branch, the execution converges on download_preparing(), which delegates to VideoService.search_process() to instantiate a pytubefix.YouTube object, print the video title, and gather adaptive video and audio streams.

FileService (located in pyutube/services/FileService.py) generates safe filenames, checks for existing files to prevent overwrites, and manages the actual I/O. The method FileService.save_file() streams the selected content to disk. In video workflows, after the video file is saved, download_audio() fetches the separate audio track, and VideoService.merging() combines both streams into a single MP4 container. The process concludes with success messages and a clean sys.exit().

Practical Usage Examples

The following commands demonstrate how flags trigger specific branches in the core command flow:

# Interactive mode: prompts for audio vs video selection

pyutube download https://youtu.be/dQw4w9WgXcQ

# Force audio-only extraction

pyutube download https://www.youtube.com/watch?v=dQw4w9WgXcQ -a

# Force video-only (footage) download

pyutube download https://www.youtube.com/watch?v=dQw4w9WgXcQ -f

# Download a full playlist with ordered filenames

pyutube download https://www.youtube.com/playlist?list=PLxxxxxx

Summary

• Entry Point: pyutube/cli.py uses Typer to parse arguments and guards against missing URLs or version flags before checking connectivity.
• Validation: URLHandler in pyutube/handlers/URLHandler.py normalizes URLs and classifies them as video, short, or playlist.
• Orchestration: DownloadService in pyutube/services/DownloadService.py instantiates once per command and routes to audio, video, or playlist handlers.
• Branching: Flags (--audio, --footage) and link types determine whether download_audio(), download_video(), or PlaylistHandler manages the workflow.
• Execution: VideoService interacts with pytubefix to fetch streams, while FileService writes to disk and VideoService.merging() combines separate tracks when required.

Frequently Asked Questions

What happens if I run pyutube download without providing a URL?

Typer detects the missing required argument in pyutube/cli.py and raises a CLI error, causing the program to exit immediately before any network or download logic executes.

How does Pyutube handle playlists differently from single videos?

When URLHandler classifies a link as a playlist, DownloadService delegates to PlaylistHandler (in pyutube/handlers/PlaylistHandler.py), which fetches all video titles concurrently, prompts the user to select specific items, and iterates through the selection while maintaining consistent quality settings across all downloads.

What is the role of VideoService in the download flow?

VideoService (in pyutube/services/VideoService.py) encapsulates all interaction with the pytubefix library, including search_process() to retrieve video metadata, get_video_streams() to list available resolutions, and merging() to combine separate video and audio files into a final MP4 using ffmpeg_merge_video_audio.

Does Pyutube automatically merge audio and video streams?

Yes. When downloading video content (either via --footage or interactive video selection), DownloadService calls FileService.save_file() for the video stream, then download_audio() for the audio stream, and finally VideoService.merging() to produce a single container file, ensuring synchronized playback.

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