본문으로 건너뛰기
KO
API 키 받기
문서 둘러보기

가이드

yt-dlp Python API

다운로드, 메타데이터, AI 데이터셋 및 중단 후 재개 가능한 작업을 위한 실행 가능한 Python 예제입니다.

이 페이지의 내용

Python 도서관 설치

Python 3.11+ 환경에서
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"

또한 Deno, FFmpeg 및 ffprobe를 설치합니다. 이 예제는 Linux, macOS 또는 Windows에서 로컬로 실행되며 API 키가 필요하지 않습니다.

첫 번째 비디오를 다운로드

1 비디오 다운로드
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까지 지역 미디어를 작성하고 별도의 흐름을 결합 할 수 있습니다.출력 컨테이너는 선택한 출처 형식에 따라 달라집니다.

CLI 설정은 유산되지 않습니다. Python 옵션에서 Deno, 인식 및 패킹을 설정하십시오, 심지어 터미널 명령이 이미 사용하는 경우에도.

다운로드()는 URL 목록을 가져와 상태 코드를 반환합니다. extract_info(URL, 다운로드=진짜) 추출 정보와 다운로드를 수행하는 것을 반환합니다. 컨텍스트 매니저를 사용하여 예제를 깨끗하게 닫고 독립적인 작업을위한 신선한 예제를 만들기보다는 끈을 통해 변동 상태를 공유합니다.

미디어 없이 메타데이터 읽기

작은 메타 데이터 기록을 수출
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))
다운로드=False는 여전히 네트워크 요청을 실행합니다. sanitize_info 결과를 JSON- 호환합니다; 그것은 비밀을 작성하거나 결과를 이러한 필드로 줄이지 않습니다.

추출 된 필드는 부재 또는 0이 될 수 있습니다. 선택적인 메타 데이터를 사용 하 여, 그리고 모든 출처가 기간, 채널 ID 또는 전체 형식 목록을 가지고 있다고 가정 하지 마십시오. 평평한 플레이리스트 목록은 완전히 해결된 비디오와도 다릅니다. 대중의 응답을 위해, 당신이 표시하려는 필드만 프로젝트합니다.

각 소스에 대한 동일한 다운로드 추출을 즉시 따르는 메타 데이터 추출을 피하십시오, 응용 프로그램이 추가 계획 단계를 필요로하지 않는 한. 그것은 출처 요청을 복제합니다. 지속 가능한 작업이 필요한 경우, 출처 ID 및 출력 정책을 저장하십시오; 메타 데이터에서 서명 된 미디어 URL은 원본 출처의 지속적인 대체가 아닙니다.

Python 옵션 참조

의논하기Python 옵션세부 사항
출력 디렉토리 및 파일 이름"outtmpl": "downloads/%(id)s.%(ext)s"소스 ID 및 역동적 확장 기능을 유지합니다.
하드 1080p 지붕"format": "bv*[height<=1080]+ba/b[height<=1080]"원본 코덱을 허용하고 결합이 없으면 실패합니다.
메타데이터 측면"writeinfojson": True미디어 외에 완전한 추출 메타 데이터를 삽입합니다.
완성된 ID 체크포인트"download_archive": "archive.txt"1개의 수출 정책에 따라 하나의 아카이브; 체크스모 인벤토리가 아닙니다.
엄격한 실수"ignoreerrors": False소리꾼이 실패를 기록하는 대신 처리 후 문제를 성공으로 처리하십시오.
던트 타임"js_runtimes": {"deno": {}}작업자에 Deno를 설치하고 PATH에서 바이너리 표시를 만듭니다.
브라우저 인식"impersonate": ImpersonateTarget()--impersonate="; 목표 클래스를 가져오고 curl-cffi를 설치합니다.
기존 쿠키 파일"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 컬렉션 대신 훈련 데이터 세트입니다.이 컬렉션은 bestvideo 및 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] 설치가 필요합니다. yt-dlp의 API에서 리무커의 선호 형식 매개 변수가 그 방식으로 표시됩니다.

ImpersonateTarget()은 --impersonate=""와 일치하는 모든 사용 가능한 브라우저 목표를 선택합니다. CLI 시나크에서 복사된 빈 줄이 아닌 개체를 통과하십시오. curl-cffi이 Python 환경에 설치되어야합니다. Deno는 여전히 JavaScript 솔루션을 실행합니다; 인식은 그것을 대체하지 않습니다.

MP4는 출력 컨테이너; 선택한 비디오는 여전히 AV1 또는 VP9가 될 수 있습니다. 훈련 디코더가 H.264/AAC를 필요로하는 경우, 합병하거나 별도의 FFmpeg 트랜스코드를 기록하기 전에 명시적인 코덱 정책을 적용하십시오. 사용 가능한 서브 타이틀은 발언에서 생성되지 않고 추출됩니다.

미디어가 끝난 후데이터베이스 기록이 필요로 하는 것
MP4와 ffprobe의 마지막을 확인하십시오Video/audio 코덱, 기간, 차원, 파일 경로 및 바이트 계산.
옆에 있는 옆에 있는 옆에 있는 옆에 있는언어, supplied/automatic 트랙, 시간표 및 파일이 실제로 존재하는지 여부.
- 접근할 수 있는 캡션이 없습니다.미디어를 유지하고 텍스트가 사라지지 않음을 표시; 필요한 경우 트랜스피어 단계로 오디오를 보내십시오.
캡션 히트 429Retry caption 리트리얼 후 IP 냉각 하위 제목 패킹; 완료 된 미디어를 다시 다운로드 하지 마십시오.

패치에 대해서는 이 데이터 세트 정책에 대한 별도의 아카이브를 사용하고 필요한 측면 팩에 대한 기록을 유지합니다. 이전 1080p 또는 미디어만 아카이브를 다시 사용하지 마십시오 : 새로 요구된 캡처가 수집되기 전에 비디오를 벗어날 수 있습니다. after_move를 사용하여 미디어 준비를 위해, 다음 전체 데이터 세트 항목을 게시하기 전에 텍스트 및 메타 데이터를 확인합니다.

마지막 파일이 언제 준비되었는지 알아보세요.

진행 호크 보고 상태=완료는 전송이 완료된 것을 의미합니다. FFmpeg 여전히 비디오와 오디오를 결합하거나 오디오 파일을 변환하거나 출력을 이동해야 할 수도 있습니다. 100%에 도달하는 비디오 스트림은 완성 이벤트가 아닙니다 당신의 응용 프로그램이 게시해야합니다.

의 의당신이 아는 것응용국가
다운로드일부 미디어 바이트가 도착합니다.달리기
⁇ 스테이블 : 완료이 전송이 끝났습니다; 처리은 여전히 계속 될 수 있습니다.처리
after_move 포스트 프로세서파일은 구성된 포스트 프로세서 및 최종 움직임을 통과했습니다.현지 파일 준비
업로드 및 통합 검사목적지는 대상과 기록된 확인을 가지고 있습니다.배달

아래의 완전한 예제는 after_move에서 사용자 지정된 PostProcessor를 기록하고 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를 넣으십시오. 라인 당 하나의 비디오 URL 또는 ID를 가진 UTF-8 urls.txt를 만듭니다. 이것은 의도적으로 순서대로 실행되므로 하나의 프로세스는 아카이브 및 출력 디렉토리를 소유합니다. 그것은 모든 시도 입력 및 출력에 대한 완료, 실패 또는 실패 결과를 작성합니다 nzero 어떤 항목이 실패 할 때.

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은 동기화되어 있습니다. 그것을 직접 실행하는 것은 거래자의 이벤트 로프를 동기화하는 웹 거래자 블록 내부; 심지어 스트립 오프로드는 브라우저 요청에 대 한 큰 다운로드에 적합한 수명으로 만들지 않습니다. 일자리를 받아들이고, 그것을 계속하라 source/options, 그리고 노동자가 최종 결과를 생성하게 하라.

  • 실행 전에 지속 가능한 작업 ID를 만들기.Canonic 비디오 ID, 출력 정책, 시도 번호 및 목적지를 저장합니다.
  • 직업별 작업 디렉토리와 제한된 노동자 수영장을 사용하십시오.YouTubeDL 사례를 동일한 직업에 공유하지 마십시오.
  • 단단한 벽 시계 기간 또는 취소가 필요한 경우 별도의 프로세스를 사용하십시오; socket_timeout 전체 작업이 아닌 개별 네트워크 작업을 제한합니다.
  • HTTP 이상의 사용자 입력을 표시하는 경우, 자발적인 URL, 출력 경로, 추출기 논쟁 또는 쉘 스니프트가 아닌 지원되는 YouTube 비디오 ID를 수락합니다.
  • 지역 파일 준비 및 클라우드 업로드 완료를 별도로 기록; 다시 다운로드하지 않고 업로드를 철회하기에 충분한 상태를 유지합니다.
  • FFmpeg, 실행 시간, yt-dlp 및 플러그인 버전을 배포와 함께 유지하십시오. 작업자 이미지를 대체하기 전에 알려진 작은 작업 부하를 연습하십시오.

간단한 노동자 수영장은 무제한 asyncio.gather 전화를 통해 많은 다운로드보다 더 나은 출발점입니다. 프로세스 전체 작업을 조정; 각 다운로드자의 수면 설정을 조정하지 않습니다 전체 서비스. 취업 시도에 대한 별도의 은퇴 예산을 유지하므로 신청 은퇴는 다운로드자의 자신의 은퇴 계산을 늘리지 않습니다.

Python 노동자를 해결하기

의 의확인
CLI에서 작업, Python에서 실패실제 옵션을 비교합니다.YouTubeDL은 CLI 구성 파일을 자동으로 업로드하지 않습니다.
진행은 끝났다고 말하고 파일이 사라졌다.after_move 경계를 사용하고 처리 후 오류를 검사합니다.
반복된 출처가 돌아오는 망설임수집 아카이브를 읽고, 출력 정책을 변경할 때 다른 아카이브를 사용합니다.
노동자는 socket_timeout보다 더 오래 묶여있다.일자리가 많은 일을 할 수 있습니다 operations/retries. 필요하다면 프로세스 수준의 기간을 추가합니다.
403 또는 서버에 보트 체크밤에 업데이트, Deno를 확인하고, 경쟁을 줄이고, 경로가 거부되면 교체 출구 IP를 테스트합니다.
429 메타 데이터 / 트랜스크립트 작업영향을받는 IP, 속도 extraction/subtitle 요청을 중단하고 메타 데이터-직업만 사이에 지연을 추가합니다.

생산량이 클라우드 파이프라인에 속하는 경우

다운로드기를 소유하고 싶다면 위의 작업 흐름은 파일, 형식 및 처리에 대한 통제를 제공합니다. 응용 프로그램이 저장에 제공되는 완성 된 미디어가 필요하다면 FlashData는 추적 된 YouTube 다운로드 작업, 보트 처리, 프로키 라우팅 및 리트리지를 제공합니다. 귀하의 응용 프로그램은 출처 및 출력 설정을 제출하고 직업 ID 및 배달 기록을 유지합니다.