Install and Usage of yt-dlp

omicx.cc
Software, NAS
Page content

yt-dlp is a youtube-dl fork and able to download videos and audios from many streaming platforms, such as YouTube.

This blog describes installation in Debian bullseye and some common usage examples.

yt-dlp logo

1. Installaation yt-dlp in Debian bullseye

Before start installation, be sure to add bullseys-backports repository in/etc/apt/sources.list file:

deb https://deb.debian.org/debian bullseye-backports main contrib non-free

$ sudo apt update
$ sudo apt -t bullseye-backports install yt-dlp

Current version is: 2022.08.19.

It depends python3, and also install python3-brotli, python3-certifi, python3-mutagen, python3-pycryptodome and python3-websockets.

And these packages are recommended, especially ffmpeg, which is very useful to convert media file formats:

$ apt install aria2 wget curl ca-certificates ffmpeg python3-pyxattr rtmpdump libfribidi-bin mpv

More installation options please see yt-dlp documentation.

2. Using yt-dlp in command line

  • View the available formats and resolutions of a video:
$ yt-dlp --list-formats https://www.youtube.com/watch?v=r3eaGCk2Acs

The output:

[youtube] r3eaGCk2Acs: Downloading webpage
[youtube] r3eaGCk2Acs: Downloading android player API JSON
[info] Available formats for r3eaGCk2Acs:
ID  EXT   RESOLUTION FPS CH │   FILESIZE   TBR PROTO │ VCODEC        VBR ACODEC      ABR ASR MORE INFO
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
sb2 mhtml 48x27        1    │                  mhtml │ images                                storyboard
sb1 mhtml 80x45        1    │                  mhtml │ images                                storyboard
sb0 mhtml 160x90       1    │                  mhtml │ images                                storyboard
139 m4a   audio only      2 │  831.13KiB   48k https │ audio only        mp4a.40.5   48k 22k low, m4a_dash
249 webm  audio only      2 │  867.37KiB   50k https │ audio only        opus        50k 48k low, webm_dash
250 webm  audio only      2 │    1.12MiB   66k https │ audio only        opus        66k 48k low, webm_dash
140 m4a   audio only      2 │    2.16MiB  127k https │ audio only        mp4a.40.2  127k 44k medium, m4a_dash
251 webm  audio only      2 │    2.24MiB  132k https │ audio only        opus       132k 48k medium, webm_dash
17  3gp   176x144     12  1 │    1.32MiB   77k https │ mp4v.20.3     77k mp4a.40.2    0k 22k 144p
160 mp4   256x144     24    │    1.49MiB   88k https │ avc1.4d400c   88k video only          144p, mp4_dash
278 webm  256x144     24    │    1.57MiB   92k https │ vp9           92k video only          144p, webm_dash
133 mp4   426x240     24    │    3.42MiB  201k https │ avc1.4d4015  201k video only          240p, mp4_dash
242 webm  426x240     24    │    3.35MiB  197k https │ vp9          197k video only          240p, webm_dash
134 mp4   640x360     24    │    7.59MiB  446k https │ avc1.4d401e  446k video only          360p, mp4_dash
18  mp4   640x360     24  2 │   12.32MiB  723k https │ avc1.42001E  723k mp4a.40.2    0k 44k 360p
243 webm  640x360     24    │    6.25MiB  367k https │ vp9          367k video only          360p, webm_dash
135 mp4   854x480     24    │   14.83MiB  871k https │ avc1.4d401e  871k video only          480p, mp4_dash
244 webm  854x480     24    │   11.46MiB  673k https │ vp9          673k video only          480p, webm_dash
22  mp4   1280x720    24  2 │ ~ 28.36MiB 1625k https │ avc1.64001F 1625k mp4a.40.2    0k 44k 720p
136 mp4   1280x720    24    │   25.51MiB 1498k https │ avc1.4d401f 1498k video only          720p, mp4_dash
247 webm  1280x720    24    │   21.89MiB 1286k https │ vp9         1286k video only          720p, webm_dash
137 mp4   1920x1080   24    │   45.93MiB 2698k https │ avc1.640028 2698k video only          1080p, mp4_dash
248 webm  1920x1080   24    │   38.78MiB 2278k https │ vp9         2278k video only          1080p, webm_dash

The option -F is the short mode of --list-formats.

  • Download a video with default options:
$ yt-dlp https://www.youtube.com/watch?v=r3eaGCk2Acs
[youtube] r3eaGCk2Acs: Downloading webpage
[youtube] r3eaGCk2Acs: Downloading android player API JSON
[info] r3eaGCk2Acs: Downloading 1 format(s): 248+251
[download] Destination: PANDAS - OFFICIAL TRAILER [HD] [r3eaGCk2Acs].f248.webm
[download] 100% of 38.78MiB in 00:33 at 1.16MiB/s
[download] Destination: PANDAS - OFFICIAL TRAILER [HD] [r3eaGCk2Acs].f251.webm
[download] 100% of 2.24MiB in 00:00 at 5.01MiB/s
[Merger] Merging formats into "PANDAS - OFFICIAL TRAILER [HD] [r3eaGCk2Acs].webm"
Deleting original file PANDAS - OFFICIAL TRAILER [HD] [r3eaGCk2Acs].f248.webm (pass -k to keep)
Deleting original file PANDAS - OFFICIAL TRAILER [HD] [r3eaGCk2Acs].f251.webm (pass -k to keep)

-f is the short mode of option --format.

  • To download a video with the best video and best audio stream:
$ yt-dlp --format "bv*+ba/b" https://www.youtube.com/watch?v=r3eaGCk2Acs

bv*+ba/b is the default format selector, which means that if a combined video + audio format that is better than the best video-only format is found, the former will be preferred.

  • To download a 1080p video with the best audio stream:
$ yt-dlp --format "bv*[height=1080]+ba/b" https://www.youtube.com/watch?v=r3eaGCk2Acs

If there were NO 1080p resolution available, yt-flp prints error message and quit.

  • To download a video with resolution better than 1080p:
$ yt-dlp --format "bv*[height>=1080]+ba/b" https://www.youtube.com/watch?v=r3eaGCk2Acs
  • To extract audio from a video:
$ yt-dlp --extract-audio https://www.youtube.com/watch?v=r3eaGCk2Acs
  • To list available formats of available subtitles:
$ yt-dlp --list-subs https://www.youtube.com/watch?v=r3eaGCk2Acs
[youtube] r3eaGCk2Acs: Downloading webpage
[youtube] r3eaGCk2Acs: Downloading android player API JSON
[info] Available automatic captions for r3eaGCk2Acs:
Language   Name                               Formats
af-en      Afrikaans from English             vtt, ttml, srv3, srv2, srv1, json3
ak-en      Akan from English                  vtt, ttml, srv3, srv2, srv1, json3
sq-en      Albanian from English              vtt, ttml, srv3, srv2, srv1, json3
...        ...                                ...
yi-en      Yiddish from English               vtt, ttml, srv3, srv2, srv1, json3
yo-en      Yoruba from English                vtt, ttml, srv3, srv2, srv1, json3
zu-en      Zulu from English                  vtt, ttml, srv3, srv2, srv1, json3
[info] Available subtitles for r3eaGCk2Acs:
Language Name    Formats
en       English vtt, ttml, srv3, srv2, srv1, json3
  • To download subtitles (if available) of a video as a default:
$ yt-dlp --write-subs en https://www.youtube.com/watch?v=r3eaGCk2Acs

Default subtitle file format is .vtt.

  • To specify the format to download subtitle:
$ yt-dlp --write-subs en --sub-format json3 https://www.youtube.com/watch?v=r3eaGCk2Acs
  • To embed subtitles into the video:
$ yt-dlp --format "bv*+ba/b" --embed-subs --merge-output-format mp4 https://www.youtube.com/watch?v=r3eaGCk2Acs

The option --embed-subs works only for mp4, webm and mkv videos.

  • To embed thumbnail into the video:

The option --embed-thumbnail embed thumbnail (if available) on the video as cover art.

$ yt-dlp --format "bv*+ba/b" --embed-thumbnail --merge-output-format mp4 https://www.youtube.com/watch?v=r3eaGCk2Acs
  • To download a video that require login

On YouTube, movies containing radical expressions such as violence and bloodshed can only be played by logging in to your account and verifying your age. Here the option --cookies-from-browser is useful.

For example, to download the The Suicide Squad - Official Red Band Trailer:

$ yt-dlp --cookies-from-browser firefox https://www.youtube.com/watch?v=Z1EbSXxrZ34

Supported browsers are: brave, chrome, chromium, edge, firefox, opera, safari, vivaldi

  • To download all videos of a playlist or channel:

Simply append the url of the playlist or channel to yt=dlp command. e.g.,

$ yt-dlp --format "bv*+ba/b" --download-archive videos.txt https://www.youtube.com/c/NatGeo/channels

--download-archive option record the IDs of all downloaded videos in the file videos.txt.

  • Batch download multiple videos:

Create a text file containing multiple URLs, one URL per line. Lines starting with ‘#’, ‘;’ or ‘]’ are considered as comments and ignored.

$ yt-dlp --batch-file urls.txt

-a is the short mode of --batch-file.

3. Using a configuration file

You can configure yt-dlp by placing any supported command line option to a configuration file. The possible configuration file locations are:

  1. Main Configuration: The file given by --config-location

  2. Portable Configuration: yt-dlp.conf in the same directory as the bundled binary. If you are running from source-code (<root dir>/yt_dlp/__main__.py), the root directory is used instead.

  3. Home Configuration: yt-dlp.conf in the home path given by -P, or in the current directory if no such path is given

  4. User Configuration:

    • %XDG_CONFIG_HOME%/yt-dlp/config (recommended on Linux/macOS)

    • %XDG_CONFIG_HOME%/yt-dlp.conf

    • %APPDATA%/yt-dlp/config (recommended on Windows)

    • %APPDATA%/yt-dlp/config.txt

    • ~/yt-dlp.conf

    • ~/yt-dlp.conf.txt

      • %XDG_CONFIG_HOME% defaults to ~/.config if undefined.
      • On windows, %APPDATA% generally points to C:\Users\<user name>\AppData\Roaming and ~ points to %HOME% if present, %USERPROFILE% (generally C:\Users\<user name>), or %HOMEDRIVE%%HOMEPATH%

  5. System Configuration: /etc/yt-dlp.conf

4. Output template

The --output|-o option is used to indicate a template for the output file names while --paths|-P option is used to specify the path each type of file should be saved to.

Please see details in yt-dlp Documentation: Output Template.

References

  1. yt-dlp Documentation
  2. Summary of how to use ‘yt-dlp’ that can download movies such as YouTube and Nico Nico video with the highest image quality and high sound quality, age-restricted movies can also be downloaded at once
  3. yt-dlp – Easily download YouTube videos in the Terminal
  4. Download YouTube Videos using yt-dlp – Youtube-dl alternative