Core¶

class asyncyt.core.AsyncYT(bin_dir: str | Path | None = None)[source]¶

Bases: AsyncFFmpeg

AsyncYT: Asynchronous YouTube Downloader and Searcher

This class provides asynchronous methods for downloading YouTube videos, playlists, and searching for videos using yt-dlp and FFmpeg. It supports progress tracking, flexible configuration, and API-friendly response formats.

Parameters:: bin_dir (Optional[str | Path]) – Path to the directory containing yt-dlp and FFmpeg binaries.

async cancel(download_id: str)[source]¶

Cancel the downloading with download_id.

Parameters:: download_id (str) – The ID of the download to cancel.
Raises:: DownloadNotFoundError – If the download ID is not found.

async download(url: str, config: DownloadConfig | None = None, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None) → str[source]¶

async download(request: DownloadRequest, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None) → str

Asynchronously download media from a given URL using yt-dlp, track progress, and process the output file.

Parameters:

args – url (str) or request (DownloadRequest)
kwargs – config (Optional[DownloadConfig]), progress_callback (Optional[Callable])

Returns:

The filename of the output File.

Return type:

str

Raises:

DownloadAlreadyExistsError – If a download with the same ID is already in progress.
YtdlpDownloadError – If yt-dlp returns a non-zero exit code.
Exception – If the output file cannot be determined from yt-dlp output.
DownloadGotCanceledError – If the download is cancelled.
FileNotFoundError – If FFmpeg wasn’t installed.

async download_playlist(url: str, config: DownloadConfig | None = None, max_videos: int | None = None, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None) → PlaylistResponse[source]¶

async download_playlist(*, request: PlaylistRequest, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None) → PlaylistResponse

Asynchronously download videos from a YouTube playlist.

You can provide either a request object containing all parameters, or specify url, config, and max_videos individually. If request is provided, you must not provide url, config, or max_videos.

Parameters:

url (Optional[str]) – The URL of the playlist to download. Required if request is not given.
config (Optional[DownloadConfig]) – Download configuration options.
max_videos (Optional[int]) – Maximum number of videos to download from the playlist. Defaults to 100.
progress_callback (Optional[Callable[[DownloadProgress], Union[None, Awaitable[None]]]]) – Optional callback to report download progress.
request (Optional[PlaylistRequest]) – An object containing all playlist download parameters.

Returns:

PlaylistResponse object with download results.

Return type:

PlaylistResponse

Raises:

TypeError – If both request and any of url, config, or max_videos are provided, or if neither is provided.

async download_with_response(url: str, config: DownloadConfig | None = None, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None) → DownloadResponse[source]¶

async download_with_response(request: DownloadRequest, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None) → DownloadResponse

Download with API-friendly response format.

Parameters:

args – url (str) or request (DownloadRequest)
kwargs – config (Optional[DownloadConfig]), progress_callback (Optional[Callable])

Returns:

DownloadResponse object with metadata and error info.

Return type:

DownloadResponse

async get_playlist_info(url: str) → Dict[str, Any][source]¶

Asynchronously retrieve information about a YouTube playlist using yt-dlp.

Parameters:: url (str) – The URL of the YouTube playlist.
Returns:: Dictionary containing playlist entries and title.
Return type:: Dict[str, Any]
Raises:: YtdlpPlaylistGetInfoError – If the yt-dlp process fails to retrieve playlist information.

async get_video_info(url: str) → VideoInfo[source]¶

Asynchronously retrieve video information from a given URL using yt-dlp.

Parameters:: url (str) – The URL of the video to retrieve information for.
Returns:: VideoInfo object containing the video’s metadata.
Return type:: VideoInfo
Raises:: YtdlpGetInfoError – If yt-dlp fails to retrieve video information.

async search(query: str, max_results: int | None = None) → SearchResponse[source]¶

async search(*, request: SearchRequest) → SearchResponse

Perform an asynchronous search operation.

Parameters:

query (Optional[str]) – The search query string. Required if request is not provided.
max_results (Optional[int]) – Maximum number of results to return. Defaults to 10.
request (Optional[SearchRequest]) – Optional SearchRequest object containing search parameters.

Returns:

SearchResponse object with results and status.

Return type:

SearchResponse

Raises:

TypeError – If both request and either query or max_results are provided, or if neither is provided.