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.

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

-F, --query-formats
    Query available formats to an URL. The returned string will contain an array of format strings, each separated by the '|' character. The array is created, by libquvi, from the data returned by the server. You can use these format strings with "--format".

    See also "EXAMPLES", "--format" and "--prefer-format".

-f, --format arg (=default)
    Download format arg of the media. The arg can also be "default", "best", "help" or "list". Note, however, that of these, 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 at runtime. If the arg is "best", libquvi will determine the "best" format available to an URL.

    If the arg is "default" libquvi attempts to return an URL to whatever was deemed to be the "default" format to the URL. libquvi will switch to "default" format if the arg was unregonized or the requested arg format was unavailable.

    For the above reasons, the downloaded format may be different from the requested arg format.

    For details about the YouTube's "fmt" IDs, refer to:
     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 (=$HOME/.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".

-p, --prefer-format arg
    Where arg is a string pair of pattern (regular expression) and format. The character ':' is expected to separate these two strings, e.g. "-p foo:bar". If the pattern matches an URL, cclive downloads the format of the media from the URL.

    "--prefer-format" works similarly to "--format" with the difference that -p binds the format value to a matching URL. In contrast, the "--format" value is used with all of the URLs fed to cclive at runtime.

    "--format" negates "--prefer-format". cclive accepts multiple occurrences of "--prefer-format".

    See also "EXAMPLES", "--query-formats" and "--format".

--progressbar arg (=normal)
    Use progressbar arg. Ignored with "--background" which will always use 'dotline' type. arg can be one of the following strings:

     normal   .. Default
     dotline  .. Used by --background as default
     simple   .. Less verbose

--update-interval arg (=1)
    Specify arg progressbar update interval in seconds. The value may be a 'double', e.g. 0.2 or 1.99.

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

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

    This option is deprecated and will be removed in the later versions of cclive. 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").

    Delimiters supported:

     <> {} () /

    Note:

     s/old/new/  .. Invalid
     s/old//new/ .. OK

    This option is deprecated and will be removed in the later versions of cclive. Use "--tr" instead.

--exec arg
    Invoke arg after each successfully finished download. Each occurence of the following specifiers will be replaced (and double-quoted) in the arg:

     %f .. Full path to the downloaded media file

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

EXAMPLES
Put the URLs inside quotes when they are specified as the command line arguments to the program. This is the recommended practice.

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.

FILES

$HOME/.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

--no-download
    Use the "--no-download" switch when you don't need to download the media.

--verbose-libcurl
    Make libcurl verbose.

Debug symbols
    Compile cclive with "-g", see also gcc(1).

Other tools
    See also gdb(1), strace(1) and valgrind(1).

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