Explorar documentação
Guias
Exemplos Python executáveis para downloads, metadados, conjuntos de dados para IA e tarefas que podem ser retomadas.
Nesta página
Instalar a biblioteca do Python
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"Instale também Deno, FFmpeg e ffprobe. Estes exemplos funcionam localmente no Linux, macOS ou Windows e não precisam de chave API.
Descarregue seu primeiro vídeo
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"])As configurações do CLI não são herdadas. Configura o Deno, a personificação e a pacing nas opções de Python, mesmo quando o seu comando terminal já os usa.
download() toma uma lista de URLs e retorna um código de estado. extract_info(url, download=True) retorna informações de extração, bem como a execução da descarga. Use um gerente de contexto para fechar a instância limpo e criar uma nova instância para um trabalho independente em vez de compartilhar estado mutabile em cadeias.
Leia os metadados sem mídia
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))
Os campos extraídos podem ser ausentes ou nulos. Use get() para metadados opcionais, e não suponha que cada fonte tenha uma duração, ID de canal ou lista completa de formato. Uma lista de playlist plana também é diferente de um vídeo totalmente resolvido. Para uma resposta pública, projetar apenas os campos que pretende expor.
Evite uma extração de metadados imediatamente seguida por uma extração de download idêntica para cada fonte, a menos que o seu aplicativo necessite do passo de planejamento adicional. duplicou as solicitações de origem. Se você precisa de um trabalho duradouro, armazenar o ID da fonte e a política de saída; um URL de mídia assinado dos metadados não é uma substituição duradoura para a fonte original.
Python Opção de Referência
| Tarefa | Opções Python | Detalhes |
|---|---|---|
| Direção de saída e filename | "outtmpl": "downloads/%(id)s.%(ext)s" | Mantenha o ID de fonte e a extensão dinâmica. |
| Cadeira 1080p Cadeira | "format": "bv*[height<=1080]+ba/b[height<=1080]" | Permite codecs de origem e falha se nenhum corresponder ao limite. |
| Metadatos de lado | "writeinfojson": True | A meta-data de extração completa é encoberta ao lado dos meios de comunicação. |
| Completos de ID Checkpoint | "download_archive": "archive.txt" | Um arquivo por política de saída; não um inventário de checksum. |
| Erros estritos | "ignoreerrors": False | Deixe o chamador registrar falhas em vez de tratar problemas pós-processamento como sucesso. |
| Dê tempo de corrida | "js_runtimes": {"deno": {}} | Instale o Deno no trabalhador e faça seu binário visível no PATH. |
| Impressão do navegador | "impersonate": ImpersonateTarget() | Python equivalente de --impersonate=""; importar a classe alvo e instalar curl-cffi. |
| arquivo de cookies existente | "cookiefile": "private/youtube-cookies.txt" | Use credenciais de sessão privadas apenas quando necessário para o acesso. |
audio_options = {
"format": "ba",
"outtmpl": "audio/%(id)s.%(ext)s",
"postprocessors": [{
"key": "FFmpegExtractAudio",
"preferredcodec": "mp3",
"preferredquality": "192",
}],
}Vídeo + áudio + capções para um conjunto de dados AI
Use esta política de saída quando o objetivo é um conjunto de dados de treinamento em vez da coleção do exemplo do trabalhador 1080p. requer bestvideo e bestaudio, permite que FFmpeg os fusione em MP4, e salva capções e metadados disponíveis em Inglês ao lado dos meios de comunicação.
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])
ImpersonateTarget() seleciona qualquer alvo do navegador disponível, correspondendo a --impersonate="". Passar o objeto, não uma fila vazia copiada da sintaxe CLI. curl-cffi deve ser instalado neste ambiente de Python. O Deno ainda executa o JavaScript resolvendo; a impersonização não o substitui.
MP4 é o contêiner de saída; o vídeo selecionado pode ainda ser AV1 ou VP9. Se o seu decoder de treinamento requer H.264/AAC, aplique uma política de codec explícita antes de fusão ou gravação de um transcódigo FFmpeg separado. Os subtitulos disponíveis são retirados, não gerados do discurso.
| Depois que os meios de comunicação acabam | O que o registro de dados precisa |
|---|---|
| Veja o final MP4 com ffprobe | Video/audio codecs, duração, dimensões, caminho de arquivo e conte byte. |
| Verificar as cargas de lado separadamente | Língua, supplied/automatic rastreamento, timestamps e se o arquivo realmente existe. |
| Não há capturas de correspondência disponíveis | Mantenha os meios e marque texto desaparecido; envie o áudio para a sua etapa de transcrição se necessário. |
| Apresentação de Captions 429 | Retry caption retrieval após um IP cooldown com subtitle pacing; não redibaixar os meios completados. |
Para um pacote, use um arquivo separado para esta política de conjunto de dados e mantenha um inventário para os painéis de lado necessários. Não use um arquivo anterior 1080p ou apenas de mídia: ele pode desligar vídeos antes que suas capturas recém-necessárias sejam coletadas. Use after_move para a preparação dos meios, então valida o texto e os metadados antes de publicar um item de conjunto de dados completo.
Saiba quando o arquivo final está pronto
Um status de relatório de progresso = finito significa uma transferência concluída. FFmpeg ainda pode precisar de combinar vídeo e áudio, converter um arquivo de áudio ou mover a saída. Um vídeo-somente streaming alcançando 100% não é o evento de conclusão que sua aplicação deve publicar.
| Estágio | O que você sabe | Estado de aplicação |
|---|---|---|
| Descarregar | Alguns bytes de mídia estão chegando. | Correr |
| Transferência de Cachoeira: Finito | Esta transferência terminou; o processamento ainda pode ser seguido. | Processamento |
| after_move Pós-processador | O arquivo passou a configuração de post-processamento e movimento final. | Arquivo local pronto |
| Avaliação e verificação de integridade | Seu destino tem o objeto e verificação registrada. | entregue |
O exemplo completo abaixo registra um PostProcessor personalizado em after_move e lê info["filepath"] lá. Verifica se o arquivo existe e não é exato. Isso evita a adivinhação da extensão final com prepare_filename(), que pode referir-se a um nome pré-conversão.
Escritório completo: trabalhadores de vídeo único
Salve isso como download_video.py. Ele aceita um ID de vídeo ou watch/Shorts/live/embed URL e rejeita a entrada playlist/channel. Cada convocação usa uma instância do YoutubeDL, retrases de downloader limitadas e um arquivo local de coleção. Um retorno de fonte repetido completado foi esquecido em vez de pretender que um novo arquivo foi criado.
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 downloadsO registro concluído contém o URL canônico da fonte, ID de vídeo, caminho final e tamanho de byte. Um registro esquecido significa que não há um novo arquivo final de chamada; reconcilia-o contra o arquivo e o inventário existente se você precisar de prova que o arquivo ainda está presente. O arquivo não verifica se um usuário posteriormente excluiu ou mudou os meios de comunicação.
Catch DownloadError for extractor/download/post-processing errores, ValueError for rejeitado input e OSError for local file system errores. Tratar essas classes como classes distintas em seus logs de aplicativos. Mensagens de erro são diagnósticos úteis, mas seu texto não é uma taxonomia estruturada estável de cada falha do YouTube.
Título: O trabalhador de batch recém-superado
E, em seguida, a download_batch.py é a download_video.py. Crie um UTF-8 urls.txt com um URL de vídeo ou ID por linha. Isto intencionalmente funciona seqüentemente, então um processo é proprietário do arquivo e diretório de saída. Escreve um resultado concluído, esquecido ou falhado para cada entrada e saída tentada não zero quando qualquer item falhou.
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)
python download_batch.py urls.txt --output collectionFlush após cada registro para que uma interrupção não deixe todos os resultados bufferados até o fim. Ainda há uma pequena janela entre a biblioteca que registra seu arquivo e o seu aplicativo que escreve um registro de tentativa. Se um acidente colidir lá, a próxima corrida pode relatar esquecida. Para um serviço, reconciliar o filesystem/archive com uma base de dados de trabalho duradoura em vez de reivindicar que este exemplo de arquivo de texto é transaccional.
Mantenha attempts.jsonl privado: erros podem incluir detalhes de fonte e solicitação. relatar totais por estado, verificar os itens falhados e reproduzir o mesmo manifesto após resolver um problema de ambiente compartilhado. Não adicione cada ID falhado ao arquivo de sucesso.
Produção: cobre, prazos e armazenamento
O Youtube é sincronizado. Jogando-o diretamente dentro de um assínculo de web handler blocos que o evento de trader loop; mesmo um thread offload não faz um navegador solicita uma vida útil apropriada para um grande download. Aceite o trabalho, persiste seu source/options e deixe que um trabalhador produza um resultado final.
- Crie um ID de trabalho duradouro antes da execução. armazenar o ID de vídeo canônico, política de saída, número de tentativa e destino.
- Use diretórios de trabalho por trabalho e uma piscina de trabalhadores limitada. Não compartilhe um exemplo YoutubeDL em empregos concorrentes.
- Use um processo separado quando você precisa de um prazo de duração ou cancelamento; socket_timeout limita as operações de rede individuais, não o trabalho inteiro.
- Se expor a entrada do usuário acima de HTTP, aceite identificadores de vídeo do YouTube suportados em vez de URLs arbitrários, caminhos de saída, argumentos de extractor ou snippets de shell.
- Recordar a preparação de arquivo local e a conclusão de upload em nuvem separadamente; manter o estado suficiente para retomar uma upload sem baixar novamente.
- Mantenha as versões FFmpeg, yt-dlp e [Plugin] com o seu desempenho. Exerce uma pequena carga de trabalho conhecida antes de substituir uma imagem de trabalhadores.
Uma piscina de trabalhadores simples é um ponto de partida melhor do que asyncio.gather não-limited chamadas em torno de muitas descargas. Coordenar o trabalho total em todos os processos; as configurações de sono de cada downloader não regulam o serviço inteiro. Manter um orçamento de retorno separado para tentativas de trabalho para que as retras de aplicação não multipliquem a conta de retorno do downloadador.
Resolver o trabalho do Python
| Problema | verificação |
|---|---|
| Trabalhos no CLI, falhar em Python | Compare as opções reais. YoutubeDL não carrega automaticamente o seu arquivo de configuração CLI. |
| O progresso diz finito, o arquivo está faltando | Use o limite after_move e inspeccione erros pós-processamento. |
| Repetido de origem retorno esquecido | Leia o arquivo de coleção; use um arquivo diferente ao alterar as políticas de saída. |
| O trabalhador pendurado mais do que socket_timeout | Um trabalho pode executar muitos operations/retries. Adicione um prazo de nível de processo se necessário. |
| 403 ou bot verifica no servidor | Atualize à noite, verifique o Deno, reduza a concorrência e teste um IP de saída de substituição quando a rota permanece rejeitada. |
| 429 em metadados / transcript trabalhos | Pausa o IP afetado, ritmo extraction/subtitle pedidos e adicione atrasos entre metadados-só trabalhos. |
Quando a produção pertence a um tubo de nuvem
Se você quiser possuir o download, os fluxos de trabalho acima lhe dão controle sobre arquivos, formatos e processamento. Se o seu aplicativo precisa de mídia concluída entregue para armazenamento, o FlashData fornece empregos de download do YouTube rastreados, manutenção de bot, roteamento de proxy e retras. Sua aplicação apresenta as configurações de fonte e de saída, e depois mantém o ID de trabalho e o registro de entrega.