yt-dlp.1 (152520B)
- .\"t
- .\" Automatically generated by Pandoc 2.9.2.1
- .\"
- .TH "yt-dlp" "1" "" "" ""
- .hy
- .SH NAME
- .PP
- yt-dlp - A feature-rich command-line audio/video downloader
- .SH SYNOPSIS
- .PP
- \f[B]yt-dlp\f[R] [OPTIONS] URL [URL...]
- .SH DESCRIPTION
- .PP
- yt-dlp is a feature-rich command-line audio/video downloader with
- support for thousands of sites.
- The project is a fork of
- youtube-dl (https://github.com/ytdl-org/youtube-dl) based on the now
- inactive youtube-dlc (https://github.com/blackjack4494/yt-dlc).
- .SH OPTIONS
- .SS General Options:
- .TP
- -h, --help
- Print this help text and exit
- .TP
- --version
- Print program version and exit
- .TP
- -U, --update
- Update this program to the latest version
- .TP
- --no-update
- Do not check for updates (default)
- .TP
- --update-to \f[I][CHANNEL]\[at][TAG]\f[R]
- Upgrade/downgrade to a specific version.
- CHANNEL can be a repository as well.
- CHANNEL and TAG default to \[dq]stable\[dq] and \[dq]latest\[dq]
- respectively if omitted; See \[dq]UPDATE\[dq] for details.
- Supported channels: stable, nightly, master
- .TP
- -i, --ignore-errors
- Ignore download and postprocessing errors.
- The download will be considered successful even if the postprocessing
- fails
- .TP
- --no-abort-on-error
- Continue with next video on download errors; e.g.
- to skip unavailable videos in a playlist (default)
- .TP
- --abort-on-error
- Abort downloading of further videos if an error occurs (Alias:
- --no-ignore-errors)
- .TP
- --dump-user-agent
- Display the current user-agent and exit
- .TP
- --list-extractors
- List all supported extractors and exit
- .TP
- --extractor-descriptions
- Output descriptions of all supported extractors and exit
- .TP
- --use-extractors \f[I]NAMES\f[R]
- Extractor names to use separated by commas.
- You can also use regexes, \[dq]all\[dq], \[dq]default\[dq] and
- \[dq]end\[dq] (end URL matching); e.g.
- --ies \[dq]holodex.*,end,youtube\[dq].
- Prefix the name with a \[dq]-\[dq] to exclude it, e.g.
- --ies default,-generic.
- Use --list-extractors for a list of extractor names.
- (Alias: --ies)
- .TP
- --default-search \f[I]PREFIX\f[R]
- Use this prefix for unqualified URLs.
- E.g.
- \[dq]gvsearch2:python\[dq] downloads two videos from google videos for
- the search term \[dq]python\[dq].
- Use the value \[dq]auto\[dq] to let yt-dlp guess (\[dq]auto_warning\[dq]
- to emit a warning when guessing).
- \[dq]error\[dq] just throws an error.
- The default value \[dq]fixup_error\[dq] repairs broken URLs, but emits
- an error if this is not possible instead of searching
- .TP
- --ignore-config
- Don\[aq]t load any more configuration files except those given to
- --config-locations.
- For backward compatibility, if this option is found inside the system
- configuration file, the user configuration is not loaded.
- (Alias: --no-config)
- .TP
- --no-config-locations
- Do not load any custom configuration files (default).
- When given inside a configuration file, ignore all previous
- --config-locations defined in the current file
- .TP
- --config-locations \f[I]PATH\f[R]
- Location of the main configuration file; either the path to the config
- or its containing directory (\[dq]-\[dq] for stdin).
- Can be used multiple times and inside other configuration files
- .TP
- --plugin-dirs \f[I]PATH\f[R]
- Path to an additional directory to search for plugins.
- This option can be used multiple times to add multiple directories.
- Note that this currently only works for extractor plugins; postprocessor
- plugins can only be loaded from the default plugin directories
- .TP
- --flat-playlist
- Do not extract a playlist\[aq]s URL result entries; some entry metadata
- may be missing and downloading may be bypassed
- .TP
- --no-flat-playlist
- Fully extract the videos of a playlist (default)
- .TP
- --live-from-start
- Download livestreams from the start.
- Currently only supported for YouTube (Experimental)
- .TP
- --no-live-from-start
- Download livestreams from the current time (default)
- .TP
- --wait-for-video \f[I]MIN[-MAX]\f[R]
- Wait for scheduled streams to become available.
- Pass the minimum number of seconds (or range) to wait between retries
- .TP
- --no-wait-for-video
- Do not wait for scheduled streams (default)
- .TP
- --mark-watched
- Mark videos watched (even with --simulate)
- .TP
- --no-mark-watched
- Do not mark videos watched (default)
- .TP
- --color \f[I][STREAM:]POLICY\f[R]
- Whether to emit color codes in output, optionally prefixed by the STREAM
- (stdout or stderr) to apply the setting to.
- Can be one of \[dq]always\[dq], \[dq]auto\[dq] (default),
- \[dq]never\[dq], or \[dq]no_color\[dq] (use non color terminal
- sequences).
- Use \[dq]auto-tty\[dq] or \[dq]no_color-tty\[dq] to decide based on
- terminal support only.
- Can be used multiple times
- .TP
- --compat-options \f[I]OPTS\f[R]
- Options that can help keep compatibility with youtube-dl or youtube-dlc
- configurations by reverting some of the changes made in yt-dlp.
- See \[dq]Differences in default behavior\[dq] for details
- .TP
- --alias \f[I]ALIASES OPTIONS\f[R]
- Create aliases for an option string.
- Unless an alias starts with a dash \[dq]-\[dq], it is prefixed with
- \[dq]--\[dq].
- Arguments are parsed according to the Python string formatting
- mini-language.
- E.g.
- --alias get-audio,-X \[dq]-S=aext:{0},abr -x --audio-format {0}\[dq]
- creates options \[dq]--get-audio\[dq] and \[dq]-X\[dq] that takes an
- argument (ARG0) and expands to \[dq]-S=aext:ARG0,abr -x --audio-format
- ARG0\[dq].
- All defined aliases are listed in the --help output.
- Alias options can trigger more aliases; so be careful to avoid defining
- recursive options.
- As a safety measure, each alias may be triggered a maximum of 100 times.
- This option can be used multiple times
- .SS Network Options:
- .TP
- --proxy \f[I]URL\f[R]
- Use the specified HTTP/HTTPS/SOCKS proxy.
- To enable SOCKS proxy, specify a proper scheme, e.g.
- socks5://user:pass\[at]127.0.0.1:1080/.
- Pass in an empty string (--proxy \[dq]\[dq]) for direct connection
- .TP
- --socket-timeout \f[I]SECONDS\f[R]
- Time to wait before giving up, in seconds
- .TP
- --source-address \f[I]IP\f[R]
- Client-side IP address to bind to
- .TP
- --impersonate \f[I]CLIENT[:OS]\f[R]
- Client to impersonate for requests.
- E.g.
- chrome, chrome-110, chrome:windows-10.
- Pass --impersonate=\[dq]\[dq] to impersonate any client.
- Note that forcing impersonation for all requests may have a detrimental
- impact on download speed and stability
- .TP
- --list-impersonate-targets
- List available clients to impersonate.
- .TP
- -4, --force-ipv4
- Make all connections via IPv4
- .TP
- -6, --force-ipv6
- Make all connections via IPv6
- .TP
- --enable-file-urls
- Enable file:// URLs.
- This is disabled by default for security reasons.
- .SS Geo-restriction:
- .TP
- --geo-verification-proxy \f[I]URL\f[R]
- Use this proxy to verify the IP address for some geo-restricted sites.
- The default proxy specified by --proxy (or none, if the option is not
- present) is used for the actual downloading
- .TP
- --xff \f[I]VALUE\f[R]
- How to fake X-Forwarded-For HTTP header to try bypassing geographic
- restriction.
- One of \[dq]default\[dq] (only when known to be useful),
- \[dq]never\[dq], an IP block in CIDR notation, or a two-letter ISO
- 3166-2 country code
- .SS Video Selection:
- .TP
- -I, --playlist-items \f[I]ITEM_SPEC\f[R]
- Comma separated playlist_index of the items to download.
- You can specify a range using \[dq][START]:[STOP][:STEP]\[dq].
- For backward compatibility, START-STOP is also supported.
- Use negative indices to count from the right and negative STEP to
- download in reverse order.
- E.g.
- \[dq]-I 1:3,7,-5::2\[dq] used on a playlist of size 15 will download the
- items at index 1,2,3,7,11,13,15
- .TP
- --min-filesize \f[I]SIZE\f[R]
- Abort download if filesize is smaller than SIZE, e.g.
- 50k or 44.6M
- .TP
- --max-filesize \f[I]SIZE\f[R]
- Abort download if filesize is larger than SIZE, e.g.
- 50k or 44.6M
- .TP
- --date \f[I]DATE\f[R]
- Download only videos uploaded on this date.
- The date can be \[dq]YYYYMMDD\[dq] or in the format
- [now|today|yesterday][-N[day|week|month|year]].
- E.g.
- \[dq]--date today-2weeks\[dq] downloads only videos uploaded on the same
- day two weeks ago
- .TP
- --datebefore \f[I]DATE\f[R]
- Download only videos uploaded on or before this date.
- The date formats accepted are the same as --date
- .TP
- --dateafter \f[I]DATE\f[R]
- Download only videos uploaded on or after this date.
- The date formats accepted are the same as --date
- .TP
- --match-filters \f[I]FILTER\f[R]
- Generic video filter.
- Any \[dq]OUTPUT TEMPLATE\[dq] field can be compared with a number or a
- string using the operators defined in \[dq]Filtering Formats\[dq].
- You can also simply specify a field to match if the field is present,
- use \[dq]!field\[dq] to check if the field is not present, and
- \[dq]&\[dq] to check multiple conditions.
- Use a \[dq]\[dq] to escape \[dq]&\[dq] or quotes if needed.
- If used multiple times, the filter matches if at least one of the
- conditions is met.
- E.g.
- --match-filters !is_live --match-filters \[dq]like_count>?100 &
- description\[ti]=\[aq](?i)& dogs\[dq] matches only videos that are not
- live OR those that have a like count more than 100 (or the like field is
- not available) and also has a description that contains the phrase
- \[dq]cats & dogs\[dq] (caseless).
- Use \[dq]--match-filters -\[dq] to interactively ask whether to download
- each video
- .TP
- --no-match-filters
- Do not use any --match-filters (default)
- .TP
- --break-match-filters \f[I]FILTER\f[R]
- Same as \[dq]--match-filters\[dq] but stops the download process when a
- video is rejected
- .TP
- --no-break-match-filters
- Do not use any --break-match-filters (default)
- .TP
- --no-playlist
- Download only the video, if the URL refers to a video and a playlist
- .TP
- --yes-playlist
- Download the playlist, if the URL refers to a video and a playlist
- .TP
- --age-limit \f[I]YEARS\f[R]
- Download only videos suitable for the given age
- .TP
- --download-archive \f[I]FILE\f[R]
- Download only videos not listed in the archive file.
- Record the IDs of all downloaded videos in it
- .TP
- --no-download-archive
- Do not use archive file (default)
- .TP
- --max-downloads \f[I]NUMBER\f[R]
- Abort after downloading NUMBER files
- .TP
- --break-on-existing
- Stop the download process when encountering a file that is in the
- archive supplied with the --download-archive option
- .TP
- --no-break-on-existing
- Do not stop the download process when encountering a file that is in the
- archive (default)
- .TP
- --break-per-input
- Alters --max-downloads, --break-on-existing, --break-match-filters, and
- autonumber to reset per input URL
- .TP
- --no-break-per-input
- --break-on-existing and similar options terminates the entire download
- queue
- .TP
- --skip-playlist-after-errors \f[I]N\f[R]
- Number of allowed failures until the rest of the playlist is skipped
- .SS Download Options:
- .TP
- -N, --concurrent-fragments \f[I]N\f[R]
- Number of fragments of a dash/hlsnative video that should be downloaded
- concurrently (default is 1)
- .TP
- -r, --limit-rate \f[I]RATE\f[R]
- Maximum download rate in bytes per second, e.g.
- 50K or 4.2M
- .TP
- --throttled-rate \f[I]RATE\f[R]
- Minimum download rate in bytes per second below which throttling is
- assumed and the video data is re-extracted, e.g.
- 100K
- .TP
- -R, --retries \f[I]RETRIES\f[R]
- Number of retries (default is 10), or \[dq]infinite\[dq]
- .TP
- --file-access-retries \f[I]RETRIES\f[R]
- Number of times to retry on file access error (default is 3), or
- \[dq]infinite\[dq]
- .TP
- --fragment-retries \f[I]RETRIES\f[R]
- Number of retries for a fragment (default is 10), or \[dq]infinite\[dq]
- (DASH, hlsnative and ISM)
- .TP
- --retry-sleep \f[I][TYPE:]EXPR\f[R]
- Time to sleep between retries in seconds (optionally) prefixed by the
- type of retry (http (default), fragment, file_access, extractor) to
- apply the sleep to.
- EXPR can be a number, linear=START[:END[:STEP=1]] or
- exp=START[:END[:BASE=2]].
- This option can be used multiple times to set the sleep for the
- different retry types, e.g.
- --retry-sleep linear=1::2 --retry-sleep fragment:exp=1:20
- .TP
- --skip-unavailable-fragments
- Skip unavailable fragments for DASH, hlsnative and ISM downloads
- (default) (Alias: --no-abort-on-unavailable-fragments)
- .TP
- --abort-on-unavailable-fragments
- Abort download if a fragment is unavailable (Alias:
- --no-skip-unavailable-fragments)
- .TP
- --keep-fragments
- Keep downloaded fragments on disk after downloading is finished
- .TP
- --no-keep-fragments
- Delete downloaded fragments after downloading is finished (default)
- .TP
- --buffer-size \f[I]SIZE\f[R]
- Size of download buffer, e.g.
- 1024 or 16K (default is 1024)
- .TP
- --resize-buffer
- The buffer size is automatically resized from an initial value of
- --buffer-size (default)
- .TP
- --no-resize-buffer
- Do not automatically adjust the buffer size
- .TP
- --http-chunk-size \f[I]SIZE\f[R]
- Size of a chunk for chunk-based HTTP downloading, e.g.
- 10485760 or 10M (default is disabled).
- May be useful for bypassing bandwidth throttling imposed by a webserver
- (experimental)
- .TP
- --playlist-random
- Download playlist videos in random order
- .TP
- --lazy-playlist
- Process entries in the playlist as they are received.
- This disables n_entries, --playlist-random and --playlist-reverse
- .TP
- --no-lazy-playlist
- Process videos in the playlist only after the entire playlist is parsed
- (default)
- .TP
- --xattr-set-filesize
- Set file xattribute ytdl.filesize with expected file size
- .TP
- --hls-use-mpegts
- Use the mpegts container for HLS videos; allowing some players to play
- the video while downloading, and reducing the chance of file corruption
- if download is interrupted.
- This is enabled by default for live streams
- .TP
- --no-hls-use-mpegts
- Do not use the mpegts container for HLS videos.
- This is default when not downloading live streams
- .TP
- --download-sections \f[I]REGEX\f[R]
- Download only chapters that match the regular expression.
- A \[dq]*\[dq] prefix denotes time-range instead of chapter.
- Negative timestamps are calculated from the end.
- \[dq]*from-url\[dq] can be used to download between the
- \[dq]start_time\[dq] and \[dq]end_time\[dq] extracted from the URL.
- Needs ffmpeg.
- This option can be used multiple times to download multiple sections,
- e.g.
- --download-sections \[dq]*10:15-inf\[dq] --download-sections
- \[dq]intro\[dq]
- .TP
- --downloader \f[I][PROTO:]NAME\f[R]
- Name or path of the external downloader to use (optionally) prefixed by
- the protocols (http, ftp, m3u8, dash, rstp, rtmp, mms) to use it for.
- Currently supports native, aria2c, avconv, axel, curl, ffmpeg, httpie,
- wget.
- You can use this option multiple times to set different downloaders for
- different protocols.
- E.g.
- --downloader aria2c --downloader \[dq]dash,m3u8:native\[dq] will use
- aria2c for http/ftp downloads, and the native downloader for dash/m3u8
- downloads (Alias: --external-downloader)
- .TP
- --downloader-args \f[I]NAME:ARGS\f[R]
- Give these arguments to the external downloader.
- Specify the downloader name and the arguments separated by a colon
- \[dq]:\[dq].
- For ffmpeg, arguments can be passed to different positions using the
- same syntax as --postprocessor-args.
- You can use this option multiple times to give different arguments to
- different downloaders (Alias: --external-downloader-args)
- .SS Filesystem Options:
- .TP
- -a, --batch-file \f[I]FILE\f[R]
- File containing URLs to download (\[dq]-\[dq] for stdin), one URL per
- line.
- Lines starting with \[dq]#\[dq], \[dq];\[dq] or \[dq]]\[dq] are
- considered as comments and ignored
- .TP
- --no-batch-file
- Do not read URLs from batch file (default)
- .TP
- -P, --paths \f[I][TYPES:]PATH\f[R]
- The paths where the files should be downloaded.
- Specify the type of file and the path separated by a colon \[dq]:\[dq].
- All the same TYPES as --output are supported.
- Additionally, you can also provide \[dq]home\[dq] (default) and
- \[dq]temp\[dq] paths.
- All intermediary files are first downloaded to the temp path and then
- the final files are moved over to the home path after download is
- finished.
- This option is ignored if --output is an absolute path
- .TP
- -o, --output \f[I][TYPES:]TEMPLATE\f[R]
- Output filename template; see \[dq]OUTPUT TEMPLATE\[dq] for details
- .TP
- --output-na-placeholder \f[I]TEXT\f[R]
- Placeholder for unavailable fields in --output (default: \[dq]NA\[dq])
- .TP
- --restrict-filenames
- Restrict filenames to only ASCII characters, and avoid \[dq]&\[dq] and
- spaces in filenames
- .TP
- --no-restrict-filenames
- Allow Unicode characters, \[dq]&\[dq] and spaces in filenames (default)
- .TP
- --windows-filenames
- Force filenames to be Windows-compatible
- .TP
- --no-windows-filenames
- Sanitize filenames only minimally
- .TP
- --trim-filenames \f[I]LENGTH\f[R]
- Limit the filename length (excluding extension) to the specified number
- of characters
- .TP
- -w, --no-overwrites
- Do not overwrite any files
- .TP
- --force-overwrites
- Overwrite all video and metadata files.
- This option includes --no-continue
- .TP
- --no-force-overwrites
- Do not overwrite the video, but overwrite related files (default)
- .TP
- -c, --continue
- Resume partially downloaded files/fragments (default)
- .TP
- --no-continue
- Do not resume partially downloaded fragments.
- If the file is not fragmented, restart download of the entire file
- .TP
- --part
- Use .part files instead of writing directly into output file (default)
- .TP
- --no-part
- Do not use .part files - write directly into output file
- .TP
- --mtime
- Use the Last-modified header to set the file modification time (default)
- .TP
- --no-mtime
- Do not use the Last-modified header to set the file modification time
- .TP
- --write-description
- Write video description to a .description file
- .TP
- --no-write-description
- Do not write video description (default)
- .TP
- --write-info-json
- Write video metadata to a .info.json file (this may contain personal
- information)
- .TP
- --no-write-info-json
- Do not write video metadata (default)
- .TP
- --write-playlist-metafiles
- Write playlist metadata in addition to the video metadata when using
- --write-info-json, --write-description etc.
- (default)
- .TP
- --no-write-playlist-metafiles
- Do not write playlist metadata when using --write-info-json,
- --write-description etc.
- .TP
- --clean-info-json
- Remove some internal metadata such as filenames from the infojson
- (default)
- .TP
- --no-clean-info-json
- Write all fields to the infojson
- .TP
- --write-comments
- Retrieve video comments to be placed in the infojson.
- The comments are fetched even without this option if the extraction is
- known to be quick (Alias: --get-comments)
- .TP
- --no-write-comments
- Do not retrieve video comments unless the extraction is known to be
- quick (Alias: --no-get-comments)
- .TP
- --load-info-json \f[I]FILE\f[R]
- JSON file containing the video information (created with the
- \[dq]--write-info-json\[dq] option)
- .TP
- --cookies \f[I]FILE\f[R]
- Netscape formatted file to read cookies from and dump cookie jar in
- .TP
- --no-cookies
- Do not read/dump cookies from/to file (default)
- .TP
- --cookies-from-browser \f[I]BROWSER[+KEYRING][:PROFILE][::CONTAINER]\f[R]
- The name of the browser to load cookies from.
- Currently supported browsers are: brave, chrome, chromium, edge,
- firefox, opera, safari, vivaldi, whale.
- Optionally, the KEYRING used for decrypting Chromium cookies on Linux,
- the name/path of the PROFILE to load cookies from, and the CONTAINER
- name (if Firefox) (\[dq]none\[dq] for no container) can be given with
- their respective separators.
- By default, all containers of the most recently accessed profile are
- used.
- Currently supported keyrings are: basictext, gnomekeyring, kwallet,
- kwallet5, kwallet6
- .TP
- --no-cookies-from-browser
- Do not load cookies from browser (default)
- .TP
- --cache-dir \f[I]DIR\f[R]
- Location in the filesystem where yt-dlp can store some downloaded
- information (such as client ids and signatures) permanently.
- By default ${XDG_CACHE_HOME}/yt-dlp
- .TP
- --no-cache-dir
- Disable filesystem caching
- .TP
- --rm-cache-dir
- Delete all filesystem cache files
- .SS Thumbnail Options:
- .TP
- --write-thumbnail
- Write thumbnail image to disk
- .TP
- --no-write-thumbnail
- Do not write thumbnail image to disk (default)
- .TP
- --write-all-thumbnails
- Write all thumbnail image formats to disk
- .TP
- --list-thumbnails
- List available thumbnails of each video.
- Simulate unless --no-simulate is used
- .SS Internet Shortcut Options:
- .TP
- --write-link
- Write an internet shortcut file, depending on the current platform
- (.url, .webloc or .desktop).
- The URL may be cached by the OS
- .TP
- --write-url-link
- Write a .url Windows internet shortcut.
- The OS caches the URL based on the file path
- .TP
- --write-webloc-link
- Write a .webloc macOS internet shortcut
- .TP
- --write-desktop-link
- Write a .desktop Linux internet shortcut
- .SS Verbosity and Simulation Options:
- .TP
- -q, --quiet
- Activate quiet mode.
- If used with --verbose, print the log to stderr
- .TP
- --no-quiet
- Deactivate quiet mode.
- (Default)
- .TP
- --no-warnings
- Ignore warnings
- .TP
- -s, --simulate
- Do not download the video and do not write anything to disk
- .TP
- --no-simulate
- Download the video even if printing/listing options are used
- .TP
- --ignore-no-formats-error
- Ignore \[dq]No video formats\[dq] error.
- Useful for extracting metadata even if the videos are not actually
- available for download (experimental)
- .TP
- --no-ignore-no-formats-error
- Throw error when no downloadable video formats are found (default)
- .TP
- --skip-download
- Do not download the video but write all related files (Alias:
- --no-download)
- .TP
- -O, --print \f[I][WHEN:]TEMPLATE\f[R]
- Field name or output template to print to screen, optionally prefixed
- with when to print it, separated by a \[dq]:\[dq].
- Supported values of \[dq]WHEN\[dq] are the same as that of
- --use-postprocessor (default: video).
- Implies --quiet.
- Implies --simulate unless --no-simulate or later stages of WHEN are
- used.
- This option can be used multiple times
- .TP
- --print-to-file \f[I][WHEN:]TEMPLATE FILE\f[R]
- Append given template to the file.
- The values of WHEN and TEMPLATE are the same as that of --print.
- FILE uses the same syntax as the output template.
- This option can be used multiple times
- .TP
- -j, --dump-json
- Quiet, but print JSON information for each video.
- Simulate unless --no-simulate is used.
- See \[dq]OUTPUT TEMPLATE\[dq] for a description of available keys
- .TP
- -J, --dump-single-json
- Quiet, but print JSON information for each URL or infojson passed.
- Simulate unless --no-simulate is used.
- If the URL refers to a playlist, the whole playlist information is
- dumped in a single line
- .TP
- --force-write-archive
- Force download archive entries to be written as far as no errors occur,
- even if -s or another simulation option is used (Alias:
- --force-download-archive)
- .TP
- --newline
- Output progress bar as new lines
- .TP
- --no-progress
- Do not print progress bar
- .TP
- --progress
- Show progress bar, even if in quiet mode
- .TP
- --console-title
- Display progress in console titlebar
- .TP
- --progress-template \f[I][TYPES:]TEMPLATE\f[R]
- Template for progress outputs, optionally prefixed with one of
- \[dq]download:\[dq] (default), \[dq]download-title:\[dq] (the console
- title), \[dq]postprocess:\[dq], or \[dq]postprocess-title:\[dq].
- The video\[aq]s fields are accessible under the \[dq]info\[dq] key and
- the progress attributes are accessible under \[dq]progress\[dq] key.
- E.g.
- --console-title --progress-template
- \[dq]download-title:%(info.id)s-%(progress.eta)s\[dq]
- .TP
- --progress-delta \f[I]SECONDS\f[R]
- Time between progress output (default: 0)
- .TP
- -v, --verbose
- Print various debugging information
- .TP
- --dump-pages
- Print downloaded pages encoded using base64 to debug problems (very
- verbose)
- .TP
- --write-pages
- Write downloaded intermediary pages to files in the current directory to
- debug problems
- .TP
- --print-traffic
- Display sent and read HTTP traffic
- .SS Workarounds:
- .TP
- --encoding \f[I]ENCODING\f[R]
- Force the specified encoding (experimental)
- .TP
- --legacy-server-connect
- Explicitly allow HTTPS connection to servers that do not support RFC
- 5746 secure renegotiation
- .TP
- --no-check-certificates
- Suppress HTTPS certificate validation
- .TP
- --prefer-insecure
- Use an unencrypted connection to retrieve information about the video
- (Currently supported only for YouTube)
- .TP
- --add-headers \f[I]FIELD:VALUE\f[R]
- Specify a custom HTTP header and its value, separated by a colon
- \[dq]:\[dq].
- You can use this option multiple times
- .TP
- --bidi-workaround
- Work around terminals that lack bidirectional text support.
- Requires bidiv or fribidi executable in PATH
- .TP
- --sleep-requests \f[I]SECONDS\f[R]
- Number of seconds to sleep between requests during data extraction
- .TP
- --sleep-interval \f[I]SECONDS\f[R]
- Number of seconds to sleep before each download.
- This is the minimum time to sleep when used along with
- --max-sleep-interval (Alias: --min-sleep-interval)
- .TP
- --max-sleep-interval \f[I]SECONDS\f[R]
- Maximum number of seconds to sleep.
- Can only be used along with --min-sleep-interval
- .TP
- --sleep-subtitles \f[I]SECONDS\f[R]
- Number of seconds to sleep before each subtitle download
- .SS Video Format Options:
- .TP
- -f, --format \f[I]FORMAT\f[R]
- Video format code, see \[dq]FORMAT SELECTION\[dq] for more details
- .TP
- -S, --format-sort \f[I]SORTORDER\f[R]
- Sort the formats by the fields given, see \[dq]Sorting Formats\[dq] for
- more details
- .TP
- --format-sort-force
- Force user specified sort order to have precedence over all fields, see
- \[dq]Sorting Formats\[dq] for more details (Alias: --S-force)
- .TP
- --no-format-sort-force
- Some fields have precedence over the user specified sort order (default)
- .TP
- --video-multistreams
- Allow multiple video streams to be merged into a single file
- .TP
- --no-video-multistreams
- Only one video stream is downloaded for each output file (default)
- .TP
- --audio-multistreams
- Allow multiple audio streams to be merged into a single file
- .TP
- --no-audio-multistreams
- Only one audio stream is downloaded for each output file (default)
- .TP
- --prefer-free-formats
- Prefer video formats with free containers over non-free ones of the same
- quality.
- Use with \[dq]-S ext\[dq] to strictly prefer free containers
- irrespective of quality
- .TP
- --no-prefer-free-formats
- Don\[aq]t give any special preference to free containers (default)
- .TP
- --check-formats
- Make sure formats are selected only from those that are actually
- downloadable
- .TP
- --check-all-formats
- Check all formats for whether they are actually downloadable
- .TP
- --no-check-formats
- Do not check that the formats are actually downloadable
- .TP
- -F, --list-formats
- List available formats of each video.
- Simulate unless --no-simulate is used
- .TP
- --merge-output-format \f[I]FORMAT\f[R]
- Containers that may be used when merging formats, separated by
- \[dq]/\[dq], e.g.
- \[dq]mp4/mkv\[dq].
- Ignored if no merge is required.
- (currently supported: avi, flv, mkv, mov, mp4, webm)
- .SS Subtitle Options:
- .TP
- --write-subs
- Write subtitle file
- .TP
- --no-write-subs
- Do not write subtitle file (default)
- .TP
- --write-auto-subs
- Write automatically generated subtitle file (Alias:
- --write-automatic-subs)
- .TP
- --no-write-auto-subs
- Do not write auto-generated subtitles (default) (Alias:
- --no-write-automatic-subs)
- .TP
- --list-subs
- List available subtitles of each video.
- Simulate unless --no-simulate is used
- .TP
- --sub-format \f[I]FORMAT\f[R]
- Subtitle format; accepts formats preference separated by \[dq]/\[dq],
- e.g.
- \[dq]srt\[dq] or \[dq]ass/srt/best\[dq]
- .TP
- --sub-langs \f[I]LANGS\f[R]
- Languages of the subtitles to download (can be regex) or \[dq]all\[dq]
- separated by commas, e.g.
- --sub-langs \[dq]en.*,ja\[dq] (where \[dq]en.*\[dq] is a regex pattern
- that matches \[dq]en\[dq] followed by 0 or more of any character).
- You can prefix the language code with a \[dq]-\[dq] to exclude it from
- the requested languages, e.g.
- --sub- langs all,-live_chat.
- Use --list-subs for a list of available language tags
- .SS Authentication Options:
- .TP
- -u, --username \f[I]USERNAME\f[R]
- Login with this account ID
- .TP
- -p, --password \f[I]PASSWORD\f[R]
- Account password.
- If this option is left out, yt-dlp will ask interactively
- .TP
- -2, --twofactor \f[I]TWOFACTOR\f[R]
- Two-factor authentication code
- .TP
- -n, --netrc
- Use .netrc authentication data
- .TP
- --netrc-location \f[I]PATH\f[R]
- Location of .netrc authentication data; either the path or its
- containing directory.
- Defaults to \[ti]/.netrc
- .TP
- --netrc-cmd \f[I]NETRC_CMD\f[R]
- Command to execute to get the credentials for an extractor.
- .TP
- --video-password \f[I]PASSWORD\f[R]
- Video-specific password
- .TP
- --ap-mso \f[I]MSO\f[R]
- Adobe Pass multiple-system operator (TV provider) identifier, use
- --ap-list-mso for a list of available MSOs
- .TP
- --ap-username \f[I]USERNAME\f[R]
- Multiple-system operator account login
- .TP
- --ap-password \f[I]PASSWORD\f[R]
- Multiple-system operator account password.
- If this option is left out, yt-dlp will ask interactively
- .TP
- --ap-list-mso
- List all supported multiple-system operators
- .TP
- --client-certificate \f[I]CERTFILE\f[R]
- Path to client certificate file in PEM format.
- May include the private key
- .TP
- --client-certificate-key \f[I]KEYFILE\f[R]
- Path to private key file for client certificate
- .TP
- --client-certificate-password \f[I]PASSWORD\f[R]
- Password for client certificate private key, if encrypted.
- If not provided, and the key is encrypted, yt-dlp will ask interactively
- .SS Post-Processing Options:
- .TP
- -x, --extract-audio
- Convert video files to audio-only files (requires ffmpeg and ffprobe)
- .TP
- --audio-format \f[I]FORMAT\f[R]
- Format to convert the audio to when -x is used.
- (currently supported: best (default), aac, alac, flac, m4a, mp3, opus,
- vorbis, wav).
- You can specify multiple rules using similar syntax as --remux-video
- .TP
- --audio-quality \f[I]QUALITY\f[R]
- Specify ffmpeg audio quality to use when converting the audio with -x.
- Insert a value between 0 (best) and 10 (worst) for VBR or a specific
- bitrate like 128K (default 5)
- .TP
- --remux-video \f[I]FORMAT\f[R]
- Remux the video into another container if necessary (currently
- supported: avi, flv, gif, mkv, mov, mp4, webm, aac, aiff, alac, flac,
- m4a, mka, mp3, ogg, opus, vorbis, wav).
- If the target container does not support the video/audio codec, remuxing
- will fail.
- You can specify multiple rules; e.g.
- \[dq]aac>m4a/mov>mp4/mkv\[dq] will remux aac to m4a, mov to mp4 and
- anything else to mkv
- .TP
- --recode-video \f[I]FORMAT\f[R]
- Re-encode the video into another format if necessary.
- The syntax and supported formats are the same as --remux-video
- .TP
- --postprocessor-args \f[I]NAME:ARGS\f[R]
- Give these arguments to the postprocessors.
- Specify the postprocessor/executable name and the arguments separated by
- a colon \[dq]:\[dq] to give the argument to the specified
- postprocessor/executable.
- Supported PP are: Merger, ModifyChapters, SplitChapters, ExtractAudio,
- VideoRemuxer, VideoConvertor, Metadata, EmbedSubtitle, EmbedThumbnail,
- SubtitlesConvertor, ThumbnailsConvertor, FixupStretched, FixupM4a,
- FixupM3u8, FixupTimestamp and FixupDuration.
- The supported executables are: AtomicParsley, FFmpeg and FFprobe.
- You can also specify \[dq]PP+EXE:ARGS\[dq] to give the arguments to the
- specified executable only when being used by the specified
- postprocessor.
- Additionally, for ffmpeg/ffprobe, \[dq]_i\[dq]/\[dq]_o\[dq] can be
- appended to the prefix optionally followed by a number to pass the
- argument before the specified input/output file, e.g.
- --ppa \[dq]Merger+ffmpeg_i1:-v quiet\[dq].
- You can use this option multiple times to give different arguments to
- different postprocessors.
- (Alias: --ppa)
- .TP
- -k, --keep-video
- Keep the intermediate video file on disk after post-processing
- .TP
- --no-keep-video
- Delete the intermediate video file after post-processing (default)
- .TP
- --post-overwrites
- Overwrite post-processed files (default)
- .TP
- --no-post-overwrites
- Do not overwrite post-processed files
- .TP
- --embed-subs
- Embed subtitles in the video (only for mp4, webm and mkv videos)
- .TP
- --no-embed-subs
- Do not embed subtitles (default)
- .TP
- --embed-thumbnail
- Embed thumbnail in the video as cover art
- .TP
- --no-embed-thumbnail
- Do not embed thumbnail (default)
- .TP
- --embed-metadata
- Embed metadata to the video file.
- Also embeds chapters/infojson if present unless
- --no-embed-chapters/--no-embed-info-json are used (Alias:
- --add-metadata)
- .TP
- --no-embed-metadata
- Do not add metadata to file (default) (Alias: --no-add-metadata)
- .TP
- --embed-chapters
- Add chapter markers to the video file (Alias: --add-chapters)
- .TP
- --no-embed-chapters
- Do not add chapter markers (default) (Alias: --no-add-chapters)
- .TP
- --embed-info-json
- Embed the infojson as an attachment to mkv/mka video files
- .TP
- --no-embed-info-json
- Do not embed the infojson as an attachment to the video file
- .TP
- --parse-metadata \f[I][WHEN:]FROM:TO\f[R]
- Parse additional metadata like title/artist from other fields; see
- \[dq]MODIFYING METADATA\[dq] for details.
- Supported values of \[dq]WHEN\[dq] are the same as that of
- --use-postprocessor (default: pre_process)
- .TP
- --replace-in-metadata \f[I][WHEN:]FIELDS REGEX REPLACE\f[R]
- Replace text in a metadata field using the given regex.
- This option can be used multiple times.
- Supported values of \[dq]WHEN\[dq] are the same as that of
- --use-postprocessor (default: pre_process)
- .TP
- --xattrs
- Write metadata to the video file\[aq]s xattrs (using Dublin Core and XDG
- standards)
- .TP
- --concat-playlist \f[I]POLICY\f[R]
- Concatenate videos in a playlist.
- One of \[dq]never\[dq], \[dq]always\[dq], or \[dq]multi_video\[dq]
- (default; only when the videos form a single show).
- All the video files must have the same codecs and number of streams to
- be concatenable.
- The \[dq]pl_video:\[dq] prefix can be used with \[dq]--paths\[dq] and
- \[dq]--output\[dq] to set the output filename for the concatenated
- files.
- See \[dq]OUTPUT TEMPLATE\[dq] for details
- .TP
- --fixup \f[I]POLICY\f[R]
- Automatically correct known faults of the file.
- One of never (do nothing), warn (only emit a warning), detect_or_warn
- (the default; fix the file if we can, warn otherwise), force (try fixing
- even if the file already exists)
- .TP
- --ffmpeg-location \f[I]PATH\f[R]
- Location of the ffmpeg binary; either the path to the binary or its
- containing directory
- .TP
- --exec \f[I][WHEN:]CMD\f[R]
- Execute a command, optionally prefixed with when to execute it,
- separated by a \[dq]:\[dq].
- Supported values of \[dq]WHEN\[dq] are the same as that of
- --use-postprocessor (default: after_move).
- The same syntax as the output template can be used to pass any field as
- arguments to the command.
- If no fields are passed, %(filepath,_filename|)q is appended to the end
- of the command.
- This option can be used multiple times
- .TP
- --no-exec
- Remove any previously defined --exec
- .TP
- --convert-subs \f[I]FORMAT\f[R]
- Convert the subtitles to another format (currently supported: ass, lrc,
- srt, vtt).
- Use \[dq]--convert-subs none\[dq] to disable conversion (default)
- (Alias: --convert- subtitles)
- .TP
- --convert-thumbnails \f[I]FORMAT\f[R]
- Convert the thumbnails to another format (currently supported: jpg, png,
- webp).
- You can specify multiple rules using similar syntax as
- \[dq]--remux-video\[dq].
- Use \[dq]--convert- thumbnails none\[dq] to disable conversion (default)
- .TP
- --split-chapters
- Split video into multiple files based on internal chapters.
- The \[dq]chapter:\[dq] prefix can be used with \[dq]--paths\[dq] and
- \[dq]--output\[dq] to set the output filename for the split files.
- See \[dq]OUTPUT TEMPLATE\[dq] for details
- .TP
- --no-split-chapters
- Do not split video based on chapters (default)
- .TP
- --remove-chapters \f[I]REGEX\f[R]
- Remove chapters whose title matches the given regular expression.
- The syntax is the same as --download-sections.
- This option can be used multiple times
- .TP
- --no-remove-chapters
- Do not remove any chapters from the file (default)
- .TP
- --force-keyframes-at-cuts
- Force keyframes at cuts when downloading/splitting/removing sections.
- This is slow due to needing a re-encode, but the resulting video may
- have fewer artifacts around the cuts
- .TP
- --no-force-keyframes-at-cuts
- Do not force keyframes around the chapters when cutting/splitting
- (default)
- .TP
- --use-postprocessor \f[I]NAME[:ARGS]\f[R]
- The (case-sensitive) name of plugin postprocessors to be enabled, and
- (optionally) arguments to be passed to it, separated by a colon
- \[dq]:\[dq].
- ARGS are a semicolon \[dq];\[dq] delimited list of NAME=VALUE.
- The \[dq]when\[dq] argument determines when the postprocessor is
- invoked.
- It can be one of \[dq]pre_process\[dq] (after video extraction),
- \[dq]after_filter\[dq] (after video passes filter), \[dq]video\[dq]
- (after --format; before --print/--output), \[dq]before_dl\[dq] (before
- each video download), \[dq]post_process\[dq] (after each video download;
- default), \[dq]after_move\[dq] (after moving the video file to its final
- location), \[dq]after_video\[dq] (after downloading and processing all
- formats of a video), or \[dq]playlist\[dq] (at end of playlist).
- This option can be used multiple times to add different postprocessors
- .SS SponsorBlock Options:
- .PP
- Make chapter entries for, or remove various segments (sponsor,
- introductions, etc.) from downloaded YouTube videos using the
- SponsorBlock API (https://sponsor.ajay.app)
- .TP
- --sponsorblock-mark \f[I]CATS\f[R]
- SponsorBlock categories to create chapters for, separated by commas.
- Available categories are sponsor, intro, outro, selfpromo, preview,
- filler, interaction, music_offtopic, poi_highlight, chapter, all and
- default (=all).
- You can prefix the category with a \[dq]-\[dq] to exclude it.
- See [1] for descriptions of the categories.
- E.g.
- --sponsorblock-mark all,-preview [1]
- https://wiki.sponsor.ajay.app/w/Segment_Categories
- .TP
- --sponsorblock-remove \f[I]CATS\f[R]
- SponsorBlock categories to be removed from the video file, separated by
- commas.
- If a category is present in both mark and remove, remove takes
- precedence.
- The syntax and available categories are the same as for
- --sponsorblock-mark except that \[dq]default\[dq] refers to
- \[dq]all,-filler\[dq] and poi_highlight, chapter are not available
- .TP
- --sponsorblock-chapter-title \f[I]TEMPLATE\f[R]
- An output template for the title of the SponsorBlock chapters created by
- --sponsorblock-mark.
- The only available fields are start_time, end_time, category,
- categories, name, category_names.
- Defaults to \[dq][SponsorBlock]: %(category_names)l\[dq]
- .TP
- --no-sponsorblock
- Disable both --sponsorblock-mark and --sponsorblock-remove
- .TP
- --sponsorblock-api \f[I]URL\f[R]
- SponsorBlock API location, defaults to https://sponsor.ajay.app
- .SS Extractor Options:
- .TP
- --extractor-retries \f[I]RETRIES\f[R]
- Number of retries for known extractor errors (default is 3), or
- \[dq]infinite\[dq]
- .TP
- --allow-dynamic-mpd
- Process dynamic DASH manifests (default) (Alias:
- --no-ignore-dynamic-mpd)
- .TP
- --ignore-dynamic-mpd
- Do not process dynamic DASH manifests (Alias: --no-allow-dynamic-mpd)
- .TP
- --hls-split-discontinuity
- Split HLS playlists to different formats at discontinuities such as ad
- breaks
- .TP
- --no-hls-split-discontinuity
- Do not split HLS playlists into different formats at discontinuities
- such as ad breaks (default)
- .TP
- --extractor-args \f[I]IE_KEY:ARGS\f[R]
- Pass ARGS arguments to the IE_KEY extractor.
- See \[dq]EXTRACTOR ARGUMENTS\[dq] for details.
- You can use this option multiple times to give arguments for different
- extractors
- .SH CONFIGURATION
- .PP
- You can configure yt-dlp by placing any supported command line option in
- a configuration file.
- The configuration is loaded from the following locations:
- .IP "1." 3
- \f[B]Main Configuration\f[R]:
- .RS 4
- .IP \[bu] 2
- The file given to \f[C]--config-location\f[R]
- .RE
- .IP "2." 3
- \f[B]Portable Configuration\f[R]: (Recommended for portable
- installations)
- .RS 4
- .IP \[bu] 2
- If using a binary, \f[C]yt-dlp.conf\f[R] in the same directory as the
- binary
- .IP \[bu] 2
- If running from source-code, \f[C]yt-dlp.conf\f[R] in the parent
- directory of \f[C]yt_dlp\f[R]
- .RE
- .IP "3." 3
- \f[B]Home Configuration\f[R]:
- .RS 4
- .IP \[bu] 2
- \f[C]yt-dlp.conf\f[R] in the home path given to \f[C]-P\f[R]
- .IP \[bu] 2
- If \f[C]-P\f[R] is not given, the current directory is searched
- .RE
- .IP "4." 3
- \f[B]User Configuration\f[R]:
- .RS 4
- .IP \[bu] 2
- \f[C]${XDG_CONFIG_HOME}/yt-dlp.conf\f[R]
- .IP \[bu] 2
- \f[C]${XDG_CONFIG_HOME}/yt-dlp/config\f[R] (recommended on Linux/macOS)
- .IP \[bu] 2
- \f[C]${XDG_CONFIG_HOME}/yt-dlp/config.txt\f[R]
- .IP \[bu] 2
- \f[C]${APPDATA}/yt-dlp.conf\f[R]
- .IP \[bu] 2
- \f[C]${APPDATA}/yt-dlp/config\f[R] (recommended on Windows)
- .IP \[bu] 2
- \f[C]${APPDATA}/yt-dlp/config.txt\f[R]
- .IP \[bu] 2
- \f[C]\[ti]/yt-dlp.conf\f[R]
- .IP \[bu] 2
- \f[C]\[ti]/yt-dlp.conf.txt\f[R]
- .IP \[bu] 2
- \f[C]\[ti]/.yt-dlp/config\f[R]
- .IP \[bu] 2
- \f[C]\[ti]/.yt-dlp/config.txt\f[R]
- See also: Notes about environment variables
- .RE
- .IP "5." 3
- \f[B]System Configuration\f[R]:
- .RS 4
- .IP \[bu] 2
- \f[C]/etc/yt-dlp.conf\f[R]
- .IP \[bu] 2
- \f[C]/etc/yt-dlp/config\f[R]
- .IP \[bu] 2
- \f[C]/etc/yt-dlp/config.txt\f[R]
- .RE
- .PP
- E.g.
- with the following configuration file, yt-dlp will always extract the
- audio, not copy the mtime, use a proxy and save all videos under
- \f[C]YouTube\f[R] directory in your home directory:
- .IP
- .nf
- \f[C]
- # Lines starting with # are comments
- # Always extract audio
- -x
- # Do not copy the mtime
- --no-mtime
- # Use this proxy
- --proxy 127.0.0.1:3128
- # Save all videos under YouTube directory in your home directory
- -o \[ti]/YouTube/%(title)s.%(ext)s
- \f[R]
- .fi
- .PP
- \f[B]Note\f[R]: Options in a configuration file are just the same
- options aka switches used in regular command line calls; thus there
- \f[B]must be no whitespace\f[R] after \f[C]-\f[R] or \f[C]--\f[R], e.g.
- \f[C]-o\f[R] or \f[C]--proxy\f[R] but not \f[C]- o\f[R] or
- \f[C]-- proxy\f[R].
- They must also be quoted when necessary, as if it were a UNIX shell.
- .PP
- You can use \f[C]--ignore-config\f[R] if you want to disable all
- configuration files for a particular yt-dlp run.
- If \f[C]--ignore-config\f[R] is found inside any configuration file, no
- further configuration will be loaded.
- For example, having the option in the portable configuration file
- prevents loading of home, user, and system configurations.
- Additionally, (for backward compatibility) if \f[C]--ignore-config\f[R]
- is found inside the system configuration file, the user configuration is
- not loaded.
- .SS Configuration file encoding
- .PP
- The configuration files are decoded according to the UTF BOM if present,
- and in the encoding from system locale otherwise.
- .PP
- If you want your file to be decoded differently, add
- \f[C]# coding: ENCODING\f[R] to the beginning of the file (e.g.
- \f[C]# coding: shift-jis\f[R]).
- There must be no characters before that, even spaces or BOM.
- .SS Authentication with netrc
- .PP
- You may also want to configure automatic credentials storage for
- extractors that support authentication (by providing login and password
- with \f[C]--username\f[R] and \f[C]--password\f[R]) in order not to pass
- credentials as command line arguments on every yt-dlp execution and
- prevent tracking plain text passwords in the shell command history.
- You can achieve this using a \f[C].netrc\f[R]
- file (https://stackoverflow.com/tags/.netrc/info) on a per-extractor
- basis.
- For that, you will need to create a \f[C].netrc\f[R] file in
- \f[C]--netrc-location\f[R] and restrict permissions to read/write by
- only you:
- .IP
- .nf
- \f[C]
- touch ${HOME}/.netrc
- chmod a-rwx,u+rw ${HOME}/.netrc
- \f[R]
- .fi
- .PP
- After that, you can add credentials for an extractor in the following
- format, where \f[I]extractor\f[R] is the name of the extractor in
- lowercase:
- .IP
- .nf
- \f[C]
- machine <extractor> login <username> password <password>
- \f[R]
- .fi
- .PP
- E.g.
- .IP
- .nf
- \f[C]
- machine youtube login myaccount\[at]gmail.com password my_youtube_password
- machine twitch login my_twitch_account_name password my_twitch_password
- \f[R]
- .fi
- .PP
- To activate authentication with the \f[C].netrc\f[R] file you should
- pass \f[C]--netrc\f[R] to yt-dlp or place it in the configuration file.
- .PP
- The default location of the .netrc file is \f[C]\[ti]\f[R] (see below).
- .PP
- As an alternative to using the \f[C].netrc\f[R] file, which has the
- disadvantage of keeping your passwords in a plain text file, you can
- configure a custom shell command to provide the credentials for an
- extractor.
- This is done by providing the \f[C]--netrc-cmd\f[R] parameter, it shall
- output the credentials in the netrc format and return \f[C]0\f[R] on
- success, other values will be treated as an error.
- \f[C]{}\f[R] in the command will be replaced by the name of the
- extractor to make it possible to select the credentials for the right
- extractor.
- .PP
- E.g.
- To use an encrypted \f[C].netrc\f[R] file stored as
- \f[C].authinfo.gpg\f[R]
- .IP
- .nf
- \f[C]
- yt-dlp --netrc-cmd \[aq]gpg --decrypt \[ti]/.authinfo.gpg\[aq] \[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]
- \f[R]
- .fi
- .SS Notes about environment variables
- .IP \[bu] 2
- Environment variables are normally specified as
- \f[C]${VARIABLE}\f[R]/\f[C]$VARIABLE\f[R] on UNIX and
- \f[C]%VARIABLE%\f[R] on Windows; but is always shown as
- \f[C]${VARIABLE}\f[R] in this documentation
- .IP \[bu] 2
- yt-dlp also allows using UNIX-style variables on Windows for path-like
- options; e.g.
- \f[C]--output\f[R], \f[C]--config-location\f[R]
- .IP \[bu] 2
- If unset, \f[C]${XDG_CONFIG_HOME}\f[R] defaults to
- \f[C]\[ti]/.config\f[R] and \f[C]${XDG_CACHE_HOME}\f[R] to
- \f[C]\[ti]/.cache\f[R]
- .IP \[bu] 2
- On Windows, \f[C]\[ti]\f[R] points to \f[C]${HOME}\f[R] if present; or,
- \f[C]${USERPROFILE}\f[R] or \f[C]${HOMEDRIVE}${HOMEPATH}\f[R] otherwise
- .IP \[bu] 2
- On Windows, \f[C]${USERPROFILE}\f[R] generally points to
- \f[C]C:\[rs]Users\[rs]<user name>\f[R] and \f[C]${APPDATA}\f[R] to
- \f[C]${USERPROFILE}\[rs]AppData\[rs]Roaming\f[R]
- .SH OUTPUT TEMPLATE
- .PP
- The \f[C]-o\f[R] option is used to indicate a template for the output
- file names while \f[C]-P\f[R] option is used to specify the path each
- type of file should be saved to.
- .PP
- The simplest usage of \f[C]-o\f[R] is not to set any template arguments
- when downloading a single file, like in
- \f[C]yt-dlp -o funny_video.flv \[dq]https://some/video\[dq]\f[R]
- (hard-coding file extension like this is \f[I]not\f[R] recommended and
- could break some post-processing).
- .PP
- It may however also contain special sequences that will be replaced when
- downloading each video.
- The special sequences may be formatted according to Python string
- formatting
- operations (https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting),
- e.g.
- \f[C]%(NAME)s\f[R] or \f[C]%(NAME)05d\f[R].
- To clarify, that is a percent symbol followed by a name in parentheses,
- followed by formatting operations.
- .PP
- The field names themselves (the part inside the parenthesis) can also
- have some special formatting:
- .IP "1." 3
- \f[B]Object traversal\f[R]: The dictionaries and lists available in
- metadata can be traversed by using a dot \f[C].\f[R] separator; e.g.
- \f[C]%(tags.0)s\f[R], \f[C]%(subtitles.en.-1.ext)s\f[R].
- You can do Python slicing with colon \f[C]:\f[R]; E.g.
- \f[C]%(id.3:7)s\f[R], \f[C]%(id.6:2:-1)s\f[R],
- \f[C]%(formats.:.format_id)s\f[R].
- Curly braces \f[C]{}\f[R] can be used to build dictionaries with only
- specific keys; e.g.
- \f[C]%(formats.:.{format_id,height})#j\f[R].
- An empty field name \f[C]%()s\f[R] refers to the entire infodict; e.g.
- \f[C]%(.{id,title})s\f[R].
- Note that all the fields that become available using this method are not
- listed below.
- Use \f[C]-j\f[R] to see such fields
- .IP "2." 3
- \f[B]Arithmetic\f[R]: Simple arithmetic can be done on numeric fields
- using \f[C]+\f[R], \f[C]-\f[R] and \f[C]*\f[R].
- E.g.
- \f[C]%(playlist_index+10)03d\f[R],
- \f[C]%(n_entries+1-playlist_index)d\f[R]
- .IP "3." 3
- \f[B]Date/time Formatting\f[R]: Date/time fields can be formatted
- according to strftime
- formatting (https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)
- by specifying it separated from the field name using a \f[C]>\f[R].
- E.g.
- \f[C]%(duration>%H-%M-%S)s\f[R], \f[C]%(upload_date>%Y-%m-%d)s\f[R],
- \f[C]%(epoch-3600>%H-%M-%S)s\f[R]
- .IP "4." 3
- \f[B]Alternatives\f[R]: Alternate fields can be specified separated with
- a \f[C],\f[R].
- E.g.
- \f[C]%(release_date>%Y,upload_date>%Y|Unknown)s\f[R]
- .IP "5." 3
- \f[B]Replacement\f[R]: A replacement value can be specified using a
- \f[C]&\f[R] separator according to the \f[C]str.format\f[R]
- mini-language (https://docs.python.org/3/library/string.html#format-specification-mini-language).
- If the field is \f[I]not\f[R] empty, this replacement value will be used
- instead of the actual field content.
- This is done after alternate fields are considered; thus the replacement
- is used if \f[I]any\f[R] of the alternative fields is \f[I]not\f[R]
- empty.
- E.g.
- \f[C]%(chapters&has chapters|no chapters)s\f[R],
- \f[C]%(title&TITLE={:>20}|NO TITLE)s\f[R]
- .IP "6." 3
- \f[B]Default\f[R]: A literal default value can be specified for when the
- field is empty using a \f[C]|\f[R] separator.
- This overrides \f[C]--output-na-placeholder\f[R].
- E.g.
- \f[C]%(uploader|Unknown)s\f[R]
- .IP "7." 3
- \f[B]More Conversions\f[R]: In addition to the normal format types
- \f[C]diouxXeEfFgGcrs\f[R], yt-dlp additionally supports converting to
- \f[C]B\f[R] = \f[B]B\f[R]ytes, \f[C]j\f[R] = \f[B]j\f[R]son (flag
- \f[C]#\f[R] for pretty-printing, \f[C]+\f[R] for Unicode), \f[C]h\f[R] =
- HTML escaping, \f[C]l\f[R] = a comma separated \f[B]l\f[R]ist (flag
- \f[C]#\f[R] for \f[C]\[rs]n\f[R] newline-separated), \f[C]q\f[R] = a
- string \f[B]q\f[R]uoted for the terminal (flag \f[C]#\f[R] to split a
- list into different arguments), \f[C]D\f[R] = add \f[B]D\f[R]ecimal
- suffixes (e.g.
- 10M) (flag \f[C]#\f[R] to use 1024 as factor), and \f[C]S\f[R] =
- \f[B]S\f[R]anitize as filename (flag \f[C]#\f[R] for restricted)
- .IP "8." 3
- \f[B]Unicode normalization\f[R]: The format type \f[C]U\f[R] can be used
- for NFC Unicode
- normalization (https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize).
- The alternate form flag (\f[C]#\f[R]) changes the normalization to NFD
- and the conversion flag \f[C]+\f[R] can be used for NFKC/NFKD
- compatibility equivalence normalization.
- E.g.
- \f[C]%(title)+.100U\f[R] is NFKC
- .PP
- To summarize, the general syntax for a field is:
- .IP
- .nf
- \f[C]
- %(name[.keys][addition][>strf][,alternate][&replacement][|default])[flags][width][.precision][length]type
- \f[R]
- .fi
- .PP
- Additionally, you can set different output templates for the various
- metadata files separately from the general output template by specifying
- the type of file followed by the template separated by a colon
- \f[C]:\f[R].
- The different file types supported are \f[C]subtitle\f[R],
- \f[C]thumbnail\f[R], \f[C]description\f[R], \f[C]annotation\f[R]
- (deprecated), \f[C]infojson\f[R], \f[C]link\f[R],
- \f[C]pl_thumbnail\f[R], \f[C]pl_description\f[R], \f[C]pl_infojson\f[R],
- \f[C]chapter\f[R], \f[C]pl_video\f[R].
- E.g.
- \f[C]-o \[dq]%(title)s.%(ext)s\[dq] -o \[dq]thumbnail:%(title)s\[rs]%(title)s.%(ext)s\[dq]\f[R]
- will put the thumbnails in a folder with the same name as the video.
- If any of the templates is empty, that type of file will not be written.
- E.g.
- \f[C]--write-thumbnail -o \[dq]thumbnail:\[dq]\f[R] will write
- thumbnails only for playlists and not for video.
- .PP
- .PP
- \f[B]Note\f[R]: Due to post-processing (i.e.
- merging etc.), the actual output filename might differ.
- Use \f[C]--print after_move:filepath\f[R] to get the name after all
- post-processing is complete.
- .PP
- The available fields are:
- .IP \[bu] 2
- \f[C]id\f[R] (string): Video identifier
- .IP \[bu] 2
- \f[C]title\f[R] (string): Video title
- .IP \[bu] 2
- \f[C]fulltitle\f[R] (string): Video title ignoring live timestamp and
- generic title
- .IP \[bu] 2
- \f[C]ext\f[R] (string): Video filename extension
- .IP \[bu] 2
- \f[C]alt_title\f[R] (string): A secondary title of the video
- .IP \[bu] 2
- \f[C]description\f[R] (string): The description of the video
- .IP \[bu] 2
- \f[C]display_id\f[R] (string): An alternative identifier for the video
- .IP \[bu] 2
- \f[C]uploader\f[R] (string): Full name of the video uploader
- .IP \[bu] 2
- \f[C]uploader_id\f[R] (string): Nickname or id of the video uploader
- .IP \[bu] 2
- \f[C]uploader_url\f[R] (string): URL to the video uploader\[aq]s profile
- .IP \[bu] 2
- \f[C]license\f[R] (string): License name the video is licensed under
- .IP \[bu] 2
- \f[C]creators\f[R] (list): The creators of the video
- .IP \[bu] 2
- \f[C]creator\f[R] (string): The creators of the video; comma-separated
- .IP \[bu] 2
- \f[C]timestamp\f[R] (numeric): UNIX timestamp of the moment the video
- became available
- .IP \[bu] 2
- \f[C]upload_date\f[R] (string): Video upload date in UTC (YYYYMMDD)
- .IP \[bu] 2
- \f[C]release_timestamp\f[R] (numeric): UNIX timestamp of the moment the
- video was released
- .IP \[bu] 2
- \f[C]release_date\f[R] (string): The date (YYYYMMDD) when the video was
- released in UTC
- .IP \[bu] 2
- \f[C]release_year\f[R] (numeric): Year (YYYY) when the video or album
- was released
- .IP \[bu] 2
- \f[C]modified_timestamp\f[R] (numeric): UNIX timestamp of the moment the
- video was last modified
- .IP \[bu] 2
- \f[C]modified_date\f[R] (string): The date (YYYYMMDD) when the video was
- last modified in UTC
- .IP \[bu] 2
- \f[C]channel\f[R] (string): Full name of the channel the video is
- uploaded on
- .IP \[bu] 2
- \f[C]channel_id\f[R] (string): Id of the channel
- .IP \[bu] 2
- \f[C]channel_url\f[R] (string): URL of the channel
- .IP \[bu] 2
- \f[C]channel_follower_count\f[R] (numeric): Number of followers of the
- channel
- .IP \[bu] 2
- \f[C]channel_is_verified\f[R] (boolean): Whether the channel is verified
- on the platform
- .IP \[bu] 2
- \f[C]location\f[R] (string): Physical location where the video was
- filmed
- .IP \[bu] 2
- \f[C]duration\f[R] (numeric): Length of the video in seconds
- .IP \[bu] 2
- \f[C]duration_string\f[R] (string): Length of the video (HH:mm:ss)
- .IP \[bu] 2
- \f[C]view_count\f[R] (numeric): How many users have watched the video on
- the platform
- .IP \[bu] 2
- \f[C]concurrent_view_count\f[R] (numeric): How many users are currently
- watching the video on the platform.
- .IP \[bu] 2
- \f[C]like_count\f[R] (numeric): Number of positive ratings of the video
- .IP \[bu] 2
- \f[C]dislike_count\f[R] (numeric): Number of negative ratings of the
- video
- .IP \[bu] 2
- \f[C]repost_count\f[R] (numeric): Number of reposts of the video
- .IP \[bu] 2
- \f[C]average_rating\f[R] (numeric): Average rating given by users, the
- scale used depends on the webpage
- .IP \[bu] 2
- \f[C]comment_count\f[R] (numeric): Number of comments on the video (For
- some extractors, comments are only downloaded at the end, and so this
- field cannot be used)
- .IP \[bu] 2
- \f[C]age_limit\f[R] (numeric): Age restriction for the video (years)
- .IP \[bu] 2
- \f[C]live_status\f[R] (string): One of \[dq]not_live\[dq],
- \[dq]is_live\[dq], \[dq]is_upcoming\[dq], \[dq]was_live\[dq],
- \[dq]post_live\[dq] (was live, but VOD is not yet processed)
- .IP \[bu] 2
- \f[C]is_live\f[R] (boolean): Whether this video is a live stream or a
- fixed-length video
- .IP \[bu] 2
- \f[C]was_live\f[R] (boolean): Whether this video was originally a live
- stream
- .IP \[bu] 2
- \f[C]playable_in_embed\f[R] (string): Whether this video is allowed to
- play in embedded players on other sites
- .IP \[bu] 2
- \f[C]availability\f[R] (string): Whether the video is \[dq]private\[dq],
- \[dq]premium_only\[dq], \[dq]subscriber_only\[dq], \[dq]needs_auth\[dq],
- \[dq]unlisted\[dq] or \[dq]public\[dq]
- .IP \[bu] 2
- \f[C]media_type\f[R] (string): The type of media as classified by the
- site, e.g.
- \[dq]episode\[dq], \[dq]clip\[dq], \[dq]trailer\[dq]
- .IP \[bu] 2
- \f[C]start_time\f[R] (numeric): Time in seconds where the reproduction
- should start, as specified in the URL
- .IP \[bu] 2
- \f[C]end_time\f[R] (numeric): Time in seconds where the reproduction
- should end, as specified in the URL
- .IP \[bu] 2
- \f[C]extractor\f[R] (string): Name of the extractor
- .IP \[bu] 2
- \f[C]extractor_key\f[R] (string): Key name of the extractor
- .IP \[bu] 2
- \f[C]epoch\f[R] (numeric): Unix epoch of when the information extraction
- was completed
- .IP \[bu] 2
- \f[C]autonumber\f[R] (numeric): Number that will be increased with each
- download, starting at \f[C]--autonumber-start\f[R], padded with leading
- zeros to 5 digits
- .IP \[bu] 2
- \f[C]video_autonumber\f[R] (numeric): Number that will be increased with
- each video
- .IP \[bu] 2
- \f[C]n_entries\f[R] (numeric): Total number of extracted items in the
- playlist
- .IP \[bu] 2
- \f[C]playlist_id\f[R] (string): Identifier of the playlist that contains
- the video
- .IP \[bu] 2
- \f[C]playlist_title\f[R] (string): Name of the playlist that contains
- the video
- .IP \[bu] 2
- \f[C]playlist\f[R] (string): \f[C]playlist_title\f[R] if available or
- else \f[C]playlist_id\f[R]
- .IP \[bu] 2
- \f[C]playlist_count\f[R] (numeric): Total number of items in the
- playlist.
- May not be known if entire playlist is not extracted
- .IP \[bu] 2
- \f[C]playlist_index\f[R] (numeric): Index of the video in the playlist
- padded with leading zeros according the final index
- .IP \[bu] 2
- \f[C]playlist_autonumber\f[R] (numeric): Position of the video in the
- playlist download queue padded with leading zeros according to the total
- length of the playlist
- .IP \[bu] 2
- \f[C]playlist_uploader\f[R] (string): Full name of the playlist uploader
- .IP \[bu] 2
- \f[C]playlist_uploader_id\f[R] (string): Nickname or id of the playlist
- uploader
- .IP \[bu] 2
- \f[C]playlist_channel\f[R] (string): Display name of the channel that
- uploaded the playlist
- .IP \[bu] 2
- \f[C]playlist_channel_id\f[R] (string): Identifier of the channel that
- uploaded the playlist
- .IP \[bu] 2
- \f[C]playlist_webpage_url\f[R] (string): URL of the playlist webpage
- .IP \[bu] 2
- \f[C]webpage_url\f[R] (string): A URL to the video webpage which, if
- given to yt-dlp, should yield the same result again
- .IP \[bu] 2
- \f[C]webpage_url_basename\f[R] (string): The basename of the webpage URL
- .IP \[bu] 2
- \f[C]webpage_url_domain\f[R] (string): The domain of the webpage URL
- .IP \[bu] 2
- \f[C]original_url\f[R] (string): The URL given by the user (or the same
- as \f[C]webpage_url\f[R] for playlist entries)
- .IP \[bu] 2
- \f[C]categories\f[R] (list): List of categories the video belongs to
- .IP \[bu] 2
- \f[C]tags\f[R] (list): List of tags assigned to the video
- .IP \[bu] 2
- \f[C]cast\f[R] (list): List of cast members
- .PP
- All the fields in Filtering Formats can also be used
- .PP
- Available for the video that belongs to some logical chapter or section:
- .IP \[bu] 2
- \f[C]chapter\f[R] (string): Name or title of the chapter the video
- belongs to
- .IP \[bu] 2
- \f[C]chapter_number\f[R] (numeric): Number of the chapter the video
- belongs to
- .IP \[bu] 2
- \f[C]chapter_id\f[R] (string): Id of the chapter the video belongs to
- .PP
- Available for the video that is an episode of some series or program:
- .IP \[bu] 2
- \f[C]series\f[R] (string): Title of the series or program the video
- episode belongs to
- .IP \[bu] 2
- \f[C]series_id\f[R] (string): Id of the series or program the video
- episode belongs to
- .IP \[bu] 2
- \f[C]season\f[R] (string): Title of the season the video episode belongs
- to
- .IP \[bu] 2
- \f[C]season_number\f[R] (numeric): Number of the season the video
- episode belongs to
- .IP \[bu] 2
- \f[C]season_id\f[R] (string): Id of the season the video episode belongs
- to
- .IP \[bu] 2
- \f[C]episode\f[R] (string): Title of the video episode
- .IP \[bu] 2
- \f[C]episode_number\f[R] (numeric): Number of the video episode within a
- season
- .IP \[bu] 2
- \f[C]episode_id\f[R] (string): Id of the video episode
- .PP
- Available for the media that is a track or a part of a music album:
- .IP \[bu] 2
- \f[C]track\f[R] (string): Title of the track
- .IP \[bu] 2
- \f[C]track_number\f[R] (numeric): Number of the track within an album or
- a disc
- .IP \[bu] 2
- \f[C]track_id\f[R] (string): Id of the track
- .IP \[bu] 2
- \f[C]artists\f[R] (list): Artist(s) of the track
- .IP \[bu] 2
- \f[C]artist\f[R] (string): Artist(s) of the track; comma-separated
- .IP \[bu] 2
- \f[C]genres\f[R] (list): Genre(s) of the track
- .IP \[bu] 2
- \f[C]genre\f[R] (string): Genre(s) of the track; comma-separated
- .IP \[bu] 2
- \f[C]composers\f[R] (list): Composer(s) of the piece
- .IP \[bu] 2
- \f[C]composer\f[R] (string): Composer(s) of the piece; comma-separated
- .IP \[bu] 2
- \f[C]album\f[R] (string): Title of the album the track belongs to
- .IP \[bu] 2
- \f[C]album_type\f[R] (string): Type of the album
- .IP \[bu] 2
- \f[C]album_artists\f[R] (list): All artists appeared on the album
- .IP \[bu] 2
- \f[C]album_artist\f[R] (string): All artists appeared on the album;
- comma-separated
- .IP \[bu] 2
- \f[C]disc_number\f[R] (numeric): Number of the disc or other physical
- medium the track belongs to
- .PP
- Available only when using \f[C]--download-sections\f[R] and for
- \f[C]chapter:\f[R] prefix when using \f[C]--split-chapters\f[R] for
- videos with internal chapters:
- .IP \[bu] 2
- \f[C]section_title\f[R] (string): Title of the chapter
- .IP \[bu] 2
- \f[C]section_number\f[R] (numeric): Number of the chapter within the
- file
- .IP \[bu] 2
- \f[C]section_start\f[R] (numeric): Start time of the chapter in seconds
- .IP \[bu] 2
- \f[C]section_end\f[R] (numeric): End time of the chapter in seconds
- .PP
- Available only when used in \f[C]--print\f[R]:
- .IP \[bu] 2
- \f[C]urls\f[R] (string): The URLs of all requested formats, one in each
- line
- .IP \[bu] 2
- \f[C]filename\f[R] (string): Name of the video file.
- Note that the actual filename may differ
- .IP \[bu] 2
- \f[C]formats_table\f[R] (table): The video format table as printed by
- \f[C]--list-formats\f[R]
- .IP \[bu] 2
- \f[C]thumbnails_table\f[R] (table): The thumbnail format table as
- printed by \f[C]--list-thumbnails\f[R]
- .IP \[bu] 2
- \f[C]subtitles_table\f[R] (table): The subtitle format table as printed
- by \f[C]--list-subs\f[R]
- .IP \[bu] 2
- \f[C]automatic_captions_table\f[R] (table): The automatic subtitle
- format table as printed by \f[C]--list-subs\f[R]
- .PP
- Available only after the video is downloaded
- (\f[C]post_process\f[R]/\f[C]after_move\f[R]):
- .IP \[bu] 2
- \f[C]filepath\f[R]: Actual path of downloaded video file
- .PP
- Available only in \f[C]--sponsorblock-chapter-title\f[R]:
- .IP \[bu] 2
- \f[C]start_time\f[R] (numeric): Start time of the chapter in seconds
- .IP \[bu] 2
- \f[C]end_time\f[R] (numeric): End time of the chapter in seconds
- .IP \[bu] 2
- \f[C]categories\f[R] (list): The SponsorBlock
- categories (https://wiki.sponsor.ajay.app/w/Types#Category) the chapter
- belongs to
- .IP \[bu] 2
- \f[C]category\f[R] (string): The smallest SponsorBlock category the
- chapter belongs to
- .IP \[bu] 2
- \f[C]category_names\f[R] (list): Friendly names of the categories
- .IP \[bu] 2
- \f[C]name\f[R] (string): Friendly name of the smallest category
- .IP \[bu] 2
- \f[C]type\f[R] (string): The SponsorBlock action
- type (https://wiki.sponsor.ajay.app/w/Types#Action_Type) of the chapter
- .PP
- Each aforementioned sequence when referenced in an output template will
- be replaced by the actual value corresponding to the sequence name.
- E.g.
- for \f[C]-o %(title)s-%(id)s.%(ext)s\f[R] and an mp4 video with title
- \f[C]yt-dlp test video\f[R] and id \f[C]BaW_jenozKc\f[R], this will
- result in a \f[C]yt-dlp test video-BaW_jenozKc.mp4\f[R] file created in
- the current directory.
- .PP
- \f[B]Note\f[R]: Some of the sequences are not guaranteed to be present,
- since they depend on the metadata obtained by a particular extractor.
- Such sequences will be replaced with placeholder value provided with
- \f[C]--output-na-placeholder\f[R] (\f[C]NA\f[R] by default).
- .PP
- \f[B]Tip\f[R]: Look at the \f[C]-j\f[R] output to identify which fields
- are available for the particular URL
- .PP
- For numeric sequences, you can use numeric related
- formatting (https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting);
- e.g.
- \f[C]%(view_count)05d\f[R] will result in a string with view count
- padded with zeros up to 5 characters, like in \f[C]00042\f[R].
- .PP
- Output templates can also contain arbitrary hierarchical path, e.g.
- \f[C]-o \[dq]%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s\[dq]\f[R]
- which will result in downloading each video in a directory corresponding
- to this path template.
- Any missing directory will be automatically created for you.
- .PP
- To use percent literals in an output template use \f[C]%%\f[R].
- To output to stdout use \f[C]-o -\f[R].
- .PP
- The current default template is \f[C]%(title)s [%(id)s].%(ext)s\f[R].
- .PP
- In some cases, you don\[aq]t want special characters such as \[u4E2D],
- spaces, or &, such as when transferring the downloaded filename to a
- Windows system or the filename through an 8bit-unsafe channel.
- In these cases, add the \f[C]--restrict-filenames\f[R] flag to get a
- shorter title.
- .SS Output template examples
- .IP
- .nf
- \f[C]
- $ yt-dlp --print filename -o \[dq]test video.%(ext)s\[dq] BaW_jenozKc
- test video.webm # Literal name with correct extension
- $ yt-dlp --print filename -o \[dq]%(title)s.%(ext)s\[dq] BaW_jenozKc
- youtube-dl test video \[aq]\[aq]_\[:a]\[u21AD]\[u1D550].webm # All kinds of weird characters
- $ yt-dlp --print filename -o \[dq]%(title)s.%(ext)s\[dq] BaW_jenozKc --restrict-filenames
- youtube-dl_test_video_.webm # Restricted file name
- # Download YouTube playlist videos in separate directory indexed by video order in a playlist
- $ yt-dlp -o \[dq]%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s\[dq] \[dq]https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re\[dq]
- # Download YouTube playlist videos in separate directories according to their uploaded year
- $ yt-dlp -o \[dq]%(upload_date>%Y)s/%(title)s.%(ext)s\[dq] \[dq]https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re\[dq]
- # Prefix playlist index with \[dq] - \[dq] separator, but only if it is available
- $ yt-dlp -o \[dq]%(playlist_index&{} - |)s%(title)s.%(ext)s\[dq] BaW_jenozKc \[dq]https://www.youtube.com/user/TheLinuxFoundation/playlists\[dq]
- # Download all playlists of YouTube channel/user keeping each playlist in separate directory:
- $ yt-dlp -o \[dq]%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s\[dq] \[dq]https://www.youtube.com/user/TheLinuxFoundation/playlists\[dq]
- # Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
- $ yt-dlp -u user -p password -P \[dq]\[ti]/MyVideos\[dq] -o \[dq]%(playlist)s/%(chapter_number)s - %(chapter)s/%(title)s.%(ext)s\[dq] \[dq]https://www.udemy.com/java-tutorial\[dq]
- # Download entire series season keeping each series and each season in separate directory under C:/MyVideos
- $ yt-dlp -P \[dq]C:/MyVideos\[dq] -o \[dq]%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s\[dq] \[dq]https://videomore.ru/kino_v_detalayah/5_sezon/367617\[dq]
- # Download video as \[dq]C:\[rs]MyVideos\[rs]uploader\[rs]title.ext\[dq], subtitles as \[dq]C:\[rs]MyVideos\[rs]subs\[rs]uploader\[rs]title.ext\[dq]
- # and put all temporary files in \[dq]C:\[rs]MyVideos\[rs]tmp\[dq]
- $ yt-dlp -P \[dq]C:/MyVideos\[dq] -P \[dq]temp:tmp\[dq] -P \[dq]subtitle:subs\[dq] -o \[dq]%(uploader)s/%(title)s.%(ext)s\[dq] BaW_jenozKc --write-subs
- # Download video as \[dq]C:\[rs]MyVideos\[rs]uploader\[rs]title.ext\[dq] and subtitles as \[dq]C:\[rs]MyVideos\[rs]uploader\[rs]subs\[rs]title.ext\[dq]
- $ yt-dlp -P \[dq]C:/MyVideos\[dq] -o \[dq]%(uploader)s/%(title)s.%(ext)s\[dq] -o \[dq]subtitle:%(uploader)s/subs/%(title)s.%(ext)s\[dq] BaW_jenozKc --write-subs
- # Stream the video being downloaded to stdout
- $ yt-dlp -o - BaW_jenozKc
- \f[R]
- .fi
- .SH FORMAT SELECTION
- .PP
- By default, yt-dlp tries to download the best available quality if you
- \f[B]don\[aq]t\f[R] pass any options.
- This is generally equivalent to using
- \f[C]-f bestvideo*+bestaudio/best\f[R].
- However, if multiple audiostreams is enabled
- (\f[C]--audio-multistreams\f[R]), the default format changes to
- \f[C]-f bestvideo+bestaudio/best\f[R].
- Similarly, if ffmpeg is unavailable, or if you use yt-dlp to stream to
- \f[C]stdout\f[R] (\f[C]-o -\f[R]), the default becomes
- \f[C]-f best/bestvideo+bestaudio\f[R].
- .PP
- \f[B]Deprecation warning\f[R]: Latest versions of yt-dlp can stream
- multiple formats to the stdout simultaneously using ffmpeg.
- So, in future versions, the default for this will be set to
- \f[C]-f bv*+ba/b\f[R] similar to normal downloads.
- If you want to preserve the \f[C]-f b/bv+ba\f[R] setting, it is
- recommended to explicitly specify it in the configuration options.
- .PP
- The general syntax for format selection is \f[C]-f FORMAT\f[R] (or
- \f[C]--format FORMAT\f[R]) where \f[C]FORMAT\f[R] is a \f[I]selector
- expression\f[R], i.e.
- an expression that describes format or formats you would like to
- download.
- .PP
- The simplest case is requesting a specific format; e.g.
- with \f[C]-f 22\f[R] you can download the format with format code equal
- to 22.
- You can get the list of available format codes for particular video
- using \f[C]--list-formats\f[R] or \f[C]-F\f[R].
- Note that these format codes are extractor specific.
- .PP
- You can also use a file extension (currently \f[C]3gp\f[R],
- \f[C]aac\f[R], \f[C]flv\f[R], \f[C]m4a\f[R], \f[C]mp3\f[R],
- \f[C]mp4\f[R], \f[C]ogg\f[R], \f[C]wav\f[R], \f[C]webm\f[R] are
- supported) to download the best quality format of a particular file
- extension served as a single file, e.g.
- \f[C]-f webm\f[R] will download the best quality format with the
- \f[C]webm\f[R] extension served as a single file.
- .PP
- You can use \f[C]-f -\f[R] to interactively provide the format selector
- \f[I]for each video\f[R]
- .PP
- You can also use special names to select particular edge case formats:
- .IP \[bu] 2
- \f[C]all\f[R]: Select \f[B]all formats\f[R] separately
- .IP \[bu] 2
- \f[C]mergeall\f[R]: Select and \f[B]merge all formats\f[R] (Must be used
- with \f[C]--audio-multistreams\f[R], \f[C]--video-multistreams\f[R] or
- both)
- .IP \[bu] 2
- \f[C]b*\f[R], \f[C]best*\f[R]: Select the best quality format that
- \f[B]contains either\f[R] a video or an audio or both (i.e.;
- \f[C]vcodec!=none or acodec!=none\f[R])
- .IP \[bu] 2
- \f[C]b\f[R], \f[C]best\f[R]: Select the best quality format that
- \f[B]contains both\f[R] video and audio.
- Equivalent to \f[C]best*[vcodec!=none][acodec!=none]\f[R]
- .IP \[bu] 2
- \f[C]bv\f[R], \f[C]bestvideo\f[R]: Select the best quality
- \f[B]video-only\f[R] format.
- Equivalent to \f[C]best*[acodec=none]\f[R]
- .IP \[bu] 2
- \f[C]bv*\f[R], \f[C]bestvideo*\f[R]: Select the best quality format that
- \f[B]contains video\f[R].
- It may also contain audio.
- Equivalent to \f[C]best*[vcodec!=none]\f[R]
- .IP \[bu] 2
- \f[C]ba\f[R], \f[C]bestaudio\f[R]: Select the best quality
- \f[B]audio-only\f[R] format.
- Equivalent to \f[C]best*[vcodec=none]\f[R]
- .IP \[bu] 2
- \f[C]ba*\f[R], \f[C]bestaudio*\f[R]: Select the best quality format that
- \f[B]contains audio\f[R].
- It may also contain video.
- Equivalent to \f[C]best*[acodec!=none]\f[R] (Do not
- use! (https://github.com/yt-dlp/yt-dlp/issues/979#issuecomment-919629354))
- .IP \[bu] 2
- \f[C]w*\f[R], \f[C]worst*\f[R]: Select the worst quality format that
- contains either a video or an audio
- .IP \[bu] 2
- \f[C]w\f[R], \f[C]worst\f[R]: Select the worst quality format that
- contains both video and audio.
- Equivalent to \f[C]worst*[vcodec!=none][acodec!=none]\f[R]
- .IP \[bu] 2
- \f[C]wv\f[R], \f[C]worstvideo\f[R]: Select the worst quality video-only
- format.
- Equivalent to \f[C]worst*[acodec=none]\f[R]
- .IP \[bu] 2
- \f[C]wv*\f[R], \f[C]worstvideo*\f[R]: Select the worst quality format
- that contains video.
- It may also contain audio.
- Equivalent to \f[C]worst*[vcodec!=none]\f[R]
- .IP \[bu] 2
- \f[C]wa\f[R], \f[C]worstaudio\f[R]: Select the worst quality audio-only
- format.
- Equivalent to \f[C]worst*[vcodec=none]\f[R]
- .IP \[bu] 2
- \f[C]wa*\f[R], \f[C]worstaudio*\f[R]: Select the worst quality format
- that contains audio.
- It may also contain video.
- Equivalent to \f[C]worst*[acodec!=none]\f[R]
- .PP
- For example, to download the worst quality video-only format you can use
- \f[C]-f worstvideo\f[R].
- It is, however, recommended not to use \f[C]worst\f[R] and related
- options.
- When your format selector is \f[C]worst\f[R], the format which is worst
- in all respects is selected.
- Most of the time, what you actually want is the video with the smallest
- filesize instead.
- So it is generally better to use \f[C]-S +size\f[R] or more rigorously,
- \f[C]-S +size,+br,+res,+fps\f[R] instead of \f[C]-f worst\f[R].
- See Sorting Formats for more details.
- .PP
- You can select the n\[aq]th best format of a type by using
- \f[C]best<type>.<n>\f[R].
- For example, \f[C]best.2\f[R] will select the 2nd best combined format.
- Similarly, \f[C]bv*.3\f[R] will select the 3rd best format that contains
- a video stream.
- .PP
- If you want to download multiple videos, and they don\[aq]t have the
- same formats available, you can specify the order of preference using
- slashes.
- Note that formats on the left hand side are preferred; e.g.
- \f[C]-f 22/17/18\f[R] will download format 22 if it\[aq]s available,
- otherwise it will download format 17 if it\[aq]s available, otherwise it
- will download format 18 if it\[aq]s available, otherwise it will
- complain that no suitable formats are available for download.
- .PP
- If you want to download several formats of the same video use a comma as
- a separator, e.g.
- \f[C]-f 22,17,18\f[R] will download all these three formats, of course
- if they are available.
- Or a more sophisticated example combined with the precedence feature:
- \f[C]-f 136/137/mp4/bestvideo,140/m4a/bestaudio\f[R].
- .PP
- You can merge the video and audio of multiple formats into a single file
- using \f[C]-f <format1>+<format2>+...\f[R] (requires ffmpeg installed);
- e.g.
- \f[C]-f bestvideo+bestaudio\f[R] will download the best video-only
- format, the best audio-only format and mux them together with ffmpeg.
- .PP
- \f[B]Deprecation warning\f[R]: Since the \f[I]below\f[R] described
- behavior is complex and counter-intuitive, this will be removed and
- multistreams will be enabled by default in the future.
- A new operator will be instead added to limit formats to single
- audio/video
- .PP
- Unless \f[C]--video-multistreams\f[R] is used, all formats with a video
- stream except the first one are ignored.
- Similarly, unless \f[C]--audio-multistreams\f[R] is used, all formats
- with an audio stream except the first one are ignored.
- E.g.
- \f[C]-f bestvideo+best+bestaudio --video-multistreams --audio-multistreams\f[R]
- will download and merge all 3 given formats.
- The resulting file will have 2 video streams and 2 audio streams.
- But \f[C]-f bestvideo+best+bestaudio --no-video-multistreams\f[R] will
- download and merge only \f[C]bestvideo\f[R] and \f[C]bestaudio\f[R].
- \f[C]best\f[R] is ignored since another format containing a video stream
- (\f[C]bestvideo\f[R]) has already been selected.
- The order of the formats is therefore important.
- \f[C]-f best+bestaudio --no-audio-multistreams\f[R] will download only
- \f[C]best\f[R] while \f[C]-f bestaudio+best --no-audio-multistreams\f[R]
- will ignore \f[C]best\f[R] and download only \f[C]bestaudio\f[R].
- .SS Filtering Formats
- .PP
- You can also filter the video formats by putting a condition in
- brackets, as in \f[C]-f \[dq]best[height=720]\[dq]\f[R] (or
- \f[C]-f \[dq][filesize>10M]\[dq]\f[R] since filters without a selector
- are interpreted as \f[C]best\f[R]).
- .PP
- The following numeric meta fields can be used with comparisons
- \f[C]<\f[R], \f[C]<=\f[R], \f[C]>\f[R], \f[C]>=\f[R], \f[C]=\f[R]
- (equals), \f[C]!=\f[R] (not equals):
- .IP \[bu] 2
- \f[C]filesize\f[R]: The number of bytes, if known in advance
- .IP \[bu] 2
- \f[C]filesize_approx\f[R]: An estimate for the number of bytes
- .IP \[bu] 2
- \f[C]width\f[R]: Width of the video, if known
- .IP \[bu] 2
- \f[C]height\f[R]: Height of the video, if known
- .IP \[bu] 2
- \f[C]aspect_ratio\f[R]: Aspect ratio of the video, if known
- .IP \[bu] 2
- \f[C]tbr\f[R]: Average bitrate of audio and video in kbps
- .IP \[bu] 2
- \f[C]abr\f[R]: Average audio bitrate in kbps
- .IP \[bu] 2
- \f[C]vbr\f[R]: Average video bitrate in kbps
- .IP \[bu] 2
- \f[C]asr\f[R]: Audio sampling rate in Hertz
- .IP \[bu] 2
- \f[C]fps\f[R]: Frame rate
- .IP \[bu] 2
- \f[C]audio_channels\f[R]: The number of audio channels
- .IP \[bu] 2
- \f[C]stretched_ratio\f[R]: \f[C]width:height\f[R] of the video\[aq]s
- pixels, if not square
- .PP
- Also filtering work for comparisons \f[C]=\f[R] (equals),
- \f[C]\[ha]=\f[R] (starts with), \f[C]$=\f[R] (ends with), \f[C]*=\f[R]
- (contains), \f[C]\[ti]=\f[R] (matches regex) and following string meta
- fields:
- .IP \[bu] 2
- \f[C]url\f[R]: Video URL
- .IP \[bu] 2
- \f[C]ext\f[R]: File extension
- .IP \[bu] 2
- \f[C]acodec\f[R]: Name of the audio codec in use
- .IP \[bu] 2
- \f[C]vcodec\f[R]: Name of the video codec in use
- .IP \[bu] 2
- \f[C]container\f[R]: Name of the container format
- .IP \[bu] 2
- \f[C]protocol\f[R]: The protocol that will be used for the actual
- download, lower-case (\f[C]http\f[R], \f[C]https\f[R], \f[C]rtsp\f[R],
- \f[C]rtmp\f[R], \f[C]rtmpe\f[R], \f[C]mms\f[R], \f[C]f4m\f[R],
- \f[C]ism\f[R], \f[C]http_dash_segments\f[R], \f[C]m3u8\f[R], or
- \f[C]m3u8_native\f[R])
- .IP \[bu] 2
- \f[C]language\f[R]: Language code
- .IP \[bu] 2
- \f[C]dynamic_range\f[R]: The dynamic range of the video
- .IP \[bu] 2
- \f[C]format_id\f[R]: A short description of the format
- .IP \[bu] 2
- \f[C]format\f[R]: A human-readable description of the format
- .IP \[bu] 2
- \f[C]format_note\f[R]: Additional info about the format
- .IP \[bu] 2
- \f[C]resolution\f[R]: Textual description of width and height
- .PP
- Any string comparison may be prefixed with negation \f[C]!\f[R] in order
- to produce an opposite comparison, e.g.
- \f[C]!*=\f[R] (does not contain).
- The comparand of a string comparison needs to be quoted with either
- double or single quotes if it contains spaces or special characters
- other than \f[C]._-\f[R].
- .PP
- \f[B]Note\f[R]: None of the aforementioned meta fields are guaranteed to
- be present since this solely depends on the metadata obtained by the
- particular extractor, i.e.
- the metadata offered by the website.
- Any other field made available by the extractor can also be used for
- filtering.
- .PP
- Formats for which the value is not known are excluded unless you put a
- question mark (\f[C]?\f[R]) after the operator.
- You can combine format filters, so
- \f[C]-f \[dq]bv[height<=?720][tbr>500]\[dq]\f[R] selects up to 720p
- videos (or videos where the height is not known) with a bitrate of at
- least 500 kbps.
- You can also use the filters with \f[C]all\f[R] to download all formats
- that satisfy the filter, e.g.
- \f[C]-f \[dq]all[vcodec=none]\[dq]\f[R] selects all audio-only formats.
- .PP
- Format selectors can also be grouped using parentheses; e.g.
- \f[C]-f \[dq](mp4,webm)[height<480]\[dq]\f[R] will download the best
- pre-merged mp4 and webm formats with a height lower than 480.
- .SS Sorting Formats
- .PP
- You can change the criteria for being considered the \f[C]best\f[R] by
- using \f[C]-S\f[R] (\f[C]--format-sort\f[R]).
- The general format for this is \f[C]--format-sort field1,field2...\f[R].
- .PP
- The available fields are:
- .IP \[bu] 2
- \f[C]hasvid\f[R]: Gives priority to formats that have a video stream
- .IP \[bu] 2
- \f[C]hasaud\f[R]: Gives priority to formats that have an audio stream
- .IP \[bu] 2
- \f[C]ie_pref\f[R]: The format preference
- .IP \[bu] 2
- \f[C]lang\f[R]: The language preference
- .IP \[bu] 2
- \f[C]quality\f[R]: The quality of the format
- .IP \[bu] 2
- \f[C]source\f[R]: The preference of the source
- .IP \[bu] 2
- \f[C]proto\f[R]: Protocol used for download
- (\f[C]https\f[R]/\f[C]ftps\f[R] > \f[C]http\f[R]/\f[C]ftp\f[R] >
- \f[C]m3u8_native\f[R]/\f[C]m3u8\f[R] > \f[C]http_dash_segments\f[R]>
- \f[C]websocket_frag\f[R] > \f[C]mms\f[R]/\f[C]rtsp\f[R] >
- \f[C]f4f\f[R]/\f[C]f4m\f[R])
- .IP \[bu] 2
- \f[C]vcodec\f[R]: Video Codec (\f[C]av01\f[R] > \f[C]vp9.2\f[R] >
- \f[C]vp9\f[R] > \f[C]h265\f[R] > \f[C]h264\f[R] > \f[C]vp8\f[R] >
- \f[C]h263\f[R] > \f[C]theora\f[R] > other)
- .IP \[bu] 2
- \f[C]acodec\f[R]: Audio Codec (\f[C]flac\f[R]/\f[C]alac\f[R] >
- \f[C]wav\f[R]/\f[C]aiff\f[R] > \f[C]opus\f[R] > \f[C]vorbis\f[R] >
- \f[C]aac\f[R] > \f[C]mp4a\f[R] > \f[C]mp3\f[R] > \f[C]ac4\f[R] >
- \f[C]eac3\f[R] > \f[C]ac3\f[R] > \f[C]dts\f[R] > other)
- .IP \[bu] 2
- \f[C]codec\f[R]: Equivalent to \f[C]vcodec,acodec\f[R]
- .IP \[bu] 2
- \f[C]vext\f[R]: Video Extension (\f[C]mp4\f[R] > \f[C]mov\f[R] >
- \f[C]webm\f[R] > \f[C]flv\f[R] > other).
- If \f[C]--prefer-free-formats\f[R] is used, \f[C]webm\f[R] is preferred.
- .IP \[bu] 2
- \f[C]aext\f[R]: Audio Extension (\f[C]m4a\f[R] > \f[C]aac\f[R] >
- \f[C]mp3\f[R] > \f[C]ogg\f[R] > \f[C]opus\f[R] > \f[C]webm\f[R] >
- other).
- If \f[C]--prefer-free-formats\f[R] is used, the order changes to
- \f[C]ogg\f[R] > \f[C]opus\f[R] > \f[C]webm\f[R] > \f[C]mp3\f[R] >
- \f[C]m4a\f[R] > \f[C]aac\f[R]
- .IP \[bu] 2
- \f[C]ext\f[R]: Equivalent to \f[C]vext,aext\f[R]
- .IP \[bu] 2
- \f[C]filesize\f[R]: Exact filesize, if known in advance
- .IP \[bu] 2
- \f[C]fs_approx\f[R]: Approximate filesize
- .IP \[bu] 2
- \f[C]size\f[R]: Exact filesize if available, otherwise approximate
- filesize
- .IP \[bu] 2
- \f[C]height\f[R]: Height of video
- .IP \[bu] 2
- \f[C]width\f[R]: Width of video
- .IP \[bu] 2
- \f[C]res\f[R]: Video resolution, calculated as the smallest dimension.
- .IP \[bu] 2
- \f[C]fps\f[R]: Framerate of video
- .IP \[bu] 2
- \f[C]hdr\f[R]: The dynamic range of the video (\f[C]DV\f[R] >
- \f[C]HDR12\f[R] > \f[C]HDR10+\f[R] > \f[C]HDR10\f[R] > \f[C]HLG\f[R] >
- \f[C]SDR\f[R])
- .IP \[bu] 2
- \f[C]channels\f[R]: The number of audio channels
- .IP \[bu] 2
- \f[C]tbr\f[R]: Total average bitrate in kbps
- .IP \[bu] 2
- \f[C]vbr\f[R]: Average video bitrate in kbps
- .IP \[bu] 2
- \f[C]abr\f[R]: Average audio bitrate in kbps
- .IP \[bu] 2
- \f[C]br\f[R]: Average bitrate in kbps,
- \f[C]tbr\f[R]/\f[C]vbr\f[R]/\f[C]abr\f[R]
- .IP \[bu] 2
- \f[C]asr\f[R]: Audio sample rate in Hz
- .PP
- \f[B]Deprecation warning\f[R]: Many of these fields have (currently
- undocumented) aliases, that may be removed in a future version.
- It is recommended to use only the documented field names.
- .PP
- All fields, unless specified otherwise, are sorted in descending order.
- To reverse this, prefix the field with a \f[C]+\f[R].
- E.g.
- \f[C]+res\f[R] prefers format with the smallest resolution.
- Additionally, you can suffix a preferred value for the fields, separated
- by a \f[C]:\f[R].
- E.g.
- \f[C]res:720\f[R] prefers larger videos, but no larger than 720p and the
- smallest video if there are no videos less than 720p.
- For \f[C]codec\f[R] and \f[C]ext\f[R], you can provide two preferred
- values, the first for video and the second for audio.
- E.g.
- \f[C]+codec:avc:m4a\f[R] (equivalent to
- \f[C]+vcodec:avc,+acodec:m4a\f[R]) sets the video codec preference to
- \f[C]h264\f[R] > \f[C]h265\f[R] > \f[C]vp9\f[R] > \f[C]vp9.2\f[R] >
- \f[C]av01\f[R] > \f[C]vp8\f[R] > \f[C]h263\f[R] > \f[C]theora\f[R] and
- audio codec preference to \f[C]mp4a\f[R] > \f[C]aac\f[R] >
- \f[C]vorbis\f[R] > \f[C]opus\f[R] > \f[C]mp3\f[R] > \f[C]ac3\f[R] >
- \f[C]dts\f[R].
- You can also make the sorting prefer the nearest values to the provided
- by using \f[C]\[ti]\f[R] as the delimiter.
- E.g.
- \f[C]filesize\[ti]1G\f[R] prefers the format with filesize closest to 1
- GiB.
- .PP
- The fields \f[C]hasvid\f[R] and \f[C]ie_pref\f[R] are always given
- highest priority in sorting, irrespective of the user-defined order.
- This behavior can be changed by using \f[C]--format-sort-force\f[R].
- Apart from these, the default order used is:
- \f[C]lang,quality,res,fps,hdr:12,vcodec,channels,acodec,size,br,asr,proto,ext,hasaud,source,id\f[R].
- The extractors may override this default order, but they cannot override
- the user-provided order.
- .PP
- Note that the default for hdr is \f[C]hdr:12\f[R]; i.e.
- Dolby Vision is not preferred.
- This choice was made since DV formats are not yet fully compatible with
- most devices.
- This may be changed in the future.
- .PP
- If your format selector is \f[C]worst\f[R], the last item is selected
- after sorting.
- This means it will select the format that is worst in all respects.
- Most of the time, what you actually want is the video with the smallest
- filesize instead.
- So it is generally better to use
- \f[C]-f best -S +size,+br,+res,+fps\f[R].
- .PP
- \f[B]Tip\f[R]: You can use the \f[C]-v -F\f[R] to see how the formats
- have been sorted (worst to best).
- .SS Format Selection examples
- .IP
- .nf
- \f[C]
- # Download and merge the best video-only format and the best audio-only format,
- # or download the best combined format if video-only format is not available
- $ yt-dlp -f \[dq]bv+ba/b\[dq]
- # Download best format that contains video,
- # and if it doesn\[aq]t already have an audio stream, merge it with best audio-only format
- $ yt-dlp -f \[dq]bv*+ba/b\[dq]
- # Same as above
- $ yt-dlp
- # Download the best video-only format and the best audio-only format without merging them
- # For this case, an output template should be used since
- # by default, bestvideo and bestaudio will have the same file name.
- $ yt-dlp -f \[dq]bv,ba\[dq] -o \[dq]%(title)s.f%(format_id)s.%(ext)s\[dq]
- # Download and merge the best format that has a video stream,
- # and all audio-only formats into one file
- $ yt-dlp -f \[dq]bv*+mergeall[vcodec=none]\[dq] --audio-multistreams
- # Download and merge the best format that has a video stream,
- # and the best 2 audio-only formats into one file
- $ yt-dlp -f \[dq]bv*+ba+ba.2\[dq] --audio-multistreams
- # The following examples show the old method (without -S) of format selection
- # and how to use -S to achieve a similar but (generally) better result
- # Download the worst video available (old method)
- $ yt-dlp -f \[dq]wv*+wa/w\[dq]
- # Download the best video available but with the smallest resolution
- $ yt-dlp -S \[dq]+res\[dq]
- # Download the smallest video available
- $ yt-dlp -S \[dq]+size,+br\[dq]
- # Download the best mp4 video available, or the best video if no mp4 available
- $ yt-dlp -f \[dq]bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4] / bv*+ba/b\[dq]
- # Download the best video with the best extension
- # (For video, mp4 > mov > webm > flv. For audio, m4a > aac > mp3 ...)
- $ yt-dlp -S \[dq]ext\[dq]
- # Download the best video available but no better than 480p,
- # or the worst video if there is no video under 480p
- $ yt-dlp -f \[dq]bv*[height<=480]+ba/b[height<=480] / wv*+ba/w\[dq]
- # Download the best video available with the largest height but no better than 480p,
- # or the best video with the smallest resolution if there is no video under 480p
- $ yt-dlp -S \[dq]height:480\[dq]
- # Download the best video available with the largest resolution but no better than 480p,
- # or the best video with the smallest resolution if there is no video under 480p
- # Resolution is determined by using the smallest dimension.
- # So this works correctly for vertical videos as well
- $ yt-dlp -S \[dq]res:480\[dq]
- # Download the best video (that also has audio) but no bigger than 50 MB,
- # or the worst video (that also has audio) if there is no video under 50 MB
- $ yt-dlp -f \[dq]b[filesize<50M] / w\[dq]
- # Download the largest video (that also has audio) but no bigger than 50 MB,
- # or the smallest video (that also has audio) if there is no video under 50 MB
- $ yt-dlp -f \[dq]b\[dq] -S \[dq]filesize:50M\[dq]
- # Download the best video (that also has audio) that is closest in size to 50 MB
- $ yt-dlp -f \[dq]b\[dq] -S \[dq]filesize\[ti]50M\[dq]
- # Download best video available via direct link over HTTP/HTTPS protocol,
- # or the best video available via any protocol if there is no such video
- $ yt-dlp -f \[dq](bv*+ba/b)[protocol\[ha]=http][protocol!*=dash] / (bv*+ba/b)\[dq]
- # Download best video available via the best protocol
- # (https/ftps > http/ftp > m3u8_native > m3u8 > http_dash_segments ...)
- $ yt-dlp -S \[dq]proto\[dq]
- # Download the best video with either h264 or h265 codec,
- # or the best video if there is no such video
- $ yt-dlp -f \[dq](bv*[vcodec\[ti]=\[aq]\[ha]((he|a)vc|h26[45])\[aq]]+ba) / (bv*+ba/b)\[dq]
- # Download the best video with best codec no better than h264,
- # or the best video with worst codec if there is no such video
- $ yt-dlp -S \[dq]codec:h264\[dq]
- # Download the best video with worst codec no worse than h264,
- # or the best video with best codec if there is no such video
- $ yt-dlp -S \[dq]+codec:h264\[dq]
- # More complex examples
- # Download the best video no better than 720p preferring framerate greater than 30,
- # or the worst video (still preferring framerate greater than 30) if there is no such video
- $ yt-dlp -f \[dq]((bv*[fps>30]/bv*)[height<=720]/(wv*[fps>30]/wv*)) + ba / (b[fps>30]/b)[height<=720]/(w[fps>30]/w)\[dq]
- # Download the video with the largest resolution no better than 720p,
- # or the video with the smallest resolution available if there is no such video,
- # preferring larger framerate for formats with the same resolution
- $ yt-dlp -S \[dq]res:720,fps\[dq]
- # Download the video with smallest resolution no worse than 480p,
- # or the video with the largest resolution available if there is no such video,
- # preferring better codec and then larger total bitrate for the same resolution
- $ yt-dlp -S \[dq]+res:480,codec,br\[dq]
- \f[R]
- .fi
- .SH MODIFYING METADATA
- .PP
- The metadata obtained by the extractors can be modified by using
- \f[C]--parse-metadata\f[R] and \f[C]--replace-in-metadata\f[R]
- .PP
- \f[C]--replace-in-metadata FIELDS REGEX REPLACE\f[R] is used to replace
- text in any metadata field using Python regular
- expression (https://docs.python.org/3/library/re.html#regular-expression-syntax).
- Backreferences (https://docs.python.org/3/library/re.html?highlight=backreferences#re.sub)
- can be used in the replace string for advanced use.
- .PP
- The general syntax of \f[C]--parse-metadata FROM:TO\f[R] is to give the
- name of a field or an output template to extract data from, and the
- format to interpret it as, separated by a colon \f[C]:\f[R].
- Either a Python regular
- expression (https://docs.python.org/3/library/re.html#regular-expression-syntax)
- with named capture groups, a single field name, or a similar syntax to
- the output template (only \f[C]%(field)s\f[R] formatting is supported)
- can be used for \f[C]TO\f[R].
- The option can be used multiple times to parse and modify various
- fields.
- .PP
- Note that these options preserve their relative order, allowing
- replacements to be made in parsed fields and vice versa.
- Also, any field thus created can be used in the output template and will
- also affect the media file\[aq]s metadata added when using
- \f[C]--embed-metadata\f[R].
- .PP
- This option also has a few special uses:
- .IP \[bu] 2
- You can download an additional URL based on the metadata of the
- currently downloaded video.
- To do this, set the field \f[C]additional_urls\f[R] to the URL that you
- want to download.
- E.g.
- \f[C]--parse-metadata \[dq]description:(?P<additional_urls>https?://www\[rs].vimeo\[rs].com/\[rs]d+)\[dq]\f[R]
- will download the first vimeo video found in the description
- .IP \[bu] 2
- You can use this to change the metadata that is embedded in the media
- file.
- To do this, set the value of the corresponding field with a
- \f[C]meta_\f[R] prefix.
- For example, any value you set to \f[C]meta_description\f[R] field will
- be added to the \f[C]description\f[R] field in the file - you can use
- this to set a different \[dq]description\[dq] and \[dq]synopsis\[dq].
- To modify the metadata of individual streams, use the \f[C]meta<n>_\f[R]
- prefix (e.g.
- \f[C]meta1_language\f[R]).
- Any value set to the \f[C]meta_\f[R] field will overwrite all default
- values.
- .PP
- \f[B]Note\f[R]: Metadata modification happens before format selection,
- post-extraction and other post-processing operations.
- Some fields may be added or changed during these steps, overriding your
- changes.
- .PP
- For reference, these are the fields yt-dlp adds by default to the file
- metadata:
- .PP
- .TS
- tab(@);
- l l.
- T{
- Metadata fields
- T}@T{
- From
- T}
- _
- T{
- \f[C]title\f[R]
- T}@T{
- \f[C]track\f[R] or \f[C]title\f[R]
- T}
- T{
- \f[C]date\f[R]
- T}@T{
- \f[C]upload_date\f[R]
- T}
- T{
- \f[C]description\f[R], \f[C]synopsis\f[R]
- T}@T{
- \f[C]description\f[R]
- T}
- T{
- \f[C]purl\f[R], \f[C]comment\f[R]
- T}@T{
- \f[C]webpage_url\f[R]
- T}
- T{
- \f[C]track\f[R]
- T}@T{
- \f[C]track_number\f[R]
- T}
- T{
- \f[C]artist\f[R]
- T}@T{
- \f[C]artist\f[R], \f[C]artists\f[R], \f[C]creator\f[R],
- \f[C]creators\f[R], \f[C]uploader\f[R] or \f[C]uploader_id\f[R]
- T}
- T{
- \f[C]composer\f[R]
- T}@T{
- \f[C]composer\f[R] or \f[C]composers\f[R]
- T}
- T{
- \f[C]genre\f[R]
- T}@T{
- \f[C]genre\f[R] or \f[C]genres\f[R]
- T}
- T{
- \f[C]album\f[R]
- T}@T{
- \f[C]album\f[R]
- T}
- T{
- \f[C]album_artist\f[R]
- T}@T{
- \f[C]album_artist\f[R] or \f[C]album_artists\f[R]
- T}
- T{
- \f[C]disc\f[R]
- T}@T{
- \f[C]disc_number\f[R]
- T}
- T{
- \f[C]show\f[R]
- T}@T{
- \f[C]series\f[R]
- T}
- T{
- \f[C]season_number\f[R]
- T}@T{
- \f[C]season_number\f[R]
- T}
- T{
- \f[C]episode_id\f[R]
- T}@T{
- \f[C]episode\f[R] or \f[C]episode_id\f[R]
- T}
- T{
- \f[C]episode_sort\f[R]
- T}@T{
- \f[C]episode_number\f[R]
- T}
- T{
- \f[C]language\f[R] of each stream
- T}@T{
- the format\[aq]s \f[C]language\f[R]
- T}
- .TE
- .PP
- \f[B]Note\f[R]: The file format may not support some of these fields
- .SS Modifying metadata examples
- .IP
- .nf
- \f[C]
- # Interpret the title as \[dq]Artist - Title\[dq]
- $ yt-dlp --parse-metadata \[dq]title:%(artist)s - %(title)s\[dq]
- # Regex example
- $ yt-dlp --parse-metadata \[dq]description:Artist - (?P<artist>.+)\[dq]
- # Set title as \[dq]Series name S01E05\[dq]
- $ yt-dlp --parse-metadata \[dq]%(series)s S%(season_number)02dE%(episode_number)02d:%(title)s\[dq]
- # Prioritize uploader as the \[dq]artist\[dq] field in video metadata
- $ yt-dlp --parse-metadata \[dq]%(uploader|)s:%(meta_artist)s\[dq] --embed-metadata
- # Set \[dq]comment\[dq] field in video metadata using description instead of webpage_url,
- # handling multiple lines correctly
- $ yt-dlp --parse-metadata \[dq]description:(?s)(?P<meta_comment>.+)\[dq] --embed-metadata
- # Do not set any \[dq]synopsis\[dq] in the video metadata
- $ yt-dlp --parse-metadata \[dq]:(?P<meta_synopsis>)\[dq]
- # Remove \[dq]formats\[dq] field from the infojson by setting it to an empty string
- $ yt-dlp --parse-metadata \[dq]video::(?P<formats>)\[dq] --write-info-json
- # Replace all spaces and \[dq]_\[dq] in title and uploader with a \[ga]-\[ga]
- $ yt-dlp --replace-in-metadata \[dq]title,uploader\[dq] \[dq][ _]\[dq] \[dq]-\[dq]
- \f[R]
- .fi
- .SH EXTRACTOR ARGUMENTS
- .PP
- Some extractors accept additional arguments which can be passed using
- \f[C]--extractor-args KEY:ARGS\f[R].
- \f[C]ARGS\f[R] is a \f[C];\f[R] (semicolon) separated string of
- \f[C]ARG=VAL1,VAL2\f[R].
- E.g.
- \f[C]--extractor-args \[dq]youtube:player-client=tv,mweb;formats=incomplete\[dq] --extractor-args \[dq]funimation:version=uncut\[dq]\f[R]
- .PP
- Note: In CLI, \f[C]ARG\f[R] can use \f[C]-\f[R] instead of \f[C]_\f[R];
- e.g.
- \f[C]youtube:player-client\[dq]\f[R] becomes
- \f[C]youtube:player_client\[dq]\f[R]
- .PP
- The following extractors use this feature:
- .SS youtube
- .IP \[bu] 2
- \f[C]lang\f[R]: Prefer translated metadata (\f[C]title\f[R],
- \f[C]description\f[R] etc) of this language code (case-sensitive).
- By default, the video primary language metadata is preferred, with a
- fallback to \f[C]en\f[R] translated.
- See
- youtube.py (https://github.com/yt-dlp/yt-dlp/blob/c26f9b991a0681fd3ea548d535919cec1fbbd430/yt_dlp/extractor/youtube.py#L381-L390)
- for list of supported content language codes
- .IP \[bu] 2
- \f[C]skip\f[R]: One or more of \f[C]hls\f[R], \f[C]dash\f[R] or
- \f[C]translated_subs\f[R] to skip extraction of the m3u8 manifests, dash
- manifests and auto-translated
- subtitles (https://github.com/yt-dlp/yt-dlp/issues/4090#issuecomment-1158102032)
- respectively
- .IP \[bu] 2
- \f[C]player_client\f[R]: Clients to extract video data from.
- The main clients are \f[C]web\f[R], \f[C]ios\f[R] and \f[C]android\f[R],
- with variants \f[C]_music\f[R] and \f[C]_creator\f[R] (e.g.
- \f[C]ios_creator\f[R]); and \f[C]mweb\f[R], \f[C]android_vr\f[R],
- \f[C]web_safari\f[R], \f[C]web_embedded\f[R], \f[C]tv\f[R] and
- \f[C]tv_embedded\f[R] with no variants.
- By default, \f[C]tv,ios,web\f[R] is used, or \f[C]tv,web\f[R] is used
- when authenticating with cookies.
- The \f[C]_music\f[R] variants may be added for
- \f[C]music.youtube.com\f[R] URLs.
- Some clients, such as \f[C]web\f[R] and \f[C]android\f[R], require a
- \f[C]po_token\f[R] for their formats to be downloadable.
- Some clients, such as the \f[C]_creator\f[R] variants, will only work
- with authentication.
- Not all clients support authentication via cookies.
- You can use \f[C]default\f[R] for the default clients, or you can use
- \f[C]all\f[R] for all clients (not recommended).
- You can prefix a client with \f[C]-\f[R] to exclude it, e.g.
- \f[C]youtube:player_client=default,-ios\f[R]
- .IP \[bu] 2
- \f[C]player_skip\f[R]: Skip some network requests that are generally
- needed for robust extraction.
- One or more of \f[C]configs\f[R] (skip client configs),
- \f[C]webpage\f[R] (skip initial webpage), \f[C]js\f[R] (skip js player).
- While these options can help reduce the number of requests needed or
- avoid some rate-limiting, they could cause some issues.
- See #860 (https://github.com/yt-dlp/yt-dlp/pull/860) for more details
- .IP \[bu] 2
- \f[C]player_params\f[R]: YouTube player parameters to use for player
- requests.
- Will overwrite any default ones set by yt-dlp.
- .IP \[bu] 2
- \f[C]comment_sort\f[R]: \f[C]top\f[R] or \f[C]new\f[R] (default) -
- choose comment sorting mode (on YouTube\[aq]s side)
- .IP \[bu] 2
- \f[C]max_comments\f[R]: Limit the amount of comments to gather.
- Comma-separated list of integers representing
- \f[C]max-comments,max-parents,max-replies,max-replies-per-thread\f[R].
- Default is \f[C]all,all,all,all\f[R]
- .RS 2
- .IP \[bu] 2
- E.g.
- \f[C]all,all,1000,10\f[R] will get a maximum of 1000 replies total, with
- up to 10 replies per thread.
- \f[C]1000,all,100\f[R] will get a maximum of 1000 comments, with a
- maximum of 100 replies total
- .RE
- .IP \[bu] 2
- \f[C]formats\f[R]: Change the types of formats to return.
- \f[C]dashy\f[R] (convert HTTP to DASH), \f[C]duplicate\f[R] (identical
- content but different URLs or protocol; includes \f[C]dashy\f[R]),
- \f[C]incomplete\f[R] (cannot be downloaded completely - live dash and
- post-live m3u8), \f[C]missing_pot\f[R] (include formats that require a
- PO Token but are missing one)
- .IP \[bu] 2
- \f[C]innertube_host\f[R]: Innertube API host to use for all API
- requests; e.g.
- \f[C]studio.youtube.com\f[R], \f[C]youtubei.googleapis.com\f[R].
- Note that cookies exported from one subdomain will not work on others
- .IP \[bu] 2
- \f[C]innertube_key\f[R]: Innertube API key to use for all API requests.
- By default, no API key is used
- .IP \[bu] 2
- \f[C]raise_incomplete_data\f[R]: \f[C]Incomplete Data Received\f[R]
- raises an error instead of reporting a warning
- .IP \[bu] 2
- \f[C]data_sync_id\f[R]: Overrides the account Data Sync ID used in
- Innertube API requests.
- This may be needed if you are using an account with
- \f[C]youtube:player_skip=webpage,configs\f[R] or
- \f[C]youtubetab:skip=webpage\f[R]
- .IP \[bu] 2
- \f[C]visitor_data\f[R]: Overrides the Visitor Data used in Innertube API
- requests.
- This should be used with \f[C]player_skip=webpage,configs\f[R] and
- without cookies.
- Note: this may have adverse effects if used improperly.
- If a session from a browser is wanted, you should pass cookies instead
- (which contain the Visitor ID)
- .IP \[bu] 2
- \f[C]po_token\f[R]: Proof of Origin (PO) Token(s) to use for requesting
- video playback.
- Comma seperated list of PO Tokens in the format
- \f[C]CLIENT+PO_TOKEN\f[R], e.g.
- \f[C]youtube:po_token=web+XXX,android+YYY\f[R]
- .SS youtubetab (YouTube playlists, channels, feeds, etc.)
- .IP \[bu] 2
- \f[C]skip\f[R]: One or more of \f[C]webpage\f[R] (skip initial webpage
- download), \f[C]authcheck\f[R] (allow the download of playlists
- requiring authentication when no initial webpage is downloaded.
- This may cause unwanted behavior, see
- #1122 (https://github.com/yt-dlp/yt-dlp/pull/1122) for more details)
- .IP \[bu] 2
- \f[C]approximate_date\f[R]: Extract approximate \f[C]upload_date\f[R]
- and \f[C]timestamp\f[R] in flat-playlist.
- This may cause date-based filters to be slightly off
- .SS generic
- .IP \[bu] 2
- \f[C]fragment_query\f[R]: Passthrough any query in mpd/m3u8 manifest
- URLs to their fragments if no value is provided, or else apply the query
- string given as \f[C]fragment_query=VALUE\f[R].
- Note that if the stream has an HLS AES-128 key, then the query
- parameters will be passed to the key URI as well, unless the
- \f[C]key_query\f[R] extractor-arg is passed, or unless an external key
- URI is provided via the \f[C]hls_key\f[R] extractor-arg.
- Does not apply to ffmpeg
- .IP \[bu] 2
- \f[C]variant_query\f[R]: Passthrough the master m3u8 URL query to its
- variant playlist URLs if no value is provided, or else apply the query
- string given as \f[C]variant_query=VALUE\f[R]
- .IP \[bu] 2
- \f[C]key_query\f[R]: Passthrough the master m3u8 URL query to its HLS
- AES-128 decryption key URI if no value is provided, or else apply the
- query string given as \f[C]key_query=VALUE\f[R].
- Note that this will have no effect if the key URI is provided via the
- \f[C]hls_key\f[R] extractor-arg.
- Does not apply to ffmpeg
- .IP \[bu] 2
- \f[C]hls_key\f[R]: An HLS AES-128 key URI \f[I]or\f[R] key (as hex), and
- optionally the IV (as hex), in the form of \f[C](URI|KEY)[,IV]\f[R];
- e.g.
- \f[C]generic:hls_key=ABCDEF1234567980,0xFEDCBA0987654321\f[R].
- Passing any of these values will force usage of the native HLS
- downloader and override the corresponding values found in the m3u8
- playlist
- .IP \[bu] 2
- \f[C]is_live\f[R]: Bypass live HLS detection and manually set
- \f[C]live_status\f[R] - a value of \f[C]false\f[R] will set
- \f[C]not_live\f[R], any other value (or no value) will set
- \f[C]is_live\f[R]
- .IP \[bu] 2
- \f[C]impersonate\f[R]: Target(s) to try and impersonate with the initial
- webpage request; e.g.
- \f[C]generic:impersonate=safari,chrome-110\f[R].
- Use \f[C]generic:impersonate\f[R] to impersonate any available target,
- and use \f[C]generic:impersonate=false\f[R] to disable impersonation
- (default)
- .SS funimation
- .IP \[bu] 2
- \f[C]language\f[R]: Audio languages to extract, e.g.
- \f[C]funimation:language=english,japanese\f[R]
- .IP \[bu] 2
- \f[C]version\f[R]: The video version to extract - \f[C]uncut\f[R] or
- \f[C]simulcast\f[R]
- .SS crunchyrollbeta (Crunchyroll)
- .IP \[bu] 2
- \f[C]hardsub\f[R]: One or more hardsub versions to extract (in order of
- preference), or \f[C]all\f[R] (default: \f[C]None\f[R] = no hardsubs
- will be extracted), e.g.
- \f[C]crunchyrollbeta:hardsub=en-US,de-DE\f[R]
- .SS vikichannel
- .IP \[bu] 2
- \f[C]video_types\f[R]: Types of videos to download - one or more of
- \f[C]episodes\f[R], \f[C]movies\f[R], \f[C]clips\f[R],
- \f[C]trailers\f[R]
- .SS niconico
- .IP \[bu] 2
- \f[C]segment_duration\f[R]: Segment duration in milliseconds for HLS-DMC
- formats.
- Use it at your own risk since this feature \f[B]may result in your
- account termination.\f[R]
- .SS youtubewebarchive
- .IP \[bu] 2
- \f[C]check_all\f[R]: Try to check more at the cost of more requests.
- One or more of \f[C]thumbnails\f[R], \f[C]captures\f[R]
- .SS gamejolt
- .IP \[bu] 2
- \f[C]comment_sort\f[R]: \f[C]hot\f[R] (default), \f[C]you\f[R] (cookies
- needed), \f[C]top\f[R], \f[C]new\f[R] - choose comment sorting mode (on
- GameJolt\[aq]s side)
- .SS hotstar
- .IP \[bu] 2
- \f[C]res\f[R]: resolution to ignore - one or more of \f[C]sd\f[R],
- \f[C]hd\f[R], \f[C]fhd\f[R]
- .IP \[bu] 2
- \f[C]vcodec\f[R]: vcodec to ignore - one or more of \f[C]h264\f[R],
- \f[C]h265\f[R], \f[C]dvh265\f[R]
- .IP \[bu] 2
- \f[C]dr\f[R]: dynamic range to ignore - one or more of \f[C]sdr\f[R],
- \f[C]hdr10\f[R], \f[C]dv\f[R]
- .SS niconicochannelplus
- .IP \[bu] 2
- \f[C]max_comments\f[R]: Maximum number of comments to extract - default
- is \f[C]120\f[R]
- .SS tiktok
- .IP \[bu] 2
- \f[C]api_hostname\f[R]: Hostname to use for mobile API calls, e.g.
- \f[C]api22-normal-c-alisg.tiktokv.com\f[R]
- .IP \[bu] 2
- \f[C]app_name\f[R]: Default app name to use with mobile API calls, e.g.
- \f[C]trill\f[R]
- .IP \[bu] 2
- \f[C]app_version\f[R]: Default app version to use with mobile API calls
- - should be set along with \f[C]manifest_app_version\f[R], e.g.
- \f[C]34.1.2\f[R]
- .IP \[bu] 2
- \f[C]manifest_app_version\f[R]: Default numeric app version to use with
- mobile API calls, e.g.
- \f[C]2023401020\f[R]
- .IP \[bu] 2
- \f[C]aid\f[R]: Default app ID to use with mobile API calls, e.g.
- \f[C]1180\f[R]
- .IP \[bu] 2
- \f[C]app_info\f[R]: Enable mobile API extraction with one or more app
- info strings in the format of
- \f[C]<iid>/[app_name]/[app_version]/[manifest_app_version]/[aid]\f[R],
- where \f[C]iid\f[R] is the unique app install ID.
- \f[C]iid\f[R] is the only required value; all other values and their
- \f[C]/\f[R] separators can be omitted, e.g.
- \f[C]tiktok:app_info=1234567890123456789\f[R] or
- \f[C]tiktok:app_info=123,456/trill///1180,789//34.0.1/340001\f[R]
- .IP \[bu] 2
- \f[C]device_id\f[R]: Enable mobile API extraction with a genuine device
- ID to be used with mobile API calls.
- Default is a random 19-digit string
- .SS rokfinchannel
- .IP \[bu] 2
- \f[C]tab\f[R]: Which tab to download - one of \f[C]new\f[R],
- \f[C]top\f[R], \f[C]videos\f[R], \f[C]podcasts\f[R], \f[C]streams\f[R],
- \f[C]stacks\f[R]
- .SS twitter
- .IP \[bu] 2
- \f[C]api\f[R]: Select one of \f[C]graphql\f[R] (default),
- \f[C]legacy\f[R] or \f[C]syndication\f[R] as the API for tweet
- extraction.
- Has no effect if logged in
- .SS stacommu, wrestleuniverse
- .IP \[bu] 2
- \f[C]device_id\f[R]: UUID value assigned by the website and used to
- enforce device limits for paid livestream content.
- Can be found in browser local storage
- .SS twitch
- .IP \[bu] 2
- \f[C]client_id\f[R]: Client ID value to be sent with GraphQL requests,
- e.g.
- \f[C]twitch:client_id=kimne78kx3ncx6brgo4mv6wki5h1ko\f[R]
- .SS nhkradirulive (NHK \[u3089]\[u3058]\[u308B]\[u2605]\[u3089]\[u3058]\[u308B] LIVE)
- .IP \[bu] 2
- \f[C]area\f[R]: Which regional variation to extract.
- Valid areas are: \f[C]sapporo\f[R], \f[C]sendai\f[R], \f[C]tokyo\f[R],
- \f[C]nagoya\f[R], \f[C]osaka\f[R], \f[C]hiroshima\f[R],
- \f[C]matsuyama\f[R], \f[C]fukuoka\f[R].
- Defaults to \f[C]tokyo\f[R]
- .SS nflplusreplay
- .IP \[bu] 2
- \f[C]type\f[R]: Type(s) of game replays to extract.
- Valid types are: \f[C]full_game\f[R], \f[C]full_game_spanish\f[R],
- \f[C]condensed_game\f[R] and \f[C]all_22\f[R].
- You can use \f[C]all\f[R] to extract all available replay types, which
- is the default
- .SS jiocinema
- .IP \[bu] 2
- \f[C]refresh_token\f[R]: The \f[C]refreshToken\f[R] UUID from browser
- local storage can be passed to extend the life of your login session
- when logging in with \f[C]token\f[R] as username and the
- \f[C]accessToken\f[R] from browser local storage as password
- .SS jiosaavn
- .IP \[bu] 2
- \f[C]bitrate\f[R]: Audio bitrates to request.
- One or more of \f[C]16\f[R], \f[C]32\f[R], \f[C]64\f[R], \f[C]128\f[R],
- \f[C]320\f[R].
- Default is \f[C]128,320\f[R]
- .SS afreecatvlive
- .IP \[bu] 2
- \f[C]cdn\f[R]: One or more CDN IDs to use with the API call for stream
- URLs, e.g.
- \f[C]gcp_cdn\f[R], \f[C]gs_cdn_pc_app\f[R], \f[C]gs_cdn_mobile_web\f[R],
- \f[C]gs_cdn_pc_web\f[R]
- .SS soundcloud
- .IP \[bu] 2
- \f[C]formats\f[R]: Formats to request from the API.
- Requested values should be in the format of
- \f[C]{protocol}_{codec}\f[R], e.g.
- \f[C]hls_opus,http_aac\f[R].
- The \f[C]*\f[R] character functions as a wildcard, e.g.
- \f[C]*_mp3\f[R], and can be passed by itself to request all formats.
- Known protocols include \f[C]http\f[R], \f[C]hls\f[R] and
- \f[C]hls-aes\f[R]; known codecs include \f[C]aac\f[R], \f[C]opus\f[R]
- and \f[C]mp3\f[R].
- Original \f[C]download\f[R] formats are always extracted.
- Default is
- \f[C]http_aac,hls_aac,http_opus,hls_opus,http_mp3,hls_mp3\f[R]
- .SS orfon (orf:on)
- .IP \[bu] 2
- \f[C]prefer_segments_playlist\f[R]: Prefer a playlist of program
- segments instead of a single complete video when available.
- If individual segments are desired, use
- \f[C]--concat-playlist never --extractor-args \[dq]orfon:prefer_segments_playlist\[dq]\f[R]
- .SS bilibili
- .IP \[bu] 2
- \f[C]prefer_multi_flv\f[R]: Prefer extracting flv formats over mp4 for
- older videos that still provide legacy formats
- .SS sonylivseries
- .IP \[bu] 2
- \f[C]sort_order\f[R]: Episode sort order for series extraction - one of
- \f[C]asc\f[R] (ascending, oldest first) or \f[C]desc\f[R] (descending,
- newest first).
- Default is \f[C]asc\f[R]
- .PP
- \f[B]Note\f[R]: These options may be changed/removed in the future
- without concern for backward compatibility
- .SH INSTALLATION
- .PP
- You can install yt-dlp using the binaries,
- pip (https://pypi.org/project/yt-dlp) or one using a third-party package
- manager.
- See the wiki (https://github.com/yt-dlp/yt-dlp/wiki/Installation) for
- detailed instructions
- .PP
- \f[B]Note\f[R]: The manpages, shell completion (autocomplete) files etc.
- are available inside the source
- tarball (https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.tar.gz)
- .SS UPDATE
- .PP
- You can use \f[C]yt-dlp -U\f[R] to update if you are using the release
- binaries
- .PP
- If you installed with
- pip (https://github.com/yt-dlp/yt-dlp/wiki/Installation#with-pip),
- simply re-run the same command that was used to install the program
- .PP
- For other third-party package managers, see the
- wiki (https://github.com/yt-dlp/yt-dlp/wiki/Installation#third-party-package-managers)
- or refer to their documentation
- .PP
- .PP
- There are currently three release channels for binaries:
- \f[C]stable\f[R], \f[C]nightly\f[R] and \f[C]master\f[R].
- .IP \[bu] 2
- \f[C]stable\f[R] is the default channel, and many of its changes have
- been tested by users of the \f[C]nightly\f[R] and \f[C]master\f[R]
- channels.
- .IP \[bu] 2
- The \f[C]nightly\f[R] channel has releases scheduled to build every day
- around midnight UTC, for a snapshot of the project\[aq]s new patches and
- changes.
- This is the \f[B]recommended channel for regular users\f[R] of yt-dlp.
- The \f[C]nightly\f[R] releases are available from
- yt-dlp/yt-dlp-nightly-builds (https://github.com/yt-dlp/yt-dlp-nightly-builds/releases)
- or as development releases of the \f[C]yt-dlp\f[R] PyPI package (which
- can be installed with pip\[aq]s \f[C]--pre\f[R] flag).
- .IP \[bu] 2
- The \f[C]master\f[R] channel features releases that are built after each
- push to the master branch, and these will have the very latest fixes and
- additions, but may also be more prone to regressions.
- They are available from
- yt-dlp/yt-dlp-master-builds (https://github.com/yt-dlp/yt-dlp-master-builds/releases).
- .PP
- When using \f[C]--update\f[R]/\f[C]-U\f[R], a release binary will only
- update to its current channel.
- \f[C]--update-to CHANNEL\f[R] can be used to switch to a different
- channel when a newer version is available.
- \f[C]--update-to [CHANNEL\[at]]TAG\f[R] can also be used to upgrade or
- downgrade to specific tags from a channel.
- .PP
- You may also use \f[C]--update-to <repository>\f[R]
- (\f[C]<owner>/<repository>\f[R]) to update to a channel on a completely
- different repository.
- Be careful with what repository you are updating to though, there is no
- verification done for binaries from different repositories.
- .PP
- Example usage:
- .IP \[bu] 2
- \f[C]yt-dlp --update-to master\f[R] switch to the \f[C]master\f[R]
- channel and update to its latest release
- .IP \[bu] 2
- \f[C]yt-dlp --update-to stable\[at]2023.07.06\f[R] upgrade/downgrade to
- release to \f[C]stable\f[R] channel tag \f[C]2023.07.06\f[R]
- .IP \[bu] 2
- \f[C]yt-dlp --update-to 2023.10.07\f[R] upgrade/downgrade to tag
- \f[C]2023.10.07\f[R] if it exists on the current channel
- .IP \[bu] 2
- \f[C]yt-dlp --update-to example/yt-dlp\[at]2023.09.24\f[R]
- upgrade/downgrade to the release from the \f[C]example/yt-dlp\f[R]
- repository, tag \f[C]2023.09.24\f[R]
- .PP
- \f[B]Important\f[R]: Any user experiencing an issue with the
- \f[C]stable\f[R] release should install or update to the
- \f[C]nightly\f[R] release before submitting a bug report:
- .IP
- .nf
- \f[C]
- # To update to nightly from stable executable/binary:
- yt-dlp --update-to nightly
- # To install nightly with pip:
- python3 -m pip install -U --pre \[dq]yt-dlp[default]\[dq]
- \f[R]
- .fi
- .SS DEPENDENCIES
- .PP
- Python versions 3.9+ (CPython) and 3.10+ (PyPy) are supported.
- Other versions and implementations may or may not work correctly.
- .PP
- While all the other dependencies are optional, \f[C]ffmpeg\f[R] and
- \f[C]ffprobe\f[R] are highly recommended
- .SS Strongly recommended
- .IP \[bu] 2
- \f[B]ffmpeg\f[R] and \f[B]ffprobe\f[R] (https://www.ffmpeg.org) -
- Required for merging separate video and audio files, as well as for
- various post-processing tasks.
- License depends on the build (https://www.ffmpeg.org/legal.html)
- .RS 2
- .PP
- There are bugs in ffmpeg that cause various issues when used alongside
- yt-dlp.
- Since ffmpeg is such an important dependency, we provide custom
- builds (https://github.com/yt-dlp/FFmpeg-Builds#ffmpeg-static-auto-builds)
- with patches for some of these issues at
- yt-dlp/FFmpeg-Builds (https://github.com/yt-dlp/FFmpeg-Builds).
- See the readme (https://github.com/yt-dlp/FFmpeg-Builds#patches-applied)
- for details on the specific issues solved by these builds
- .PP
- \f[B]Important\f[R]: What you need is ffmpeg \f[I]binary\f[R],
- \f[B]NOT\f[R] the Python package of the same
- name (https://pypi.org/project/ffmpeg)
- .RE
- .SS Networking
- .IP \[bu] 2
- \f[B]certifi\f[R] (https://github.com/certifi/python-certifi)* -
- Provides Mozilla\[aq]s root certificate bundle.
- Licensed under
- MPLv2 (https://github.com/certifi/python-certifi/blob/master/LICENSE)
- .IP \[bu] 2
- \f[B]brotli\f[R] (https://github.com/google/brotli)* or
- \f[B]brotlicffi\f[R] (https://github.com/python-hyper/brotlicffi) -
- Brotli (https://en.wikipedia.org/wiki/Brotli) content encoding support.
- Both licensed under MIT
- 1 (https://github.com/google/brotli/blob/master/LICENSE)
- 2 (https://github.com/python-hyper/brotlicffi/blob/master/LICENSE)
- .IP \[bu] 2
- \f[B]websockets\f[R] (https://github.com/aaugustin/websockets)* - For
- downloading over websocket.
- Licensed under
- BSD-3-Clause (https://github.com/aaugustin/websockets/blob/main/LICENSE)
- .IP \[bu] 2
- \f[B]requests\f[R] (https://github.com/psf/requests)* - HTTP library.
- For HTTPS proxy and persistent connections support.
- Licensed under
- Apache-2.0 (https://github.com/psf/requests/blob/main/LICENSE)
- .SS Impersonation
- .PP
- The following provide support for impersonating browser requests.
- This may be required for some sites that employ TLS fingerprinting.
- .IP \[bu] 2
- \f[B]curl_cffi\f[R] (https://github.com/lexiforest/curl_cffi)
- (recommended) - Python binding for
- curl-impersonate (https://github.com/lexiforest/curl-impersonate).
- Provides impersonation targets for Chrome, Edge and Safari.
- Licensed under
- MIT (https://github.com/lexiforest/curl_cffi/blob/main/LICENSE)
- .RS 2
- .IP \[bu] 2
- Can be installed with the \f[C]curl-cffi\f[R] group, e.g.
- \f[C]pip install \[dq]yt-dlp[default,curl-cffi]\[dq]\f[R]
- .IP \[bu] 2
- Currently included in \f[C]yt-dlp.exe\f[R], \f[C]yt-dlp_linux\f[R] and
- \f[C]yt-dlp_macos\f[R] builds
- .RE
- .SS Metadata
- .IP \[bu] 2
- \f[B]mutagen\f[R] (https://github.com/quodlibet/mutagen)* - For
- \f[C]--embed-thumbnail\f[R] in certain formats.
- Licensed under
- GPLv2+ (https://github.com/quodlibet/mutagen/blob/master/COPYING)
- .IP \[bu] 2
- \f[B]AtomicParsley\f[R] (https://github.com/wez/atomicparsley) - For
- \f[C]--embed-thumbnail\f[R] in \f[C]mp4\f[R]/\f[C]m4a\f[R] files when
- \f[C]mutagen\f[R]/\f[C]ffmpeg\f[R] cannot.
- Licensed under
- GPLv2+ (https://github.com/wez/atomicparsley/blob/master/COPYING)
- .IP \[bu] 2
- \f[B]xattr\f[R] (https://github.com/xattr/xattr),
- \f[B]pyxattr\f[R] (https://github.com/iustin/pyxattr) or
- \f[B]setfattr\f[R] (http://savannah.nongnu.org/projects/attr) - For
- writing xattr metadata (\f[C]--xattr\f[R]) on \f[B]Mac\f[R] and
- \f[B]BSD\f[R].
- Licensed under
- MIT (https://github.com/xattr/xattr/blob/master/LICENSE.txt),
- LGPL2.1 (https://github.com/iustin/pyxattr/blob/master/COPYING) and
- GPLv2+ (http://git.savannah.nongnu.org/cgit/attr.git/tree/doc/COPYING)
- respectively
- .SS Misc
- .IP \[bu] 2
- \f[B]pycryptodomex\f[R] (https://github.com/Legrandin/pycryptodome)* -
- For decrypting AES-128 HLS streams and various other data.
- Licensed under
- BSD-2-Clause (https://github.com/Legrandin/pycryptodome/blob/master/LICENSE.rst)
- .IP \[bu] 2
- \f[B]phantomjs\f[R] (https://github.com/ariya/phantomjs) - Used in
- extractors where javascript needs to be run.
- Licensed under
- BSD-3-Clause (https://github.com/ariya/phantomjs/blob/master/LICENSE.BSD)
- .IP \[bu] 2
- \f[B]secretstorage\f[R] (https://github.com/mitya57/secretstorage)* -
- For \f[C]--cookies-from-browser\f[R] to access the \f[B]Gnome\f[R]
- keyring while decrypting cookies of \f[B]Chromium\f[R]-based browsers on
- \f[B]Linux\f[R].
- Licensed under
- BSD-3-Clause (https://github.com/mitya57/secretstorage/blob/master/LICENSE)
- .IP \[bu] 2
- Any external downloader that you want to use with \f[C]--downloader\f[R]
- .SS Deprecated
- .IP \[bu] 2
- \f[B]avconv\f[R] and \f[B]avprobe\f[R] (https://www.libav.org) - Now
- \f[B]deprecated\f[R] alternative to ffmpeg.
- License depends on the build (https://libav.org/legal)
- .IP \[bu] 2
- \f[B]sponskrub\f[R] (https://github.com/faissaloo/SponSkrub) - For using
- the now \f[B]deprecated\f[R] sponskrub options.
- Licensed under
- GPLv3+ (https://github.com/faissaloo/SponSkrub/blob/master/LICENCE.md)
- .IP \[bu] 2
- \f[B]rtmpdump\f[R] (http://rtmpdump.mplayerhq.hu) - For downloading
- \f[C]rtmp\f[R] streams.
- ffmpeg can be used instead with \f[C]--downloader ffmpeg\f[R].
- Licensed under GPLv2+ (http://rtmpdump.mplayerhq.hu)
- .IP \[bu] 2
- \f[B]mplayer\f[R] (http://mplayerhq.hu/design7/info.html) or
- \f[B]mpv\f[R] (https://mpv.io) - For downloading
- \f[C]rstp\f[R]/\f[C]mms\f[R] streams.
- ffmpeg can be used instead with \f[C]--downloader ffmpeg\f[R].
- Licensed under
- GPLv2+ (https://github.com/mpv-player/mpv/blob/master/Copyright)
- .PP
- To use or redistribute the dependencies, you must agree to their
- respective licensing terms.
- .PP
- The standalone release binaries are built with the Python interpreter
- and the packages marked with \f[B]*\f[R] included.
- .PP
- If you do not have the necessary dependencies for a task you are
- attempting, yt-dlp will warn you.
- All the currently available dependencies are visible at the top of the
- \f[C]--verbose\f[R] output
- .SS COMPILE
- .SS Standalone PyInstaller Builds
- .PP
- To build the standalone executable, you must have Python and
- \f[C]pyinstaller\f[R] (plus any of yt-dlp\[aq]s optional dependencies if
- needed).
- The executable will be built for the same CPU architecture as the Python
- used.
- .PP
- You can run the following commands:
- .IP
- .nf
- \f[C]
- python3 devscripts/install_deps.py --include pyinstaller
- python3 devscripts/make_lazy_extractors.py
- python3 -m bundle.pyinstaller
- \f[R]
- .fi
- .PP
- On some systems, you may need to use \f[C]py\f[R] or \f[C]python\f[R]
- instead of \f[C]python3\f[R].
- .PP
- \f[C]python -m bundle.pyinstaller\f[R] accepts any arguments that can be
- passed to \f[C]pyinstaller\f[R], such as \f[C]--onefile/-F\f[R] or
- \f[C]--onedir/-D\f[R], which is further documented
- here (https://pyinstaller.org/en/stable/usage.html#what-to-generate).
- .PP
- \f[B]Note\f[R]: Pyinstaller versions below 4.4 do not
- support (https://github.com/pyinstaller/pyinstaller#requirements-and-tested-platforms)
- Python installed from the Windows store without using a virtual
- environment.
- .PP
- \f[B]Important\f[R]: Running \f[C]pyinstaller\f[R] directly \f[B]instead
- of\f[R] using \f[C]python -m bundle.pyinstaller\f[R] is \f[B]not\f[R]
- officially supported.
- This may or may not work correctly.
- .SS Platform-independent Binary (UNIX)
- .PP
- You will need the build tools \f[C]python\f[R] (3.9+), \f[C]zip\f[R],
- \f[C]make\f[R] (GNU), \f[C]pandoc\f[R]* and \f[C]pytest\f[R]*.
- .PP
- After installing these, simply run \f[C]make\f[R].
- .PP
- You can also run \f[C]make yt-dlp\f[R] instead to compile only the
- binary without updating any of the additional files.
- (The build tools marked with \f[B]*\f[R] are not needed for this)
- .SS Related scripts
- .IP \[bu] 2
- \f[B]\f[CB]devscripts/install_deps.py\f[B]\f[R] - Install dependencies
- for yt-dlp.
- .IP \[bu] 2
- \f[B]\f[CB]devscripts/update-version.py\f[B]\f[R] - Update the version
- number based on the current date.
- .IP \[bu] 2
- \f[B]\f[CB]devscripts/set-variant.py\f[B]\f[R] - Set the build variant
- of the executable.
- .IP \[bu] 2
- \f[B]\f[CB]devscripts/make_changelog.py\f[B]\f[R] - Create a markdown
- changelog using short commit messages and update \f[C]CONTRIBUTORS\f[R]
- file.
- .IP \[bu] 2
- \f[B]\f[CB]devscripts/make_lazy_extractors.py\f[B]\f[R] - Create lazy
- extractors.
- Running this before building the binaries (any variant) will improve
- their startup performance.
- Set the environment variable \f[C]YTDLP_NO_LAZY_EXTRACTORS\f[R] to
- something nonempty to forcefully disable lazy extractor loading.
- .PP
- Note: See their \f[C]--help\f[R] for more info.
- .SS Forking the project
- .PP
- If you fork the project on GitHub, you can run your fork\[aq]s build
- workflow to automatically build the selected version(s) as artifacts.
- Alternatively, you can run the release workflow or enable the nightly
- workflow to create full (pre-)releases.
- .SH PLUGINS
- .PP
- Note that \f[B]all\f[R] plugins are imported even if not invoked, and
- that \f[B]there are no checks\f[R] performed on plugin code.
- \f[B]Use plugins at your own risk and only if you trust the code!\f[R]
- .PP
- Plugins can be of \f[C]<type>\f[R]s \f[C]extractor\f[R] or
- \f[C]postprocessor\f[R].
- - Extractor plugins do not need to be enabled from the CLI and are
- automatically invoked when the input URL is suitable for it.
- - Extractor plugins take priority over built-in extractors.
- - Postprocessor plugins can be invoked using
- \f[C]--use-postprocessor NAME\f[R].
- .PP
- Plugins are loaded from the namespace packages
- \f[C]yt_dlp_plugins.extractor\f[R] and
- \f[C]yt_dlp_plugins.postprocessor\f[R].
- .PP
- In other words, the file structure on the disk looks something like:
- .IP
- .nf
- \f[C]
- yt_dlp_plugins/
- extractor/
- myplugin.py
- postprocessor/
- myplugin.py
- \f[R]
- .fi
- .PP
- yt-dlp looks for these \f[C]yt_dlp_plugins\f[R] namespace folders in
- many locations (see below) and loads in plugins from \f[B]all\f[R] of
- them.
- Set the environment variable \f[C]YTDLP_NO_PLUGINS\f[R] to something
- nonempty to disable loading plugins entirely.
- .PP
- See the wiki for some known
- plugins (https://github.com/yt-dlp/yt-dlp/wiki/Plugins)
- .SS Installing Plugins
- .PP
- Plugins can be installed using various methods and locations.
- .IP "1." 3
- \f[B]Configuration directories\f[R]: Plugin packages (containing a
- \f[C]yt_dlp_plugins\f[R] namespace folder) can be dropped into the
- following standard configuration locations:
- .RS 4
- .IP \[bu] 2
- \f[B]User Plugins\f[R]
- .RS 2
- .IP \[bu] 2
- \f[C]${XDG_CONFIG_HOME}/yt-dlp/plugins/<package name>/yt_dlp_plugins/\f[R]
- (recommended on Linux/macOS)
- .IP \[bu] 2
- \f[C]${XDG_CONFIG_HOME}/yt-dlp-plugins/<package name>/yt_dlp_plugins/\f[R]
- .IP \[bu] 2
- \f[C]${APPDATA}/yt-dlp/plugins/<package name>/yt_dlp_plugins/\f[R]
- (recommended on Windows)
- .IP \[bu] 2
- \f[C]${APPDATA}/yt-dlp-plugins/<package name>/yt_dlp_plugins/\f[R]
- .IP \[bu] 2
- \f[C]\[ti]/.yt-dlp/plugins/<package name>/yt_dlp_plugins/\f[R]
- .IP \[bu] 2
- \f[C]\[ti]/yt-dlp-plugins/<package name>/yt_dlp_plugins/\f[R]
- .RE
- .IP \[bu] 2
- \f[B]System Plugins\f[R]
- .RS 2
- .IP \[bu] 2
- \f[C]/etc/yt-dlp/plugins/<package name>/yt_dlp_plugins/\f[R]
- .IP \[bu] 2
- \f[C]/etc/yt-dlp-plugins/<package name>/yt_dlp_plugins/\f[R]
- .RE
- .RE
- .IP "2." 3
- \f[B]Executable location\f[R]: Plugin packages can similarly be
- installed in a \f[C]yt-dlp-plugins\f[R] directory under the executable
- location (recommended for portable installations):
- .RS 4
- .IP \[bu] 2
- Binary: where \f[C]<root-dir>/yt-dlp.exe\f[R],
- \f[C]<root-dir>/yt-dlp-plugins/<package name>/yt_dlp_plugins/\f[R]
- .IP \[bu] 2
- Source: where \f[C]<root-dir>/yt_dlp/__main__.py\f[R],
- \f[C]<root-dir>/yt-dlp-plugins/<package name>/yt_dlp_plugins/\f[R]
- .RE
- .IP "3." 3
- \f[B]pip and other locations in \f[CB]PYTHONPATH\f[B]\f[R]
- .RS 4
- .IP \[bu] 2
- Plugin packages can be installed and managed using \f[C]pip\f[R].
- See
- yt-dlp-sample-plugins (https://github.com/yt-dlp/yt-dlp-sample-plugins)
- for an example.
- .RS 2
- .IP \[bu] 2
- Note: plugin files between plugin packages installed with pip must have
- unique filenames.
- .RE
- .IP \[bu] 2
- Any path in \f[C]PYTHONPATH\f[R] is searched in for the
- \f[C]yt_dlp_plugins\f[R] namespace folder.
- .RS 2
- .IP \[bu] 2
- Note: This does not apply for Pyinstaller builds.
- .RE
- .RE
- .PP
- \f[C].zip\f[R], \f[C].egg\f[R] and \f[C].whl\f[R] archives containing a
- \f[C]yt_dlp_plugins\f[R] namespace folder in their root are also
- supported as plugin packages.
- .IP \[bu] 2
- e.g.
- \f[C]${XDG_CONFIG_HOME}/yt-dlp/plugins/mypluginpkg.zip\f[R] where
- \f[C]mypluginpkg.zip\f[R] contains
- \f[C]yt_dlp_plugins/<type>/myplugin.py\f[R]
- .PP
- Run yt-dlp with \f[C]--verbose\f[R] to check if the plugin has been
- loaded.
- .SS Developing Plugins
- .PP
- See the
- yt-dlp-sample-plugins (https://github.com/yt-dlp/yt-dlp-sample-plugins)
- repo for a template plugin package and the Plugin
- Development (https://github.com/yt-dlp/yt-dlp/wiki/Plugin-Development)
- section of the wiki for a plugin development guide.
- .PP
- All public classes with a name ending in \f[C]IE\f[R]/\f[C]PP\f[R] are
- imported from each file for extractors and postprocessors respectively.
- This respects underscore prefix (e.g.
- \f[C]_MyBasePluginIE\f[R] is private) and \f[C]__all__\f[R].
- Modules can similarly be excluded by prefixing the module name with an
- underscore (e.g.
- \f[C]_myplugin.py\f[R]).
- .PP
- To replace an existing extractor with a subclass of one, set the
- \f[C]plugin_name\f[R] class keyword argument (e.g.
- \f[C]class MyPluginIE(ABuiltInIE, plugin_name=\[aq]myplugin\[aq])\f[R]
- will replace \f[C]ABuiltInIE\f[R] with \f[C]MyPluginIE\f[R]).
- Since the extractor replaces the parent, you should exclude the subclass
- extractor from being imported separately by making it private using one
- of the methods described above.
- .PP
- If you are a plugin author, add
- yt-dlp-plugins (https://github.com/topics/yt-dlp-plugins) as a topic to
- your repository for discoverability.
- .PP
- See the Developer
- Instructions (https://github.com/yt-dlp/yt-dlp/blob/master/CONTRIBUTING.md#developer-instructions)
- on how to write and test an extractor.
- .SH EMBEDDING YT-DLP
- .PP
- yt-dlp makes the best effort to be a good command-line program, and thus
- should be callable from any programming language.
- .PP
- Your program should avoid parsing the normal stdout since they may
- change in future versions.
- Instead, they should use options such as \f[C]-J\f[R],
- \f[C]--print\f[R], \f[C]--progress-template\f[R], \f[C]--exec\f[R] etc
- to create console output that you can reliably reproduce and parse.
- .PP
- From a Python program, you can embed yt-dlp in a more powerful fashion,
- like this:
- .IP
- .nf
- \f[C]
- from yt_dlp import YoutubeDL
- URLS = [\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]]
- with YoutubeDL() as ydl:
- ydl.download(URLS)
- \f[R]
- .fi
- .PP
- Most likely, you\[aq]ll want to use various options.
- For a list of options available, have a look at
- \f[C]yt_dlp/YoutubeDL.py\f[R] or \f[C]help(yt_dlp.YoutubeDL)\f[R] in a
- Python shell.
- If you are already familiar with the CLI, you can use
- \f[C]devscripts/cli_to_api.py\f[R] (https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py)
- to translate any CLI switches to \f[C]YoutubeDL\f[R] params.
- .PP
- \f[B]Tip\f[R]: If you are porting your code from youtube-dl to yt-dlp,
- one important point to look out for is that we do not guarantee the
- return value of \f[C]YoutubeDL.extract_info\f[R] to be json
- serializable, or even be a dictionary.
- It will be dictionary-like, but if you want to ensure it is a
- serializable dictionary, pass it through
- \f[C]YoutubeDL.sanitize_info\f[R] as shown in the example below
- .SS Embedding examples
- .SS Extracting information
- .IP
- .nf
- \f[C]
- import json
- import yt_dlp
- URL = \[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]
- # \[u2139]\[uFE0F] See help(yt_dlp.YoutubeDL) for a list of available options and public functions
- ydl_opts = {}
- with yt_dlp.YoutubeDL(ydl_opts) as ydl:
- info = ydl.extract_info(URL, download=False)
- # \[u2139]\[uFE0F] ydl.sanitize_info makes the info json-serializable
- print(json.dumps(ydl.sanitize_info(info)))
- \f[R]
- .fi
- .SS Download using an info-json
- .IP
- .nf
- \f[C]
- import yt_dlp
- INFO_FILE = \[aq]path/to/video.info.json\[aq]
- with yt_dlp.YoutubeDL() as ydl:
- error_code = ydl.download_with_info_file(INFO_FILE)
- print(\[aq]Some videos failed to download\[aq] if error_code
- else \[aq]All videos successfully downloaded\[aq])
- \f[R]
- .fi
- .SS Extract audio
- .IP
- .nf
- \f[C]
- import yt_dlp
- URLS = [\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]]
- ydl_opts = {
- \[aq]format\[aq]: \[aq]m4a/bestaudio/best\[aq],
- # \[u2139]\[uFE0F] See help(yt_dlp.postprocessor) for a list of available Postprocessors and their arguments
- \[aq]postprocessors\[aq]: [{ # Extract audio using ffmpeg
- \[aq]key\[aq]: \[aq]FFmpegExtractAudio\[aq],
- \[aq]preferredcodec\[aq]: \[aq]m4a\[aq],
- }]
- }
- with yt_dlp.YoutubeDL(ydl_opts) as ydl:
- error_code = ydl.download(URLS)
- \f[R]
- .fi
- .SS Filter videos
- .IP
- .nf
- \f[C]
- import yt_dlp
- URLS = [\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]]
- def longer_than_a_minute(info, *, incomplete):
- \[dq]\[dq]\[dq]Download only videos longer than a minute (or with unknown duration)\[dq]\[dq]\[dq]
- duration = info.get(\[aq]duration\[aq])
- if duration and duration < 60:
- return \[aq]The video is too short\[aq]
- ydl_opts = {
- \[aq]match_filter\[aq]: longer_than_a_minute,
- }
- with yt_dlp.YoutubeDL(ydl_opts) as ydl:
- error_code = ydl.download(URLS)
- \f[R]
- .fi
- .SS Adding logger and progress hook
- .IP
- .nf
- \f[C]
- import yt_dlp
- URLS = [\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]]
- class MyLogger:
- def debug(self, msg):
- # For compatibility with youtube-dl, both debug and info are passed into debug
- # You can distinguish them by the prefix \[aq][debug] \[aq]
- if msg.startswith(\[aq][debug] \[aq]):
- pass
- else:
- self.info(msg)
- def info(self, msg):
- pass
- def warning(self, msg):
- pass
- def error(self, msg):
- print(msg)
- # \[u2139]\[uFE0F] See \[dq]progress_hooks\[dq] in help(yt_dlp.YoutubeDL)
- def my_hook(d):
- if d[\[aq]status\[aq]] == \[aq]finished\[aq]:
- print(\[aq]Done downloading, now post-processing ...\[aq])
- ydl_opts = {
- \[aq]logger\[aq]: MyLogger(),
- \[aq]progress_hooks\[aq]: [my_hook],
- }
- with yt_dlp.YoutubeDL(ydl_opts) as ydl:
- ydl.download(URLS)
- \f[R]
- .fi
- .SS Add a custom PostProcessor
- .IP
- .nf
- \f[C]
- import yt_dlp
- URLS = [\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]]
- # \[u2139]\[uFE0F] See help(yt_dlp.postprocessor.PostProcessor)
- class MyCustomPP(yt_dlp.postprocessor.PostProcessor):
- def run(self, info):
- self.to_screen(\[aq]Doing stuff\[aq])
- return [], info
- with yt_dlp.YoutubeDL() as ydl:
- # \[u2139]\[uFE0F] \[dq]when\[dq] can take any value in yt_dlp.utils.POSTPROCESS_WHEN
- ydl.add_post_processor(MyCustomPP(), when=\[aq]pre_process\[aq])
- ydl.download(URLS)
- \f[R]
- .fi
- .SS Use a custom format selector
- .IP
- .nf
- \f[C]
- import yt_dlp
- URLS = [\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]]
- def format_selector(ctx):
- \[dq]\[dq]\[dq] Select the best video and the best audio that won\[aq]t result in an mkv.
- NOTE: This is just an example and does not handle all cases \[dq]\[dq]\[dq]
- # formats are already sorted worst to best
- formats = ctx.get(\[aq]formats\[aq])[::-1]
- # acodec=\[aq]none\[aq] means there is no audio
- best_video = next(f for f in formats
- if f[\[aq]vcodec\[aq]] != \[aq]none\[aq] and f[\[aq]acodec\[aq]] == \[aq]none\[aq])
- # find compatible audio extension
- audio_ext = {\[aq]mp4\[aq]: \[aq]m4a\[aq], \[aq]webm\[aq]: \[aq]webm\[aq]}[best_video[\[aq]ext\[aq]]]
- # vcodec=\[aq]none\[aq] means there is no video
- best_audio = next(f for f in formats if (
- f[\[aq]acodec\[aq]] != \[aq]none\[aq] and f[\[aq]vcodec\[aq]] == \[aq]none\[aq] and f[\[aq]ext\[aq]] == audio_ext))
- # These are the minimum required fields for a merged format
- yield {
- \[aq]format_id\[aq]: f\[aq]{best_video[\[dq]format_id\[dq]]}+{best_audio[\[dq]format_id\[dq]]}\[aq],
- \[aq]ext\[aq]: best_video[\[aq]ext\[aq]],
- \[aq]requested_formats\[aq]: [best_video, best_audio],
- # Must be + separated list of protocols
- \[aq]protocol\[aq]: f\[aq]{best_video[\[dq]protocol\[dq]]}+{best_audio[\[dq]protocol\[dq]]}\[aq]
- }
- ydl_opts = {
- \[aq]format\[aq]: format_selector,
- }
- with yt_dlp.YoutubeDL(ydl_opts) as ydl:
- ydl.download(URLS)
- \f[R]
- .fi
- .SH CHANGES FROM YOUTUBE-DL
- .SS New features
- .IP \[bu] 2
- Forked from
- \f[B]yt-dlc\[at]f9401f2\f[R] (https://github.com/blackjack4494/yt-dlc/commit/f9401f2a91987068139c5f757b12fc711d4c0cee)
- and merged with
- \f[B]youtube-dl\[at]a08f2b7\f[R] (https://github.com/ytdl-org/youtube-dl/commit/a08f2b7e4567cdc50c0614ee0a4ffdff49b8b6e6)
- (exceptions (https://github.com/yt-dlp/yt-dlp/issues/21))
- .IP \[bu] 2
- \f[B]SponsorBlock Integration\f[R]: You can mark/remove sponsor sections
- in YouTube videos by utilizing the
- SponsorBlock (https://sponsor.ajay.app) API
- .IP \[bu] 2
- \f[B]Format Sorting\f[R]: The default format sorting options have been
- changed so that higher resolution and better codecs will be now
- preferred instead of simply using larger bitrate.
- Furthermore, you can now specify the sort order using \f[C]-S\f[R].
- This allows for much easier format selection than what is possible by
- simply using \f[C]--format\f[R] (examples)
- .IP \[bu] 2
- \f[B]Merged with animelover1984/youtube-dl\f[R]: You get most of the
- features and improvements from
- animelover1984/youtube-dl (https://github.com/animelover1984/youtube-dl)
- including \f[C]--write-comments\f[R], \f[C]BiliBiliSearch\f[R],
- \f[C]BilibiliChannel\f[R], Embedding thumbnail in mp4/ogg/opus, playlist
- infojson etc.
- Note that NicoNico livestreams are not available.
- See #31 (https://github.com/yt-dlp/yt-dlp/pull/31) for details.
- .IP \[bu] 2
- \f[B]YouTube improvements\f[R]:
- .RS 2
- .IP \[bu] 2
- Supports Clips, Stories (\f[C]ytstories:<channel UCID>\f[R]), Search
- (including filters)\f[B]*\f[R], YouTube Music Search, Channel-specific
- search, Search prefixes (\f[C]ytsearch:\f[R],
- \f[C]ytsearchdate:\f[R])\f[B]*\f[R], Mixes, and Feeds (\f[C]:ytfav\f[R],
- \f[C]:ytwatchlater\f[R], \f[C]:ytsubs\f[R], \f[C]:ythistory\f[R],
- \f[C]:ytrec\f[R], \f[C]:ytnotif\f[R])
- .IP \[bu] 2
- Fix for n-sig based
- throttling (https://github.com/ytdl-org/youtube-dl/issues/29326)
- \f[B]*\f[R]
- .IP \[bu] 2
- Download livestreams from the start using \f[C]--live-from-start\f[R]
- (\f[I]experimental\f[R])
- .IP \[bu] 2
- Channel URLs download all uploads of the channel, including shorts and
- live
- .IP \[bu] 2
- Support for logging in with
- OAuth (https://github.com/yt-dlp/yt-dlp/wiki/Extractors#logging-in-with-oauth)
- .RE
- .IP \[bu] 2
- \f[B]Cookies from browser\f[R]: Cookies can be automatically extracted
- from all major web browsers using
- \f[C]--cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]\f[R]
- .IP \[bu] 2
- \f[B]Download time range\f[R]: Videos can be downloaded partially based
- on either timestamps or chapters using \f[C]--download-sections\f[R]
- .IP \[bu] 2
- \f[B]Split video by chapters\f[R]: Videos can be split into multiple
- files based on chapters using \f[C]--split-chapters\f[R]
- .IP \[bu] 2
- \f[B]Multi-threaded fragment downloads\f[R]: Download multiple fragments
- of m3u8/mpd videos in parallel.
- Use \f[C]--concurrent-fragments\f[R] (\f[C]-N\f[R]) option to set the
- number of threads used
- .IP \[bu] 2
- \f[B]Aria2c with HLS/DASH\f[R]: You can use \f[C]aria2c\f[R] as the
- external downloader for DASH(mpd) and HLS(m3u8) formats
- .IP \[bu] 2
- \f[B]New and fixed extractors\f[R]: Many new extractors have been added
- and a lot of existing ones have been fixed.
- See the changelog or the list of supported sites
- .IP \[bu] 2
- \f[B]New MSOs\f[R]: Philo, Spectrum, SlingTV, Cablevision, RCN etc.
- .IP \[bu] 2
- \f[B]Subtitle extraction from manifests\f[R]: Subtitles can be extracted
- from streaming media manifests.
- See
- commit/be6202f (https://github.com/yt-dlp/yt-dlp/commit/be6202f12b97858b9d716e608394b51065d0419f)
- for details
- .IP \[bu] 2
- \f[B]Multiple paths and output templates\f[R]: You can give different
- output templates and download paths for different types of files.
- You can also set a temporary path where intermediary files are
- downloaded to using \f[C]--paths\f[R] (\f[C]-P\f[R])
- .IP \[bu] 2
- \f[B]Portable Configuration\f[R]: Configuration files are automatically
- loaded from the home and root directories.
- See CONFIGURATION for details
- .IP \[bu] 2
- \f[B]Output template improvements\f[R]: Output templates can now have
- date-time formatting, numeric offsets, object traversal etc.
- See output template for details.
- Even more advanced operations can also be done with the help of
- \f[C]--parse-metadata\f[R] and \f[C]--replace-in-metadata\f[R]
- .IP \[bu] 2
- \f[B]Other new options\f[R]: Many new options have been added such as
- \f[C]--alias\f[R], \f[C]--print\f[R], \f[C]--concat-playlist\f[R],
- \f[C]--wait-for-video\f[R], \f[C]--retry-sleep\f[R],
- \f[C]--sleep-requests\f[R], \f[C]--convert-thumbnails\f[R],
- \f[C]--force-download-archive\f[R], \f[C]--force-overwrites\f[R],
- \f[C]--break-match-filters\f[R] etc
- .IP \[bu] 2
- \f[B]Improvements\f[R]: Regex and other operators in
- \f[C]--format\f[R]/\f[C]--match-filters\f[R], multiple
- \f[C]--postprocessor-args\f[R] and \f[C]--downloader-args\f[R], faster
- archive checking, more format selection options, merge
- multi-video/audio, multiple \f[C]--config-locations\f[R],
- \f[C]--exec\f[R] at different stages, etc
- .IP \[bu] 2
- \f[B]Plugins\f[R]: Extractors and PostProcessors can be loaded from an
- external file.
- See plugins for details
- .IP \[bu] 2
- \f[B]Self updater\f[R]: The releases can be updated using
- \f[C]yt-dlp -U\f[R], and downgraded using \f[C]--update-to\f[R] if
- required
- .IP \[bu] 2
- \f[B]Automated builds\f[R]: Nightly/master builds can be used with
- \f[C]--update-to nightly\f[R] and \f[C]--update-to master\f[R]
- .PP
- See changelog or commits (https://github.com/yt-dlp/yt-dlp/commits) for
- the full list of changes
- .PP
- Features marked with a \f[B]*\f[R] have been back-ported to youtube-dl
- .SS Differences in default behavior
- .PP
- Some of yt-dlp\[aq]s default options are different from that of
- youtube-dl and youtube-dlc:
- .IP \[bu] 2
- yt-dlp supports only Python 3.9+, and will remove support for more
- versions as they become
- EOL (https://devguide.python.org/versions/#python-release-cycle); while
- youtube-dl still supports Python 2.6+ and
- 3.2+ (https://github.com/ytdl-org/youtube-dl/issues/30568#issue-1118238743)
- .IP \[bu] 2
- The options \f[C]--auto-number\f[R] (\f[C]-A\f[R]), \f[C]--title\f[R]
- (\f[C]-t\f[R]) and \f[C]--literal\f[R] (\f[C]-l\f[R]), no longer work.
- See removed options for details
- .IP \[bu] 2
- \f[C]avconv\f[R] is not supported as an alternative to \f[C]ffmpeg\f[R]
- .IP \[bu] 2
- yt-dlp stores config files in slightly different locations to
- youtube-dl.
- See CONFIGURATION for a list of correct locations
- .IP \[bu] 2
- The default output template is \f[C]%(title)s [%(id)s].%(ext)s\f[R].
- There is no real reason for this change.
- This was changed before yt-dlp was ever made public and now there are no
- plans to change it back to \f[C]%(title)s-%(id)s.%(ext)s\f[R].
- Instead, you may use \f[C]--compat-options filename\f[R]
- .IP \[bu] 2
- The default format sorting is different from youtube-dl and prefers
- higher resolution and better codecs rather than higher bitrates.
- You can use the \f[C]--format-sort\f[R] option to change this to any
- order you prefer, or use \f[C]--compat-options format-sort\f[R] to use
- youtube-dl\[aq]s sorting order.
- Older versions of yt-dlp preferred VP9 due to its broader compatibility;
- you can use \f[C]--compat-options prefer-vp9-sort\f[R] to revert to that
- format sorting preference.
- These two compat options cannot be used together
- .IP \[bu] 2
- The default format selector is \f[C]bv*+ba/b\f[R].
- This means that if a combined video + audio format that is better than
- the best video-only format is found, the former will be preferred.
- Use \f[C]-f bv+ba/b\f[R] or \f[C]--compat-options format-spec\f[R] to
- revert this
- .IP \[bu] 2
- Unlike youtube-dlc, yt-dlp does not allow merging multiple audio/video
- streams into one file by default (since this conflicts with the use of
- \f[C]-f bv*+ba\f[R]).
- If needed, this feature must be enabled using
- \f[C]--audio-multistreams\f[R] and \f[C]--video-multistreams\f[R].
- You can also use \f[C]--compat-options multistreams\f[R] to enable both
- .IP \[bu] 2
- \f[C]--no-abort-on-error\f[R] is enabled by default.
- Use \f[C]--abort-on-error\f[R] or
- \f[C]--compat-options abort-on-error\f[R] to abort on errors instead
- .IP \[bu] 2
- When writing metadata files such as thumbnails, description or infojson,
- the same information (if available) is also written for playlists.
- Use \f[C]--no-write-playlist-metafiles\f[R] or
- \f[C]--compat-options no-playlist-metafiles\f[R] to not write these
- files
- .IP \[bu] 2
- \f[C]--add-metadata\f[R] attaches the \f[C]infojson\f[R] to
- \f[C]mkv\f[R] files in addition to writing the metadata when used with
- \f[C]--write-info-json\f[R].
- Use \f[C]--no-embed-info-json\f[R] or
- \f[C]--compat-options no-attach-info-json\f[R] to revert this
- .IP \[bu] 2
- Some metadata are embedded into different fields when using
- \f[C]--add-metadata\f[R] as compared to youtube-dl.
- Most notably, \f[C]comment\f[R] field contains the \f[C]webpage_url\f[R]
- and \f[C]synopsis\f[R] contains the \f[C]description\f[R].
- You can use \f[C]--parse-metadata\f[R] to modify this to your liking or
- use \f[C]--compat-options embed-metadata\f[R] to revert this
- .IP \[bu] 2
- \f[C]playlist_index\f[R] behaves differently when used with options like
- \f[C]--playlist-reverse\f[R] and \f[C]--playlist-items\f[R].
- See #302 (https://github.com/yt-dlp/yt-dlp/issues/302) for details.
- You can use \f[C]--compat-options playlist-index\f[R] if you want to
- keep the earlier behavior
- .IP \[bu] 2
- The output of \f[C]-F\f[R] is listed in a new format.
- Use \f[C]--compat-options list-formats\f[R] to revert this
- .IP \[bu] 2
- Live chats (if available) are considered as subtitles.
- Use \f[C]--sub-langs all,-live_chat\f[R] to download all subtitles
- except live chat.
- You can also use \f[C]--compat-options no-live-chat\f[R] to prevent any
- live chat/danmaku from downloading
- .IP \[bu] 2
- YouTube channel URLs download all uploads of the channel.
- To download only the videos in a specific tab, pass the tab\[aq]s URL.
- If the channel does not show the requested tab, an error will be raised.
- Also, \f[C]/live\f[R] URLs raise an error if there are no live videos
- instead of silently downloading the entire channel.
- You may use \f[C]--compat-options no-youtube-channel-redirect\f[R] to
- revert all these redirections
- .IP \[bu] 2
- Unavailable videos are also listed for YouTube playlists.
- Use \f[C]--compat-options no-youtube-unavailable-videos\f[R] to remove
- this
- .IP \[bu] 2
- The upload dates extracted from YouTube are in UTC when
- available (https://github.com/yt-dlp/yt-dlp/blob/89e4d86171c7b7c997c77d4714542e0383bf0db0/yt_dlp/extractor/youtube.py#L3898-L3900).
- Use \f[C]--compat-options no-youtube-prefer-utc-upload-date\f[R] to
- prefer the non-UTC upload date.
- .IP \[bu] 2
- If \f[C]ffmpeg\f[R] is used as the downloader, the downloading and
- merging of formats happen in a single step when possible.
- Use \f[C]--compat-options no-direct-merge\f[R] to revert this
- .IP \[bu] 2
- Thumbnail embedding in \f[C]mp4\f[R] is done with mutagen if possible.
- Use \f[C]--compat-options embed-thumbnail-atomicparsley\f[R] to force
- the use of AtomicParsley instead
- .IP \[bu] 2
- Some internal metadata such as filenames are removed by default from the
- infojson.
- Use \f[C]--no-clean-infojson\f[R] or
- \f[C]--compat-options no-clean-infojson\f[R] to revert this
- .IP \[bu] 2
- When \f[C]--embed-subs\f[R] and \f[C]--write-subs\f[R] are used
- together, the subtitles are written to disk and also embedded in the
- media file.
- You can use just \f[C]--embed-subs\f[R] to embed the subs and
- automatically delete the separate file.
- See #630
- (comment) (https://github.com/yt-dlp/yt-dlp/issues/630#issuecomment-893659460)
- for more info.
- \f[C]--compat-options no-keep-subs\f[R] can be used to revert this
- .IP \[bu] 2
- \f[C]certifi\f[R] will be used for SSL root certificates, if installed.
- If you want to use system certificates (e.g.
- self-signed), use \f[C]--compat-options no-certifi\f[R]
- .IP \[bu] 2
- yt-dlp\[aq]s sanitization of invalid characters in filenames is
- different/smarter than in youtube-dl.
- You can use \f[C]--compat-options filename-sanitization\f[R] to revert
- to youtube-dl\[aq]s behavior
- .IP \[bu] 2
- [STRIKEOUT:yt-dlp tries to parse the external downloader outputs into
- the standard progress output if possible (Currently implemented:
- aria2c (https://github.com/yt-dlp/yt-dlp/issues/5931)). You can use
- \f[C]--compat-options no-external-downloader-progress\f[R] to get the
- downloader output as-is]
- .IP \[bu] 2
- yt-dlp versions between 2021.09.01 and 2023.01.02 applies
- \f[C]--match-filters\f[R] to nested playlists.
- This was an unintentional side-effect of
- 8f18ac (https://github.com/yt-dlp/yt-dlp/commit/8f18aca8717bb0dd49054555af8d386e5eda3a88)
- and is fixed in
- d7b460 (https://github.com/yt-dlp/yt-dlp/commit/d7b460d0e5fc710950582baed2e3fc616ed98a80).
- Use \f[C]--compat-options playlist-match-filter\f[R] to revert this
- .IP \[bu] 2
- yt-dlp versions between 2021.11.10 and 2023.06.21 estimated
- \f[C]filesize_approx\f[R] values for fragmented/manifest formats.
- This was added for convenience in
- f2fe69 (https://github.com/yt-dlp/yt-dlp/commit/f2fe69c7b0d208bdb1f6292b4ae92bc1e1a7444a),
- but was reverted in
- 0dff8e (https://github.com/yt-dlp/yt-dlp/commit/0dff8e4d1e6e9fb938f4256ea9af7d81f42fd54f)
- due to the potentially extreme inaccuracy of the estimated values.
- Use \f[C]--compat-options manifest-filesize-approx\f[R] to keep
- extracting the estimated values
- .IP \[bu] 2
- yt-dlp uses modern http client backends such as \f[C]requests\f[R].
- Use \f[C]--compat-options prefer-legacy-http-handler\f[R] to prefer the
- legacy http handler (\f[C]urllib\f[R]) to be used for standard http
- requests.
- .IP \[bu] 2
- The sub-modules \f[C]swfinterp\f[R], \f[C]casefold\f[R] are removed.
- .IP \[bu] 2
- Passing \f[C]--simulate\f[R] (or calling \f[C]extract_info\f[R] with
- \f[C]download=False\f[R]) no longer alters the default format selection.
- See #9843 (https://github.com/yt-dlp/yt-dlp/issues/9843) for details.
- .PP
- For ease of use, a few more compat options are available:
- .IP \[bu] 2
- \f[C]--compat-options all\f[R]: Use all compat options (\f[B]Do NOT use
- this!\f[R])
- .IP \[bu] 2
- \f[C]--compat-options youtube-dl\f[R]: Same as
- \f[C]--compat-options all,-multistreams,-playlist-match-filter,-manifest-filesize-approx,-allow-unsafe-ext,-prefer-vp9-sort\f[R]
- .IP \[bu] 2
- \f[C]--compat-options youtube-dlc\f[R]: Same as
- \f[C]--compat-options all,-no-live-chat,-no-youtube-channel-redirect,-playlist-match-filter,-manifest-filesize-approx,-allow-unsafe-ext,-prefer-vp9-sort\f[R]
- .IP \[bu] 2
- \f[C]--compat-options 2021\f[R]: Same as
- \f[C]--compat-options 2022,no-certifi,filename-sanitization,no-youtube-prefer-utc-upload-date\f[R]
- .IP \[bu] 2
- \f[C]--compat-options 2022\f[R]: Same as
- \f[C]--compat-options 2023,playlist-match-filter,no-external-downloader-progress,prefer-legacy-http-handler,manifest-filesize-approx\f[R]
- .IP \[bu] 2
- \f[C]--compat-options 2023\f[R]: Same as
- \f[C]--compat-options prefer-vp9-sort\f[R].
- Use this to enable all future compat options
- .PP
- The following compat options restore vulnerable behavior from before
- security patches:
- .IP \[bu] 2
- \f[C]--compat-options allow-unsafe-ext\f[R]: Allow files with any
- extension (including unsafe ones) to be downloaded
- (GHSA-79w7-vh3h-8g4j (https://github.com/yt-dlp/yt-dlp/security/advisories/GHSA-79w7-vh3h-8g4j))
- .RS 2
- .RS
- .PP
- :warning: Only use if a valid file download is rejected because its
- extension is detected as uncommon
- .PP
- \f[B]This option can enable remote code execution! Consider opening an
- issue (https://github.com/yt-dlp/yt-dlp/issues/new/choose) instead!\f[R]
- .RE
- .RE
- .SS Deprecated options
- .PP
- These are all the deprecated options and the current alternative to
- achieve the same effect
- .SS Almost redundant options
- .PP
- While these options are almost the same as their new counterparts, there
- are some differences that prevents them being redundant
- .IP
- .nf
- \f[C]
- -j, --dump-json --print \[dq]%()j\[dq]
- -F, --list-formats --print formats_table
- --list-thumbnails --print thumbnails_table --print playlist:thumbnails_table
- --list-subs --print automatic_captions_table --print subtitles_table
- \f[R]
- .fi
- .SS Redundant options
- .PP
- While these options are redundant, they are still expected to be used
- due to their ease of use
- .IP
- .nf
- \f[C]
- --get-description --print description
- --get-duration --print duration_string
- --get-filename --print filename
- --get-format --print format
- --get-id --print id
- --get-thumbnail --print thumbnail
- -e, --get-title --print title
- -g, --get-url --print urls
- --match-title REGEX --match-filters \[dq]title \[ti]= (?i)REGEX\[dq]
- --reject-title REGEX --match-filters \[dq]title !\[ti]= (?i)REGEX\[dq]
- --min-views COUNT --match-filters \[dq]view_count >=? COUNT\[dq]
- --max-views COUNT --match-filters \[dq]view_count <=? COUNT\[dq]
- --break-on-reject Use --break-match-filters
- --user-agent UA --add-headers \[dq]User-Agent:UA\[dq]
- --referer URL --add-headers \[dq]Referer:URL\[dq]
- --playlist-start NUMBER -I NUMBER:
- --playlist-end NUMBER -I :NUMBER
- --playlist-reverse -I ::-1
- --no-playlist-reverse Default
- --no-colors --color no_color
- \f[R]
- .fi
- .SS Not recommended
- .PP
- While these options still work, their use is not recommended since there
- are other alternatives to achieve the same
- .IP
- .nf
- \f[C]
- --force-generic-extractor --ies generic,default
- --exec-before-download CMD --exec \[dq]before_dl:CMD\[dq]
- --no-exec-before-download --no-exec
- --all-formats -f all
- --all-subs --sub-langs all --write-subs
- --print-json -j --no-simulate
- --autonumber-size NUMBER Use string formatting, e.g. %(autonumber)03d
- --autonumber-start NUMBER Use internal field formatting like %(autonumber+NUMBER)s
- --id -o \[dq]%(id)s.%(ext)s\[dq]
- --metadata-from-title FORMAT --parse-metadata \[dq]%(title)s:FORMAT\[dq]
- --hls-prefer-native --downloader \[dq]m3u8:native\[dq]
- --hls-prefer-ffmpeg --downloader \[dq]m3u8:ffmpeg\[dq]
- --list-formats-old --compat-options list-formats (Alias: --no-list-formats-as-table)
- --list-formats-as-table --compat-options -list-formats [Default] (Alias: --no-list-formats-old)
- --youtube-skip-dash-manifest --extractor-args \[dq]youtube:skip=dash\[dq] (Alias: --no-youtube-include-dash-manifest)
- --youtube-skip-hls-manifest --extractor-args \[dq]youtube:skip=hls\[dq] (Alias: --no-youtube-include-hls-manifest)
- --youtube-include-dash-manifest Default (Alias: --no-youtube-skip-dash-manifest)
- --youtube-include-hls-manifest Default (Alias: --no-youtube-skip-hls-manifest)
- --geo-bypass --xff \[dq]default\[dq]
- --no-geo-bypass --xff \[dq]never\[dq]
- --geo-bypass-country CODE --xff CODE
- --geo-bypass-ip-block IP_BLOCK --xff IP_BLOCK
- \f[R]
- .fi
- .SS Developer options
- .PP
- These options are not intended to be used by the end-user
- .IP
- .nf
- \f[C]
- --test Download only part of video for testing extractors
- --load-pages Load pages dumped by --write-pages
- --youtube-print-sig-code For testing youtube signatures
- --allow-unplayable-formats List unplayable formats also
- --no-allow-unplayable-formats Default
- \f[R]
- .fi
- .SS Old aliases
- .PP
- These are aliases that are no longer documented for various reasons
- .IP
- .nf
- \f[C]
- --avconv-location --ffmpeg-location
- --clean-infojson --clean-info-json
- --cn-verification-proxy URL --geo-verification-proxy URL
- --dump-headers --print-traffic
- --dump-intermediate-pages --dump-pages
- --force-write-download-archive --force-write-archive
- --load-info --load-info-json
- --no-clean-infojson --no-clean-info-json
- --no-split-tracks --no-split-chapters
- --no-write-srt --no-write-subs
- --prefer-unsecure --prefer-insecure
- --rate-limit RATE --limit-rate RATE
- --split-tracks --split-chapters
- --srt-lang LANGS --sub-langs LANGS
- --trim-file-names LENGTH --trim-filenames LENGTH
- --write-srt --write-subs
- --yes-overwrites --force-overwrites
- \f[R]
- .fi
- .SS Sponskrub Options
- .PP
- Support for SponSkrub (https://github.com/faissaloo/SponSkrub) has been
- deprecated in favor of the \f[C]--sponsorblock\f[R] options
- .IP
- .nf
- \f[C]
- --sponskrub --sponsorblock-mark all
- --no-sponskrub --no-sponsorblock
- --sponskrub-cut --sponsorblock-remove all
- --no-sponskrub-cut --sponsorblock-remove -all
- --sponskrub-force Not applicable
- --no-sponskrub-force Not applicable
- --sponskrub-location Not applicable
- --sponskrub-args Not applicable
- \f[R]
- .fi
- .SS No longer supported
- .PP
- These options may no longer work as intended
- .IP
- .nf
- \f[C]
- --prefer-avconv avconv is not officially supported by yt-dlp (Alias: --no-prefer-ffmpeg)
- --prefer-ffmpeg Default (Alias: --no-prefer-avconv)
- -C, --call-home Not implemented
- --no-call-home Default
- --include-ads No longer supported
- --no-include-ads Default
- --write-annotations No supported site has annotations now
- --no-write-annotations Default
- --compat-options seperate-video-versions No longer needed
- --compat-options no-youtube-prefer-utc-upload-date No longer supported
- \f[R]
- .fi
- .SS Removed
- .PP
- These options were deprecated since 2014 and have now been entirely
- removed
- .IP
- .nf
- \f[C]
- -A, --auto-number -o \[dq]%(autonumber)s-%(id)s.%(ext)s\[dq]
- -t, -l, --title, --literal -o \[dq]%(title)s-%(id)s.%(ext)s\[dq]
- \f[R]
- .fi
- .SH CONTRIBUTING
- .PP
- See CONTRIBUTING.md for instructions on Opening an Issue and
- Contributing code to the project
- .SH WIKI
- .PP
- See the Wiki (https://github.com/yt-dlp/yt-dlp/wiki) for more
- information