cclive(1)
=========

NAME
----
cclive - media stream extraction tool

SYNOPSIS
--------
[verse]
'cclive' [OPTIONS] [URL|FILE ...]

DESCRIPTION
-----------
cclive is a command line tool for downloading media streams from YouTube
and similar websites.

INPUT
-----
The command will read stdin by default. The input is expected to contain
URLs. The command arguments are expected to be either URLs or file
paths. If the input is read from either stdin or a file, the contents
are read as RFC2483. The input may also contain URIs (file://) to local
files.

OPTIONS
-------

Core
~~~~

-b, --background::
  Go to background after startup. The output written to stdout
  will be written to the file specified with --log-file.

-F, --config-file <arg>::
  Read the program arguments from the specified file instead of the
  default ~/.ccliverc file. See also <<FILES>>.

-c, --continue::
  Resume partially downloaded media.
----
config:
  continue = {true|false}
----

-e, --exec <arg>::
  Invoke the specified command after each successfully finished
  download. The command is also invoked if the media is fully
  retrieved already. This option may be specified multiple times.
  See also <<EXAMPLES>>.
  +
  All occurences of the following sequences will be replaced
  in the 'arg':
----
  %f  .. Full path to the downloaded media file
  %n  .. Name of the downloaded media file
  %t  .. Unfiltered media title

config:
  exec = arg
----

-n, --no-download::
  Do not download the media, print the details only.

-s, --stream <ID>::
  Download the specified media stream. By default the program will get
  the 'default' stream. The stream selection with linkman:libquvi[3] 0.4
  is basic at most, whereas linkman:libquvi[3] 0.9+ provides a more
  advanced facility for this.
  +
  linkman:libquvi[3] 0.9+ treats the ID value as a regex PATTERN and
  matches it against the linkman:libquvi-scripts[7] returned media
  stream IDs. Additionally, the value of ID may be a 'comma-separated
  list' of regex PATTERNs.
  +
  In comparison, linkman:libquvi[3] 0.4 only checks whether the strings
  (the value of ID and the returned media stream ID) are equal.
  +
  The ID value may also contain the following reserved keywords:
+
- 'croak' - tell linkman:libquvi[3] (0.9+) to exit with an error
  when reached
- 'best'  - tell linkman:libquvi[3] to choose the best quality stream

+
The 'best' quality is determined by linkman:libquvi-scripts[7]. The
method varies, depending on the linkman:libquvi[3] version and the
website.
+
For example, linkman:libquvi-scripts[7] 0.9+ would typically compare the
media quality properties (e.g. the video height property). In reality,
the method will vary depending on the data provided by the media hosting
service, and the implementation of the support script that was written
for the website.
+
See the --version output to confirm whether cclive was built with
linkman:libquvi[3] 0.9 or later.  See also <<EXAMPLES>>.
----
config:
  stream = arg
----

-N, --timestamp::
  Try to preserve the file modification time (as returned by the server,
  if any). Using this option will cause the program to change the
  modification time of the file to that of returned by the server.
+
NOTE: libcurl will parse this value from the returned "Last-Modified"
      HTTP header. This header may not always be present in which case
      the program will quietly ignore this option.
----
config:
  timestamp = {true|false}
----

Informative
~~~~~~~~~~~

-h, --help::
  Print help and exit.

-S, --print-streams::
  Print the available media streams. The printed values (media stream
  IDs) may be used with --stream and --prefer-format options. The
  available streams are determined by linkman:libquvi[3] and
  linkman:libquvi-scripts[7].

-D, --print-config::
  Print the value of all defined configuration options to stdout.

-u, --support::
  Print the supported website domains and exit.

-v, --version::
  Print the program version and exit.

Output
~~~~~~

-f, --filename-format <arg>::
  Specify how the downloaded media file should be named. All occurences
  of the following sequences will be replaced in the 'arg':
----
  %t  .. Media title (after applying --tr)
  %s  .. Media file extension
  %i  .. Media ID
----
  The default value is "%t.%s".
----
config:
  filename-format = arg
----

-l, --log-file <arg>::
  Write log output to the specified file. The program will ignore this
  option value unless it is being used together with --background. The
  existing log file will be ovewritten. By default, the program will use
  "cclive_log" as the log file name.

-d, --output-dir <arg>::
  Write downloaded media to the specified directory. By default, the
  program will write the media to the current working directory.
----
config:
  output-dir = arg
----
  
-O, --output-file <arg>::
  Write media to the specified file. Overrides --filename-format.

-W, --overwrite::
  Overwrite existing media files.

-R, --progressbar <arg>::
  Use the progressbar of the specified type.  The program will ignore
  the value of this option with --background. The arg may be one of the
  following values:
  * dotline (also implied by --background)
  * normal (default)
  * simple
----
config:
  progressbar = arg
----

-q, --quiet::
  Turn off all output to stdout and stderr with the exception of
  --verbose-libcurl.

-t, --tr <arg>::
  Specify to translate the characters in the media titles before they
  are used in the media file names. The 'arg' is a regular expression
  pattern. The default value is "/(\w|\s)/g". This option may be
  specified multiple times. See also <<EXAMPLES>>.
----
config:
  tr = arg
----

-i, --update-interval <arg>::
  Specify the progressbar update interval in seconds. The default value
  is 1.
----
config:
  update-interval = arg
----

-B, --verbose-libcurl::
  Enable libcURL verbose output.

Network
~~~~~~~

-a, --agent <arg>::
  Identify cclive as 'arg' to the HTTP servers. The default value is
  "Mozilla/5.0".
----
config:
  agent = arg
----

-C, --connect-timeout <arg>::
  Maximum time in seconds that the program should allow the connection
  to the server to take. This only limits the connection phase, once it
  has connected, this option is no more of use. Set to 0 to disable
  connection timeout (it will then only timeout on the system's internal
  timeouts). The default is 30.
----
config:
  connect-time = arg
----

-A, --dns-cache-timeout <arg>::
  The name resolves will be kept in the memory for this number of
  seconds. Set to 0 to completely disable DNS caching, or to -1 to make
  the cached entries to remain in the memory forever. The default is 60.
----
config:
  dns-cache-timeout = arg
----

-m, --max-retries <arg>::
  Specify the number of downloading retries before giving up. Set to 0
  to disable. The default is 5.
  +
  Note that the program will skip retrying altogether if the server
  returned HTTP 400 (and over), or if linkman:libquvi[3] returned an
  unrecoverable error (e.g. missing linkman:libquvi-scripts[7]).
----
config:
  max-retries = arg
----

-X, --no-proxy::
  Disable use of HTTP proxy. Overrides --proxy and http_proxy environment
  settings.

-r, --no-resolve::
  Do not resolve HTTP URL redirections. Using this option will result in
  the program not being able to follow URL redirections which are often
  used by different URL shortening services.
  +
  When libquvi 0.9 or later is being used with cclive, this option will
  be ignored. The library will always resolve any URL redirections.  See
  --version output to see if cclive was compiled with libquvi 0.9+.
----
config:
  no-resolve = {true|false}
----

-x, --proxy I<arg>::
  Use the specified proxy address (e.g. http://foo:1234) for HTTP
  connections. By default, libcURL (which cclive and linkman:libquvi[3]
  use) will use the value of http_proxy. Using this option will override
  the http_proxy environment value.
  +
  See linkman:curl[1] for more information about the supported
  environment variables.
----
config:
  proxy = arg
----

-w, --retry-wait <arg>::
  Wait the specified number of seconds before retrying after a failed
  attempt. The default is 5. If the value is 0, the program will skip
  this step.
----
config:
  retry-wait = arg
----

-H, --throttle <arg>::
  Do not exceed the specified transfer rate (Ki/s). If 'arg' is 0
  (default), the throttling will be disabled.
----
config:
  throttle = arg
----

-T, --transfer-timeout <arg>::
  Maximum time in seconds that the program should allow the transfer
  operation to take. Normally, name lookups can take a considerable
  amount of time, and limiting operations to less than a few minutes
  will risk aborting perfectly normal operations. This option will cause
  libcURL to use the SIGALRM to enable the timeout system calls. The
  default is 0 (disabled).
----
config:
  transfer-timeout = arg
----

Deprecated
~~~~~~~~~~

These options will be removed eventually in the later versions of
cclive.

-p, --prefer-format <arg>::
  The '--stream' is intended to replace this option, eventually.  The
  stream selection will be provided by libquvi 0.9+. This was done
  previously by cclive. See also <<EXAMPLES>>.
  +
  Have the program choose the format (media stream) to download by
  matching the regular expression pattern match to the media URL as
  specified in the 'arg'.
  +
  This option may be specified multiple times. The use of --stream will
  override the rules specified using this option.
  +
  The 'arg' is a 'string pair' separated by a colon.  The 'string pair'
  consists of:
  * a regular expression pattern
  * format (media stream) to download
----
config:
  prefer-format = arg
----

[[EXAMPLES]]
EXAMPLES
--------

* Typical use:
+
----
$ cclive "URL"
----

* Query the available media streams:
+
----
$ cclive -S "URL"
----

* Download the best quality media stream:
+
----
$ cclive -s best "URL"
----

* With linkman:libquvi[3] 0.9+, you can pass a list of stream ID
  patterns to match:
+
----
$ cclive -s foo,baz,best "URL"
----
+
See the --stream description for more details.

* Replace all occurences of 'foo' with 'bar' in the media title before
  it is used in the media file name:
+
----
$ cclive -t 's/foo/bar/g' "URL"
----

* Go to background, redirect output to 'foo.log' file:
+
----
$ cclive -b --log-file foo.log "URL"
----

* Interrupt the current transfer of all of the matching processes,
  this (USR1) will cause cclive to move onto the next URL in the batch:
+
----
$ pkill -USR1 cclive
----

* Print the path to the downloaded media file using linkman:echo[1] and
  open the media file in linkman:totem[1]:
+
----
$ cclive --exec 'echo "%f"' --exec 'totem "%f"' "URL"
----

* Process a batch of media URLs:
+
----
$ cat URLs
http://foo
http://bar
http://baz
http://qux
$ cat URLs | cclive
$ cclive < URLs
$ cclive URLs
----

[[FILES]]
FILES
-----

~/.ccliverc::
  The program will read this location by default. A different location
  may be defined with --config-file.

Example
~~~~~~~

  prefer-format = ^.*youtube.*\.com:fmt43_360p
  prefer-format = dailym:best

  filename-format = %i_(%t).%s
  tr = /(\w)/g

  progressbar = simple
  continue = true

  proxy = http://foo:1234
  no-resolve = false

  exec = /usr/bin/totem %f

[[STREAMS]]
STREAMS
-------
The availability and the identification of the media streams is
determined by linkman:libquvi[3] and linkman:libquvi-scripts[7].

YouTube
~~~~~~~

linkman:libquvi-scripts[7] returns the media stream IDs containing the
'itag' value so that they can be referred to as such using the --stream
or --prefer-format options. The --print-streams may be used to get a
list of the available media streams.

libquvi-scripts 0.4::
  The 'fmt' prefix is used to identify the streams. For example:

    itag: 22
    quvi: fmt22_720p

libquvi-scripts 0.9 and later::
  The 'iXX' prefix is used in the media stream IDs. For example:

    itag: 22
    quvi: hd720_mp4_i22_720p

For more information about the YouTube video quality and codecs, visit
`http://en.wikipedia.org/wiki/YouTube#Quality_and_codecs`.

EXIT STATUS
-----------
The program will exit with EXIT_SUCCESS (on POSIX systems this is 0) on
success, and with EXIT_FAILURE (on POSIX systems this is 1) if an error
occurred.

FURTHER RESOURCES
-----------------
The development code may be cloned from `git://repo.or.cz/cclive.git`.
The gitweb is accessible at `http://repo.or.cz/w/cclive.git`.

Authors
-------
Toni Gundogdu <legatvs@gmail.com>::
  Author.

Reporting bugs
--------------
Report bugs to the cclive-devel mailing list
<cclive-devel@lists.sourceforge.net> where the development and the
maintenance is primarily done.  You do not have to be subscribed to the
list to send a message there.

LICENSE
-------
cclive is Free Software, licensed under the GNU Affero GPLv3+.

SEE ALSO
--------
linkman:libquvi-scripts[7], linkman:libquvi[3]
