跳转到正文
中文
获取 API 密钥
浏览文档

指南

yt-dlp 的 Python API

可运行的 Python 示例,涵盖下载、元数据、AI 数据集及可续跑的批处理。

本页内容

安装 Python 库

在 Python 3.11+ 环境中运行
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"

同时安装 Deno、FFmpeg 和 ffprobe。 这些示例在 Linux、macOS 或 Windows 上本地运行,无需 API 密钥。确保下载进程可通过 PATH 找到这些可执行文件。

下载第一个视频

下载一张视频
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget

options = {
    "js_runtimes": {"deno": {}},
    "impersonate": ImpersonateTarget(),
    "concurrent_fragment_downloads": 1,
    "noplaylist": True,
    "outtmpl": "downloads/%(id)s.%(ext)s",
    "format": "bv*[height<=1080]+ba/b[height<=1080]",
}
with YoutubeDL(options) as downloader:
    downloader.download(["https://www.youtube.com/watch?v=jNQXAC9IVRw"])
此示例在本地保存分辨率最高为 1080p 的媒体,并可合并单独的视频流和音频流。输出容器取决于选中的源格式。

Python 不会继承 CLI 设置。 即使终端命令已经配置了 Deno、浏览器模拟和请求间隔,也要在 Python 选项中设置。

download() 取出 URL 列表并返回状态代码。 extract_info(url, download=True) 返回提取信息以及下载。使用背景管理员清洁地关闭例子,并创建一个新例子为独立工作而不是在线上分享可变状态。

阅读无媒体的数据

出口小型数据记录
import json
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget

url = "https://www.youtube.com/watch?v=jNQXAC9IVRw"
options = {
    "js_runtimes": {"deno": {}},
    "impersonate": ImpersonateTarget(),
    "noplaylist": True,
    "sleep_interval_requests": 3,
}
with YoutubeDL(options) as downloader:
    info = downloader.sanitize_info(downloader.extract_info(url, download=False))

record = {key: info.get(key) for key in (
    "id", "webpage_url", "title", "channel_id", "duration", "upload_date"
)}
print(json.dumps(record, ensure_ascii=False, indent=2))
download=False 仍然执行网络请求。 sanitize_info 使结果 JSON 兼容;它不会编写秘密或将结果减少到这些字段。

提取的字段可能是缺席或零。使用 get() 可选的代数据,并且不要假设每个来源都有一个长度、频道 ID 或完整的格式列表。平板播放列表列表也与完全解决的视频不同。对于公众的回应,仅项目您打算展示的领域。

避免即时进行的数据提取,随后每个来源的相同下载提取,除非您的应用程序需要额外的规划步骤。它将源源请求复制。如果您需要持久的工作,请存储源代码和输出政策;从元数据中签署的媒体URL不是原始来源的持久替代品。

Python 选项参考

任务Python 選擇细节
输出目录和文件名"outtmpl": "downloads/%(id)s.%(ext)s"保持源识别和动态扩展。
硬 1080p 天花板"format": "bv*[height<=1080]+ba/b[height<=1080]"允许源代码,如果没有匹配限制,则失败。
甲状腺 侧面"writeinfojson": True将完整的提取数据与媒体相结合。
完整的ID检查点"download_archive": "archive.txt"每份输出政策一份档案,而不是支票存储。
严格的错误"ignoreerrors": False让呼叫者记录失败,而不是处理后处理问题作为成功。
丹尼尔时间"js_runtimes": {"deno": {}}安装 Deno 在下载进程,并在PATH上显示其二进制。
浏览器 印象"impersonate": ImpersonateTarget()Python 等于 --impersonate=""; 输入目标类,并安装 curl-cffi。
现有 Cookie 文件"cookiefile": "private/youtube-cookies.txt"使用私人会话证书,只有在需要访问时。
MP3 转换选项
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
转换 audio_options 到 YoutubeDL. 后处理器 FFmpeg 转换为目标比特率 192 kbps; 它不会改善源的原始质量。

视频 + 音频 + 录像带为 AI 数据集

使用此输出政策,当目标是训练数据集而不是下载进程示例的1080p收藏时,它要求最佳视频和 bestaudio,允许FFmpeg将它们融入MP4中,并在媒体旁边保存可用的英语录像和代数据。

一个数据集项目在Python
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget

url = "https://www.youtube.com/watch?v=jNQXAC9IVRw"
options = {
    "js_runtimes": {"deno": {}},
    "impersonate": ImpersonateTarget(),
    "noplaylist": True,
    "format": "bestvideo+bestaudio/best",
    "merge_output_format": "mp4",
    "postprocessors": [{
        "key": "FFmpegVideoRemuxer",
        "preferedformat": "mp4",
    }],
    "outtmpl": "dataset/%(id)s/%(id)s.%(ext)s",
    "writeinfojson": True,
    "writesubtitles": True,
    "writeautomaticsub": True,
    "subtitleslangs": ["en"],
    "subtitlesformat": "vtt/best",
    "sleep_interval_requests": 2,
    "sleep_interval_subtitles": 5,
    "sleep_interval": 5,
    "max_sleep_interval": 10,
    "concurrent_fragment_downloads": 1,
    "retries": 3,
    "fragment_retries": 3,
}
with YoutubeDL(options) as downloader:
    downloader.download([url])
需要 FFmpeg/ffprobe、Deno 和夜间 [默认 curl-cffi] 安装,而 remuxer 的偏好格式参数则以此方式在 yt-dlp 的 API 中播放。

ImpersonateTarget() 选择任何可用的浏览器目标,匹配 --impersonate="”。通过对象,而不是从 CLI 合成中复制的空行。 curl-cffi 必须安装在这个 Python 环境中。目前,Deno 仍然运行 JavaScript 解决方案;定制不取代它。

MP4是输出容器;所选择的视频仍然可以是AV1或 VP9。如果您的训练解码器需要 H.264/AAC,在合并或记录一个单独的 FFmpeg 转码之前,请应用明确的编码政策。可用的字幕被收回,而不是从演讲中产生。

媒體結束後数据集记录需要什么
查看最后的MP4与 ffprobeVideo/audio编码器,长度,尺寸,文件路径和比特计算。
查看 标签 侧面 单独语言, supplied/automatic 轨道,时间表,以及文件是否实际存在。
没有可用的匹配容器保持媒体并标记文本缺席;如果需要的话,将音频发送到您的转写阶段。
第429章 打了退出标题在IP冷却后退出标题;不要重新下载完成的媒体。

对于一个集合,请使用这个数据集政策的单独档案,并保存所需的侧面图的存储库。不要重复使用以前的 1080p 或媒体仅存档:它可能会在收集新需要的录像之前删除视频。使用 after_move 以便媒体准备,然后在发布完整的数据集项目之前验证文本和代数据。

知道最后文件什么时候准备好

进展霍克报告状态=完成,意味着转会完成。FFmpeg 可能仍然需要将视频和音频合并,转换音频文件,或移动输出。视频仅流达到 100% 不是完成事件,您的申请应该发布。

阶段你所知道的应用状态
下载一些媒体比特正在到来。跑步
转换:完成此转移已结束;处理仍可追踪。处理
after_move 后处理器文件已通过了配置后处理和最终转移。地点文件准备
升级和完整性检查您的目的地有对象和记录验证。交付

下面的完整示例记录了一个自定义的邮件处理器在 after_move 并在那里阅读 info["filepath"]。它检查文件是否存在并不被泄露。此避免猜测最终延伸与 prepare_filename(),可以提到一个预转换名称。

完整剧本:单视频下载进程

此分類上一篇: download_video.py它接受视频 ID 或 watch/Shorts/live/embed URL 并拒绝 playlist/channel 输入。每个邀请都使用一个YouTubeDL例子,有限的下载退款和集合地点档案。重复完成的源返回被错过,而不是假设新的文件创建。

download_video.py
import argparse
import json
import re
from pathlib import Path
from urllib.parse import parse_qs, urlparse

from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget
from yt_dlp.postprocessor.common import PostProcessor
from yt_dlp.utils import DownloadError, PostProcessingError


def watch_url(value):
    """Accept a video ID or a single YouTube video URL, never a playlist."""
    video_id = value
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", value):
        parsed = urlparse(value)
        parts = parsed.path.strip("/").split("/")
        host = (parsed.hostname or "").lower()
        if parsed.scheme not in {"http", "https"}:
            raise ValueError("Use a YouTube watch URL or 11-character video ID")
        if host in {"youtu.be", "www.youtu.be"}:
            video_id = parts[0]
        elif host in {"youtube.com", "www.youtube.com", "m.youtube.com"}:
            if parsed.path == "/watch":
                video_id = parse_qs(parsed.query).get("v", [""])[0]
            elif len(parts) == 2 and parts[0] in {"shorts", "live", "embed"}:
                video_id = parts[1]
            else:
                video_id = ""
        else:
            video_id = ""
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id):
        raise ValueError("Expected one YouTube video, not a channel or playlist")
    return "https://www.youtube.com/watch?v=" + video_id


class FinalFile(PostProcessor):
    def __init__(self):
        super().__init__()
        self.result = None

    def run(self, info):
        path = Path(info["filepath"]).resolve()
        if not path.is_file() or path.stat().st_size == 0:
            raise PostProcessingError("Final media file is missing or empty")
        self.result = {
            "status": "completed", "video_id": info["id"],
            "title": info.get("title"), "duration": info.get("duration"),
            "path": str(path), "bytes": path.stat().st_size,
        }
        return [], info


def download_video(source, output="downloads"):
    url = watch_url(source)
    folder = Path(output).resolve()
    folder.mkdir(parents=True, exist_ok=True)
    final_file = FinalFile()
    options = {
        "js_runtimes": {"deno": {}},
        "impersonate": ImpersonateTarget(),
        "concurrent_fragment_downloads": 1,
        "noplaylist": True,
        "format": "bv*[height<=1080]+ba/b[height<=1080]",
        "outtmpl": str(folder / "%(id)s.%(ext)s"),
        "download_archive": str(folder / "archive.txt"),
        "writeinfojson": True,
        "ignoreerrors": False,
        "retries": 3, "fragment_retries": 3, "socket_timeout": 30,
        "sleep_interval_requests": 1,
        "sleep_interval": 5, "max_sleep_interval": 10,
    }
    with YoutubeDL(options) as downloader:
        downloader.add_post_processor(final_file, when="after_move")
        downloader.extract_info(url, download=True)
    if final_file.result is None:
        return {"status": "skipped", "source": url,
                "reason": "No new file recorded; check the archive"}
    return {**final_file.result, "source": url}


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("source", help="YouTube video URL or ID")
    parser.add_argument("--output", default="downloads")
    args = parser.parse_args()
    try:
        result = download_video(args.source, args.output)
    except (DownloadError, ValueError, OSError) as error:
        raise SystemExit(f"Job failed: {error}") from error
    print(json.dumps(result, ensure_ascii=False, indent=2))
完整的脚本也可以从上面的下载链接中获取,它只拥有本地输出;在下一个应用程序阶段添加解码检查和上传记录。
运行一份工作
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

完成的记录包含可通源URL、视频ID、最终路径和比特大小。被打破的记录意味着没有新的最终文件的呼叫回归;将其与存档和现有存档相匹配,如果您需要证明文件仍然存在。仅此地,档案不检查用户是否随后删除或移动媒体。

捕获 extractor/download/post-processing 故障的 DownloadError, 拒绝输入的 ValueError 和 地方文件系统故障的 OSError。将这些类作为您的应用程序日志中的单独类。错误消息是有用的诊断,但它们的文本不是每个YouTube失败的稳定的结构化税率。

完整剧本:可重复的包下载进程

放下 download_batch.py 在 download_video.py 旁边。创建一个 UTF-8 urls.txt 与一个视频 URL 或 ID 每行。故意运行序列,因此一个过程拥有档案和输出目录。它写下完成、失败或失败的结果,每一次尝试输入和输出,当任何项目失败时,则不零。

download_batch.py
import argparse
import json
from datetime import datetime, timezone
from pathlib import Path

from yt_dlp.utils import DownloadError
from download_video import download_video


def run_batch(manifest, output):
    folder = Path(output).resolve()
    folder.mkdir(parents=True, exist_ok=True)
    sources = list(dict.fromkeys(
        line.strip()
        for line in Path(manifest).read_text(encoding="utf-8-sig").splitlines()
        if line.strip() and not line.lstrip().startswith("#")
    ))
    counts = {"completed": 0, "skipped": 0, "failed": 0}
    with (folder / "attempts.jsonl").open("a", encoding="utf-8") as log:
        for source in sources:
            try:
                result = download_video(source, folder)
            except (DownloadError, ValueError, OSError) as error:
                result = {"source": source, "status": "failed",
                          "error_type": type(error).__name__, "error": str(error)}
            result["recorded_at"] = datetime.now(timezone.utc).isoformat()
            log.write(json.dumps(result, ensure_ascii=False) + "\n")
            log.flush()
            counts[result["status"]] += 1
    return counts


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("manifest", help="UTF-8 file, one video URL or ID per line")
    parser.add_argument("--output", default="collection")
    args = parser.parse_args()
    counts = run_batch(args.manifest, args.output)
    print(json.dumps(counts, indent=2))
    raise SystemExit(1 if counts["failed"] else 0)
附件仅 attempts.jsonl 保持退出作为单独的尝试。 在一个显明内复制线被删除;下载档案处理完成 ID 经过运行。
运行或重复相同的行
python download_batch.py urls.txt --output collection

每次记录后流动,以便中断不会让每个结果都被打破到结束。图书馆记录其档案和您的应用程序写试图记录之间仍然有一小窗口。如果发生事故,下一轮可以报告失败。对于一个服务,将 filesystem/archive 与可持续的工作数据库相匹配,而不是声称这个文本文件示例是交易性的。

保持 attempts.jsonl 隐私:错误可能包括源和请求详细信息。 根据状态报告总数,检查失败的项目,并在解决共享环境问题后重新播放相同的显而易见。

生产:条,期限和存储

YouTubeDL 是同步的。运行它直接在一个无与伦比的网页交易员的区块,交易员的事件路径;即使一个线条下载不会使浏览器请求适合一个大下载的寿命。接受工作,坚持其来源/选项,让下载进程产生最终结果。

  • 在执行之前创建一个可持续的工作 ID. 存储视频 ID、输出政策、尝试号码和目的地。
  • 使用工作日志和有限的下载进程游泳池。 不要在竞争对手的工作中分享YouTubeDL例子。
  • 使用单独的过程,当您需要硬墙时钟期限或取消; socket_timeout限制个人网络操作,而不是整个工作。
  • 如果曝光用户输入超过 HTTP,接受支持的YouTube视频识别器,而不是任意的URL,输出路径,抽象论点或壳牌剪辑。
  • 记录本地文件准备和云上传完成单独;保持足够的状态,以恢复上传而不再下载。
  • 保持 FFmpeg、运行时间、 yt-dlp 和插件版本与您的部署。

一个简单的下载进程游泳池比无限 asyncio.gather 呼叫周围的许多下载更好。协调整个过程的整体工作;每个下载器的睡眠设置不调节整个服务。保持工作企图的单独退休预算,以便申请退休不会增加下载者的退休数量。

解决Python下载进程的问题

问题检查项
工作在CLI,失败在Python比较实际选项。 YoutubeDL 不自动加载您的 CLI 配置文件。
进展说结束,文件缺失使用 after_move 边界,检查后处理错误。
重复回归的源头阅读收藏档案;在更改输出政策时使用不同的档案。
下载进程挂得比socket_timeout更长一个工作可以完成许多 operations/retries. 需要时添加过程级的期限。
403 或机器人在服务器上检查更新 nightly 版,检查 Deno,减少竞争力,并在路线被拒绝时测试替换输出IP。
429 在 数据 / 转写工作停止受影响的IP,速度extraction/subtitle请求,并在代数据之间添加延迟 - 只有工作。

当产量属于云管道时

如果您想要拥有下载器,上述工作流将为您提供对文件、格式和处理的控制权。如果您的应用程序需要完成的存储媒体,FlashData提供跟踪的YouTube下载工作,机器人处理,代理路由和退出。您的申请提交源和输出设置,然后保留工作身份证和交付记录。