YouTubeDownloader vs YouTubeDownloaderForCLI: Key Differences in Spotify Saver

YouTubeDownloaderForCLI is a subclass of YouTubeDownloader that adds progress callbacks, Spanish-language error messages, and richer return values specifically designed for command-line interfaces, while the base class provides core download functionality for library use.

The gabrielbaute/spotify-saver repository provides two distinct implementations for downloading YouTube Music content: a base downloader for programmatic use and a specialized variant for CLI tools. Understanding the architectural differences between these classes helps developers choose the right abstraction for their specific integration context.

Architecture Overview

Both classes reside in the spotifysaver/downloader/ package but serve different execution contexts.

The base implementation in spotifysaver/downloader/youtube_downloader.py defines YouTubeDownloader as a standalone class containing the complete download workflow. It handles YouTube Music searching, audio extraction via yt-dlp, metadata embedding, and optional NFO generation.

The CLI variant in spotifysaver/downloader/youtube_downloader_for_cli.py declares YouTubeDownloaderForCLI as a subclass that inherits all core methods—including _get_ydl_opts(), _download_cover(), and _embed_metadata()—while overriding initialization and public APIs to support interactive command-line usage.

Key Differences Between YouTubeDownloader and YouTubeDownloaderForCLI

Inheritance and Base Functionality

YouTubeDownloader operates as a self-contained utility. It initializes its own logger via spotifysaver.spotlog.get_logger() and creates a Config-aware download directory during instantiation.

YouTubeDownloaderForCLI inherits this infrastructure but re-implements __init__ to maintain the same logging and directory setup without directly importing Config, instead relying on the parent class for cookie handling and path resolution.

Public API Methods

The base class exposes three primary methods for different content types:

• download_track() → returns (Path, Track) or (None, None)
• download_album() → returns None (side-effects only)
• download_playlist() → returns bool indicating any successful download

The CLI subclass provides parallel methods with _cli suffixes and enhanced signatures:

• download_track_cli() → same return type but adds exception handling with Spanish error messages
• download_album_cli() → returns (successful, total) tuple and accepts progress_callback
• download_playlist_cli() → returns (successful, total) tuple with optional progress_callback

Progress Reporting and Callbacks

YouTubeDownloader provides no built-in progress reporting. Callers must implement their own polling or wrapping logic to track download status.

YouTubeDownloaderForCLI introduces an optional progress_callback parameter in download_album_cli() and download_playlist_cli(). This callback receives (idx, total, track_name) arguments, enabling real-time progress bars or console output updates during batch operations.

Return Values and Error Handling

The base class uses minimal return semantics: boolean flags for playlists and tuples for individual tracks. Errors are logged via the internal logger with generic English messages.

The CLI variant returns detailed counts (successful, total) for batch operations, making it easier for interfaces to display completion statistics like "5/12 downloaded". It also implements Spanish-language exception handling and error logging (raise ValueError(f"No se encontró ..."), self.logger.error(f"Error al descargar ...")).

Language and Localization

YouTubeDownloader outputs generic English log messages suitable for library integration where the consuming application controls user-facing text.

YouTubeDownloaderForCLI hardcodes Spanish error messages and status updates, reflecting its origin as a Spanish-language CLI tool. This localization is embedded in exception strings and log output within the CLI-specific methods.

Code Examples

Using YouTubeDownloader for Library Integration

When building a custom application or wrapper that manages its own UI, use the base class for direct control over error handling and progress tracking.

from spotifysaver.downloader.youtube_downloader import YouTubeDownloader
from spotifysaver.enums import AudioFormat, Bitrate
from spotifysaver.models import Track

# Initialize downloader with custom base directory

dl = YouTubeDownloader(base_dir="MyMusic")

# Prepare track metadata (typically from Spotify API)

track = Track(
    name="Never Gonna Give You Up",
    artists=["Rick Astley"],
    album_name="Whenever You Need Somebody",
    release_date="1987-07-27",
    cover_url="https://i.scdn.co/image/.../cover.jpg",
)

# Download as MP3 at 192 kbps with embedded lyrics

path, updated_track = dl.download_track(
    track,
    output_format=AudioFormat.MP3,
    bitrate=Bitrate.B192,
    download_lyrics=True,
)

if path:
    print(f"Saved to: {path}")

Implementation reference: download_track in spotifysaver/downloader/youtube_downloader.py【/cache/repos/github.com/gabrielbaute/spotify-saver/main/spotifysaver/downloader/youtube_downloader.py#L311-L360】

Using YouTubeDownloaderForCLI with Progress Callbacks

For command-line tools or scripts requiring user feedback during batch operations, use the CLI subclass with callback support.

from spotifysaver.downloader.youtube_downloader_for_cli import YouTubeDownloaderForCLI
from spotifysaver.enums import AudioFormat, Bitrate
from spotifysaver.models import Album

def show_progress(idx, total, track_name):
    """Callback to display progress in terminal"""
    print(f"[{idx}/{total}] Downloading: {track_name}")

# Initialize CLI downloader

dl_cli = YouTubeDownloaderForCLI(base_dir="MusicCLI")

# Album object with tracks list

album = Album(
    name="Thriller",
    artists=["Michael Jackson"],
    release_date="1982-11-30",
    cover_url="https://i.scdn.co/image/.../thriller.jpg",
    tracks=[...]  # List of Track objects

)

# Download with progress reporting and NFO generation

successful, total = dl_cli.download_album_cli(
    album,
    output_format=AudioFormat.M4A,
    bitrate=Bitrate.B256,
    download_lyrics=True,
    nfo=True,
    cover=True,
    progress_callback=show_progress,
)

print(f"Finished: {successful}/{total} tracks downloaded")

Implementation reference: download_album_cli in spotifysaver/downloader/youtube_downloader_for_cli.py【/cache/repos/github.com/gabrielbaute/spotify-saver/main/spotifysaver/downloader/youtube_downloader_for_cli.py#L94-L156】

Summary

• YouTubeDownloader (spotifysaver/downloader/youtube_downloader.py) provides the core download engine with methods like download_track(), download_album(), and download_playlist(), returning minimal boolean or tuple values suitable for library integration.

• YouTubeDownloaderForCLI (spotifysaver/downloader/youtube_downloader_for_cli.py) inherits from the base class and adds CLI-specific features including progress_callback support, Spanish-language error messages, and richer return semantics (successful, total) for batch operations.

• Both classes share the same low-level infrastructure including yt-dlp options (_get_ydl_opts), cover art downloading (_download_cover), and metadata embedding, but the CLI variant is optimized for interactive command-line usage while the base class targets programmatic integration.

Frequently Asked Questions

Can I use YouTubeDownloaderForCLI in a GUI application?

While technically possible, it is not recommended. YouTubeDownloaderForCLI contains hardcoded Spanish error messages and console-specific progress callbacks designed for terminal output. For GUI applications, use the base YouTubeDownloader class and implement your own progress handling using the standard return values.

Why does YouTubeDownloaderForCLI return tuples instead of booleans?

The CLI variant returns (successful, total) tuples from methods like download_album_cli() and download_playlist_cli() to provide granular progress metrics for user interfaces. This allows command-line tools to display specific completion statistics (e.g., "Downloaded 8 of 12 tracks") rather than simple success/failure states.

Do both classes support the same audio formats and bitrates?

Yes. Both YouTubeDownloader and YouTubeDownloaderForCLI inherit the same low-level configuration from _get_ydl_opts() and utilize the AudioFormat and Bitrate enums from spotifysaver/enums/. Supported formats include MP3, M4A, FLAC, and OGG across both implementations.

Which class should I use for batch downloading playlists?

For batch operations, choose based on your interface requirements. Use YouTubeDownloader if you are building a custom wrapper or service that manages its own state, or use YouTubeDownloaderForCLI if you need built-in progress callbacks and detailed completion counts for terminal output. Both classes ultimately execute the same yt-dlp pipeline defined in the parent class.

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