Pyutube Service Layer: Key Files and Architecture Explained

The Pyutube service layer consists of four core files in pyutube/services/—VideoService.py, AudioService.py, FileService.py, and DownloadService.py—that handle stream discovery, audio extraction, file operations, and download orchestration respectively.

The hetari/pyutube repository implements a clean service-oriented architecture to manage YouTube media downloads. At the heart of this design lies the Pyutube service layer, which encapsulates all business logic for resolving URLs, selecting streams, and persisting files to disk. Understanding these components is essential for extending functionality or debugging download workflows.

Architecture of the Pyutube Service Layer

The service layer follows a facade pattern where DownloadService acts as the unified entry point while delegating specialized tasks to three supporting services. This separation of concerns ensures that stream handling, audio processing, and file system operations remain isolated and testable.

The four primary components are:

• VideoService (pyutube/services/VideoService.py): Manages video stream discovery, resolution selection, and audio/video merging.
• AudioService (pyutube/services/AudioService.py): Handles extraction of audio-only streams.
• FileService (pyutube/services/FileService.py): Generates safe filenames, resolves naming conflicts, and writes bytes to disk.
• DownloadService (pyutube/services/DownloadService.py): Orchestrates the entire workflow, coordinates playlist processing, and invokes the other services.

Core Service Files and Responsibilities

VideoService: Stream Discovery and Merging

Located at pyutube/services/VideoService.py, this class handles the complexities of YouTube's adaptive streaming format. It queries available resolutions via get_available_resolutions(), retrieves specific streams using get_video_streams(), and manages the merging of separate video and audio tracks through the merging() method.

The search_process() method serves as the primary entry point for video URL resolution, while get_selected_stream() handles user-driven quality selection. According to the source code, this service relies on pytubefix for stream enumeration and moviepy for post-processing concatenation.

AudioService: Audio-Only Extraction

The pyutube/services/AudioService.py module provides a streamlined interface for extracting audio streams. Its primary method, get_audio_streams(), returns the highest-quality audio-only stream available for a given YouTube URL.

This service is invoked by DownloadService when the is_audio=True flag is set, bypassing video stream selection entirely and reducing bandwidth usage for music or podcast downloads.

FileService: Safe File Operations

Found in pyutube/services/FileService.py, this utility class ensures robust file system interactions. The generate_filename() method creates sanitized filenames from video metadata, while handle_existing_file() manages collision detection to prevent accidental overwrites.

The save_file() method performs the actual byte-level writing, acting as the persistence layer for both video and audio downloads. This service abstracts OS-specific path handling and ensures consistent naming conventions across platforms.

DownloadService: Orchestration and Facade

The pyutube/services/DownloadService.py file implements the primary facade for the entire service layer. Its constructor accepts the target URL, destination path, quality preferences, and audio-only flags.

Key methods include:

• download(): The main entry point that returns the final resolution or file path.
• download_preparing(): Sets up the download environment and validates inputs.
• download_video(): Delegates to VideoService for video-specific workflows.
• download_audio(): Delegates to AudioService for audio extraction.
• get_playlist_links(): Handles playlist enumeration and sequential processing.

This service composes the other three services to deliver a unified download experience while managing CLI interactions and playlist ordering.

Practical Usage Examples

Downloading a Single Video

To download a video using the service layer, instantiate DownloadService with the target URL and destination path:

from pyutube.services.DownloadService import DownloadService

downloader = DownloadService(
    url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    path="/tmp/pyutube",
    quality=None,  # Prompts user for resolution selection

    is_audio=False
)

final_quality = downloader.download()
print(f"Video saved with quality: {final_quality}")

Internally, this invokes VideoService.search_process() to resolve the URL, VideoService.get_selected_stream() for quality selection, and FileService.save_file() for persistence.

Extracting Audio Only

For audio-only downloads, set the is_audio flag to True:

from pyutube.services.DownloadService import DownloadService

audio_downloader = DownloadService(
    url="https://www.youtube.com/watch?v=3JZ_D3ELwOQ",
    path="./music",
    quality=None,
    is_audio=True
)

audio_file = audio_downloader.download()
print(f"Audio saved as: {audio_file}")

This configuration causes DownloadService to route the request to AudioService.get_audio_streams() instead of VideoService, bypassing video stream processing entirely.

Processing Playlists

To download an entire playlist while preserving order:

from pyutube.services.DownloadService import DownloadService

playlist = DownloadService(
    url="https://www.youtube.com/playlist?list=PL1234567890",
    path="./playlist",
    quality=None,
    is_audio=False,
    make_playlist_in_order=True
)

# Enumerate and download each video with numeric prefixes

playlist.get_playlist_links()

The get_playlist_links() method detects playlist URLs, enumerates contained videos, and processes each entry with indexed filenames (e.g., 01__title.mp4).

Summary

The Pyutube service layer implements a clean, modular architecture through four specialized files:

• pyutube/services/VideoService.py – Handles stream discovery, resolution selection, and audio/video merging via moviepy.
• pyutube/services/AudioService.py – Extracts high-quality audio streams when video is not required.
• pyutube/services/FileService.py – Manages safe filename generation, conflict resolution, and disk persistence.
• pyutube/services/DownloadService.py – Acts as the orchestration facade, coordinating the other services and handling playlist processing.

This separation of concerns ensures that each component has a single responsibility, making the codebase testable, extensible, and maintainable.

Frequently Asked Questions

What is the entry point for downloading videos in Pyutube?

The primary entry point is the DownloadService class located in pyutube/services/DownloadService.py. This facade class provides the download() method, which coordinates the entire workflow by delegating to VideoService or AudioService depending on the download type, and uses FileService for persistence.

How does Pyutube handle video and audio merging?

Pyutube handles merging through the VideoService.merging() method in pyutube/services/VideoService.py. When a video stream lacks an audio track (common in high-resolution YouTube formats), this method uses moviepy to concatenate the separate video and audio files into a single output file.

Where does Pyutube manage filename generation and conflict resolution?

Filename handling occurs in pyutube/services/FileService.py. The generate_filename() method creates sanitized names from video metadata, while handle_existing_file() checks for collisions and prevents accidental overwrites. The save_file() method completes the process by writing bytes to the generated path.

Can Pyutube download entire YouTube playlists?

Yes, Pyutube supports playlist downloads through the DownloadService.get_playlist_links() method. This functionality detects playlist URLs, enumerates all contained videos, and can preserve order by prefixing filenames with numeric indices (e.g., 01__title.mp4). The method coordinates with the CLI to allow users to select specific videos from the playlist before downloading.

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