async-yt-dlp
Строго типизированная асинхронная обёртка над yt-dlp для Python 3.11+.
Все блокирующие операции yt-dlp выполняются через asyncio.to_thread, поэтому event loop не блокируется. Подходит для Telegram-ботов, Discord-ботов, веб-сервисов (FastAPI, Litestar, aiohttp) и фоновых очередей задач.
Возможности
- Асинхронность: блокирующие вызовы yt-dlp вынесены в
asyncio.to_thread, event loop свободен. - Типизация: модели
MediaInfo,FormatInfo,DownloadResult,ProgressEvent— frozen dataclass соslots=True. PEP 561py.typed, совместимо сmypy --strict. - Потокобезопасность: каждая операция получает изолированный экземпляр
YoutubeDL. - Стриминг прогресса: асинхронный генератор
download_with_progressс адаптивным троттлингом. - Контроль параллельности:
DownloadManagerна базеasyncio.Semaphoreс ограничением очереди (backpressure). - Отмена и таймауты: корректная обработка
task.cancel(),asyncio.timeoutи graceful shutdown. - Объектная конфигурация:
FormatSelector(fluent-построитель форматов),OutputTemplate(построитель шаблонов имён файлов),VideoContainer(выбор контейнера). - Маскировка данных: пароли, токены, cookies и прокси автоматически скрываются в логах.
- Диагностика окружения:
check_dependencies()проверяет наличиеyt-dlp,ffmpeg,ffprobeи JS-движков. - Автоматический EJS (JS runtimes): автоматическое обнаружение Node.js, Deno, Bun в системе для работы YouTube без троттлинга (
auto_detect_js=True). - Чистые логи: служебные предупреждения ядра yt-dlp фильтруются (
no_warnings=True), не засоряя консоль.
Установка
Требуется Python 3.11+.
# Базовая установка:
pip install async-yt-dlp
# С интеграцией aio-ffmpeg (постобработка видео):
pip install "async-yt-dlp[ffmpeg]"
# Полный набор (aio-ffmpeg + curl-cffi, websockets и др.):
pip install "async-yt-dlp[full]"
Или через uv:
uv add async-yt-dlp
Быстрый старт
1. Извлечение метаданных
import asyncio
import sys
from async_yt_dlp import AsyncYTDLP
# Корректный вывод Unicode/эмодзи в консоли Windows
if sys.stdout.encoding != "utf-8":
sys.stdout.reconfigure(encoding="utf-8")
async def main() -> None:
async with AsyncYTDLP() as ytdlp:
info = await ytdlp.extract_info("https://www.youtube.com/watch?v=BaW_jenozKc")
print(f"Название: {info.title}")
print(f"Автор: {info.uploader}")
print(f"Длительность: {info.duration_seconds} сек.")
asyncio.run(main())
2. Скачивание видео
import asyncio
from pathlib import Path
from async_yt_dlp import AsyncYTDLP, YTDLPOptions, FormatSelector, OutputTemplate, VideoContainer
async def main() -> None:
options = YTDLPOptions(
format=FormatSelector.preset_720p(container=VideoContainer.MP4),
container=VideoContainer.MP4,
output_path=Path("./downloads"),
output_template=OutputTemplate.title_only(),
)
async with AsyncYTDLP(default_options=options) as ytdlp:
result = await ytdlp.download("https://www.youtube.com/watch?v=BaW_jenozKc")
print(f"Файл: {result.filepath} ({result.file_size} байт)")
asyncio.run(main())
3. Стриминг прогресса загрузки
import asyncio
from async_yt_dlp import AsyncYTDLP, DownloadStatus
async def main() -> None:
async with AsyncYTDLP() as ytdlp:
async for event in ytdlp.download_with_progress(
"https://www.youtube.com/watch?v=BaW_jenozKc",
throttle_interval=0.2,
):
if event.status == DownloadStatus.DOWNLOADING:
line = f"Загрузка: {event.percent:.1f}% | {event.speed_str} | ETA: {event.eta_str}"
# \033[K очищает остаток строки, ljust(70) исключает наложение старых символов
print(f"\r\033[K{line:<70}", end="", flush=True)
elif event.status == DownloadStatus.POST_PROCESSING:
if event.postprocessor_status == "started":
print(f"\r\033[KПостобработка: {event.postprocessor}...", flush=True)
elif event.status == DownloadStatus.COMPLETE:
print("\r\033[KЗагрузка успешно завершена!", flush=True)
asyncio.run(main())
Объектная конфигурация
FormatSelector — построитель строки --format
from async_yt_dlp import FormatSelector, VideoContainer
# Универсальный выбор любого разрешения:
FormatSelector.resolution(720)
FormatSelector.resolution(1080, fps=60)
# Готовые пресеты (144p .. 4K/8K):
FormatSelector.preset_720p() # 720p HD
FormatSelector.preset_1080p() # 1080p Full HD
FormatSelector.preset_4k() # 4K UHD
FormatSelector.preset_audio_only("mp3") # только аудио (mp3, m4a, flac)
FormatSelector.preset_max_quality() # максимальное качество
# Ручная сборка (fluent builder):
fmt = FormatSelector.video().max_height(480).ext("mp4").merge(FormatSelector.audio())
OutputTemplate — построитель шаблона имени файла
from async_yt_dlp import OutputTemplate
# Готовые пресеты:
OutputTemplate.title_only() # "%(title)s.%(ext)s"
OutputTemplate.title_and_id() # "%(title)s [%(id)s].%(ext)s"
OutputTemplate.dated() # "%(upload_date)s - %(title)s.%(ext)s"
OutputTemplate.playlist_folder() # "%(playlist_title)s/%(playlist_index)02d - %(title)s.%(ext)s"
OutputTemplate.channel_folder() # "%(uploader)s/%(upload_date)s - %(title)s.%(ext)s"
# Ручная сборка через fluent-API:
tpl = OutputTemplate().channel().dir().title().ext() # "%(channel)s/%(title)s.%(ext)s"
# Операторы:
tpl = OutputTemplate().channel() / OutputTemplate.title_only() # то же самое
VideoContainer — гарантия формата выходного файла
from async_yt_dlp import VideoContainer, YTDLPOptions
# Гарантирует .mp4 на выходе (ffmpeg remux без перекодирования):
options = YTDLPOptions(container=VideoContainer.MP4)
# Доступные: MP4, MKV, WEBM, MOV, AVI, FLV, TS
Конвейер загрузки и принцип DRY (Don't Repeat Yourself)
Библиотека строго разделяет задачи на два этапа конвейера:
- Сетевой уровень (
FormatSelector): отвечает за выбор стримов на удаленном сервере (разрешение, частота кадров, битрейт). - Файловый уровень (
YTDLPOptions.container): отвечает за итоговый файл на диске (быстрое слияние видео/аудио и ремуксинг FFmpeg в целевой.mp4).
Не дублируйте container в обоих местах — используйте каноничный паттерн:
# ✅ Рекомендуемый лаконичный код:
options = YTDLPOptions(
format=FormatSelector.resolution(720), # ТОЛЬКО качество/высота
container=VideoContainer.MP4, # ТОЛЬКО формат итогового файла
output_path=Path("./downloads"),
)
Архитектура
flowchart TD
App["Приложение<br/>(Telegram, Web, CLI, Bot)"] --> Client["AsyncYTDLP<br/>фасад, lifecycle, API"]
Client --> Manager["DownloadManager<br/>Semaphore, backpressure"]
Manager --> Backend["ThreadBackend<br/>asyncio.to_thread"]
Backend --> YTDLP["yt_dlp.YoutubeDL<br/>синхронное ядро"]
Примеры использования
В каталоге examples/ представлены готовые примеры:
simple_extract.py— извлечение метаданныхsimple_download.py— скачивание файлаprogress.py— отображение прогрессаplaylist.py— работа с плейлистамиaudio_extraction.py— извлечение аудиоpostprocessing_pipeline.py— постобработка через aio-ffmpegcustom_options.py— настройка параметровcancellation.py— отмена задач и таймаутыconcurrency.py— параллельная загрузка
Лицензия
Проект распространяется под лицензией MIT. См. файл LICENSE.
Metadata
Release files for async-yt-dlp 0.1.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| async_yt_dlp-0.1.6.tar.gz | 343.0 kB | Without provenance | Details for async_yt_dlp-0.1.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| async_yt_dlp-0.1.6-py3-none-any.whl | Python 3 | none | any | Details for async_yt_dlp-0.1.6-py3-none-any.whl |
Total release size: 405.5 kB
Release files / async_yt_dlp-0.1.6.tar.gz
| Download URL | async_yt_dlp-0.1.6.tar.gz |
|---|---|
| Size | 343.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
93542690725cb8cad8719f36141406a46036a45de0de9922f4f998bd6f3d85ba
|
|
BLAKE2b-256 checksum How to use checksums |
228e2522379f8c1d664ea6a0e06da353451de60b1d24578e5bd8b209a1b6f917
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / async_yt_dlp-0.1.6-py3-none-any.whl
| Download URL | async_yt_dlp-0.1.6-py3-none-any.whl |
|---|---|
| Size | 62.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8c7d84af21863f6dfc98644c6a292c7bf7e728f270141736eb85971cff763778
|
|
BLAKE2b-256 checksum How to use checksums |
954e16b1b0dd5c7234cdf59c75685ed0725c40fef20c11378583ff5777be69d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for async-yt-dlp 0.1.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.