]> jfr.im git - yt-dlp.git/blame - README.md
projects / yt-dlp.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Merge branch 'tpikonen-elonet'
[yt-dlp.git] / README.md
CommitLineData
424dc7be 1[![PyPi](https://img.shields.io/pypi/v/youtube-dlc.svg)](https://pypi.org/project/youtube-dlc)
c8598bbe 2[![Build Status](https://travis-ci.com/blackjack4494/youtube-dlc.svg?branch=master)](https://travis-ci.com/blackjack4494/youtube-dlc)
a90d4f7e 3[![Downloads](https://pepy.tech/badge/youtube-dlc)](https://pepy.tech/project/youtube-dlc)
5c0e5bc4 4
1c547dc8
TOH		 5[![Gitter chat](https://badges.gitter.im/youtube-dlc/gitter.png)](https://gitter.im/youtube-dlc)
6[![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](https://github.com/blackjack4494/youtube-dlc/blob/master/LICENSE)
7
9ab41610 8youtube-dlc - download videos from youtube.com or other video platforms
893afc2c 9youtube-dls is a fork of youtube-dl with the intention of getting features tested by the community merged in the tool faster, since youtube-dl's development seems to be slowing down (https://github.com/ytdl-org/youtube-dl/issues/26462)
6bcd846b 10
b50e3bc6
PH		 11- [INSTALLATION](#installation)
12- [DESCRIPTION](#description)
13- [OPTIONS](#options)
b50e3bc6 14- [COPYRIGHT](#copyright)
cfcec693 15
d19bb9c0
PH		 16# INSTALLATION
17
5f326cf5
TOH		 18**All Platforms**
19Preferred way using pip:
9ab41610 20You may want to use `python3` instead of `python`
d19bb9c0 21
9ab41610 22 python -m pip install --upgrade youtube-dlc
d19bb9c0 23
5f326cf5
TOH		 24**UNIX** (Linux, macOS, etc.)
25Using wget:
26
27 sudo wget https://github.com/blackjack4494/youtube-dlc/releases/latest/download/youtube-dlc -O /usr/local/bin/youtube-dlc
28 sudo chmod a+rx /usr/local/bin/youtube-dlc
29
30Using curl:
31
32 sudo curl -L https://github.com/blackjack4494/youtube-dlc/releases/latest/download/youtube-dlc -o /usr/local/bin/youtube-dlc
33 sudo chmod a+rx /usr/local/bin/youtube-dlc
34
35
36**Windows** users can download [youtube-dlc.exe](https://github.com/blackjack4494/youtube-dlc/releases/latest/download/youtube-dlc.exe) (**do not** put in `C:\Windows\System32`!).
37
38**Compile**
39To build the Windows executable yourself
d19bb9c0 40
9ab41610 41 python -m pip install --upgrade pyinstaller
cefecac1 42 pyinstaller.exe youtube_dlc\__main__.py --onefile --name youtube-dlc
8f1aaa97 43
9ab41610 44Or simply execute the `make_win.bat` if pyinstaller is installed.
5f326cf5
TOH		 45There will be a `youtube-dlc.exe` in `/dist`
46
47For Unix:
48You will need the required build tools
49python, make (GNU), pandoc, zip, nosetests
50Then simply type this
51
52 make
53
d19bb9c0 54
cfcec693 55# DESCRIPTION
9ab41610 56**youtube-dlc** is a command-line program to download videos from YouTube.com and a few more sites. It requires the Python interpreter, version 2.6, 2.7, or 3.2+, and it is not platform specific. It should work on your Unix box, on Windows or on macOS. It is released to the public domain, which means you can modify it, redistribute it or use it however you like.
6bcd846b 57
9ab41610 58 youtube-dlc [OPTIONS] URL [URL...]
b50e3bc6 59
cfcec693 60# OPTIONS
1dc2726f
PH		 61 -h, --help Print this help text and exit
62 --version Print program version and exit
c4af7684
PH		 63 -U, --update Update this program to latest version. Make
64 sure that you have sufficient permissions
65 (run with sudo if needed)
66 -i, --ignore-errors Continue on download errors, for example to
67 skip unavailable videos in a playlist
68 --abort-on-error Abort downloading of further videos (in the
69 playlist or the command line) if an error
70 occurs
1dc2726f 71 --dump-user-agent Display the current browser identification
4b9f9010 72 --list-extractors List all supported extractors
c4af7684
PH		 73 --extractor-descriptions Output descriptions of all supported
74 extractors
75 --force-generic-extractor Force extraction to use the generic
76 extractor
77 --default-search PREFIX Use this prefix for unqualified URLs. For
78 example "gvsearch2:" downloads two videos
cefecac1 79 from google videos for youtube-dlc "large
c4af7684 80 apple". Use the value "auto" to let
cefecac1 81 youtube-dlc guess ("auto_warning" to emit a
c4af7684
PH		 82 warning when guessing). "error" just throws
83 an error. The default value "fixup_error"
84 repairs broken URLs, but emits an error if
85 this is not possible instead of searching.
86 --ignore-config Do not read configuration files. When given
82674236 87 in the global configuration file
cefecac1 88 /etc/youtube-dlc.conf: Do not read the user
c4af7684 89 configuration in ~/.config/youtube-
e3671279
U		 90 dlc/config (%APPDATA%/youtube-
91 dlc/config.txt on Windows)
dc48a354
S		 92 --config-location PATH Location of the configuration file; either
93 the path to the config or its containing
94 directory.
c4af7684
PH		 95 --flat-playlist Do not extract the videos of a playlist,
96 only list them.
bdf7f139
PH		 97 --mark-watched Mark videos watched (YouTube only)
98 --no-mark-watched Do not mark videos watched (YouTube only)
1dc2726f 99 --no-color Do not emit color codes in output
08c1d0d3 100
149f05c7 101## Network Options:
28b4f736 102 --proxy URL Use the specified HTTP/HTTPS/SOCKS proxy.
0934c9d4
S		 103 To enable SOCKS proxy, specify a proper
104 scheme. For example
28b4f736
PH		 105 socks5://127.0.0.1:1080/. Pass in an empty
106 string (--proxy "") for direct connection
149f05c7 107 --socket-timeout SECONDS Time to wait before giving up, in seconds
c4af7684 108 --source-address IP Client-side IP address to bind to
c4af7684 109 -4, --force-ipv4 Make all connections via IPv4
c4af7684 110 -6, --force-ipv6 Make all connections via IPv6
8c6c88c7
S		 111
112## Geo Restriction:
c25f1a9b
S		 113 --geo-verification-proxy URL Use this proxy to verify the IP address for
114 some geo-restricted sites. The default
115 proxy specified by --proxy (or none, if the
7550ea50 116 option is not present) is used for the
4d2fdb07 117 actual downloading.
8c6c88c7 118 --geo-bypass Bypass geographic restriction via faking
0934c9d4 119 X-Forwarded-For HTTP header
8c6c88c7
S		 120 --no-geo-bypass Do not bypass geographic restriction via
121 faking X-Forwarded-For HTTP header
8c6c88c7
S		 122 --geo-bypass-country CODE Force bypass geographic restriction with
123 explicitly provided two-letter ISO 3166-2
0934c9d4 124 country code
9e18bb4c
S		 125 --geo-bypass-ip-block IP_BLOCK Force bypass geographic restriction with
126 explicitly provided IP block in CIDR
0934c9d4 127 notation
149f05c7 128
cfcec693 129## Video Selection:
1dc2726f
PH		 130 --playlist-start NUMBER Playlist video to start at (default is 1)
131 --playlist-end NUMBER Playlist video to end at (default is last)
c4af7684
PH		 132 --playlist-items ITEM_SPEC Playlist video items to download. Specify
133 indices of the videos in the playlist
134 separated by commas like: "--playlist-items
135 1,2,5,8" if you want to download videos
136 indexed 1, 2, 5, 8 in the playlist. You can
137 specify range: "--playlist-items
138 1-3,7,10-13", it will download the videos
139 at index 1, 2, 3, 7, 10, 11, 12 and 13.
140 --match-title REGEX Download only matching titles (regex or
141 caseless sub-string)
142 --reject-title REGEX Skip download for matching titles (regex or
143 caseless sub-string)
780083db 144 --max-downloads NUMBER Abort after downloading NUMBER files
c4af7684
PH		 145 --min-filesize SIZE Do not download any videos smaller than
146 SIZE (e.g. 50k or 44.6m)
147 --max-filesize SIZE Do not download any videos larger than SIZE
148 (e.g. 50k or 44.6m)
1dc2726f 149 --date DATE Download only videos uploaded in this date
c4af7684
PH		 150 --datebefore DATE Download only videos uploaded on or before
151 this date (i.e. inclusive)
152 --dateafter DATE Download only videos uploaded on or after
153 this date (i.e. inclusive)
154 --min-views COUNT Do not download any videos with less than
155 COUNT views
156 --max-views COUNT Do not download any videos with more than
157 COUNT views
4d2fdb07 158 --match-filter FILTER Generic video filter. Specify any key (see
cb1e6d89
S		 159 the "OUTPUT TEMPLATE" for a list of
160 available keys) to match if the key is
161 present, !key to check if the key is not
162 present, key > NUMBER (like "comment_count
163 > 12", also works with >=, <, <=, !=, =) to
164 compare against a number, key = 'LITERAL'
165 (like "uploader = 'Mike Smith'", also works
166 with !=) to match against a string literal
167 and & to require multiple matches. Values
168 which are not known are excluded unless you
169 put a question mark (?) after the operator.
170 For example, to only match videos that have
8c6c88c7
S		 171 been liked more than 100 times and disliked
172 less than 50 times (or the dislike
173 functionality is not available at the given
174 service), but who also have a description,
175 use --match-filter "like_count > 100 &
176 dislike_count <? 50 & description" .
c4af7684
PH		 177 --no-playlist Download only the video, if the URL refers
178 to a video and a playlist.
179 --yes-playlist Download the playlist, if the URL refers to
180 a video and a playlist.
181 --age-limit YEARS Download only videos suitable for the given
182 age
183 --download-archive FILE Download only videos not listed in the
184 archive file. Record the IDs of all
185 downloaded videos in it.
186 --include-ads Download advertisements as well
187 (experimental)
6bcd846b 188
d5a62e4f 189## Download Options:
5e3856a2 190 -r, --limit-rate RATE Maximum download rate in bytes per second
c4af7684
PH		 191 (e.g. 50K or 4.2M)
192 -R, --retries RETRIES Number of retries (default is 10), or
193 "infinite".
0be8314d 194 --fragment-retries RETRIES Number of retries for a fragment (default
b56e41a7
S		 195 is 10), or "infinite" (DASH, hlsnative and
196 ISM)
197 --skip-unavailable-fragments Skip unavailable fragments (DASH, hlsnative
198 and ISM)
4d2fdb07
S		 199 --abort-on-unavailable-fragment Abort downloading when some fragment is not
200 available
a82f4184
S		 201 --keep-fragments Keep downloaded fragments on disk after
202 downloading is finished; fragments are
203 erased by default
c4af7684
PH		 204 --buffer-size SIZE Size of download buffer (e.g. 1024 or 16K)
205 (default is 1024)
206 --no-resize-buffer Do not automatically adjust the buffer
207 size. By default, the buffer size is
208 automatically resized from an initial value
209 of SIZE.
db157d2a
S		 210 --http-chunk-size SIZE Size of a chunk for chunk-based HTTP
211 downloading (e.g. 10485760 or 10M) (default
212 is disabled). May be useful for bypassing
213 bandwidth throttling imposed by a webserver
214 (experimental)
2101f5d4 215 --playlist-reverse Download playlist videos in reverse order
31487eb9 216 --playlist-random Download playlist videos in random order
c4af7684 217 --xattr-set-filesize Set file xattribute ytdl.filesize with
0934c9d4 218 expected file size
c4af7684 219 --hls-prefer-native Use the native HLS downloader instead of
8b38f2ac
PH		 220 ffmpeg
221 --hls-prefer-ffmpeg Use ffmpeg instead of the native HLS
222 downloader
a69bee47
PH		 223 --hls-use-mpegts Use the mpegts container for HLS videos,
224 allowing to play the video while
225 downloading (some players may not be able
226 to play it)
c4af7684
PH		 227 --external-downloader COMMAND Use the specified external downloader.
228 Currently supports
6bb26669 229 aria2c,avconv,axel,curl,ffmpeg,httpie,wget
c4af7684
PH		 230 --external-downloader-args ARGS Give these arguments to the external
231 downloader
d5a62e4f 232
cfcec693 233## Filesystem Options:
c4af7684 234 -a, --batch-file FILE File containing URLs to download ('-' for
e8dfecb3
S		 235 stdin), one URL per line. Lines starting
236 with '#', ';' or ']' are considered as
237 comments and ignored.
1dc2726f 238 --id Use only video ID in file name
bd1bcd3e
S		 239 -o, --output TEMPLATE Output filename template, see the "OUTPUT
240 TEMPLATE" for all the info
4d2fdb07
S		 241 --autonumber-start NUMBER Specify the start value for %(autonumber)s
242 (default is 1)
c4af7684
PH		 243 --restrict-filenames Restrict filenames to only ASCII
244 characters, and avoid "&" and spaces in
245 filenames
1dc2726f 246 -w, --no-overwrites Do not overwrite files
c4af7684 247 -c, --continue Force resume of partially downloaded files.
cefecac1 248 By default, youtube-dlc will resume
c4af7684
PH		 249 downloads if possible.
250 --no-continue Do not resume partially downloaded files
251 (restart from beginning)
252 --no-part Do not use .part files - write directly
253 into output file
254 --no-mtime Do not use the Last-modified header to set
255 the file modification time
256 --write-description Write video description to a .description
257 file
1dc2726f 258 --write-info-json Write video metadata to a .info.json file
c4af7684
PH		 259 --write-annotations Write video annotations to a
260 .annotations.xml file
d845622b 261 --load-info-json FILE JSON file containing the video information
c4af7684
PH		 262 (created with the "--write-info-json"
263 option)
264 --cookies FILE File to read cookies from and dump cookie
265 jar in
e3671279
U		 266 --cache-dir DIR Location in the filesystem where youtube-
267 dlc can store some downloaded information
82674236 268 permanently. By default
cefecac1
U		 269 $XDG_CACHE_HOME/youtube-dlc or
270 ~/.cache/youtube-dlc . At the moment, only
82674236
S		 271 YouTube player files (for videos with
272 obfuscated signatures) are cached, but that
273 may change.
36f35428
PH		 274 --no-cache-dir Disable filesystem caching
275 --rm-cache-dir Delete all filesystem cache files
6bcd846b 276
2b1bd292 277## Thumbnail images:
1dc2726f
PH		 278 --write-thumbnail Write thumbnail image to disk
279 --write-all-thumbnails Write all thumbnail image formats to disk
c4af7684
PH		 280 --list-thumbnails Simulate and list all available thumbnail
281 formats
2b1bd292 282
cfcec693 283## Verbosity / Simulation Options:
1dc2726f 284 -q, --quiet Activate quiet mode
6c072e7d 285 --no-warnings Ignore warnings
c4af7684
PH		 286 -s, --simulate Do not download the video and do not write
287 anything to disk
1dc2726f
PH		 288 --skip-download Do not download the video
289 -g, --get-url Simulate, quiet but print URL
290 -e, --get-title Simulate, quiet but print title
291 --get-id Simulate, quiet but print id
292 --get-thumbnail Simulate, quiet but print thumbnail URL
293 --get-description Simulate, quiet but print video description
294 --get-duration Simulate, quiet but print video length
295 --get-filename Simulate, quiet but print output filename
296 --get-format Simulate, quiet but print output format
c4af7684 297 -j, --dump-json Simulate, quiet but print JSON information.
cb1e6d89
S		 298 See the "OUTPUT TEMPLATE" for a description
299 of available keys.
c4af7684
PH		 300 -J, --dump-single-json Simulate, quiet but print JSON information
301 for each command-line argument. If the URL
302 refers to a playlist, dump the whole
303 playlist information in a single line.
304 --print-json Be quiet and print the video information as
305 JSON (video is still being downloaded).
1dc2726f
PH		 306 --newline Output progress bar as new lines
307 --no-progress Do not print progress bar
308 --console-title Display progress in console titlebar
309 -v, --verbose Print various debugging information
c4af7684
PH		 310 --dump-pages Print downloaded pages encoded using base64
311 to debug problems (very verbose)
312 --write-pages Write downloaded intermediary pages to
313 files in the current directory to debug
314 problems
780083db 315 --print-traffic Display sent and read HTTP traffic
e3671279
U		 316 -C, --call-home Contact the youtube-dlc server for
317 debugging
cefecac1 318 --no-call-home Do NOT contact the youtube-dlc server for
c4af7684 319 debugging
6bcd846b 320
36f35428
PH		 321## Workarounds:
322 --encoding ENCODING Force the specified encoding (experimental)
1dc2726f 323 --no-check-certificate Suppress HTTPS certificate validation
c4af7684 324 --prefer-insecure Use an unencrypted connection to retrieve
05a7ffb1
S		 325 information about the video. (Currently
326 supported only for YouTube)
1dc2726f 327 --user-agent UA Specify a custom user agent
c4af7684
PH		 328 --referer URL Specify a custom referer, use if the video
329 access is restricted to one domain
330 --add-header FIELD:VALUE Specify a custom HTTP header and its value,
331 separated by a colon ':'. You can use this
332 option multiple times
333 --bidi-workaround Work around terminals that lack
334 bidirectional text support. Requires bidiv
335 or fribidi executable in PATH
336 --sleep-interval SECONDS Number of seconds to sleep before each
b1ce2ba1
S		 337 download when used alone or a lower bound
338 of a range for randomized sleep before each
339 download (minimum possible number of
340 seconds to sleep) when used along with
341 --max-sleep-interval.
342 --max-sleep-interval SECONDS Upper bound of a range for randomized sleep
343 before each download (maximum possible
344 number of seconds to sleep). Must only be
345 used along with --min-sleep-interval.
36f35428 346
cfcec693 347## Video Format Options:
c4af7684
PH		 348 -f, --format FORMAT Video format code, see the "FORMAT
349 SELECTION" for all the info
1dc2726f 350 --all-formats Download all available video formats
c4af7684
PH		 351 --prefer-free-formats Prefer free video formats unless a specific
352 one is requested
535d7b68 353 -F, --list-formats List all available formats of requested
bb6ac836 354 videos
c4af7684
PH		 355 --youtube-skip-dash-manifest Do not download the DASH manifests and
356 related data on YouTube videos
357 --merge-output-format FORMAT If a merge is required (e.g.
358 bestvideo+bestaudio), output to given
359 container format. One of mkv, mp4, ogg,
360 webm, flv. Ignored if no merge is required
8ae7be3e
PH		 361
362## Subtitle Options:
1dc2726f 363 --write-sub Write subtitle file
741dd8ea
RB		 364 --write-auto-sub Write automatically generated subtitle file
365 (YouTube only)
c4af7684
PH		 366 --all-subs Download all the available subtitles of the
367 video
1dc2726f 368 --list-subs List all available subtitles for the video
c4af7684
PH		 369 --sub-format FORMAT Subtitle format, accepts formats
370 preference, for example: "srt" or
371 "ass/srt/best"
372 --sub-lang LANGS Languages of the subtitles to download
f733b053
PH		 373 (optional) separated by commas, use --list-
374 subs for available language tags
6bcd846b 375
cfcec693 376## Authentication Options:
1dc2726f 377 -u, --username USERNAME Login with this account ID
c4af7684 378 -p, --password PASSWORD Account password. If this option is left
cefecac1 379 out, youtube-dlc will ask interactively.
dc48a354 380 -2, --twofactor TWOFACTOR Two-factor authentication code
1dc2726f 381 -n, --netrc Use .netrc authentication data
804c343a 382 --video-password PASSWORD Video password (vimeo, smotri, youku)
6bcd846b 383
f5e008d1
S		 384## Adobe Pass Options:
385 --ap-mso MSO Adobe Pass multiple-system operator (TV
386 provider) identifier, use --ap-list-mso for
387 a list of available MSOs
388 --ap-username USERNAME Multiple-system operator account login
389 --ap-password PASSWORD Multiple-system operator account password.
e3671279
U		 390 If this option is left out, youtube-dlc
391 will ask interactively.
f5e008d1
S		 392 --ap-list-mso List all supported multiple-system
393 operators
394
cfcec693 395## Post-processing Options:
c4af7684
PH		 396 -x, --extract-audio Convert video files to audio-only files
397 (requires ffmpeg or avconv and ffprobe or
398 avprobe)
399 --audio-format FORMAT Specify audio format: "best", "aac",
7d539ee1
S		 400 "flac", "mp3", "m4a", "opus", "vorbis", or
401 "wav"; "best" by default; No effect without
402 -x
c4af7684
PH		 403 --audio-quality QUALITY Specify ffmpeg/avconv audio quality, insert
404 a value between 0 (better) and 9 (worse)
405 for VBR or a specific bitrate like 128K
406 (default 5)
407 --recode-video FORMAT Encode the video to another format if
408 necessary (currently supported:
409 mp4|flv|ogg|webm|mkv|avi)
f72b0a60 410 --postprocessor-args ARGS Give these arguments to the postprocessor
c4af7684
PH		 411 -k, --keep-video Keep the video file on disk after the post-
412 processing; the video is erased by default
413 --no-post-overwrites Do not overwrite post-processed files; the
414 post-processed files are overwritten by
415 default
0be8314d
PH		 416 --embed-subs Embed subtitles in the video (only for mp4,
417 webm and mkv videos)
1dc2726f
PH		 418 --embed-thumbnail Embed thumbnail in the audio as cover art
419 --add-metadata Write metadata to the video file
c4af7684
PH		 420 --metadata-from-title FORMAT Parse additional metadata like song title /
421 artist from the video title. The format
6f3c632c
S		 422 syntax is the same as --output. Regular
423 expression with named capture groups may
424 also be used. The parsed parameters replace
425 existing values. Example: --metadata-from-
426 title "%(artist)s - %(title)s" matches a
427 title like "Coldplay - Paradise". Example
428 (regex): --metadata-from-title
429 "(?P<artist>.+?) - (?P<title>.+)"
c4af7684
PH		 430 --xattrs Write metadata to the video file's xattrs
431 (using dublin core and xdg standards)
432 --fixup POLICY Automatically correct known faults of the
433 file. One of never (do nothing), warn (only
434 emit a warning), detect_or_warn (the
435 default; fix file if we can, warn
436 otherwise)
437 --prefer-avconv Prefer avconv over ffmpeg for running the
c4af7684 438 postprocessors
689af496
S		 439 --prefer-ffmpeg Prefer ffmpeg over avconv for running the
440 postprocessors (default)
c4af7684
PH		 441 --ffmpeg-location PATH Location of the ffmpeg/avconv binary;
442 either the path to the binary or its
443 containing directory.
444 --exec CMD Execute a command on the file after
00a41ca4
S		 445 downloading and post-processing, similar to
446 find's -exec syntax. Example: --exec 'adb
447 push {} /sdcard/Music/ && rm {}'
7de81fcc 448 --convert-subs FORMAT Convert the subtitles to other format
9fc41bcb 449 (currently supported: srt|ass|vtt|lrc)
6bcd846b 450
fork of https://github.com/yt-dlp/yt-dlp/