asyncyt.basemodels module¶

class asyncyt.basemodels.DownloadConfig(*, output_path: str = './downloads', quality: Quality = Quality.BEST, audio_format: AudioFormat | None = None, video_format: VideoFormat | None = None, extract_audio: bool = False, embed_subs: bool = False, write_subs: bool = False, subtitle_lang: str = 'en', write_thumbnail: bool = False, embed_thumbnail: bool = False, embed_metadata: bool = True, write_info_json: bool = False, write_live_chat: bool = False, custom_filename: str | None = None, cookies_file: str | None = None, proxy: str | None = None, rate_limit: str | None = None, retries: Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=10)] = 3, fragment_retries: Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=10)] = 3, custom_options: Dict[str, ~typing.Any]=<factory>, encoding: EncodingConfig | None = None)[source]¶

Bases: BaseModel

Configuration for a single video download.

Parameters:

output_path – Directory where files are saved.
quality – Desired video quality.
audio_format – Audio container when extracting audio.
video_format – Video container format for remux/recode.
extract_audio – Download audio only.
embed_subs – Embed subtitles into the container.
write_subs – Write subtitle sidecar files.
subtitle_lang – BCP-47 subtitle language code.
write_thumbnail – Download thumbnail as a sidecar file.
embed_thumbnail – Embed thumbnail into the media file.
embed_metadata – Embed title/uploader/etc. metadata.
write_info_json – Write yt-dlp info JSON sidecar.
write_live_chat – Download live chat replay.
custom_filename – Custom yt-dlp output template.
cookies_file – Path to a Netscape cookies file.
proxy – Proxy URL.
rate_limit – Download rate limit (e.g. "1M", "500K").
retries – yt-dlp retry count.
fragment_retries – yt-dlp fragment retry count.
custom_options – Extra yt-dlp options passed as {key: value}.
encoding – Fine-grained FFmpeg encoding settings.

class Config[source]¶

Bases: object

json_schema_extra = {'example': {'embed_metadata': True, 'embed_thumbnail': True, 'encoding': {'audio': {'bitrate': '192k', 'codec': 'aac'}, 'video': {'codec': 'libx264', 'crf': 20, 'preset': 'slow'}}, 'extract_audio': False, 'output_path': './downloads', 'quality': '1080p', 'video_format': 'mp4'}}¶

use_enum_values = True¶

audio_format: AudioFormat | None¶

cookies_file: str | None¶

custom_filename: str | None¶

custom_options: Dict[str, Any]¶

embed_metadata: bool¶

embed_subs: bool¶

embed_thumbnail: bool¶

encoding: EncodingConfig | None¶

extract_audio: bool¶

fragment_retries: int¶

handle_extract_audio() → DownloadConfig[source]¶

model_config = {'json_schema_extra': {'example': {'embed_metadata': True, 'embed_thumbnail': True, 'encoding': {'audio': {'bitrate': '192k', 'codec': 'aac'}, 'video': {'codec': 'libx264', 'crf': 20, 'preset': 'slow'}}, 'extract_audio': False, 'output_path': './downloads', 'quality': '1080p', 'video_format': 'mp4'}}, 'use_enum_values': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_path: str¶

proxy: str | None¶

quality: Quality¶

rate_limit: str | None¶

retries: int¶

subtitle_lang: str¶

classmethod validate_output_path(v)[source]¶

classmethod validate_rate_limit(v)[source]¶

video_format: VideoFormat | None¶

write_info_json: bool¶

write_live_chat: bool¶

write_subs: bool¶

write_thumbnail: bool¶

class asyncyt.basemodels.DownloadFileProgress(*, status: ProgressStatus = ProgressStatus.DOWNLOADING, downloaded_bytes: int = 0, total_bytes: int = 0, percentage: Annotated[float, Ge(ge=0.0), Le(le=100.0)] = 0.0)[source]¶

Bases: BaseModel

Progress for binary file downloads (yt-dlp / ffmpeg setup).

class Config[source]¶

Bases: object

json_encoders = {<class 'float'>: <function DownloadFileProgress.Config.<lambda>>}¶

downloaded_bytes: int¶

property is_complete: bool¶

model_config = {'json_encoders': {<class 'float'>: <function DownloadFileProgress.Config.<lambda>>}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

percentage: float¶

status: ProgressStatus¶

total_bytes: int¶

class asyncyt.basemodels.DownloadProgress(*, id: str, url: str, title: str = '', status: ProgressStatus = ProgressStatus.DOWNLOADING, downloaded_bytes: int = 0, total_bytes: int = 0, speed: str = '', eta: int = 0, percentage: Annotated[float, Ge(ge=0.0), Le(le=100.0)] = 0.0, encoding_percentage: Annotated[float, Ge(ge=0.0), Le(le=100.0)] = 0.0, encoding_fps: float | None = None, encoding_speed: str | None = None, encoding_frame: int | None = None, encoding_bitrate: str | None = None, encoding_size: str | None = None, encoding_time: str | None = None)[source]¶

Bases: BaseModel

Real-time progress for a single video download.

During FFmpeg encode/remux, the encoding_* fields are populated from FFmpeg’s -progress pipe:1 output, which AsyncYT parses in real-time by using --external-downloader ffmpeg with custom args.

Parameters:

id – Download ID (SHA-256 of URL + config).
url – Source URL.
title – Video title (filled once yt-dlp reports it).
status – Current phase.
downloaded_bytes – Bytes received so far.
total_bytes – Expected total bytes.
speed – Download speed string, e.g. "3.20MiB/s".
eta – Estimated remaining seconds during download.
percentage – Overall download progress 0–100.
encoding_percentage – FFmpeg encode progress 0–100.
encoding_fps – Frames per second during encode.
encoding_speed – Encoding speed multiplier, e.g. "2.50x".
encoding_frame – Current frame being encoded.
encoding_bitrate – Output bitrate during encode, e.g. "2048kbits/s".
encoding_size – Output size so far, e.g. "4096KiB".
encoding_time – Elapsed encode time as HH:MM:SS.mmm.

class Config[source]¶

Bases: object

json_encoders = {<class 'float'>: <function DownloadProgress.Config.<lambda>>}¶

downloaded_bytes: int¶

encoding_bitrate: str | None¶

encoding_fps: float | None¶

encoding_frame: int | None¶

encoding_percentage: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.0), Le(le=100.0)])]¶

encoding_size: str | None¶

encoding_speed: str | None¶

encoding_time: str | None¶

eta: int¶

id: str¶

property is_complete: bool¶

model_config = {'json_encoders': {<class 'float'>: <function DownloadProgress.Config.<lambda>>}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

percentage: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.0), Le(le=100.0)])]¶

speed: str¶

status: ProgressStatus¶

title: str¶

total_bytes: int¶

url: str¶

class asyncyt.basemodels.DownloadRequest(*, url: str, config: DownloadConfig | None = None)[source]¶

Bases: BaseModel

Request model for single-video download endpoints.

class Config[source]¶

Bases: object

json_schema_extra = {'example': {'config': {'audio_format': 'mp3', 'extract_audio': True, 'output_path': './downloads', 'quality': '720p'}, 'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'}}¶

config: DownloadConfig | None¶

model_config = {'json_schema_extra': {'example': {'config': {'audio_format': 'mp3', 'extract_audio': True, 'output_path': './downloads', 'quality': '720p'}, 'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'}}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: str¶

classmethod validate_url(v)[source]¶

class asyncyt.basemodels.DownloadResponse(*, success: bool, message: str, id: str, filename: str | None = None, video_info: VideoInfo | None = None, error: str | None = None)[source]¶

Bases: BaseModel

Response model for single-video download operations.

class Config[source]¶

Bases: object

json_schema_extra = {'example': {'filename': './downloads/Rick Astley - Never Gonna Give You Up.mp4', 'message': 'Download completed successfully', 'success': True, 'video_info': {'duration': 212, 'title': 'Rick Astley - Never Gonna Give You Up', 'uploader': 'RickAstleyVEVO'}}}¶

error: str | None¶

filename: str | None¶

id: str¶

message: str¶

model_config = {'json_schema_extra': {'example': {'filename': './downloads/Rick Astley - Never Gonna Give You Up.mp4', 'message': 'Download completed successfully', 'success': True, 'video_info': {'duration': 212, 'title': 'Rick Astley - Never Gonna Give You Up', 'uploader': 'RickAstleyVEVO'}}}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

success: bool¶

video_info: VideoInfo | None¶

class asyncyt.basemodels.HealthResponse(*, status: str = 'healthy', yt_dlp_available: bool = False, ffmpeg_available: bool = False, version: str = '1.0.0', binaries_path: str | None = None, error: str | None = None)[source]¶

Bases: BaseModel

Health check response.

binaries_path: str | None¶

error: str | None¶

ffmpeg_available: bool¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

status: str¶

version: str¶

yt_dlp_available: bool¶

class asyncyt.basemodels.InputFile(*, path: str, type: InputType, options: List[str] = <factory>, stream_index: int | None = None)[source]¶

Bases: BaseModel

Single input file configuration.

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

options: List[str]¶

path: str¶

stream_index: int | None¶

type: InputType¶

classmethod validate_path_exists(v)[source]¶

class asyncyt.basemodels.MediaInfo(*, filename: str, format_name: str, format_long_name: str, duration: float, size: int, bit_rate: int, streams: List[StreamInfo])[source]¶

Bases: BaseModel

Media file information.

bit_rate: int¶

duration: float¶

filename: str¶

format_long_name: str¶

format_name: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

size: int¶

streams: List[StreamInfo]¶

class asyncyt.basemodels.PlaylistConfig(**data: Any)[source]¶

Bases: BaseModel

Configuration specific to playlist downloads.

Extends the concept of DownloadConfig at the playlist level, letting you control concurrency, item ranges, and failure behaviour without duplicating all per-video settings (those live inside item_config).

Parameters:

item_config – Per-video DownloadConfig applied to each item.
max_videos – Maximum number of videos to download (0 = all).
start_index – 1-based playlist index to start from.
end_index – 1-based playlist index to stop at (inclusive). None = end.
concurrency – How many videos to download simultaneously (1 = sequential).
skip_on_error – If True, log failed items and continue; otherwise abort.
reverse – Download playlist in reverse order.
write_playlist_metadata – Write a playlist.json file with PlaylistInfo metadata alongside the videos.

class Config[source]¶

Bases: object

json_schema_extra = {'example': {'concurrency': 2, 'item_config': {'embed_metadata': True, 'output_path': './playlist_out', 'quality': '1080p'}, 'skip_on_error': True, 'video_indices': [1, 3, 7]}}¶

concurrency: int¶

end_index: int | None¶

item_config: DownloadConfig | None¶

max_videos: int¶

model_config = {'json_schema_extra': {'example': {'concurrency': 2, 'item_config': {'embed_metadata': True, 'output_path': './playlist_out', 'quality': '1080p'}, 'skip_on_error': True, 'video_indices': [1, 3, 7]}}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reverse: bool¶

skip_on_error: bool¶

start_index: int¶

classmethod validate_video_ids(v)[source]¶

classmethod validate_video_indices(v)[source]¶

video_ids: List[str] | None¶

video_indices: List[int] | None¶

write_playlist_metadata: bool¶

class asyncyt.basemodels.PlaylistDownloadProgress(**data: Any)[source]¶

Bases: BaseModel

Real-time progress for a full playlist download operation.

The current_video_progress field mirrors a normal DownloadProgress so callers can render per-video progress bars alongside the overall playlist progress.

Parameters:

playlist_id – Unique ID for this playlist download session.
playlist_info – Full playlist metadata (available after fetch stage).
status – High-level playlist status.
total_videos – Total number of videos selected for download.
completed_videos – Number of successfully downloaded videos.
failed_videos – Number of failed videos so far.
current_index – 1-based index of the video currently being processed.
current_video – Metadata of the video currently being downloaded.
current_video_progress – Live DownloadProgress for the active video.
overall_percentage – Overall playlist completion 0–100.
results – Completed item results accumulated so far.

class Config[source]¶

Bases: object

json_encoders = {<class 'float'>: <function PlaylistDownloadProgress.Config.<lambda>>}¶

completed_videos: int¶

current_index: int¶

current_video: PlaylistVideoInfo | None¶

current_video_progress: DownloadProgress | None¶

failed_videos: int¶

model_config = {'json_encoders': {<class 'float'>: <function PlaylistDownloadProgress.Config.<lambda>>}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

overall_percentage: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.0), Le(le=100.0)])]¶

playlist_id: str¶

playlist_info: PlaylistInfo | None¶

results: List[PlaylistItemResult]¶

status: PlaylistStatus¶

total_videos: int¶

class asyncyt.basemodels.PlaylistInfo(*, id: str = '', url: str = '', title: str = 'Unknown Playlist', description: str | None = None, uploader: str | None = None, thumbnail: str | None = None, entry_count: int = 0, entries: List[PlaylistVideoInfo] = <factory>)[source]¶

Bases: BaseModel

Full metadata for a playlist, including all video entries.

Parameters:

id – Playlist ID.
url – Playlist URL.
title – Playlist title.
description – Playlist description.
uploader – Channel / uploader name.
thumbnail – Playlist thumbnail URL.
entry_count – Total number of entries in the playlist (may exceed entries if max_videos was applied).
entries – List of PlaylistVideoInfo objects.

description: str | None¶

entries: List[PlaylistVideoInfo]¶

entry_count: int¶

classmethod from_ytdlp(raw_entries: List[dict], playlist_url: str, max_videos: int | None = None) → PlaylistInfo[source]¶

Build a PlaylistInfo from a list of raw yt-dlp flat-playlist dicts.

Parameters:

raw_entries – Raw list of entry dicts from yt-dlp.
playlist_url – The original playlist URL.
max_videos – Limit to this many entries (None = all).

id: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

thumbnail: str | None¶

title: str¶

uploader: str | None¶

url: str¶

class asyncyt.basemodels.PlaylistItemResult(*, index: int, video_info: PlaylistVideoInfo, success: bool, filepath: str | None = None, error: str | None = None)[source]¶

Bases: BaseModel

Result of downloading a single playlist item.

Parameters:

index – 1-based playlist index.
video_info – Video metadata.
success – Whether the download succeeded.
filepath – Final output file path (None if failed).
error – Error message (None if succeeded).

error: str | None¶

filepath: str | None¶

index: int¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

success: bool¶

video_info: PlaylistVideoInfo¶

class asyncyt.basemodels.PlaylistRequest(*, url: str, playlist_config: PlaylistConfig | None = None)[source]¶

Bases: BaseModel

Request model for playlist download endpoints.

Parameters:

url – Playlist URL.
playlist_config – Playlist-level configuration (concurrency, ranges, etc.). When omitted, sensible defaults are used.

class Config[source]¶

Bases: object

json_schema_extra = {'example': {'playlist_config': {'concurrency': 2, 'item_config': {'output_path': './playlist', 'quality': '720p'}, 'max_videos': 10, 'skip_on_error': True}, 'url': 'https://www.youtube.com/playlist?list=PLxxxxxxx'}}¶

model_config = {'json_schema_extra': {'example': {'playlist_config': {'concurrency': 2, 'item_config': {'output_path': './playlist', 'quality': '720p'}, 'max_videos': 10, 'skip_on_error': True}, 'url': 'https://www.youtube.com/playlist?list=PLxxxxxxx'}}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

playlist_config: PlaylistConfig | None¶

url: str¶

classmethod validate_playlist_url(v)[source]¶

class asyncyt.basemodels.PlaylistResponse(*, success: bool, message: str, playlist_info: PlaylistInfo | None = None, results: List[PlaylistItemResult] = <factory>, total_videos: int = 0, successful_downloads: int = 0, failed_downloads: int = 0, downloaded_files: List[str] = <factory>, error: str | None = None)[source]¶

Bases: BaseModel

Response model for playlist download operations.

Parameters:

success – Overall success flag (True even when some items failed if skip_on_error was enabled and at least one succeeded).
message – Human-readable summary.
playlist_info – Full playlist metadata.
results – Per-item download results.
total_videos – Total number of playlist videos selected.
successful_downloads – Count of successfully downloaded videos.
failed_downloads – Count of failed videos.
downloaded_files – Convenience list of output file paths.
error – Top-level error message (only set when the entire operation failed).

downloaded_files: List[str]¶

error: str | None¶

failed_downloads: int¶

message: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

playlist_info: PlaylistInfo | None¶

results: List[PlaylistItemResult]¶

success: bool¶

successful_downloads: int¶

total_videos: int¶

class asyncyt.basemodels.PlaylistVideoInfo(*, id: str = '', url: str, title: str | None = None, duration: Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, uploader: str | None = None, thumbnail: str | None = None, thumbnails: Dict[str, ~typing.Any]]=<factory>, upload_date: str = '', view_count: Annotated[int, ~annotated_types.Ge(ge=0)] = 0, playlist_index: int | None = None)[source]¶

Bases: BaseModel

Lightweight info for a single video inside a playlist.

This is populated during get_playlist_info from yt-dlp’s --flat-playlist output, so heavy fields like formats are absent. Use get_video_info(entry.url) if you need full format data.

Parameters:

id – Video ID (e.g. YouTube video ID).
url – Full video URL.
title – Video title.
duration – Duration in seconds (may be 0 if unavailable flat).
uploader – Channel / uploader name.
thumbnail – Best thumbnail URL available from flat data.
thumbnails – All thumbnail variants returned by yt-dlp.
upload_date – Upload date string (YYYYMMDD).
view_count – View count (may be 0 if unavailable flat).
playlist_index – 1-based position inside the playlist.

duration: float¶

classmethod from_flat_dict(data: dict, index: int | None = None) → PlaylistVideoInfo[source]¶

Build a PlaylistVideoInfo from a yt-dlp --flat-playlist entry.

Parameters:

data – Raw yt-dlp entry dict.
index – 1-based position in the playlist (optional).

id: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

playlist_index: int | None¶

thumbnail: str | None¶

thumbnails: List[Dict[str, Any]]¶

title: str | None¶

upload_date: str¶

uploader: str | None¶

url: str¶

view_count: int¶

class asyncyt.basemodels.SearchRequest(*, query: Annotated[str, MinLen(min_length=1), MaxLen(max_length=200)], max_results: Annotated[int, Ge(ge=1), Le(le=50)] = 10)[source]¶

Bases: BaseModel

Request model for search endpoints.

class Config[source]¶

Bases: object

json_schema_extra = {'example': {'max_results': 5, 'query': 'python tutorial'}}¶

max_results: int¶

model_config = {'json_schema_extra': {'example': {'max_results': 5, 'query': 'python tutorial'}}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

query: str¶

class asyncyt.basemodels.SearchResponse(*, success: bool, message: str, results: List[VideoInfo] = <factory>, total_results: int = 0, error: str | None = None)[source]¶

Bases: BaseModel

Response model for search operations.

error: str | None¶

message: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

results: List[VideoInfo]¶

success: bool¶

total_results: int¶

class asyncyt.basemodels.SetupProgress(*, file: str = 'yt-dlp', download_file_progress: DownloadFileProgress)[source]¶

Bases: BaseModel

Progress for binary setup (yt-dlp / ffmpeg download).

class Config[source]¶

Bases: object

json_encoders = {<class 'float'>: <function SetupProgress.Config.<lambda>>}¶

download_file_progress: DownloadFileProgress¶

file: str¶

model_config = {'json_encoders': {<class 'float'>: <function SetupProgress.Config.<lambda>>}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Bases: BaseModel

Stream information for media files.

bit_rate: int | None¶

channels: int | None¶

codec_name: str | None¶

codec_type: str¶

height: int | None¶

index: int¶

language: str | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sample_rate: int | None¶

width: int | None¶

class asyncyt.basemodels.VideoInfo(*, url: str, title: str, duration: Annotated[float, ~annotated_types.Ge(ge=-1)] = 0, uploader: str, view_count: Annotated[int, ~annotated_types.Ge(ge=-1)] = 0, like_count: Annotated[int | None, ~annotated_types.Ge(ge=-1)] = None, description: str = '', thumbnail: str = '', upload_date: str = '', formats: Dict[str, ~typing.Any]]=<factory>)[source]¶

Bases: BaseModel

Video information extracted from URL.

Parameters:

url – Video URL.
title – Video title.
duration – Duration in seconds.
uploader – Uploader name.
view_count – Number of views.
like_count – Number of likes.
description – Video description.
thumbnail – Thumbnail URL.
upload_date – Upload date string (YYYYMMDD).
formats – List of available formats.

class Config[source]¶

Bases: object

json_schema_extra = {'example': {'description': 'Official video...', 'duration': 212, 'like_count': 10000000, 'thumbnail': 'https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg', 'title': 'Rick Astley - Never Gonna Give You Up', 'upload_date': '20091025', 'uploader': 'RickAstleyVEVO', 'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ', 'view_count': 1000000000}}¶

description: str¶

duration: float¶

formats: List[Dict[str, Any]]¶

classmethod from_dict(data: dict) → VideoInfo[source]¶

like_count: int | None¶

model_config = {'json_schema_extra': {'example': {'description': 'Official video...', 'duration': 212, 'like_count': 10000000, 'thumbnail': 'https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg', 'title': 'Rick Astley - Never Gonna Give You Up', 'upload_date': '20091025', 'uploader': 'RickAstleyVEVO', 'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ', 'view_count': 1000000000}}}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

thumbnail: str¶

title: str¶

upload_date: str¶

uploader: str¶

url: str¶

classmethod validate_url(v)[source]¶

view_count: int¶