cclive(1)

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.

INPUT
Unless an argument is specified on the command line, cclive reads from the stdin. The command line arguments 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 a whitespace character.

OPTIONS - COMMAND LINE
These options may be specified on the command line only. See also "OPTIONS - CONFIGURATION".

  --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".

  -F, --query-formats
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".

  -f, --format arg (=default)
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
The following options may be specified on the command line and read from a configuration file. Any such option specified on the command line will override the value read from the configuration file. See also "FILES" and "--config-file".

  -p, --prefer-format arg
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.

  --filename-format arg (="%t.%s")
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 on 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
This location is read by default. "--config-file" may be used to specify a different location. See also "OPTIONS - CONFIGURATION".

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 EXIT_SUCCESS (on POSIX systems this is 0) on success and EXIT_FAILURE (on POSIX systems this is 1) if an 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.