1CCLIVE(1) cclive Manual CCLIVE(1)
2
6 cclive - media stream extraction tool
7
9 cclive [OPTIONS] [URL|FILE ...]
10
12 cclive is a command line tool for downloading media streams from
13 YouTube and similar websites.
14
16 The command will read stdin by default. The input is expected to
17 contain URLs. The command arguments are expected to be either URLs or
18 file paths. If the input is read from either stdin or a file, the
19 contents are read as RFC2483. The input may also contain URIs (file://)
20 to local files.
21
23 Core
24 -b, --background
25 Go to background after startup. The output written to stdout will
26 be written to the file specified with --log-file.
27 -F, --config-file <arg>
29 Read the program arguments from the specified file instead of the
30 default ~/.ccliverc file. See also the section called “FILES”.
31 -c, --continue
33 Resume partially downloaded media.
34 config:
36 continue = {true|false}
37 -e, --exec <arg>
39 Invoke the specified command after each successfully finished
40 download. The command is also invoked if the media is fully
41 retrieved already. This option may be specified multiple times. See
42 also the section called “EXAMPLES”.
43 All occurences of the following sequences will be replaced in the
45 arg:
46 %f .. Full path to the downloaded media file
48 %n .. Name of the downloaded media file
49 %t .. Unfiltered media title
50 config:
52 exec = arg
53 -n, --no-download
55 Do not download the media, print the details only.
56 -s, --stream <ID>
58 Download the specified media stream. By default the program will
59 get the default stream. The stream selection with libquvi(3) 0.4 is
60 basic at most, whereas libquvi(3) 0.9+ provides a more advanced
61 facility for this.
62 libquvi(3) 0.9+ treats the ID value as a regex PATTERN and matches
64 it against the libquvi-scripts(7) returned media stream IDs.
65 Additionally, the value of ID may be a comma-separated list of
66 regex PATTERNs.
67 In comparison, libquvi(3) 0.4 only checks whether the strings (the
69 value of ID and the returned media stream ID) are equal.
70 The ID value may also contain the following reserved keywords:
72 · croak - tell libquvi(3) (0.9+) to exit with an error when
74 reached
75 · best - tell libquvi(3) to choose the best quality stream
77 The best quality is determined by libquvi-scripts(7). The method
79 varies, depending on the libquvi(3) version and the website.
80 For example, libquvi-scripts(7) 0.9+ would typically compare the
82 media quality properties (e.g. the video height property). In
83 reality, the method will vary depending on the data provided by the
84 media hosting service, and the implementation of the support script
85 that was written for the website.
86 See the --version output to confirm whether cclive was built with
88 libquvi(3) 0.9 or later. See also the section called “EXAMPLES”.
89 config:
91 stream = arg
92 -N, --timestamp
94 Try to preserve the file modification time (as returned by the
95 server, if any). Using this option will cause the program to change
96 the modification time of the file to that of returned by the
97 server.
98 Note
100 libcurl will parse this value from the returned "Last-Modified"
101 HTTP header. This header may not always be present in which
102 case the program will quietly ignore this option.
103 config:
105 timestamp = {true|false}
106 Informative
108 -h, --help
109 Print help and exit.
110 -S, --print-streams
112 Print the available media streams. The printed values (media stream
113 IDs) may be used with --stream and --prefer-format options. The
114 available streams are determined by libquvi(3) and libquvi-
115 scripts(7).
116 -D, --print-config
118 Print the value of all defined configuration options to stdout.
119 -u, --support
121 Print the supported website domains and exit.
122 -v, --version
124 Print the program version and exit.
125 Output
127 -f, --filename-format <arg>
128 Specify how the downloaded media file should be named. All
129 occurences of the following sequences will be replaced in the arg:
130 %t .. Media title (after applying --tr)
132 %s .. Media file extension
133 %i .. Media ID
134 The default value is "%t.%s".
136 config:
138 filename-format = arg
139 -l, --log-file <arg>
141 Write log output to the specified file. The program will ignore
142 this option value unless it is being used together with
143 --background. The existing log file will be ovewritten. By default,
144 the program will use "cclive_log" as the log file name.
145 -d, --output-dir <arg>
147 Write downloaded media to the specified directory. By default, the
148 program will write the media to the current working directory.
149 config:
151 output-dir = arg
152 -O, --output-file <arg>
154 Write media to the specified file. Overrides --filename-format.
155 -W, --overwrite
157 Overwrite existing media files.
158 -R, --progressbar <arg>
160 Use the progressbar of the specified type. The program will ignore
161 the value of this option with --background. The arg may be one of
162 the following values:
163 · dotline (also implied by --background)
165 · normal (default)
167 · simple
169 config:
171 progressbar = arg
172 -q, --quiet
174 Turn off all output to stdout and stderr with the exception of
175 --verbose-libcurl.
176 -t, --tr <arg>
178 Specify to translate the characters in the media titles before they
179 are used in the media file names. The arg is a regular expression
180 pattern. The default value is "/(\w|\s)/g". This option may be
181 specified multiple times. See also the section called “EXAMPLES”.
182 config:
184 tr = arg
185 -i, --update-interval <arg>
187 Specify the progressbar update interval in seconds. The default
188 value is 1.
189 config:
191 update-interval = arg
192 -B, --verbose-libcurl
194 Enable libcURL verbose output.
195 Network
197 -a, --agent <arg>
198 Identify cclive as arg to the HTTP servers. The default value is
199 "Mozilla/5.0".
200 config:
202 agent = arg
203 -C, --connect-timeout <arg>
205 Maximum time in seconds that the program should allow the
206 connection to the server to take. This only limits the connection
207 phase, once it has connected, this option is no more of use. Set to
208 0 to disable connection timeout (it will then only timeout on the
209 system’s internal timeouts). The default is 30.
210 config:
212 connect-time = arg
213 -A, --dns-cache-timeout <arg>
215 The name resolves will be kept in the memory for this number of
216 seconds. Set to 0 to completely disable DNS caching, or to -1 to
217 make the cached entries to remain in the memory forever. The
218 default is 60.
219 config:
221 dns-cache-timeout = arg
222 -m, --max-retries <arg>
224 Specify the number of downloading retries before giving up. Set to
225 0 to disable. The default is 5.
226 Note that the program will skip retrying altogether if the server
228 returned HTTP 400 (and over), or if libquvi(3) returned an
229 unrecoverable error (e.g. missing libquvi-scripts(7)).
230 config:
232 max-retries = arg
233 -X, --no-proxy
235 Disable use of HTTP proxy. Overrides --proxy and http_proxy
236 environment settings.
237 -r, --no-resolve
239 Do not resolve HTTP URL redirections. Using this option will result
240 in the program not being able to follow URL redirections which are
241 often used by different URL shortening services.
242 When libquvi 0.9 or later is being used with cclive, this option
244 will be ignored. The library will always resolve any URL
245 redirections. See --version output to see if cclive was compiled
246 with libquvi 0.9+.
247 config:
249 no-resolve = {true|false}
250 -x, --proxy I<arg>
252 Use the specified proxy address (e.g. http://foo:1234) for HTTP
253 connections. By default, libcURL (which cclive and libquvi(3) use)
254 will use the value of http_proxy. Using this option will override
255 the http_proxy environment value.
256 See curl(1) for more information about the supported environment
258 variables.
259 config:
261 proxy = arg
262 -w, --retry-wait <arg>
264 Wait the specified number of seconds before retrying after a failed
265 attempt. The default is 5. If the value is 0, the program will skip
266 this step.
267 config:
269 retry-wait = arg
270 -H, --throttle <arg>
272 Do not exceed the specified transfer rate (Ki/s). If arg is 0
273 (default), the throttling will be disabled.
274 config:
276 throttle = arg
277 -T, --transfer-timeout <arg>
279 Maximum time in seconds that the program should allow the transfer
280 operation to take. Normally, name lookups can take a considerable
281 amount of time, and limiting operations to less than a few minutes
282 will risk aborting perfectly normal operations. This option will
283 cause libcURL to use the SIGALRM to enable the timeout system
284 calls. The default is 0 (disabled).
285 config:
287 transfer-timeout = arg
288 Deprecated
290 These options will be removed eventually in the later versions of
291 cclive.
292 -p, --prefer-format <arg>
294 The --stream is intended to replace this option, eventually. The
295 stream selection will be provided by libquvi 0.9+. This was done
296 previously by cclive. See also the section called “EXAMPLES”.
297 Have the program choose the format (media stream) to download by
299 matching the regular expression pattern match to the media URL as
300 specified in the arg.
301 This option may be specified multiple times. The use of --stream
303 will override the rules specified using this option.
304 The arg is a string pair separated by a colon. The string pair
306 consists of:
307 · a regular expression pattern
309 · format (media stream) to download
311 config:
313 prefer-format = arg
314
316 · Typical use:
317 $ cclive "URL"
319 · Query the available media streams:
321 $ cclive -S "URL"
323 · Download the best quality media stream:
325 $ cclive -s best "URL"
327 · With libquvi(3) 0.9+, you can pass a list of stream ID patterns to
329 match:
330 $ cclive -s foo,baz,best "URL"
332 See the --stream description for more details.
334 · Replace all occurences of foo with bar in the media title before it
336 is used in the media file name:
337 $ cclive -t 's/foo/bar/g' "URL"
339 · Go to background, redirect output to foo.log file:
341 $ cclive -b --log-file foo.log "URL"
343 · Interrupt the current transfer of all of the matching processes,
345 this (USR1) will cause cclive to move onto the next URL in the
346 batch:
347 $ pkill -USR1 cclive
349 · Print the path to the downloaded media file using echo(1) and open
351 the media file in totem(1):
352 $ cclive --exec 'echo "%f"' --exec 'totem "%f"' "URL"
354 · Process a batch of media URLs:
356 $ cat URLs
358 http://foo
359 http://bar
360 http://baz
361 http://qux
362 $ cat URLs | cclive
363 $ cclive < URLs
364 $ cclive URLs
365
367 ~/.ccliverc
368 The program will read this location by default. A different
369 location may be defined with --config-file.
370 Example
372 prefer-format = ^.*youtube.*\.com:fmt43_360p
373 prefer-format = dailym:best
374 filename-format = %i_(%t).%s
376 tr = /(\w)/g
377 progressbar = simple
379 continue = true
380 proxy = http://foo:1234
382 no-resolve = false
383 exec = /usr/bin/totem %f
385
387 The availability and the identification of the media streams is
388 determined by libquvi(3) and libquvi-scripts(7).
389 YouTube
391 libquvi-scripts(7) returns the media stream IDs containing the itag
392 value so that they can be referred to as such using the --stream or
393 --prefer-format options. The --print-streams may be used to get a list
394 of the available media streams.
395 libquvi-scripts 0.4
397 The fmt prefix is used to identify the streams. For example:
398 itag: 22
400 quvi: fmt22_720p
401 libquvi-scripts 0.9 and later
403 The iXX prefix is used in the media stream IDs. For example:
404 itag: 22
406 quvi: hd720_mp4_i22_720p
407 For more information about the YouTube video quality and codecs, visit
409 http://en.wikipedia.org/wiki/YouTube#Quality_and_codecs.
410
412 The program will exit with EXIT_SUCCESS (on POSIX systems this is 0) on
413 success, and with EXIT_FAILURE (on POSIX systems this is 1) if an error
414 occurred.
415
417 The development code may be cloned from git://repo.or.cz/cclive.git.
418 The gitweb is accessible at http://repo.or.cz/w/cclive.git.
419
421 Toni Gundogdu <legatvs@gmail.com>
422 Author.
423
425 Report bugs to the cclive-devel mailing list
426 <cclive-devel@lists.sourceforge.net> where the development and the
427 maintenance is primarily done. You do not have to be subscribed to the
428 list to send a message there.
429
431 cclive is Free Software, licensed under the GNU Affero GPLv3+.
432
434 libquvi-scripts(7), libquvi(3)
435cclive 0.9.3 11/23/2013 CCLIVE(1)