# YT-DLP
-<!-- See: https://github.com/marketplace/actions/dynamic-badges -->
-[](https://github.com/pukkandan/yt-dlp/releases/latest)
-[](https://github.com/pukkandan/yt-dlp/blob/master/LICENSE)
-[](https://github.com/pukkandan/yt-dlp/actions?query=workflow%3ACore)
-[](https://github.com/pukkandan/yt-dlp/actions?query=workflow%3AFull)
+[](https://github.com/pukkandan/yt-dlp/releases/latest)
+[](LICENSE)
+[](https://github.com/pukkandan/yt-dlp/actions)
+[](https://github.com/pukkandan/yt-dlp/commits)
+[](https://github.com/pukkandan/yt-dlp/commits)
+[](https://github.com/pukkandan/yt-dlp/releases/latest)
+[](https://pypi.org/project/yt-dlp)
A command-line program to download videos from youtube.com and many other [video platforms](docs/supportedsites.md)
* [Filtering Formats](#filtering-formats)
* [Sorting Formats](#sorting-formats)
* [Format Selection examples](#format-selection-examples)
+* [PLUGINS](#plugins)
* [MORE](#more)
* **[Format Sorting](#sorting-formats)**: 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 `-S`. This allows for much easier format selection that what is possible by simply using `--format` ([examples](#format-selection-examples))
-* **Merged with youtube-dl v2021.01.16**: You get all the latest features and patches of [youtube-dl](https://github.com/ytdl-org/youtube-dl) in addition to all the features of [youtube-dlc](https://github.com/blackjack4494/yt-dlc)
+* **Merged with youtube-dl v2021.01.24.1**: You get all the latest features and patches of [youtube-dl](https://github.com/ytdl-org/youtube-dl) in addition to all the features of [youtube-dlc](https://github.com/blackjack4494/yt-dlc)
* **Youtube improvements**:
* All Youtube Feeds (`:ytfav`, `:ytwatchlater`, `:ytsubs`, `:ythistory`, `:ytrec`) works correctly and support downloading multiple pages of content
* Youtube search works correctly (`ytsearch:`, `ytsearchdate:`) along with Search URLs
* Redirect channel's home URL automatically to `/video` to preserve the old behaviour
-* **New extractors**: Trovo.live, AnimeLab, Philo MSO, Rcs, Gedi, bitwave.tv
+* **New extractors**: AnimeLab, Philo MSO, Rcs, Gedi, bitwave.tv, mildom
* **Fixed extractors**: archive.org, roosterteeth.com, skyit, instagram, itv, SouthparkDe, spreaker, Vlive, tiktok, akamai, ina
-* **New options**: `--list-formats-as-table`, `--write-link`, `--force-download-archive`, `--force-overwrites`, `--break-on-reject` etc
+* **Plugin support**: Extractors can be loaded from an external file. See [plugins](#plugins) for details
-* **Improvements**: Multiple `--postprocessor-args`, `%(duration_string)s` in `-o`, faster archive checking, more [format selection options](#format-selection) etc
+* **Multiple paths**: You can give different paths for different types of files. You can also set a temporary path where intermediary files are downloaded to. See [`--paths`](https://github.com/pukkandan/yt-dlp/#:~:text=-P,%20--paths%20TYPE:PATH) for details
+
+<!-- Relative link doesn't work for "#:~:text=" -->
+
+* **Portable Configuration**: Configuration files are automatically loaded from the home and root directories. See [configuration](#configuration) for details
+
+* **Other new options**: `--list-formats-as-table`, `--write-link`, `--force-download-archive`, `--force-overwrites`, `--break-on-reject` etc
+
+* **Improvements**: Multiple `--postprocessor-args` and `--external-downloader-args`, `%(duration_string)s` in `-o`, faster archive checking, more [format selection options](#format-selection) etc
See [changelog](Changelog.md) or [commits](https://github.com/pukkandan/yt-dlp/commits) for the full list of changes
# INSTALLATION
You can install yt-dlp using one of the following methods:
-* Use [PyPI package](https://pypi.org/project/yt-dlp/): `python -m pip install --upgrade yt-dlp`
+* Use [PyPI package](https://pypi.org/project/yt-dlp): `python -m pip install --upgrade yt-dlp`
* Download the binary from the [latest release](https://github.com/pukkandan/yt-dlp/releases/latest)
* Use pip+git: `python -m pip install --upgrade git+https://github.com/pukkandan/yt-dlp.git@release`
* Install master branch: `python -m pip install --upgrade git+https://github.com/pukkandan/yt-dlp`
compatibility) if this option is found
inside the system configuration file, the
user configuration is not loaded
- --config-location PATH Location of the configuration file; either
- the path to the config or its containing
- directory
+ --config-location PATH Location of the main configuration file;
+ either the path to the config or its
+ containing directory
--flat-playlist Do not extract the videos of a playlist,
only list them
--flat-videos Do not resolve the video urls
allowing to play the video while
downloading (some players may not be able
to play it)
- --external-downloader COMMAND Use the specified external downloader.
- Currently supports
- aria2c,avconv,axel,curl,ffmpeg,httpie,wget
- --external-downloader-args ARGS Give these arguments to the external
- downloader
+ --external-downloader NAME Use the specified external downloader.
+ Currently supports aria2c, avconv, axel,
+ curl, ffmpeg, httpie, wget
+ --downloader-args NAME:ARGS Give these arguments to the external
+ downloader. Specify the downloader name and
+ the arguments separated by a colon ":". You
+ can use this option multiple times (Alias:
+ --external-downloader-args)
## Filesystem Options:
-a, --batch-file FILE File containing URLs to download ('-' for
stdin), one URL per line. Lines starting
with '#', ';' or ']' are considered as
comments and ignored
+ -P, --paths TYPE:PATH The paths where the files should be
+ downloaded. Specify the type of file and
+ the path separated by a colon ":"
+ (supported: description|annotation|subtitle
+ |infojson|thumbnail). Additionally, you can
+ also provide "home" and "temp" 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. Note that this option is
+ ignored if --output is an absolute path
-o, --output TEMPLATE Output filename template, see "OUTPUT
TEMPLATE" for details
+ --output-na-placeholder TEXT Placeholder value for unavailable meta
+ fields in output filename template
+ (default: "NA")
--autonumber-start NUMBER Specify the start value for %(autonumber)s
(default is 1)
--restrict-filenames Restrict filenames to only ASCII
--write-annotations Write video annotations to a
.annotations.xml file
--no-write-annotations Do not write video annotations (default)
+ --get-comments Retrieve video comments to be placed in the
+ .info.json file
--load-info-json FILE JSON file containing the video information
(created with the "--write-info-json"
option)
--referer URL Specify a custom referer, use if the video
access is restricted to one domain
--add-header FIELD:VALUE Specify a custom HTTP header and its value,
- separated by a colon ':'. You can use this
+ separated by a colon ":". You can use this
option multiple times
--bidi-workaround Work around terminals that lack
bidirectional text support. Requires bidiv
## Post-Processing Options:
-x, --extract-audio Convert video files to audio-only files
- (requires ffmpeg or avconv and ffprobe or
- avprobe)
+ (requires ffmpeg and ffprobe)
--audio-format FORMAT Specify audio format: "best", "aac",
"flac", "mp3", "m4a", "opus", "vorbis", or
"wav"; "best" by default; No effect without
-x
- --audio-quality QUALITY Specify ffmpeg/avconv audio quality, insert
- a value between 0 (better) and 9 (worse)
- for VBR or a specific bitrate like 128K
+ --audio-quality QUALITY Specify ffmpeg audio quality, insert a
+ value between 0 (better) and 9 (worse) for
+ VBR or a specific bitrate like 128K
(default 5)
--remux-video FORMAT Remux the video into another container if
necessary (currently supported: mp4|mkv).
If target container does not support the
- video/audio codec, remuxing will fail
+ video/audio codec, remuxing will fail. You
+ can specify multiple rules; eg.
+ "aac>m4a/mov>mp4/mkv" will remux aac to
+ m4a, mov to mp4 and anything else to mkv.
--recode-video FORMAT Re-encode the video into another format if
re-encoding is necessary (currently
supported: mp4|flv|ogg|webm|mkv|avi)
--postprocessor-args NAME:ARGS Give these arguments to the postprocessors.
Specify the postprocessor/executable name
- and the arguments separated by a colon ':'
- to give the argument to only the specified
+ and the arguments separated by a colon ":"
+ to give the argument to the specified
postprocessor/executable. Supported
postprocessors are: SponSkrub,
ExtractAudio, VideoRemuxer, VideoConvertor,
FixupStretched, FixupM4a, FixupM3u8,
SubtitlesConvertor and EmbedThumbnail. The
supported executables are: SponSkrub,
- FFmpeg, FFprobe, avconf, avprobe and
- AtomicParsley. You can use this option
- multiple times to give different arguments
- to different postprocessors. You can also
- specify "PP+EXE:ARGS" to give the arguments
- to the specified executable only when being
- used by the specified postprocessor (Alias:
- --ppa)
+ FFmpeg, FFprobe, and AtomicParsley. You can
+ use this option multiple times to give
+ different arguments to different
+ postprocessors. You can also specify
+ "PP+EXE:ARGS" to give the arguments to the
+ specified executable only when being used
+ by the specified postprocessor. You can use
+ this option multiple times (Alias: --ppa)
-k, --keep-video Keep the intermediate video file on disk
after post-processing
--no-keep-video Delete the intermediate video file after
--no-embed-thumbnail Do not embed thumbnail (default)
--add-metadata Write metadata to the video file
--no-add-metadata Do not write metadata (default)
- --metadata-from-title FORMAT Parse additional metadata like song title /
- artist from the video title. The format
- syntax is the same as --output. Regular
- expression with named capture groups may
- also be used. The parsed parameters replace
- existing values. Example: --metadata-from-
- title "%(artist)s - %(title)s" matches a
+ --parse-metadata FIELD:FORMAT Parse additional metadata like title/artist
+ from other fields. Give field name to
+ extract data from, and format of the field
+ seperated by a ":". The format syntax is
+ the same as --output. Regular expression
+ with named capture groups may also be used.
+ The parsed parameters replace existing
+ values. This option can be used multiple
+ times. Example: --parse-metadata
+ "title:%(artist)s - %(title)s" matches a
title like "Coldplay - Paradise". Example
- (regex): --metadata-from-title
- "(?P<artist>.+?) - (?P<title>.+)"
+ (regex): --parse-metadata
+ "description:Artist - (?P<artist>.+?)"
--xattrs Write metadata to the video file's xattrs
(using dublin core and xdg standards)
--fixup POLICY Automatically correct known faults of the
emit a warning), detect_or_warn (the
default; fix file if we can, warn
otherwise)
- --prefer-avconv Prefer avconv over ffmpeg for running the
- postprocessors (Alias: --no-prefer-ffmpeg)
- --prefer-ffmpeg Prefer ffmpeg over avconv for running the
- postprocessors (default)
- (Alias: --no-prefer-avconv)
- --ffmpeg-location PATH Location of the ffmpeg/avconv binary;
- either the path to the binary or its
- containing directory
- (Alias: --avconv-location)
+ --ffmpeg-location PATH Location of the ffmpeg binary; either the
+ path to the binary or its containing
+ directory
--exec CMD Execute a command on the file after
downloading and post-processing, similar to
find's -exec syntax. Example: --exec 'adb
You can configure youtube-dlc by placing any supported command line option to a configuration file. The configuration is loaded from the following locations:
-1. The file given by `--config-location`
+1. **Main Configuration**: The file given by `--config-location`
1. **Portable Configuration**: `yt-dlp.conf` or `youtube-dlc.conf` in the same directory as the bundled binary. If you are running from source-code (`<root dir>/youtube_dlc/__main__.py`), the root directory is used instead.
+1. **Home Configuration**: `yt-dlp.conf` or `youtube-dlc.conf` in the home path given by `-P "home:<path>"`, or in the current directory if no such path is given
1. **User Configuration**:
* `%XDG_CONFIG_HOME%/yt-dlp/config` (recommended on Linux/macOS)
* `%XDG_CONFIG_HOME%/yt-dlp.conf`
# OUTPUT TEMPLATE
-The `-o` option allows users to indicate a template for the output file names.
+The `-o` option is used to indicate a template for the output file names while `-P` option is used to specify the path each type of file should be saved to.
**tl;dr:** [navigate me to examples](#output-template-examples).
- `disc_number` (numeric): Number of the disc or other physical medium the track belongs to
- `release_year` (numeric): Year (YYYY) when the album was released
-Each aforementioned sequence when referenced in an output template will be replaced by the actual value corresponding to the sequence name. Note that 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 `NA`.
+Each aforementioned sequence when referenced in an output template will be replaced by the actual value corresponding to the sequence name. Note that 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 `--output-na-placeholder` (`NA` by default).
For example for `-o %(title)s-%(id)s.%(ext)s` and an mp4 video with title `youtube-dlc test video` and id `BaW_jenozKcj`, this will result in a `youtube-dlc test video-BaW_jenozKcj.mp4` file created in the current directory.
# FORMAT SELECTION
By default, youtube-dlc tries to download the best available quality if you **don't** pass any options.
-This is generally equivalent to using `-f bestvideo*+bestaudio/best`. However, if multiple audiostreams is enabled (`--audio-multistreams`), the default format changes to `-f bestvideo+bestaudio/best`. Similarly, if ffmpeg and avconv are unavailable, or if you use youtube-dlc to stream to `stdout` (`-o -`), the default becomes `-f best/bestvideo+bestaudio`.
+This is generally equivalent to using `-f bestvideo*+bestaudio/best`. However, if multiple audiostreams is enabled (`--audio-multistreams`), the default format changes to `-f bestvideo+bestaudio/best`. Similarly, if ffmpeg is unavailable, or if you use youtube-dlc to stream to `stdout` (`-o -`), the default becomes `-f best/bestvideo+bestaudio`.
The general syntax for format selection is `--f FORMAT` (or `--format FORMAT`) where `FORMAT` is a *selector expression*, i.e. an expression that describes format or formats you would like to download.
If you want to download several formats of the same video use a comma as a separator, e.g. `-f 22,17,18` will download all these three formats, of course if they are available. Or a more sophisticated example combined with the precedence feature: `-f 136/137/mp4/bestvideo,140/m4a/bestaudio`.
-You can merge the video and audio of multiple formats into a single file using `-f <format1>+<format2>+...` (requires ffmpeg or avconv installed), for example `-f bestvideo+bestaudio` will download the best video-only format, the best audio-only format and mux them together with ffmpeg/avconv. If `--no-video-multistreams` is used, all formats with a video stream except the first one are ignored. Similarly, if `--no-audio-multistreams` is used, all formats with an audio stream except the first one are ignored. For example, `-f bestvideo+best+bestaudio` will download and merge all 3 given formats. The resulting file will have 2 video streams and 2 audio streams. But `-f bestvideo+best+bestaudio --no-video-multistreams` will download and merge only `bestvideo` and `bestaudio`. `best` is ignored since another format containing a video stream (`bestvideo`) has already been selected. The order of the formats is therefore important. `-f best+bestaudio --no-audio-multistreams` will download and merge both formats while `-f bestaudio+best --no-audio-multistreams` will ignore `best` and download only `bestaudio`.
+You can merge the video and audio of multiple formats into a single file using `-f <format1>+<format2>+...` (requires ffmpeg installed), for example `-f bestvideo+bestaudio` will download the best video-only format, the best audio-only format and mux them together with ffmpeg. If `--no-video-multistreams` is used, all formats with a video stream except the first one are ignored. Similarly, if `--no-audio-multistreams` is used, all formats with an audio stream except the first one are ignored. For example, `-f bestvideo+best+bestaudio` will download and merge all 3 given formats. The resulting file will have 2 video streams and 2 audio streams. But `-f bestvideo+best+bestaudio --no-video-multistreams` will download and merge only `bestvideo` and `bestaudio`. `best` is ignored since another format containing a video stream (`bestvideo`) has already been selected. The order of the formats is therefore important. `-f best+bestaudio --no-audio-multistreams` will download and merge both formats while `-f bestaudio+best --no-audio-multistreams` will ignore `best` and download only `bestaudio`.
## Filtering Formats
$ youtube-dlc -S '+res:480,codec,br'
```
+# PLUGINS
+Plugins are loaded from `<root-dir>/ytdlp_plugins/<type>/__init__.py`. Currently only `extractor` plugins are supported. Support for `downloader` and `postprocessor` plugins may be added in the future. See [ytdlp_plugins](ytdlp_plugins) for example.
-
+**Note**: `<root-dir>` is the directory of the binary (`<root-dir>/youtube-dlc`), or the root directory of the module if you are running directly from source-code (`<root dir>/youtube_dlc/__main__.py`)
# MORE
-For FAQ, Developer Instructions etc., see the [original README](https://github.com/ytdl-org/youtube-dl)
+For FAQ, Developer Instructions etc., see the [original README](https://github.com/ytdl-org/youtube-dl#faq)
projects / yt-dlp.git / blobdiff