youtube_helper.main module

YouTube Helper — download and metadata utilities.

Module summary

Utility functions to download videos, audio, and thumbnails from URLs such as YouTube, Vimeo, or DailyMotion using yt-dlp, plus the post-processing steps (format conversion / merging via ffmpeg) needed to land the result in the exact container / sample-rate the caller asked for. It consumes a user-facing page URL and produces a file on disk (or, for video_url_meta_data(), a plain metadata dict).

Dependencies

  • yt-dlp : extraction and download engine.

  • ffmpeg : media conversion (invoked via the helper packages).

  • PIL : thumbnail format conversion.

  • os_helper : filesystem / URL utilities.

  • audio_helper : audio validation and conversion.

  • video_helper : video validation and conversion.

Author

Project maintainers.

youtube_helper.main.default_ytdlp_options(overwrites=True, audio=False, video=False, cookie_dir=None)[source]

Generate default yt-dlp options based on provided parameters.

Parameters:

  • overwrites (bool, optional) – Whether to overwrite existing files. Default is True.

  • audio (bool, optional) – Whether to download audio only. Default is False.

  • video (bool, optional) – Whether to download video only (overrides audio). Default is False.

  • cookie_dir (str or None, optional) – Directory in which yt-dlp’s session cookie jar is written. The download helpers pass their temporary_folder here so the jar disappears when the with block exits; when omitted it falls back to the system temp directory. It is never written to the current working directory.

Returns:

A dictionary of options for yt-dlp.

Return type:

dict

Notes

The function sets various options for yt-dlp. If audio is set to True, the format is set to download the best audio available. If video is set to True, it overrides the audio flag and downloads video+audio.

youtube_helper.main.download_audio(url, output_path=None, target_sample_rate=44100)[source]

Download the best quality audio from a given URL and save it to the specified output path.

Parameters:

  • url (str) – The URL of the video to download the audio from.

  • output_path (str, optional) – The path where the downloaded audio should be saved.

  • target_sample_rate (int, optional) – The sample rate of the output audio file. Defaults to 44100.

Returns:

Path of downloaded audio

Return type:

str

Notes

This function uses yt-dlp to download the best quality audio from the given URL. It handles different output formats and ensures the audio is saved with the desired sample rate using a conversion step if necessary.

youtube_helper.main.download_thumbnail(url, output_path=None)[source]

Download the thumbnail of a video from a given URL and save it to the specified output path.

Parameters:

  • url (str) – The URL of the video from which to download the thumbnail.

  • output_path (str, optional) – The path where the downloaded thumbnail should be saved.

Returns:

Path of downloaded thumbnail

Return type:

str

Notes

This function uses yt-dlp to download the thumbnail of the specified video. It handles different output formats and ensures the thumbnail is saved in the desired format using PIL.

youtube_helper.main.download_video(url, output_path=None)[source]

Download video from a given URL and save it to the specified output path.

Parameters:

  • url (str) – The URL of the video to be downloaded.

  • output_path (str, optional) – The path where the downloaded video should be saved.

Returns:

Path of downloaded video

Return type:

str

Notes

This function downloads the best quality video from the given URL using yt-dlp. It handles different formats and ensures that the video is saved in the desired format using ffmpeg if necessary. The function checks whether the downloaded video is valid and converts it to the specified output format if needed.

youtube_helper.main.is_valid_video_url(url)[source]

Check if a given URL is a valid video URL using yt-dlp.

Parameters:

url (str) – The URL to check.

Returns:

True if the URL is valid, False otherwise.

Return type:

bool

Notes

This function extracts metadata from the URL using yt-dlp to determine if the URL points to a valid video.

youtube_helper.main.video_url_meta_data(url)[source]

Retrieve metadata from a video URL without downloading the video.

Parameters:

url (str) – The URL of the video.

Returns:

A dictionary containing the video’s metadata, including title and description.

Return type:

dict

Notes

The function checks for metadata extraction success, logs the title and a part of the description, and returns metadata.