NAME¶
cclive - media download tool
SYNOPSIS¶
cclive [options] [url | file...]
DESCRIPTION¶
cclive is a tool for downloading media from YouTube and similar websites. It has
a low memory footprint compared to other existing tools.
OPTIONS¶
Unless an arg is specified in the command line, cclive reads from the stdin. The
command line args may be either URLs or files to read. If cclive reads from
either stdin or files, it expects each URL to be separated by a newline or
whitespace character.
--version¶
Print version and exit.
--help¶
Print help and exit.
--license¶
Print license and exit.
--support¶
Print supported hosts and exit.
--verbose-libcurl¶
Turn on libcurl verbose output.
-q, --quiet¶
Turn off all output to stdout and stderr with the exception of
"--verbose-libcurl", if enabled, libcurl will continue to print
messages to stderr.
-b, --background¶
Go to background after startup. Output will be written to the file specified
with "--log-file".
Query available formats to the URL. The returned array is created from the data
returned by the server. You can use the
format strings in this array
with "--format".
The available formats are determined by the
libquvi script responsible
for parsing the media details.
See also "EXAMPLES", "--format" and
"--prefer-format".
Download the format
arg of the media. The
arg may also be
"default", "best", "help" or "list".
Note, however, that the "list" and the "help" are
deprecated and will be removed in the later versions of cclive. The
arg value is used with
all of the URLs fed to cclive.
If the
arg is "best", the
libquvi script responsible for
parsing the media details will determine the "best" format available
to an URL.
If the
arg is "default" the
libquvi script attempts to
return an URL to whatever it deemed to be the "default" format for
the URL.
The
libquvi script will return the "default" format if the
arg was unrecognized or the requested format was not available.
You can find more information about the YouTube specific "fmt" IDs at:
<
http://en.wikipedia.org/wiki/YouTube#Quality_and_codecs>
See also "EXAMPLES", "--query-formats" and
"--prefer-format".
-c, --continue¶
Resume partially downloaded media.
-W, --overwrite¶
Overwrite existing media.
-O, --output-file arg¶
Write media to
arg. Overrides "--filename-format".
-n, --no-download¶
Do not download the media, print details only.
-r, --no-resolve¶
Do not resolve URL redirections. If enabled, breaks the compatibility with most
"shortened" URLs.
--no-proxy¶
Disable use of HTTP proxy. Overrides both "--proxy" and http_proxy
environment settings.
--log-file arg (=cclive_log)¶
Write log output to
arg. Ignored unless used with
"--background". Overwrites the existing
arg file (if any).
See also "--background" and "--update-interval".
--config-file arg (=~/.ccliverc)¶
Path to a file to read cclive arguments from.
OPTIONS - CONFIGURATION¶
In addition to the command line, the configurable options may also be read from
the configuration file. See "FILES".
Download the
specified format of the media when the pattern matches to
the media page URL.
arg is a
string pair of
pattern (regular expression) and
format. The character ':' is expected to separate these two strings,
e.g. "pattern:format".
"--format" overrides "--prefer-format". cclive accepts
multiple occurrences of "--prefer-format".
See also "EXAMPLES", "--query-formats" and
"--format".
--progressbar arg (=normal)¶
Use the progressbar of type
arg. Ignored with "--background"
which will always use the "dotline" type. Possible values:
normal (default)
dotline (implied by --background)
simple (basic)
--update-interval arg (=1)¶
Specify
arg progressbar update interval in seconds. Use of decimal
fractions, e.g. "0.2" or "1.99", is acceptable.
How the downloaded media file should be named. Each occurence of the following
specifiers will be replaced in the
arg:
%t .. Media title
%i .. Media ID
%h .. Media host ID (e.g. "vimeo")
%s .. Media file suffix (e.g. "flv")
See also "--tr".
--output-dir arg¶
Write downloaded media to
arg directory.
-t, --tr arg¶
Where
arg is a pattern (regular expression). "--tr" can be used
to translate the characters in the media titles before they are used in the
filenames of the downloaded media. Default is "/(\w|\s)/g".
cclive accepts multiple occurrences of "--tr". See also
"EXAMPLES".
--exec arg¶
Invoke
arg after each successfully finished download. Each occurence of
the following specifiers will be replaced in the
arg:
%f .. Full path to the downloaded media file
%n .. Name of the downloaded media file
%t .. Media title (unfiltered)
The
arg is also invoked if the media is fully retrieved already. cclive
accepts multiple occurrences of "--exec". See also
"EXAMPLES".
--agent arg (="Mozilla/5.0")¶
Identify cclive as
arg to the HTTP servers.
--proxy arg¶
Use
arg for HTTP proxy, e.g. "
http://foo:1234". Overrides
http_proxy environment setting.
--throttle arg (=0, disabled)¶
Do not exceed the transfer rate
arg KB/s.
--connect-timeout arg (=30)¶
This option wraps the CURLOPT_CONNECTTIMEOUT (libcurl):
"Pass a long. It should contain the maximum time in seconds that you allow
the connection to the server to take.
This only limits the connection phase, once it has connected, this option is of
no more use. Set to zero to disable connection timeout (it will then only
timeout on the system's internal timeouts). See also the CURLOPT_TIMEOUT
option." --
curl_easy_setopt(3)
--transfer-timeout arg (=0, disabled)¶
This option wraps the CURLOPT_TIMEOUT (libcurl):
"Pass a long as parameter containing the maximum time in seconds that you
allow the libcurl transfer operation to take.
Normally, name lookups can take a considerable time and limiting operations to
less than a few minutes risk aborting perfectly normal operations. This option
will cause curl to use the SIGALRM to enable time-outing system calls."
--
curl_easy_setopt(3)
--dns-cache-timeout arg (=60)¶
This option wraps the CURLOPT_DNS_CACHE_TIMEOUT (libcurl):
"Pass a long, this sets the timeout in seconds. Name resolves will be kept
in memory for this number of seconds. Set to zero to completely disable
caching, or set to -1 to make the cached entries remain forever. By default,
libcurl caches this info for 60 seconds.
The name resolve functions of various libc implementations don't re-read name
server information unless explicitly told so (for example, by calling
res_init(3)). This may cause libcurl to keep using the older server
even if DHCP has updated the server info, and this may look like a DNS cache
issue to the casual libcurl-app user." --
curl_easy_setopt(3)
--max-retries arg (=5, 0=disabled)¶
Retry downloading
arg times before giving up.
--retry-wait arg (=5)¶
Wait
arg seconds before retrying after a failed attempt.
DEPRECATED¶
These options are deprecated and will be removed in the later versions of
cclive.
--regexp arg (="/(\w|\s)/g")¶
Regular expression
arg to cleanup the media title before it is used in
the filename. Supports "i" (case-insensitive) and "g"
(global or "find all").
Use "--tr" instead.
--subst arg ...¶
Replace matched occurences in the media filename after applying
"--filename-format" and "--regexp". To use multiple
substitutions, separate each expression in
arg with a whitespace.
Supports "i" (case-insensitive) and "g" (global or
"find all").
Supported delimiters
<> {} () /
Note
s/old/new/ .. Invalid
s/old//new/ .. OK
Use "--tr" instead.
EXAMPLES¶
Always quote the URLs in the command line as seen below. Many URLs contain
parameters that may otherwise cause the shell to behave with unexpected
results.
cclive "URL"¶
Typical use.
cclive -F "URL"¶
Query available formats to the URL. You can then use one of the format strings
from the returned array with "--format".
cclive -f best "URL"¶
Download the best available format of the media.
cclive -p "^.*youtube.*\.com:fmt43_360p"
"YOUTUBE_URL"¶
Get the fmt43_360p format of YouTube videos whenever possible.
cclive -n "URL"¶
Do not download the media, print the details only.
cclive "URL" -t 's/foo/bar/g'¶
Replace any "foo" substrings with "bar" in the media title
before using it in the output filename.
cclive "URL" -b --log-file foo.log¶
Go to background, redirect output to "foo.log".
pkill -USR1 cclive¶
Interrupt the current download of all matching cclive processes. Causes cclive
to move onto the next URL in the queue, if any.
cclive "URL" --exec 'echo "%f"' --exec 'vlc
"%f"'¶
Print path to the downloaded media file using
echo(1), open the media
file in
vlc(1).
More examples¶
You can find more examples in the project wiki, see "WWW" for the
URLs.
FILES¶
~/.ccliverc¶
Or use "--config-file". See "--help" or "OPTIONS -
CONFIGURATION" for the configurable options.
Example
filename-format = %h_%i_(%t).%s
proxy = http://foo:1234
exec = /usr/bin/vlc %f
regexp = /(\w|\pL)/g
progressbar = simple
prefer-format = ^.*youtube.*\.com:fmt43_360p
prefer-format = dailym:best
EXIT STATUS¶
cclive exits with 0 on success and >0 if an (unrecoverable) error occurred.
DEBUGGING TIPS¶
--verbose-libcurl¶
Make libcurl verbose.
WWW¶
Home : http://cclive.sourceforge.net/
gitweb: http://repo.or.cz/w/cclive.git
BACKGROUND¶
The name "clive" originates from the words "command line video
extraction", the prepending "c" refers to C or C++. cclive is a
rewrite of
clive(1) in C++.
LICENSE¶
cclive is free software, licensed under the GPLv3+.
AUTHOR¶
Toni Gundogdu <legatvs at sign gmail com>.
Thanks to all those who have contributed to the project by sending patches,
reporting bugs and writing feedback. You know who you are.
