]>
Commit | Line | Data |
---|---|---|
d94adc26 | 1 | .TH YOUTUBE-DL 1 "" |
cfcec693 FV |
2 | .SH NAME |
3 | .PP | |
4 | youtube-dl | |
5 | .SH SYNOPSIS | |
6 | .PP | |
7 | \f[B]youtube-dl\f[] [OPTIONS] URL [URL...] | |
8 | .SH DESCRIPTION | |
9 | .PP | |
10 | \f[B]youtube-dl\f[] is a small command-line program to download videos | |
11 | from YouTube.com and a few more sites. | |
12 | It requires the Python interpreter, version 2.x (x being at least 6), | |
13 | and it is not platform specific. | |
14 | It should work in your Unix box, in Windows or in Mac OS X. | |
15 | It is released to the public domain, which means you can modify it, | |
16 | redistribute it or use it however you like. | |
17 | .SH OPTIONS | |
18 | .IP | |
19 | .nf | |
20 | \f[C] | |
21 | -h,\ --help\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ print\ this\ help\ text\ and\ exit | |
22 | --version\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ print\ program\ version\ and\ exit | |
23 | -U,\ --update\ \ \ \ \ \ \ \ \ \ \ \ \ update\ this\ program\ to\ latest\ version | |
24 | -i,\ --ignore-errors\ \ \ \ \ \ continue\ on\ download\ errors | |
25 | -r,\ --rate-limit\ LIMIT\ \ \ download\ rate\ limit\ (e.g.\ 50k\ or\ 44.6m) | |
26 | -R,\ --retries\ RETRIES\ \ \ \ number\ of\ retries\ (default\ is\ 10) | |
cc872b68 PH |
27 | --buffer-size\ SIZE\ \ \ \ \ \ \ size\ of\ download\ buffer\ (e.g.\ 1024\ or\ 16k)\ (default |
28 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ is\ 1024) | |
29 | --no-resize-buffer\ \ \ \ \ \ \ do\ not\ automatically\ adjust\ the\ buffer\ size.\ By | |
30 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ default,\ the\ buffer\ size\ is\ automatically\ resized | |
31 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ from\ an\ initial\ value\ of\ SIZE. | |
cfcec693 | 32 | --dump-user-agent\ \ \ \ \ \ \ \ display\ the\ current\ browser\ identification |
20326b8b | 33 | --user-agent\ UA\ \ \ \ \ \ \ \ \ \ specify\ a\ custom\ user\ agent |
cfcec693 FV |
34 | --list-extractors\ \ \ \ \ \ \ \ List\ all\ supported\ extractors\ and\ the\ URLs\ they |
35 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ would\ handle | |
36 | \f[] | |
37 | .fi | |
38 | .SS Video Selection: | |
39 | .IP | |
40 | .nf | |
41 | \f[C] | |
42 | --playlist-start\ NUMBER\ \ playlist\ video\ to\ start\ at\ (default\ is\ 1) | |
43 | --playlist-end\ NUMBER\ \ \ \ playlist\ video\ to\ end\ at\ (default\ is\ last) | |
44 | --match-title\ REGEX\ \ \ \ \ \ download\ only\ matching\ titles\ (regex\ or\ caseless | |
45 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ sub-string) | |
46 | --reject-title\ REGEX\ \ \ \ \ skip\ download\ for\ matching\ titles\ (regex\ or | |
47 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ caseless\ sub-string) | |
48 | --max-downloads\ NUMBER\ \ \ Abort\ after\ downloading\ NUMBER\ files | |
49 | \f[] | |
50 | .fi | |
51 | .SS Filesystem Options: | |
52 | .IP | |
53 | .nf | |
54 | \f[C] | |
55 | -t,\ --title\ \ \ \ \ \ \ \ \ \ \ \ \ \ use\ title\ in\ file\ name | |
74e453bd | 56 | --id\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ use\ video\ ID\ in\ file\ name |
baec1538 | 57 | -l,\ --literal\ \ \ \ \ \ \ \ \ \ \ \ [deprecated]\ alias\ of\ --title |
cfcec693 | 58 | -A,\ --auto-number\ \ \ \ \ \ \ \ number\ downloaded\ files\ starting\ from\ 00000 |
b6fab35b | 59 | -o,\ --output\ TEMPLATE\ \ \ \ output\ filename\ template.\ Use\ %(title)s\ to\ get\ the |
cfcec693 FV |
60 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ title,\ %(uploader)s\ for\ the\ uploader\ name, |
61 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ %(autonumber)s\ to\ get\ an\ automatically\ incremented | |
62 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ number,\ %(ext)s\ for\ the\ filename\ extension, | |
551fa9df | 63 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ %(upload_date)s\ for\ the\ upload\ date\ (YYYYMMDD), |
b7b4796b | 64 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ %(extractor)s\ for\ the\ provider\ (youtube,\ metacafe, |
551fa9df FV |
65 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ etc),\ %(id)s\ for\ the\ video\ id\ and\ %%\ for\ a\ literal |
66 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ percent.\ Use\ -\ to\ output\ to\ stdout. | |
56781d3d PH |
67 | --restrict-filenames\ \ \ \ \ Restrict\ filenames\ to\ only\ ASCII\ characters,\ and |
68 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ avoid\ "&"\ and\ spaces\ in\ filenames | |
cfcec693 FV |
69 | -a,\ --batch-file\ FILE\ \ \ \ file\ containing\ URLs\ to\ download\ (\[aq]-\[aq]\ for\ stdin) |
70 | -w,\ --no-overwrites\ \ \ \ \ \ do\ not\ overwrite\ files | |
71 | -c,\ --continue\ \ \ \ \ \ \ \ \ \ \ resume\ partially\ downloaded\ files | |
72 | --no-continue\ \ \ \ \ \ \ \ \ \ \ \ do\ not\ resume\ partially\ downloaded\ files\ (restart | |
73 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ from\ beginning) | |
74 | --cookies\ FILE\ \ \ \ \ \ \ \ \ \ \ file\ to\ read\ cookies\ from\ and\ dump\ cookie\ jar\ in | |
75 | --no-part\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ do\ not\ use\ .part\ files | |
76 | --no-mtime\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ do\ not\ use\ the\ Last-modified\ header\ to\ set\ the\ file | |
77 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ modification\ time | |
78 | --write-description\ \ \ \ \ \ write\ video\ description\ to\ a\ .description\ file | |
79 | --write-info-json\ \ \ \ \ \ \ \ write\ video\ metadata\ to\ a\ .info.json\ file | |
80 | \f[] | |
81 | .fi | |
82 | .SS Verbosity / Simulation Options: | |
83 | .IP | |
84 | .nf | |
85 | \f[C] | |
86 | -q,\ --quiet\ \ \ \ \ \ \ \ \ \ \ \ \ \ activates\ quiet\ mode | |
87 | -s,\ --simulate\ \ \ \ \ \ \ \ \ \ \ do\ not\ download\ the\ video\ and\ do\ not\ write\ anything | |
88 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ to\ disk | |
89 | --skip-download\ \ \ \ \ \ \ \ \ \ do\ not\ download\ the\ video | |
90 | -g,\ --get-url\ \ \ \ \ \ \ \ \ \ \ \ simulate,\ quiet\ but\ print\ URL | |
91 | -e,\ --get-title\ \ \ \ \ \ \ \ \ \ simulate,\ quiet\ but\ print\ title | |
92 | --get-thumbnail\ \ \ \ \ \ \ \ \ \ simulate,\ quiet\ but\ print\ thumbnail\ URL | |
93 | --get-description\ \ \ \ \ \ \ \ simulate,\ quiet\ but\ print\ video\ description | |
94 | --get-filename\ \ \ \ \ \ \ \ \ \ \ simulate,\ quiet\ but\ print\ output\ filename | |
95 | --get-format\ \ \ \ \ \ \ \ \ \ \ \ \ simulate,\ quiet\ but\ print\ output\ format | |
96 | --no-progress\ \ \ \ \ \ \ \ \ \ \ \ do\ not\ print\ progress\ bar | |
97 | --console-title\ \ \ \ \ \ \ \ \ \ display\ progress\ in\ console\ titlebar | |
98 | -v,\ --verbose\ \ \ \ \ \ \ \ \ \ \ \ print\ various\ debugging\ information | |
99 | \f[] | |
100 | .fi | |
101 | .SS Video Format Options: | |
102 | .IP | |
103 | .nf | |
104 | \f[C] | |
105 | -f,\ --format\ FORMAT\ \ \ \ \ \ video\ format\ code | |
106 | --all-formats\ \ \ \ \ \ \ \ \ \ \ \ download\ all\ available\ video\ formats | |
107 | --prefer-free-formats\ \ \ \ prefer\ free\ video\ formats\ unless\ a\ specific\ one\ is | |
108 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ requested | |
109 | --max-quality\ FORMAT\ \ \ \ \ highest\ quality\ format\ to\ download | |
110 | -F,\ --list-formats\ \ \ \ \ \ \ list\ all\ available\ formats\ (currently\ youtube\ only) | |
111 | --write-srt\ \ \ \ \ \ \ \ \ \ \ \ \ \ write\ video\ closed\ captions\ to\ a\ .srt\ file | |
112 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (currently\ youtube\ only) | |
113 | --srt-lang\ LANG\ \ \ \ \ \ \ \ \ \ language\ of\ the\ closed\ captions\ to\ download | |
114 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (optional)\ use\ IETF\ language\ tags\ like\ \[aq]en\[aq] | |
115 | \f[] | |
116 | .fi | |
117 | .SS Authentication Options: | |
118 | .IP | |
119 | .nf | |
120 | \f[C] | |
121 | -u,\ --username\ USERNAME\ \ account\ username | |
122 | -p,\ --password\ PASSWORD\ \ account\ password | |
123 | -n,\ --netrc\ \ \ \ \ \ \ \ \ \ \ \ \ \ use\ .netrc\ authentication\ data | |
124 | \f[] | |
125 | .fi | |
126 | .SS Post-processing Options: | |
127 | .IP | |
128 | .nf | |
129 | \f[C] | |
b7a34316 | 130 | -x,\ --extract-audio\ \ \ \ \ \ convert\ video\ files\ to\ audio-only\ files\ (requires |
cfcec693 FV |
131 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ffmpeg\ or\ avconv\ and\ ffprobe\ or\ avprobe) |
132 | --audio-format\ FORMAT\ \ \ \ "best",\ "aac",\ "vorbis",\ "mp3",\ "m4a",\ or\ "wav"; | |
133 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ best\ by\ default | |
234e230c PH |
134 | --audio-quality\ QUALITY\ \ ffmpeg/avconv\ audio\ quality\ specification,\ insert\ a |
135 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ value\ between\ 0\ (better)\ and\ 9\ (worse)\ for\ VBR\ or\ a | |
136 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ specific\ bitrate\ like\ 128K\ (default\ 5) | |
cfcec693 FV |
137 | -k,\ --keep-video\ \ \ \ \ \ \ \ \ keeps\ the\ video\ file\ on\ disk\ after\ the\ post- |
138 | \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ processing;\ the\ video\ is\ erased\ by\ default | |
139 | \f[] | |
140 | .fi | |
df4bad32 PH |
141 | .SH CONFIGURATION |
142 | .PP | |
143 | You can configure youtube-dl by placing default arguments (such as | |
144 | \f[C]--extract-audio\ --no-mtime\f[] to always extract the audio and not | |
145 | copy the mtime) into \f[C]/etc/youtube-dl.conf\f[] and/or | |
146 | \f[C]~/.local/config/youtube-dl.conf\f[]. | |
02531431 PH |
147 | .SH OUTPUT TEMPLATE |
148 | .PP | |
149 | The \f[C]-o\f[] option allows users to indicate a template for the | |
150 | output file names. | |
151 | The basic usage is not to set any template arguments when downloading a | |
152 | single file, like in | |
153 | \f[C]youtube-dl\ -o\ funny_video.flv\ "http://some/video"\f[]. | |
154 | However, it may contain special sequences that will be replaced when | |
155 | downloading each video. | |
156 | The special sequences have the format \f[C]%(NAME)s\f[]. | |
157 | To clarify, that is a percent symbol followed by a name in parenthesis, | |
158 | followed by a lowercase S. | |
159 | Allowed names are: | |
160 | .IP \[bu] 2 | |
161 | \f[C]id\f[]: The sequence will be replaced by the video identifier. | |
162 | .IP \[bu] 2 | |
163 | \f[C]url\f[]: The sequence will be replaced by the video URL. | |
164 | .IP \[bu] 2 | |
165 | \f[C]uploader\f[]: The sequence will be replaced by the nickname of the | |
166 | person who uploaded the video. | |
167 | .IP \[bu] 2 | |
168 | \f[C]upload_date\f[]: The sequence will be replaced by the upload date | |
169 | in YYYYMMDD format. | |
170 | .IP \[bu] 2 | |
171 | \f[C]title\f[]: The sequence will be replaced by the video title. | |
877f4c45 PH |
172 | .IP \[bu] 2 |
173 | \f[C]ext\f[]: The sequence will be replaced by the appropriate extension | |
174 | (like flv or mp4). | |
175 | .IP \[bu] 2 | |
176 | \f[C]epoch\f[]: The sequence will be replaced by the Unix epoch when | |
177 | creating the file. | |
178 | .IP \[bu] 2 | |
179 | \f[C]autonumber\f[]: The sequence will be replaced by a five-digit | |
180 | number that will be increased with each download, starting at zero. | |
02531431 PH |
181 | .PP |
182 | The current default template is \f[C]%(id)s.%(ext)s\f[], but that will | |
183 | be switchted to \f[C]%(title)s-%(id)s.%(ext)s\f[] (which can be | |
184 | requested with \f[C]-t\f[] at the moment). | |
185 | .PP | |
186 | In some cases, you don\[aq]t want special characters such as 中, spaces, | |
187 | or &, such as when transferring the downloaded filename to a Windows | |
188 | system or the filename through an 8bit-unsafe channel. | |
189 | In these cases, add the \f[C]--restrict-filenames\f[] flag to get a | |
190 | shorter title: | |
191 | .IP | |
192 | .nf | |
193 | \f[C] | |
194 | $\ youtube-dl\ --get-filename\ -o\ "%(title)s.%(ext)s"\ BaW_jenozKc | |
195 | youtube-dl\ test\ video\ \[aq]\[aq]_ä↭𝕐.mp4\ \ \ \ #\ All\ kinds\ of\ weird\ characters | |
196 | $\ youtube-dl\ --get-filename\ -o\ "%(title)s.%(ext)s"\ BaW_jenozKc\ --restrict-filenames | |
197 | youtube-dl_test_video_.mp4\ \ \ \ \ \ \ \ \ \ #\ A\ simple\ file\ name | |
198 | \f[] | |
199 | .fi | |
cfcec693 FV |
200 | .SH FAQ |
201 | .SS Can you please put the -b option back? | |
202 | .PP | |
203 | Most people asking this question are not aware that youtube-dl now | |
204 | defaults to downloading the highest available quality as reported by | |
205 | YouTube, which will be 1080p or 720p in some cases, so you no longer | |
206 | need the -b option. | |
207 | For some specific videos, maybe YouTube does not report them to be | |
208 | available in a specific high quality format you\[aq]\[aq]re interested | |
209 | in. | |
210 | In that case, simply request it with the -f option and youtube-dl will | |
211 | try to download it. | |
212 | .SS I get HTTP error 402 when trying to download a video. What\[aq]s | |
213 | this? | |
214 | .PP | |
215 | Apparently YouTube requires you to pass a CAPTCHA test if you download | |
216 | too much. | |
217 | We\[aq]\[aq]re considering to provide a way to let you solve the | |
218 | CAPTCHA (https://github.com/rg3/youtube-dl/issues/154), but at the | |
219 | moment, your best course of action is pointing a webbrowser to the | |
220 | youtube URL, solving the CAPTCHA, and restart youtube-dl. | |
221 | .SS I have downloaded a video but how can I play it? | |
222 | .PP | |
223 | Once the video is fully downloaded, use any video player, such as | |
224 | vlc (http://www.videolan.org) or mplayer (http://www.mplayerhq.hu/). | |
225 | .SS The links provided by youtube-dl -g are not working anymore | |
226 | .PP | |
227 | The URLs youtube-dl outputs require the downloader to have the correct | |
228 | cookies. | |
229 | Use the \f[C]--cookies\f[] option to write the required cookies into a | |
230 | file, and advise your downloader to read cookies from that file. | |
231 | Some sites also require a common user agent to be used, use | |
232 | \f[C]--dump-user-agent\f[] to see the one in use by youtube-dl. | |
233 | .SS ERROR: no fmt_url_map or conn information found in video info | |
234 | .PP | |
235 | youtube has switched to a new video info format in July 2011 which is | |
236 | not supported by old versions of youtube-dl. | |
237 | You can update youtube-dl with \f[C]sudo\ youtube-dl\ --update\f[]. | |
6c5b442a PH |
238 | .SS ERROR: unable to download video |
239 | .PP | |
240 | youtube requires an additional signature since September 2012 which is | |
241 | not supported by old versions of youtube-dl. | |
242 | You can update youtube-dl with \f[C]sudo\ youtube-dl\ --update\f[]. | |
551fa9df | 243 | .SS SyntaxError: Non-ASCII character |
6c5b442a PH |
244 | .PP |
245 | The error | |
246 | .IP | |
247 | .nf | |
248 | \f[C] | |
249 | File\ "youtube-dl",\ line\ 2 | |
250 | SyntaxError:\ Non-ASCII\ character\ \[aq]\\x93\[aq]\ ... | |
251 | \f[] | |
252 | .fi | |
253 | .PP | |
254 | means you\[aq]re using an outdated version of Python. | |
255 | Please update to Python 2.6 or 2.7. | |
256 | .PP | |
257 | To run youtube-dl under Python 2.5, you\[aq]ll have to manually check it | |
258 | out like this: | |
259 | .IP | |
260 | .nf | |
261 | \f[C] | |
262 | git\ clone\ git://github.com/rg3/youtube-dl.git | |
263 | cd\ youtube-dl | |
551fa9df | 264 | python\ -m\ youtube_dl\ --help |
6c5b442a PH |
265 | \f[] |
266 | .fi | |
267 | .PP | |
268 | Please note that Python 2.5 is not supported anymore. | |
551fa9df FV |
269 | .SS What is this binary file? Where has the code gone? |
270 | .PP | |
271 | Since June 2012 (#342) youtube-dl is packed as an executable zipfile, | |
272 | simply unzip it (might need renaming to \f[C]youtube-dl.zip\f[] first on | |
1c469a94 | 273 | some systems) or clone the git repository, as laid out above. |
551fa9df FV |
274 | If you modify the code, you can run it by executing the |
275 | \f[C]__main__.py\f[] file. | |
a7b5c8d6 | 276 | To recompile the executable, run \f[C]make\ youtube-dl\f[]. |
551fa9df FV |
277 | .SS The exe throws a \f[I]Runtime error from Visual C++\f[] |
278 | .PP | |
279 | To run the exe you need to install first the Microsoft Visual C++ 2008 | |
280 | Redistributable | |
281 | Package (http://www.microsoft.com/en-us/download/details.aspx?id=29). | |
cfcec693 FV |
282 | .SH COPYRIGHT |
283 | .PP | |
284 | youtube-dl is released into the public domain by the copyright holders. | |
285 | .PP | |
286 | This README file was originally written by Daniel Bolton | |
287 | (<https://github.com/dbbolton>) and is likewise released into the public | |
288 | domain. | |
289 | .SH BUGS | |
290 | .PP | |
291 | Bugs and suggestions should be reported at: | |
292 | <https://github.com/rg3/youtube-dl/issues> | |
293 | .PP | |
294 | Please include: | |
295 | .IP \[bu] 2 | |
296 | Your exact command line, like | |
297 | \f[C]youtube-dl\ -t\ "http://www.youtube.com/watch?v=uHlDtZ6Oc3s&feature=channel_video_title"\f[]. | |
298 | A common mistake is not to escape the \f[C]&\f[]. | |
299 | Putting URLs in quotes should solve this problem. | |
300 | .IP \[bu] 2 | |
301 | The output of \f[C]youtube-dl\ --version\f[] | |
302 | .IP \[bu] 2 | |
303 | The output of \f[C]python\ --version\f[] | |
304 | .IP \[bu] 2 | |
305 | The name and version of your Operating System ("Ubuntu 11.04 x64" or | |
306 | "Windows 7 x64" is usually enough). |