=pod

=head1 NAME

cclive - media download tool

=head1 SYNOPSIS

cclive [OPTIONS] [URL | FILE ...]

=head1 DESCRIPTION

cclive is a tool for downloading media from YouTube and similar
websites. It has a low memory footprint compared to other existing
tools.

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

=head1 OPTIONS - COMMAND LINE

These options may be specified on the command line only.
See also L</OPTIONS - CONFIGURATION>.

=head2 --version

Print version and exit.

=head2 --help

Print help and exit.

=head2 --license

Print license and exit.

=head2 --support

Print supported hosts and exit.

=head2 --verbose-libcurl

Turn on libcurl verbose output.

=head2 -q, --quiet

Turn off all output to stdout and stderr with the exception of
C<--verbose-libcurl>, if enabled, libcurl will continue to print
messages to stderr.

=head2 -b, --background

Go to background after startup. Output will be written to
the file specified with C<--log-file>.

=head2 -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
I<format strings> in this array with C<--format>.

The available formats are determined by the I<libquvi script>
responsible for parsing the media details.

See also L</EXAMPLES>, C<--format> and C<--prefer-format>.

=head2 -f, --format I<arg> (=default)

Download the format I<arg> of the media. The I<arg> may also be C<default>,
C<best>, C<help> or C<list>. Note, however, that the C<list> and the C<help>
are I<deprecated> and will be removed in the later versions of cclive.
The I<arg> value is used with B<all> of the URLs fed to cclive.

If the I<arg> is C<best>, the I<libquvi script> responsible for parsing
the media details will determine the C<best> format available to an URL.

If the I<arg> is C<default> the I<libquvi script> attempts to return an
URL to whatever it deemed to be the C<default> format for the URL.

The I<libquvi script> will return the C<default> format if the I<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 L</EXAMPLES>, C<--query-formats> and C<--prefer-format>.

=head2 -c, --continue

Resume partially downloaded media.

=head2 -W, --overwrite

Overwrite existing media.

=head2 -O, --output-file I<arg>

Write media to I<arg>. Overrides C<--filename-format>.

=head2 -n, --no-download

Do not download the media, print details only.

=head2 -r, --no-resolve

Do not resolve URL redirections. If enabled, breaks the compatibility
with most "shortened" URLs.

=head2 --no-proxy

Disable use of HTTP proxy. Overrides both C<--proxy> and http_proxy environment
settings.

=head2 --log-file I<arg> (=cclive_log)

Write log output to I<arg>. Ignored unless used with C<--background>.
Overwrites the existing I<arg> file (if any). See also C<--background>
and C<--update-interval>.

=head2 --config-file I<arg> (=~/.ccliverc)

Path to a file to read cclive arguments from.

=head1 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 L</FILES> and C<--config-file>.

=head2 -p, --prefer-format I<arg>

Download the I<specified> format of the media when the pattern matches
to the media page URL.

I<arg> is a B<string pair> of I<pattern> (regular expression) and
I<format>. The character ':' is expected to separate these two
strings, e.g. C<pattern:format>.

C<--format> overrides C<--prefer-format>. cclive accepts multiple
occurrences of C<--prefer-format>.

See also L</EXAMPLES>, C<--query-formats> and C<--format>.

=head2 --progressbar I<arg> (=normal)

Use the progressbar of type I<arg>. Ignored with C<--background> which
will always use the C<dotline> type. Possible values:

 normal  (default)
 dotline (implied by --background)
 simple  (basic)

=head2 --update-interval I<arg> (=1)

Specify I<arg> progressbar update interval in seconds. Use of decimal
fractions, e.g. "0.2" or "1.99", is acceptable.

=head2 --filename-format I<arg> (="%t.%s")

How the downloaded media file should be named.  Each occurence of the
following specifiers will be replaced in the I<arg>:

 %t .. Media title
 %i .. Media ID
 %h .. Media host ID (e.g. "vimeo")
 %s .. Media file suffix (e.g. "flv")

See also C<--tr>.

=head2 --output-dir I<arg>

Write downloaded media to I<arg> directory.

=head2 -t, --tr I<arg>

Where I<arg> is a pattern (regular expression). C<--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 C</(\w|\s)/g>.

cclive accepts multiple occurrences of C<--tr>. See also L</EXAMPLES>.

=head2 --exec I<arg>

Invoke I<arg> after each successfully finished download. Each occurence
of the following specifiers will be replaced in the I<arg>:

 %f .. Full path to the downloaded media file
 %n .. Name of the downloaded media file
 %t .. Media title (unfiltered)

The I<arg> is also invoked if the media is fully retrieved already.
cclive accepts multiple occurrences of C<--exec>. See also L</EXAMPLES>.

=head2 --agent I<arg> (="Mozilla/5.0")

Identify cclive as I<arg> to the HTTP servers.

=head2 --proxy I<arg>

Use I<arg> for HTTP proxy, e.g. "http://foo:1234". Overrides
http_proxy environment setting.

=head2 --throttle I<arg> (=0, disabled)

Do not exceed the transfer rate I<arg> KB/s.

=head2 --connect-timeout I<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)

=head2 --transfer-timeout I<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)

=head2 --dns-cache-timeout I<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)

=head2 --max-retries I<arg> (=5, 0=disabled)

Retry downloading I<arg> times before giving up.

=head2 --retry-wait I<arg> (=5)

Wait I<arg> seconds before retrying after a failed attempt.

=head1 DEPRECATED

These options are deprecated and will be removed in the later versions
of cclive.

=head2 --regexp I<arg> (="/(\w|\s)/g")

Regular expression I<arg> to cleanup the media title before it
is used in the filename. Supports "i" (case-insensitive) and "g"
(global or "find all").

Use C<--tr> instead.

=head2 --subst I<arg> ...

Replace matched occurences in the media filename after applying
C<--filename-format> and C<--regexp>. To use multiple substitutions,
separate each expression in I<arg> with a whitespace. Supports "i"
(case-insensitive) and "g" (global or "find all").

=head3 Supported delimiters

 <> {} () /

=head3 Note

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

Use C<--tr> instead.

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

=head2 cclive "URL"

Typical use.

=head2 cclive -F "URL"

Query available formats to the URL. You can then use one of the
format strings from the returned array with C<--format>.

=head2 cclive -f best "URL"

Download the best available format of the media.

=head2 cclive -p "^.*youtube.*\.com:fmt43_360p" "YOUTUBE_URL"

Get the fmt43_360p format of YouTube videos whenever possible.

=head2 cclive -n "URL"

Do not download the media, print the details only.

=head2 cclive "URL" -t 's/foo/bar/g'

Replace any "foo" substrings with "bar" in the media title before
using it in the output filename.

=head2 cclive "URL" -b --log-file foo.log

Go to background, redirect output to C<foo.log>.

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

=head2 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).

=head2 More examples

You can find more examples in the project wiki, see L</WWW> for the
URLs.

=head1 FILES

=head2 ~/.ccliverc

This location is read by default. C<--config-file> may be used to specify
a different location. See also L</OPTIONS - CONFIGURATION>.

=head3 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

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

=head1 DEBUGGING TIPS

=head2 --verbose-libcurl

Make libcurl verbose.

=head1 WWW

 Home  : http://cclive.sourceforge.net/
 gitweb: http://repo.or.cz/w/cclive.git

=head1 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++.

=head1 LICENSE

cclive is Free Software, licensed under the GPLv3+.

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

=cut
