Explorar documentación
Guías
Guía de descargas con Linux como punto de partida. Incluye la versión nightly, formatos, subtítulos, conjuntos de datos y recopilaciones reanudables.
En esta página
Instalar la base de uso diario
Comienza con Nightly + Deno + FFmpeg. Utilice un entorno virtual del proyecto y habilite la personalización del navegador con --impersonate="". La configuración Linux a continuación instala las herramientas; las alternativas de macOS y Windows están en las carpetas.
Ubuntu / Debian ejemplo con Python 3.11+. Instalar las herramientas del sistema, crear un entorno virtual del proyecto, luego instalar el nocturno y sus extra.
sudo apt-get update
sudo apt-get install -y python3 python3-venv ffmpeg aria2 curl unzip
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
curl -fsSL https://deno.land/install.sh -o /tmp/install-deno.sh
sh /tmp/install-deno.sh
export PATH="$HOME/.deno/bin:$PATH"
deno --version
python -m yt_dlp --versionCon Homebrew instalado, uselo para Python, Deno, FFmpeg y aria2. Mantenga yt-dlp en el entorno del proyecto para que el comando de actualización nocturna sea el mismo que en Linux.
brew install python deno ffmpeg aria2
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
deno --version
python -m yt_dlp --versionInstalar Python 3.11+, Deno y los ejecutables FFmpeg, luego abrir un nuevo terminal. Utilice el intérprete del entorno directamente si PowerShell bloquea la activación. aria2 es opcional; instale separadamente si utiliza la receta de descarga externa.
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U --pre "yt-dlp[default,curl-cffi]"
deno --version
ffmpeg -version
.\.venv\Scripts\python.exe -m yt_dlp --version| Herencia | Lo que hace | Verifica |
|---|---|---|
| Python 3.11+ | El paquete Python y los ejemplos en esta serie. | python --version |
| Último yt-dlp nocturno + default,curl-cffi extras | Extractor de YouTube actual, que se ajusta al solvente EJS y al soporte de personalización del navegador. | python -m yt_dlp --version |
| FFmpeg y ffprobe | Múltiples flujos, convertir audio, cortar clips y inspeccionar los medios salvados. | ffmpeg -version / ffprobe -version |
| Deno 2.3+ (necesario en este flujo de trabajo) | Instalarlo en cada trabajador, no sólo su máquina de desarrollo. | deno --version |
Instalar los ejecutables también. [default] suministra los escritos EJS; Deno es separado. FFmpeg y ffprobe también debe estar en el PATH del trabajador.
deno --version
ffmpeg -version
ffprobe -version
python -m pip show yt-dlp yt-dlp-ejs curl-cffi
python -m yt_dlp --list-impersonate-targetspython -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose \
--simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw"La base de operaciones de FlashData incluye --impersonate=": permite a curl-cffi elegir una imprenta de un navegador disponible. Esto cambia la impresión de la solicitud; no proporciona cookies de login, soluciona los desafíos de JavaScript o cambia el IP de salida. Si esta opción acelera una ruta de trabajo o introduce errores, repita el mismo test de un vídeo sin él y mantiene la configuración de trabajo.
Verifique el lanzamiento antes de ponerlo en un trabajador
Obtenga ejecutables desde la página de lanzamiento del proyecto oficial, o instale el paquete Python desde su fuente de paquete publicado. Si descargas un binario independiente, compares su SHA-256 con el nombre de fil de la versión SHA2-256SUMS. Recordar el lanzamiento y el checksum con su imagen de trabajador para que pueda identificar exactamente lo que se llevó.
sha256sum yt-dlpshasum -a 256 yt-dlp_macosGet-FileHash -Algorithm SHA256 .\yt-dlp.exeUna comparación de los checksum es útil sólo cuando el valor esperado proviene de la liberación confiada, no el mismo espejo desconocido que el ejecutable. Si el software de seguridad flamena un archivo, investigue su fuente y informe antes de hacer una excepción. La disponibilidad de código abierto solo no es la prueba de que cada plugin binario o de terceros descargado es seguro.
Tratar los archivos de configuración compartida como código para revisar: opciones como --exec pueden lanzar comandos, y los plugins añaden código al proceso de descarga. Mantenerse cookies de navegador, credenciales de proxy y URLs firmados fuera de los ejemplos de configuración y informes de diagnóstico.
Descargar un video
Use un vídeo corto primero. Cita la URL, añade --no-playlist y nomme el archivo por ID de vídeo.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -P downloads \
-o "%(id)s.%(ext)s" --print after_move:filepath \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Sin un formato de sobrecord, yt-dlp elige sus flujos disponibles preferidos. Las fuentes de alta calidad a menudo tienen flujos de vídeo y audio separados, por lo que dos transferencias seguidas por una fusión FFmpeg son normales. Los archivos intermedios y un archivo .part pueden aparecer mientras el trabajo está en funcionamiento.
Elegir calidad y codecs
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-F "https://www.youtube.com/watch?v=jNQXAC9IVRw"Elegir una política, no un ID de formato copiado. Verificar la resolución, los codecos y las pistas separadas audio/video.
| Selector o opción | Significado | Cuando usarlo |
|---|---|---|
| Bv + B | Elige un solo flujo de vídeo y un solo flujo de audio; FFmpeg los combina. | Tiene que tener dos pistas y puede fusionarse localmente. |
| A/B | Tenga el selector A, y B si A no está disponible. | Define un fallback explícito en lugar de asumir que cada fuente tiene los mismos formatos. |
| [height<=1080] | Exclude los flujos de arriba 1080 píxeles altos. | Un fuerte límite superior es un requisito. |
| -S res:1080 | Preferir la resolución hasta 1080; puede seleccionar una mayor cuando no hay ninguna de las siguientes. | 1080p es una preferencia en lugar de un techo duro. |
| --merge-output-format mp4 | Seleccione el contenedor al combinar corrientes separadas. | Ya has seleccionado flujos compatibles. no transcoda codecs. |
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-f "bv*[height<=1080]+ba/b[height<=1080]" -P downloads \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Para un editor o grabación que requiera específicamente H.264 vídeo y AAC audio, filtrar esos codecos y fusionar en MP4. MP4 es un contenedor: un flujo en un contenedor MP4 puede todavía contener un codec que su aplicación no puede decodificar.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-f "bv[vcodec^=avc1][height<=1080]+ba[acodec^=mp4a]/b[vcodec^=avc1][acodec^=mp4a][height<=1080]" \
--merge-output-format mp4 -P downloads "https://www.youtube.com/watch?v=jNQXAC9IVRw"Remuxing repacas los flujos sin re-encodalos. Transcodificación cambia codecs y consume CPU mientras potencialmente cambia la calidad. Utilice --remux-video cuando los flujos ya se ajusten al contenedor objetivo; utilice una conversión deliberada FFmpeg cuando un decoder de flujo inferior requiere codecos diferentes.
Salva audio o MP3
Si su pipeline de transcripción acepta el codec de audio de fuente, descargue ese flujo directamente. Esto evita una conversión desnecessaria de pérdidas. MP3 es útil cuando un consumidor lo requiere específicamente; un alto MP3 bitrate no puede restaurar el detalle ya perdido en la fuente.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -P audio \
-o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -x \
--audio-format mp3 --audio-quality 0 -P audio -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Salva capciones y metadatos
Una colección útil necesita más que filenames. Mantenga los ID de vídeo, las URL de fuente, los títulos, las duraderas y las capciones disponibles para que pueda buscar la colección y rastrear un activo de vuelta a su fuente. Comenzar listando las pistas de la etiqueta; solicitar en no significa que cada video tenga una pista en inglés.
python -m yt_dlp --list-subs "https://www.youtube.com/watch?v=jNQXAC9IVRw"
python -m yt_dlp --skip-download --write-subs --write-auto-subs --sub-langs "en.*" \
--sub-format "vtt/best" -P captions -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist --write-info-json \
--write-thumbnail -P downloads -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"El .info.json es un metadato de operación detallado, no una respuesta de API pública limpia. Puede incluir URL de medios expirando y campos relacionados con la solicitud. Mantenga el recinto lateral completo con la colección, y exporta solo los campos que necesita su sistema de descenso. Si necesitas SRT en lugar de VTT, añade --convert-subs srt y asegúrese que FFmpeg está disponible.
Construir un elemento de la base de datos
Para una colección de entrenamiento, decida los medios y las fuentes de texto juntos. Un requisito común es el mejor vídeo y audio disponibles, combinado en MP4, con capciones timestampadas y metadatos de extracción conservados bajo el mismo ID de vídeo. Un techo de resolución útil para las previstas es generalmente el defecto equivocado para un conjunto de datos de calidad fuente.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-f "bestvideo+bestaudio/best" \
--merge-output-format mp4 --remux-video mp4 \
--write-info-json --write-subs --write-auto-subs \
--sub-langs "en" --sub-format "vtt/best" \
--sleep-subtitles 5 --concurrent-fragments 1 \
-P dataset -o "%(id)s/%(id)s.%(ext)s" \
--print after_move:filepath "https://www.youtube.com/watch?v=jNQXAC9IVRw"Comenzar con un lenguaje de nota exacto. En nuestro check en vivo, en.* seleccionados en, en-en y en-de; la tercera pista regresó 429 antes de que comenzara la descarga de medios. Un error de señal puede detener el elemento en esa etapa. Después de un colapso, retire sólo la pista necesaria, o dividir los medios y los trabajos de la etiqueta si su colección debe mantener el ingreso de los medios en movimiento.
El /best fallback permite un flujo combinado video/audio cuando las pistas separadas no están disponibles. Removemos ese fallback si su contrato de colección requiere fuentes separadas de bestvideo y bestaudio. MP4 no significa H.264: esta receta mantiene los codecos de fuente seleccionados. Utilice el selector estricto H.264/AAC anteriormente si su decoder de entrenamiento requiere esos codecs, o transcode como un paso separado, registrado.
dataset/VIDEO_ID/
VIDEO_ID.mp4
VIDEO_ID.info.json
VIDEO_ID.en.vtt| Requisitos | Decisión de recogida |
|---|---|
| La mayor calidad disponible de la fuente | Utilice bestvideo+bestaudio, mantiene codecos de fuente y verifica los flujos combinados con ffprobe. |
| Texto de tiempo | Mantenga los segmentos y el lenguaje VTT/SRT junto al ID de vídeo.El texto en su flanque descartará el tiempo necesario para la alineación de los clip. |
| Subtítulos faltantes | Recuerda el texto perdido explicitamente.Ruta el audio guardado a la etapa de transcripción si el texto es obligatorio. |
| Capciones para muchas lenguas | Cada pista adicional añade solicitudes y puede encontrar 429 independientemente de los medios. |
| Medios de resumen + entrega de texto | Utilice un archivo de conjunto de datos separado y un inventario con estados de medios, metadatos y etiquetas.Una entrada de archivo no demuestra que existen todas las páginas requeridas. |
No reutilizes un archivo creado por un antiguo medio que solo se ejecuta para esta nueva política: los videos archivados pueden ser eliminados antes de que se recogen sus capciones perdidas. O se ejecuta la política de conjunto de datos con su propio archivo o se planifica un pasaporte de reparación de inscripciones separado para los IDs que faltan en el texto. Almacenar capciones originales; si su modelo necesita texto transcriptado limpio, derive en un paso de procesamiento de versión.
Mejora la transmisión sin sobrecargar un IP
aria2c puede ayudar cuando una conexión única sube un enlace no fiable o de alta latencia. No puede reparar una solicitud de jugador rechazada o un IP de salida marcado. En primer lugar, hacer que el descargador nativo funcione en una fuente; luego comparar el tiempo de transferencia y los errores con un pequeño número de conexiones aria2.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
--downloader aria2c --downloader "dash,m3u8:native" \
--downloader-args "aria2c:-x 2 -s 2 -j 1" \
--concurrent-fragments 1 \
-P downloads -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"| Control | Lo que limita |
|---|---|
| aria2c -x 2 | Conectar a un servidor para una descarga. |
| aria2c -s 2 | Se solicitan divisas para un archivo; la división también depende del tamaño del archivo y el soporte del servidor. |
| aria2c -j 1 | Los objetos concurrentes dentro de la invocación aria2, no otros trabajadores yt-dlp. |
| --concurrent-fragments 1 | El fragmento se descarga dentro del nativo DASH/HLS descargador. |
| Tu trabajo queue | Los videos activos en total comparte el mismo IP de salida de host o proxy. |
curl-cffi la impersonización pertenece a las propias solicitudes de yt-dlp; no configura la imprenta de la aria2 TLS. Si las descargas nativas funcionan pero aria2 recibe 403, vuelve a la nativa antes de cambiar las configuraciones de extractor no relacionadas. Mantenga la extracción y la transferencia externa en la misma sesión de proxy.
En el funcionamiento de FlashData, aumentar la concurrencia demasiado agresivamente puede hacer que una ruta de trabajo comience a regresar 403 de inmediato. Si esto sucede, detenga los otros trabajos, vuelve a un trabajador y una conexión, luego retesta. No compensa agregando más aria2 divisións o retirando el mismo flujo negado en paralelo. Si ese IP permanece rechazado a baja carga, utilice el flujo de trabajo de reemplazo de IP 403.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
--downloader native --concurrent-fragments 1 --limit-rate 2M \
--sleep-requests 2 --sleep-interval 5 --max-sleep-interval 10 \
-P diagnostics "https://www.youtube.com/watch?v=jNQXAC9IVRw"Preparar una colección
Para un pequeño conjunto conocido, crea un UTF-8 urls.txt con una URL de horario por línea. Para una lista de reproducción de YouTube, primero enumera sus IDs en un manifiesto. La extracción plana inspecta la lista de reproducción sin hacer una extracción completa para cada vídeo; es útil para la revisión de alcance, pero sus entradas pueden faltar la duración, los formatos y los detalles de disponibilidad.
python -m yt_dlp --flat-playlist --print "https://www.youtube.com/watch?v=%(id)s" \
"https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID" > urls.txtPara probar una colección, seleccione algunas entradas de la lista de reproducción con --playlist-items 1: 5. La tabla /videos de un canal es un punto de partida más claro para los videos cargados que una página de inicio ambigua del canal. No trate el pedido de playlist como identidad: los artículos pueden ser insertados, reordenados o eliminados.
| Filter | Uso | Consejos |
|---|---|---|
| --playlist-items 1:5 | Los cinco primeros enlaces de la lista actual. | Utilidad para un pequeño ensayo, no un punto de control duradero. |
| --dateafter 20260101 | Mantenga las entradas datadas en o después de enero 1, 2026. | La filtración de fecha puede requerir la extracción por vídeo. |
| --match-filters "!is_live & duration <= 1800" | Require un elemento no vivo con una duración conocida en el máximo 30 minutos. | Las entradas con una duración desconocida no se ajustan a este filtro estricto. |
| --download-archive archive.txt | Descargar los ID de fuente ya registrados por descargas anteriores. | Trabajando en diferentes títulos y posiciones de playlist. |
Recuperar una colección de forma segura
Salva lo siguiente como yt-dlp-work.conf en tu carpeta de colección, junto a urls.txt. Define la política de producción una vez, da a la colección su propio archivo y limita las retrasas. Mantener los archivos de salida y este archivo juntos: un archivo registra el éxito por el extractor y la identificación, no por el número de verificación o la ubicación del archivo actual.
# YouTube worker baseline
--js-runtimes deno
--impersonate=""
--concurrent-fragments 1
# Output policy
--no-playlist
-f "bv*[height<=1080]+ba/b[height<=1080]"
-P downloads
-o "%(channel_id)s/%(id)s.%(ext)s"
--write-info-json
# Resume and remember completed media
--continue
--download-archive archive.txt
--no-abort-on-error
# Bound each attempt and spread out work
--retries 5
--fragment-retries 5
--socket-timeout 30
--sleep-requests 1
--sleep-interval 5
--max-sleep-interval 10
# Append paths only after the final move
--print-to-file after_move:filepath completed-paths.txtpython -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf --batch-file urls.txtReunir el mismo mando después de una interrupción. Los ID completos se descuidan, y las transferencias parciales recurrentes continúan donde se apoyan. Los fallos de extracción se pueden revisar en la siguiente ronda. Los archivos de parte .default son útiles; no los eliminen como una etapa de retiro rutinaria.
--no-abort-on-error sigue pasando las entradas inaccesibles, pero un curso todavía puede salir no cero y los errores post-procesamiento necesitan atención. Evite agregar --ignore-errors simplemente para obtener un trabajo verde: puede tratar fallos post-procesamiento como descargas exitosas. Revise el log y las salida completadas antes de declarar la colección completa.
Verificar los archivos terminados
El archivo completed-paths.txt es un inventario de inicio útil. Teste la salida final real en lugar de un solo streaming de vídeo temporal. ffprobe lee los contenedores y los metadatos de flujo; un paso de decodificación separado capta problemas que solo un título leible perderá.
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height -of json "downloads/CHANNEL_ID/VIDEO_ID.mp4"ffmpeg -v error -i "downloads/CHANNEL_ID/VIDEO_ID.mp4" -f null -| Encontrar | Qué hacer |
|---|---|
| Sólo queda un .part o un archivo de flujo separado | Inspeccione el error transfer/merge y resume el trabajo original; no etiquete el archivo intermedio completo. |
| Videojuego sin sonido | Inspecciona el formato seleccionado y ffprobe flujos. un formato de vídeo solo necesita una selección de audio y fusión. |
| MP4 no se abrirá en su editor | Inspeccionan los codecos, no sólo la extensión; seleccione flujos compatibles o transcodes explicitamente. |
| Archivo de archivos pero no archivo local | Verificar si el archivo fue moved/deleted. Reconcilia el inventario antes de cambiar las entradas de archivo. |
9 Mover un comando probado en un trabajo programado
Ejecuta el comando completo con éxito por mano antes de planificarlo. Un calendario normalmente comienza con un PATH y directorio de trabajo diferente. Dale el camino completo de Python del entorno virtual, el camino de configuración completo y un directorio de trabajo explícito; también haga FFmpeg y el tiempo de trabajo de JavaScript disponibles para ese proceso.
- Utilice un solo trabajador para un collection/archive. No dejes que el curso de ayer sobrepase el curso de hoy contra las mismas fuentes.
- En Linux, use una entrada timer/service o cron con un directorio de trabajo y un bloqueo como el grupo. Mantener los logs fuera de la pasta de medios y girarlos.
- En macOS, use la lanzada con pistas de dirección de trabajo y de ejecución absolutas.
- En Windows Task Scheduler, configura el Programa para el entorno python.exe, Argumentos para -m yt_dlp y las opciones de configuración y de batch, y Comienza a la carpeta de colección.
- Record start/end tiempo, versión ejecutable, manifiesto de fuente, estado de salida y completed/failed cuentan. una salida de batch no zero no implica que cada elemento se haya fallado.
- Mantenga los archivos de cookies y las credenciales de destino fuera del repositorio de configuración compartida.Dale un trabajo sólo las credenciales que necesita.
Las opciones de sueño en el config actúan dentro de un proceso. Diez trabajadores que utilizan las mismas configuraciones todavía producen diez flujos de solicitudes. El aumento de --concurrent-fragments modifica la concorrencia de fragmentos dentro de un descargo, no el número de videos en su cuenca de trabajo.
Elegir el guía de error correcto
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --versionCuando se rompe una fuente de trabajo anterior, actualice a la última noche primero, incluyendo los extras de ajuste. Para el uso binario de manera independiente yt-dlp --update-to por la noche; -U solo permanece en el canal actual. Después de cada actualización, haga un pequeño canario, luego reconstruye a los trabajadores y graba la revisión para que la flota no mezcla silenciosamente las publicaciones.
| Síntoma | Empieza aquí |
|---|---|
Requested format is not available | Listar los formatos y inspeccionar sus filtros estrictos antes de cambiar las retrasas. |
ffmpeg not found / ffprobe and ffmpeg not found | Verifique el PATH desde la cuenta del trabajador o del calendario real. |
| JavaScript desafío / falta de tiempo de trabajo alerta | Verifique la detección del tiempo de trabajo y el paquete EJS que se ajusta. |
| HTTP 403 durante el traslado | Identificar el anfitrión y la etapa rechazados; extración separada de la transferencia de medios. |
| HTTP 429 | Pausa la IP afectada, permite un cooldown y una frecuencia de solicitud extraction/caption más baja. |
Sign in to confirm you’re not a bot | Pase el pacto y diagnostica una fuente, sesión y red. |
Cuando la producción pertenece a un tubo de nube
Si quieres poseer el descargador, los flujos de trabajo anteriormente te dan control sobre los archivos, formatos y procesamiento. Si su aplicación necesita medios completos entregados al almacenamiento, FlashData proporciona trabajos de descarga de YouTube rastreados, manejo de botes, rotación de proxy y retrasos. Su aplicación envía las configuraciones de fuente y salida, luego mantiene el ID de trabajo y el registro de entrega.
Materiales de referencia
La referencia de la opción de upstream es la fuente de verdad para su versión instalada. Utilice estas secciones cuando cambia una política de recogida o actualiza una imagen de un trabajador.