asyncyt.core module

core.py

AsyncYT core downloader. Contains the main AsyncYT class with methods for video info retrieval, single-video download, playlist download, and search. Also includes internal helper functions and the _FfmpegProgressParser class for parsing FFmpeg progress output. Exceptions are defined in exceptions.py and data models in basemodels.py. Binary management is handled by binaries.py.

class asyncyt.core.AsyncYT(bin_dir=None)

Bases: BinaryManager

AsyncYT: Asynchronous media downloader powered by yt-dlp.

Supports single-video downloads, audio extraction, YouTube search, and native playlist downloads — all with real-time progress callbacks.

FFmpeg encoding/download progress is captured via --external-downloader ffmpeg -progress pipe:1 so you receive accurate frame, fps, speed, bitrate, size, and percentage updates.

Parameters:

bin_dir – Directory containing yt-dlp (and optionally ffmpeg) binaries.

async cancel(download_id: str) → None

Cancel a running single-video download.

Kills the yt-dlp process and any child FFmpeg process.

Parameters:

download_id – The ID returned by get_id().

Raises:

DownloadNotFoundError – If no download with that ID is running.

async cancel_playlist(playlist_id: str) → None

Request cancellation of a running playlist download.

The playlist loop checks the cancel event between each video. The currently-downloading video is also cancelled immediately.

Parameters:

playlist_id – The playlist ID returned by get_id().

Raises:

DownloadNotFoundError – If no playlist with that ID is running.

async download(url: str, config: DownloadConfig | None = None, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None, finalize: bool = True, include_cmd: Literal[False] = False) → Path

async download(request: DownloadRequest, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None, finalize: bool = True, include_cmd: Literal[False] = False) → Path

async download(url: str, config: DownloadConfig | None = None, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None, finalize: bool = True, include_cmd: Literal[True] = True) → Tuple[Path, List[str], str]

async download(request: DownloadRequest, progress_callback: Callable[[DownloadProgress], None | Awaitable[None]] | None = None, finalize: bool = True, include_cmd: Literal[True] = True) → Tuple[Path, List[str], str]

Download a single video or audio resource.

This method supports two calling conventions: 1. Passing a url string and an optional DownloadConfig. 2. Passing a pre-built DownloadRequest.

Parameters:

• url – The target video URL (Position 0).

• request – A DownloadRequest instance (Position 0).

• config – Optional DownloadConfig if a URL was provided.

• progress_callback – An async or sync callable that receives DownloadProgress updates during the download.

• finalize – If True (default), moves the file from the temporary directory to the final config.output_path.

• include_cmd – If True, the return type changes to include the raw command and terminal output for debugging or logging.

Returns:

• If include_cmd is False: The Path to the downloaded file.

• If include_cmd is True: A Tuple containing:

  1. Path: The path to the downloaded file.

  2. List[str]: The full CLI command list executed.

  3. str: The raw stdout/stderr output from the process.

Raises:

• DownloadAlreadyExistsError – If the same download is already in progress.

• YtdlpDownloadError – If yt-dlp returns a non-zero exit code.

• DownloadGotCanceledError – If the task was aborted via cancel().

• FileNotFoundError – If FFmpeg is missing or no file was generated.

async download_playlist(url: str | None = None, playlist_config: PlaylistConfig | None = None, progress_callback: Callable[[PlaylistDownloadProgress], None | Awaitable[None]] | None = None, *, request: PlaylistRequest | None = None) → PlaylistResponse

Download all (or a subset of) videos from a playlist.

Supports concurrent downloads via PlaylistConfig.concurrency. Progress is reported through progress_callback with a PlaylistDownloadProgress that includes both the overall playlist state and per-video DownloadProgress for every active download.

Parameters:

• url – Playlist URL (required when request is not given).

• playlist_config – Playlist-level configuration.

• progress_callback – Async or sync callable receiving PlaylistDownloadProgress updates.

• request – Optional PlaylistRequest.

Returns:

PlaylistResponse with per-item results and aggregated stats.

Raises:

TypeError – If conflicting arguments are supplied.

async download_with_response(*args, **kwargs) → DownloadResponse

Download with an API-friendly DownloadResponse return value.

Parameters:

• url – Video URL or a DownloadRequest.

• config – Optional DownloadConfig.

• progress_callback – Async or sync callable receiving DownloadProgress.

• finalize – Move output from temp dir to config.output_path.

Raises:

• DownloadAlreadyExistsError – Same download already running.

• YtdlpDownloadError – yt-dlp returned a non-zero exit code.

• DownloadGotCanceledError – cancel() was called.

• FileNotFoundError – FFmpeg not found, or no output file produced.

Returns:

DownloadResponse with metadata and optional error.

async finalize_download(temp_dir: TemporaryDirectory | Path, output_dir: Path, config: DownloadConfig) → List[Path]

Move processed files from temp_dir to output_dir.

Parameters:

• temp_dir – Temporary directory (cleaned up afterwards).

• output_dir – Final destination directory.

• config – Download config (used for overwrite setting).

Returns:

List of moved Path objects.

async get_playlist(url: str, max_videos: int | None = None) → PlaylistInfo

Fetch playlist metadata without downloading any videos.

Parameters:

• url – Playlist URL.

• max_videos – Limit entries returned (None = all).

Returns:

PlaylistInfo with per-video PlaylistVideoInfo entries (each containing thumbnail URLs).

async get_playlist_info(url: str, max_videos: int | None = None) → PlaylistInfo

Fetch full playlist metadata, including per-video thumbnails.

Uses yt-dlp’s --flat-playlist so it is fast — no individual video pages are fetched. Thumbnails come from the flat data that YouTube/yt-dlp provides in the playlist manifest.

Parameters:

• url – Playlist URL.

• max_videos – Limit to this many entries (None = all).

Returns:

PlaylistInfo with all PlaylistVideoInfo entries.

Raises:

YtdlpPlaylistGetInfoError – If yt-dlp fails.

async get_video_info(url: str) → VideoInfo

Retrieve video metadata from url using yt-dlp.

Parameters:

url – Video URL.

Returns:

VideoInfo with title, duration, thumbnail, etc.

Raises:

YtdlpGetInfoError – If yt-dlp returns a non-zero exit code.

async search(query: str | None = None, max_results: int | None = None, *, request: SearchRequest | None = None) → SearchResponse

Search YouTube for videos.

Parameters:

• query – Search query (required when request is not given).

• max_results – Maximum results (default 10, max 50).

• request – Optional SearchRequest (mutually exclusive with query).

Returns:

SearchResponse with a list of VideoInfo objects.