yt-dlp-utils¶

Utilities for programmatic use of yt-dlp. To use the async API, install with the extra asyncio.

GitHub commits since latest release (by SemVer including pre-releases)

yt_dlp_utils.get_configured_yt_dlp(sleep_time: int = 3, *, debug: bool = False, **kwargs: Unpack[yt_dlp._Params]) → yt_dlp.YoutubeDL¶

Get a configured YoutubeDL instance.

This function sets up a yt_dlp.YoutubeDL instance with the user’s configuration (e.g. located at ~/.config/yt-dlp/config). It overrides the default logger (logger option), disables colours (color option), and sets the sleep time between requests (sleep_interval_requests option). It also sets the verbose flag based on the debug parameter.

All other keyword arguments are passed directly to the yt_dlp.YoutubeDL constructor.

Parameters:¶

sleep_time : int¶: The time to sleep between requests, in seconds. Default is 3 seconds.
debug : bool¶: Whether to enable debug mode. Default is False.

Returns:¶

A configured instance of yt_dlp.YoutubeDL.

Return type:¶

yt_dlp.YoutubeDL

yt_dlp_utils.setup_session(browser: str, profile: str, add_headers: Mapping[str, str] | None = None, backoff_factor: float = 2.5, domains: Iterable[str] | None = None, headers: Mapping[str, str] | None = None, session: requests.Session | None = None, status_forcelist: Collection[int] = (429, 500, 502, 503, 504), *, setup_retry: bool = False) → requests.Session¶

Create or modify a Requests requests.Session instance with cookies from the browser.

Parameters:¶

browser : str¶: The browser to extract cookies from.
profile : str¶: The profile to extract cookies from.
add_headers : Mapping[str, str]¶: Additional headers to add to the requests session.
backoff_factor : float¶: The backoff factor to use for the retry mechanism.
domains : Iterable[str]¶: Filter the cookies to only those that match the specified domains.
headers : Mapping[str, str]¶: The headers to use for the requests session. If not specified, a default set will be used.
session : requests.Session | None¶: An existing session to modify. If not specified, a new session will be created.
status_forcelist : Collection[int]¶: The status codes to retry on.
setup_retry : bool¶: Whether to set up a retry mechanism for the Requests session.

Returns:¶

A Requests session.

Return type:¶

requests.Session

Async utilities.

class yt_dlp_utils.aio.AsyncYoutubeDL(ydl: YoutubeDL)¶

Async wrapper around yt_dlp.YoutubeDL.

This class wraps a synchronous YoutubeDL instance and provides async methods that run blocking operations in a thread executor.

Only download and extract_info are implemented in this wrapper.

Parameters:¶

ydl : yt_dlp.YoutubeDL¶: The wrapped YoutubeDL instance.

async download(urls: Iterable[str]) → int¶

Download videos asynchronously.

Parameters:¶

urls : Iterable[str]¶: The URLs to download.

Returns:¶

The return code (0 for success).

Return type:¶

int

async extract_info(url: str, ie_key: str | None = None, extra_info: Mapping[str, Any] | None = None, *, download: bool = True, process: bool = True, force_generic_extractor: bool = False) → dict[str, Any] | None¶

Extract info asynchronously.

Parameters:¶

url : str¶: The URL to extract info from.
download : bool¶: Whether to download the video. Default is True.
ie_key : str | None¶: The extractor key to use.
extra_info : Mapping[str, Any] | None¶: Extra info to pass to the extractor.
process : bool¶: Whether to process the info. Default is True.
force_generic_extractor : bool¶: Whether to force the generic extractor. Default is False.

Returns:¶

The extracted info, or None if extraction failed.

Return type:¶

dict[str, Any] | None

ydl¶: The wrapped YoutubeDL instance.

yt_dlp_utils.aio.get_configured_yt_dlp(sleep_time: int = 3, *, debug: bool = False, **kwargs: Unpack[yt_dlp._Params]) → AsyncYoutubeDL¶

Get an async-wrapped configured YoutubeDL instance.

All other keyword arguments are passed directly to the yt_dlp.YoutubeDL constructor.

Parameters:¶

sleep_time : int¶: The time to sleep between requests, in seconds. Default is 3 seconds.
debug : bool¶: Whether to enable debug mode. Default is False.

Returns:¶

An async wrapper around a configured yt_dlp.YoutubeDL instance.

Return type:¶

AsyncYoutubeDL

async yt_dlp_utils.aio.setup_session(browser: str, profile: str, add_headers: Mapping[str, str] | None = None, backoff_factor: float = 2.5, domains: Iterable[str] | None = None, headers: Mapping[str, str] | None = None, session: AsyncSession | None = None, status_forcelist: Collection[int] = (429, 500, 502, 503, 504), *, setup_retry: bool = False) → AsyncSession¶

Create or modify a niquests AsyncSession with cookies from the browser.

Parameters:¶

browser : str¶: The browser to extract cookies from.
profile : str¶: The profile to extract cookies from.
add_headers : Mapping[str, str]¶: Additional headers to add to the session.
backoff_factor : float¶: The backoff factor to use for the retry mechanism.
domains : Iterable[str]¶: Filter the cookies to only those that match the specified domains.
headers : Mapping[str, str]¶: The headers to use for the session. If not specified, a default set will be used.
session : AsyncSession | None¶: An existing session to modify. If not specified, a new session will be created.
status_forcelist : Collection[int]¶: The status codes to retry on.
setup_retry : bool¶: Whether to configure automatic retries (urllib3_future Retry).

Returns:¶

A niquests async session.

Return type:¶

AsyncSession

Notes

The session should be closed with await session.close() when done.

class yt_dlp_utils.YoutubeDLLogger(ydl=None)¶

Logger for yt-dlp.

debug(message: str) → None¶: Log a debug message.

error(message: str) → None¶: Log an error message.

info(message: str) → None¶: Log an info message.

warning(message: str, *, only_once: bool = False) → None¶: Log a warning message.

yt-dlp-utils¶

Indices and tables¶