]> Raphaël G. Git Repositories - youtubedl/blob - README.txt
fc84c9b6982648c857860f04e6c6e8f7c8688a82
[youtubedl] / README.txt
1 NAME
2 ====
3
4 youtube-dl - download videos from youtube.com or other video platforms
5
6 SYNOPSIS
7 ========
8
9 youtube-dl OPTIONS URL [URL...]
10
11 DESCRIPTION
12 ===========
13
14 youtube-dl is a small command-line program to download videos from
15 YouTube.com and a few more sites. It requires the Python interpreter,
16 version 2.6, 2.7, or 3.3+, and it is not platform specific. It should
17 work on your Unix box, on Windows or on Mac OS X. It is released to the
18 public domain, which means you can modify it, redistribute it or use it
19 however you like.
20
21 OPTIONS
22 =======
23
24 -h, --help print this help text and exit
25 --version print program version and exit
26 -U, --update update this program to latest version. Make sure
27 that you have sufficient permissions (run with
28 sudo if needed)
29 -i, --ignore-errors continue on download errors, for example to to
30 skip unavailable videos in a playlist
31 --dump-user-agent display the current browser identification
32 --user-agent UA specify a custom user agent
33 --referer REF specify a custom referer, use if the video access
34 is restricted to one domain
35 --list-extractors List all supported extractors and the URLs they
36 would handle
37 --extractor-descriptions Output descriptions of all supported extractors
38 --proxy URL Use the specified HTTP/HTTPS proxy
39 --no-check-certificate Suppress HTTPS certificate validation.
40 --cache-dir None Location in the filesystem where youtube-dl can
41 store downloaded information permanently. By
42 default $XDG_CACHE_HOME/youtube-dl or ~/.cache
43 /youtube-dl .
44 --no-cache-dir Disable filesystem caching
45
46 Video Selection:
47 ----------------
48
49 --playlist-start NUMBER playlist video to start at (default is 1)
50 --playlist-end NUMBER playlist video to end at (default is last)
51 --match-title REGEX download only matching titles (regex or caseless
52 sub-string)
53 --reject-title REGEX skip download for matching titles (regex or
54 caseless sub-string)
55 --max-downloads NUMBER Abort after downloading NUMBER files
56 --min-filesize SIZE Do not download any videos smaller than SIZE
57 (e.g. 50k or 44.6m)
58 --max-filesize SIZE Do not download any videos larger than SIZE (e.g.
59 50k or 44.6m)
60 --date DATE download only videos uploaded in this date
61 --datebefore DATE download only videos uploaded before this date
62 --dateafter DATE download only videos uploaded after this date
63 --no-playlist download only the currently playing video
64
65 Download Options:
66 -----------------
67
68 -r, --rate-limit LIMIT maximum download rate (e.g. 50k or 44.6m)
69 -R, --retries RETRIES number of retries (default is 10)
70 --buffer-size SIZE size of download buffer (e.g. 1024 or 16k)
71 (default is 1024)
72 --no-resize-buffer do not automatically adjust the buffer size. By
73 default, the buffer size is automatically resized
74 from an initial value of SIZE.
75
76 Filesystem Options:
77 -------------------
78
79 -t, --title use title in file name (default)
80 --id use only video ID in file name
81 -l, --literal [deprecated] alias of --title
82 -A, --auto-number number downloaded files starting from 00000
83 -o, --output TEMPLATE output filename template. Use %(title)s to get
84 the title, %(uploader)s for the uploader name,
85 %(uploader_id)s for the uploader nickname if
86 different, %(autonumber)s to get an automatically
87 incremented number, %(ext)s for the filename
88 extension, %(upload_date)s for the upload date
89 (YYYYMMDD), %(extractor)s for the provider
90 (youtube, metacafe, etc), %(id)s for the video id
91 , %(playlist)s for the playlist the video is in,
92 %(playlist_index)s for the position in the
93 playlist and %% for a literal percent. Use - to
94 output to stdout. Can also be used to download to
95 a different directory, for example with -o '/my/d
96 ownloads/%(uploader)s/%(title)s-%(id)s.%(ext)s' .
97 --autonumber-size NUMBER Specifies the number of digits in %(autonumber)s
98 when it is present in output filename template or
99 --autonumber option is given
100 --restrict-filenames Restrict filenames to only ASCII characters, and
101 avoid "&" and spaces in filenames
102 -a, --batch-file FILE file containing URLs to download ('-' for stdin)
103 -w, --no-overwrites do not overwrite files
104 -c, --continue resume partially downloaded files
105 --no-continue do not resume partially downloaded files (restart
106 from beginning)
107 --cookies FILE file to read cookies from and dump cookie jar in
108 --no-part do not use .part files
109 --no-mtime do not use the Last-modified header to set the
110 file modification time
111 --write-description write video description to a .description file
112 --write-info-json write video metadata to a .info.json file
113 --write-thumbnail write thumbnail image to disk
114
115 Verbosity / Simulation Options:
116 -------------------------------
117
118 -q, --quiet activates quiet mode
119 -s, --simulate do not download the video and do not write
120 anything to disk
121 --skip-download do not download the video
122 -g, --get-url simulate, quiet but print URL
123 -e, --get-title simulate, quiet but print title
124 --get-id simulate, quiet but print id
125 --get-thumbnail simulate, quiet but print thumbnail URL
126 --get-description simulate, quiet but print video description
127 --get-filename simulate, quiet but print output filename
128 --get-format simulate, quiet but print output format
129 --newline output progress bar as new lines
130 --no-progress do not print progress bar
131 --console-title display progress in console titlebar
132 -v, --verbose print various debugging information
133 --dump-intermediate-pages print downloaded pages to debug problems(very
134 verbose)
135
136 Video Format Options:
137 ---------------------
138
139 -f, --format FORMAT video format code, specifiy the order of
140 preference using slashes: "-f 22/17/18". "-f mp4"
141 and "-f flv" are also supported
142 --all-formats download all available video formats
143 --prefer-free-formats prefer free video formats unless a specific one
144 is requested
145 --max-quality FORMAT highest quality format to download
146 -F, --list-formats list all available formats (currently youtube
147 only)
148
149 Subtitle Options:
150 -----------------
151
152 --write-sub write subtitle file
153 --write-auto-sub write automatic subtitle file (youtube only)
154 --all-subs downloads all the available subtitles of the
155 video
156 --list-subs lists all available subtitles for the video
157 --sub-format FORMAT subtitle format (default=srt) ([sbv/vtt] youtube
158 only)
159 --sub-lang LANGS languages of the subtitles to download (optional)
160 separated by commas, use IETF language tags like
161 'en,pt'
162
163 Authentication Options:
164 -----------------------
165
166 -u, --username USERNAME account username
167 -p, --password PASSWORD account password
168 -n, --netrc use .netrc authentication data
169 --video-password PASSWORD video password (vimeo only)
170
171 Post-processing Options:
172 ------------------------
173
174 -x, --extract-audio convert video files to audio-only files (requires
175 ffmpeg or avconv and ffprobe or avprobe)
176 --audio-format FORMAT "best", "aac", "vorbis", "mp3", "m4a", "opus", or
177 "wav"; best by default
178 --audio-quality QUALITY ffmpeg/avconv audio quality specification, insert
179 a value between 0 (better) and 9 (worse) for VBR
180 or a specific bitrate like 128K (default 5)
181 --recode-video FORMAT Encode the video to another format if necessary
182 (currently supported: mp4|flv|ogg|webm)
183 -k, --keep-video keeps the video file on disk after the post-
184 processing; the video is erased by default
185 --no-post-overwrites do not overwrite post-processed files; the post-
186 processed files are overwritten by default
187 --embed-subs embed subtitles in the video (only for mp4
188 videos)
189
190 CONFIGURATION
191 =============
192
193 You can configure youtube-dl by placing default arguments (such as
194 --extract-audio --no-mtime to always extract the audio and not copy the
195 mtime) into /etc/youtube-dl.conf and/or ~/.config/youtube-dl.conf.
196
197 OUTPUT TEMPLATE
198 ===============
199
200 The -o option allows users to indicate a template for the output file
201 names. The basic usage is not to set any template arguments when
202 downloading a single file, like in
203 youtube-dl -o funny_video.flv "http://some/video". However, it may
204 contain special sequences that will be replaced when downloading each
205 video. The special sequences have the format %(NAME)s. To clarify, that
206 is a percent symbol followed by a name in parenthesis, followed by a
207 lowercase S. Allowed names are:
208
209 - id: The sequence will be replaced by the video identifier.
210 - url: The sequence will be replaced by the video URL.
211 - uploader: The sequence will be replaced by the nickname of the
212 person who uploaded the video.
213 - upload_date: The sequence will be replaced by the upload date in
214 YYYYMMDD format.
215 - title: The sequence will be replaced by the video title.
216 - ext: The sequence will be replaced by the appropriate extension
217 (like flv or mp4).
218 - epoch: The sequence will be replaced by the Unix epoch when creating
219 the file.
220 - autonumber: The sequence will be replaced by a five-digit number
221 that will be increased with each download, starting at zero.
222 - playlist: The name or the id of the playlist that contains the
223 video.
224 - playlist_index: The index of the video in the playlist, a five-digit
225 number.
226
227 The current default template is %(title)s-%(id)s.%(ext)s.
228
229 In some cases, you don't want special characters such as 中, spaces, or
230 &, such as when transferring the downloaded filename to a Windows system
231 or the filename through an 8bit-unsafe channel. In these cases, add the
232 --restrict-filenames flag to get a shorter title:
233
234 $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc
235 youtube-dl test video ''_ä↭𝕐.mp4 # All kinds of weird characters
236 $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
237 youtube-dl_test_video_.mp4 # A simple file name
238
239 VIDEO SELECTION
240 ===============
241
242 Videos can be filtered by their upload date using the options --date,
243 --datebefore or --dateafter, they accept dates in two formats:
244
245 - Absolute dates: Dates in the format YYYYMMDD.
246 - Relative dates: Dates in the format
247 (now|today)[+-][0-9](day|week|month|year)(s)?
248
249 Examples:
250
251 $ youtube-dl --dateafter now-6months #will only download the videos uploaded in the last 6 months
252 $ youtube-dl --date 19700101 #will only download the videos uploaded in January 1, 1970
253 $ youtube-dl --dateafter 20000101 --datebefore 20100101 #will only download the videos uploaded between 2000 and 2010
254
255 FAQ
256 ===
257
258 Can you please put the -b option back?
259
260 Most people asking this question are not aware that youtube-dl now
261 defaults to downloading the highest available quality as reported by
262 YouTube, which will be 1080p or 720p in some cases, so you no longer
263 need the -b option. For some specific videos, maybe YouTube does not
264 report them to be available in a specific high quality format you're
265 interested in. In that case, simply request it with the -f option and
266 youtube-dl will try to download it.
267
268 I get HTTP error 402 when trying to download a video. What's this?
269
270 Apparently YouTube requires you to pass a CAPTCHA test if you download
271 too much. We're considering to provide a way to let you solve the
272 CAPTCHA, but at the moment, your best course of action is pointing a
273 webbrowser to the youtube URL, solving the CAPTCHA, and restart
274 youtube-dl.
275
276 I have downloaded a video but how can I play it?
277
278 Once the video is fully downloaded, use any video player, such as vlc or
279 mplayer.
280
281 The links provided by youtube-dl -g are not working anymore
282
283 The URLs youtube-dl outputs require the downloader to have the correct
284 cookies. Use the --cookies option to write the required cookies into a
285 file, and advise your downloader to read cookies from that file. Some
286 sites also require a common user agent to be used, use --dump-user-agent
287 to see the one in use by youtube-dl.
288
289 ERROR: no fmt_url_map or conn information found in video info
290
291 youtube has switched to a new video info format in July 2011 which is
292 not supported by old versions of youtube-dl. You can update youtube-dl
293 with sudo youtube-dl --update.
294
295 ERROR: unable to download video
296
297 youtube requires an additional signature since September 2012 which is
298 not supported by old versions of youtube-dl. You can update youtube-dl
299 with sudo youtube-dl --update.
300
301 SyntaxError: Non-ASCII character
302
303 The error
304
305 File "youtube-dl", line 2
306 SyntaxError: Non-ASCII character '\x93' ...
307
308 means you're using an outdated version of Python. Please update to
309 Python 2.6 or 2.7.
310
311 What is this binary file? Where has the code gone?
312
313 Since June 2012 (#342) youtube-dl is packed as an executable zipfile,
314 simply unzip it (might need renaming to youtube-dl.zip first on some
315 systems) or clone the git repository, as laid out above. If you modify
316 the code, you can run it by executing the __main__.py file. To recompile
317 the executable, run make youtube-dl.
318
319 The exe throws a Runtime error from Visual C++
320
321 To run the exe you need to install first the Microsoft Visual C++ 2008
322 Redistributable Package.
323
324 COPYRIGHT
325 =========
326
327 youtube-dl is released into the public domain by the copyright holders.
328
329 This README file was originally written by Daniel Bolton
330 (https://github.com/dbbolton) and is likewise released into the public
331 domain.
332
333 BUGS
334 ====
335
336 Bugs and suggestions should be reported at:
337 https://github.com/rg3/youtube-dl/issues
338
339 Please include:
340
341 - Your exact command line, like
342 youtube-dl -t "http://www.youtube.com/watch?v=uHlDtZ6Oc3s&feature=channel_video_title".
343 A common mistake is not to escape the &. Putting URLs in quotes
344 should solve this problem.
345 - If possible re-run the command with --verbose, and include the full
346 output, it is really helpful to us.
347 - The output of youtube-dl --version
348 - The output of python --version
349 - The name and version of your Operating System ("Ubuntu 11.04 x64" or
350 "Windows 7 x64" is usually enough).
351
352 For discussions, join us in the irc channel #youtube-dl on freenode.