Skip to content

VideoDownloader

VideoDownloader is the central class of StreamFlow.

It coordinates source configuration, download settings, output paths and the interaction with yt-dlp.

Responsibilities

The class is responsible for:

  • configuring the download directory;
  • accepting URLs;
  • detecting playlists;
  • selecting quality;
  • selecting output formats;
  • generating output paths;
  • monitoring network availability;
  • invoking yt-dlp;
  • handling download errors.

Download lifecycle

The typical lifecycle is: 

downloader = VideoDownloader()


downloader.prompt_user_options()


if downloader.confirm_options():
    downloader.download_video()
The application entry point uses this lifecycle internally.

Quality configuration

The downloader uses a quality map to translate human-readable quality labels into yt-dlp format selectors. For example: 

High (720p)
maps to: 
bestvideo[height<=720]+bestaudio/best[height<=720]

Output handling

Single videos use the configured download directory.

Playlist downloads use a playlist-specific directory.

Output filenames are based on the media title unless a custom filename is provided.

Class reference

Video downloader

src.classes.video_downloader

This module provides a VideoDownloader class that allows users to download videos, audio, and playlists using yt-dlp via subprocess. It supports multiple quality options, output formats, network handling, and downloading from TXT URL lists and YAML configuration files.

VideoDownloader

A class to handle video and audio downloading from YouTube.

Features
  • Download single URLs, TXT URL lists, and grouped YAML configurations.
  • Provides various quality options for video downloads.
  • Supports multiple output formats (Mp4, Mkv, Mp3).
  • Handles network disconnections gracefully.
  • Ensures the download folder exists and is correctly set.

Attributes:

Name Type Description
QUALITY_MAP Dict[str, str]

Mapping of human-readable quality labels to yt-dlp format selectors.
OUTPUT_FORMATS List[str]

Supported output formats.
download_folder str

Path where downloaded files will be saved.
urls List[str]

List of video URLs to download.
quality str

Selected video quality.
output_format str

Selected output format.
is_playlist bool

Flag indicating if the URL is a playlist.
playlist_folder str

Folder path for playlist downloads.
mode str

Download mode, either 'Video' or 'Audio only'.

confirm_options()

Display selected options and ask the user for confirmation.

Returns:

Name Type Description
bool bool

True if the user confirms, False otherwise.

download_video()

Download configured URLs using yt-dlp and the project's cookies.

Applies the selected quality and output format. Handles playlists by placing downloads in a playlist folder when configured. Errors from subprocess calls are caught and reported per-URL.

Returns:

Type Description
None

None

progress_hook(d)

Monitor download progress and handle network interruptions.

Parameters:

Name Type Description Default
d dict

yt-dlp download status dictionary.

 required

Returns:

Type Description
None

None

prompt_user_options()

Prompt the user for download source, mode and format options.

After this call the instance attributes urls, mode, quality and output_format will be set based on user choices.

Returns:

Type Description
None

None

verify_download_folder()

Ensure the configured download folder exists, prompting user if needed.

If the configured folder does not exist, the user can provide a different path. The function will create the folder if it does not exist.

Returns:

Name Type Description
None None

This function updates the instance's download_folder attribute.