'\" t
.\"     Title: cclive
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 09/14/2013
.\"    Manual: cclive Manual
.\"    Source: cclive 0.7.16
.\"  Language: English
.\"
.TH "CCLIVE" "1" "09/14/2013" "cclive 0\&.7\&.16" "cclive Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
cclive \- media stream extraction tool
.SH "SYNOPSIS"
.sp
.nf
\fIcclive\fR [OPTIONS] [URL|FILE \&...]
.fi
.SH "DESCRIPTION"
.sp
cclive is a command line tool for downloading media streams from YouTube and similar websites\&.
.SH "INPUT"
.sp
The program reads input from the \fIstdin\fR by default\&. The arguments may be either an \fIURL\fR or a \fIFILE\fR\&. When the input is read from either \fIstdin\fR or a \fIFILE\fR, the data is expected to be a newline\-separated list of URLs\&.
.SH "OPTIONS"
.SS "Core"
.PP
\-\-agent <arg>
.RS 4
Identify cclive as
\fIarg\fR
to the HTTP servers\&. The default value is "Mozilla/5\&.0"\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  agent = arg
.fi
.if n \{\
.RE
.\}
.PP
\-b, \-\-background
.RS 4
Go to background after startup\&. The output written to stdout will be written to the file specified with \-\-log\-file\&.
.RE
.PP
\-c, \-\-continue
.RS 4
Resume partially downloaded media\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  continue = {true|false}
.fi
.if n \{\
.RE
.\}
.PP
\-N, \-\-timestamp
.RS 4
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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
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\&.
.sp .5v
.RE
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  timestamp = {true|false}
.fi
.if n \{\
.RE
.\}
.PP
\-\-config\-file <arg>
.RS 4
Read the program arguments from the specified file instead of the default ~/\&.ccliverc file\&. See also
the section called \(lqFILES\(rq\&.
.RE
.PP
\-\-exec <arg>
.RS 4
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
the section called \(lqEXAMPLES\(rq\&.

All occurences of the following sequences will be replaced in the
\fIarg\fR:
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
  %f  \&.\&. Full path to the downloaded media file
  %n  \&.\&. Name of the downloaded media file
  %t  \&.\&. Unfiltered media title

config:
  exec = arg
.fi
.if n \{\
.RE
.\}
.PP
\-n, \-\-no\-download
.RS 4
Do not download the media, print the details only\&.
.RE
.PP
\-p, \-\-prefer\-format <arg>
.RS 4
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
\fIarg\fR\&.

This option may be specified multiple times\&. The use of \-\-stream will override the rules specified using this option\&. See also
the section called \(lqEXAMPLES\(rq\&.

The
\fIarg\fR
is a
\fIstring pair\fR
separated by a colon\&. The
\fIstring pair\fR
consists of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a regular expression pattern
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
format (media stream) to download
.RE
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  prefer\-format = arg
.fi
.if n \{\
.RE
.\}
.PP
\-s,\-\-stream <ID>
.RS 4
Download the specified media stream\&. By default the program will get the
\fIdefault\fR
stream\&. The ID may also be
\fIbest\fR, in which case
\fBlibquvi-scripts\fR(7)
will determine the best available quality stream\&.
.RE
.SS "Informative"
.PP
\-h, \-\-help
.RS 4
Print help and exit\&.
.RE
.PP
\-\-license
.RS 4
Print the license and exit\&.
.RE
.PP
\-S, \-\-print\-streams
.RS 4
Query 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
\fBlibquvi\fR(3)
and
\fBlibquvi-scripts\fR(7)\&.
.RE
.PP
\-\-progressbar <arg>
.RS 4
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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
dotline (also implied by \-\-background)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
normal (default)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
simple
.RE
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  progressbar = arg
.fi
.if n \{\
.RE
.\}
.PP
\-\-support
.RS 4
Print the supported website domains and exit\&.
.RE
.PP
\-\-update\-interval <arg>
.RS 4
Specify the progressbar update interval in seconds\&. Use of decimal fractions (e\&.g\&. "0\&.2") is acceptable\&. The program will use the default value 1\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  update\-interval = arg
.fi
.if n \{\
.RE
.\}
.PP
\-D, \-\-print\-config
.RS 4
Print the value of all defined configuration options to stdout\&.
.RE
.PP
\-v, \-\-version
.RS 4
Print the program version and exit\&.
.RE
.SS "Output"
.PP
\-\-filename\-format <arg>
.RS 4
Specify how the downloaded media file should be named\&. All occurences of the following sequences will be replaced in the
\fIarg\fR:
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
  %t  \&.\&. Media title (after applying \-\-tr)
  %s  \&.\&. Media file extension
  %i  \&.\&. Media ID
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The default value is "%t\&.%s"\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  filename\-format = arg
.fi
.if n \{\
.RE
.\}
.PP
\-\-log\-file <arg>
.RS 4
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\&.
.RE
.PP
\-\-output\-dir <arg>
.RS 4
Write downloaded media to the specified directory\&. By default, the program will write the media to the current working directory\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  output\-dir = arg
.fi
.if n \{\
.RE
.\}
.PP
\-O, \-\-output\-file <arg>
.RS 4
Write media to the specified file\&. Overrides \-\-filename\-format\&.
.RE
.PP
\-q, \-\-quiet
.RS 4
Turn off all output to stdout and stderr with the exception of \-\-verbose\-libcurl\&.
.RE
.PP
\-t, \-\-tr <arg>
.RS 4
Specify to translate the characters in the media titles before they are used in the media file names\&. The
\fIarg\fR
is a regular expression pattern\&. The default value is "/(\ew|\es)/g"\&. This option may be specified multiple times\&. See also
the section called \(lqEXAMPLES\(rq\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  tr = arg
.fi
.if n \{\
.RE
.\}
.PP
\-B, \-\-verbose\-libcurl
.RS 4
Enable libcURL verbose output\&.
.RE
.PP
\-W, \-\-overwrite
.RS 4
Overwrite existing media files\&.
.RE
.SS "Network"
.PP
\-\-connect\-timeout <arg>
.RS 4
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\(cqs internal timeouts)\&. The default is 30\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  connect\-time = arg
.fi
.if n \{\
.RE
.\}
.PP
\-\-dns\-cache\-timeout <arg>
.RS 4
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\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  dns\-cache\-timeout = arg
.fi
.if n \{\
.RE
.\}
.PP
\-\-no\-proxy
.RS 4
Disable use of HTTP proxy\&. Overrides \-\-proxy and http_proxy environment settings\&.
.RE
.PP
\-\-max\-retries <arg>
.RS 4
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
\fBlibquvi\fR(3)
returned an unrecoverable error (e\&.g\&. missing
\fBlibquvi-scripts\fR(7))\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  max\-retries = arg
.fi
.if n \{\
.RE
.\}
.PP
\-\-retry\-wait <arg>
.RS 4
Wait the specified number of seconds before retrying after a failed attempt\&. The default is 5\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  retry\-wait = arg
.fi
.if n \{\
.RE
.\}
.PP
\-\-proxy I<arg>
.RS 4
Use the specified proxy address (e\&.g\&.
http://foo:1234) for HTTP connections\&. By default, libcURL (which cclive and
\fBlibquvi\fR(3)
use) will use the value of http_proxy\&. Using this option will override the http_proxy environment value\&.

See
\fBcurl\fR(1)
for more information about the supported environment variables\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  proxy = arg
.fi
.if n \{\
.RE
.\}
.PP
\-r, \-\-no\-resolve
.RS 4
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\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  no\-resolve = {true|false}
.fi
.if n \{\
.RE
.\}
.PP
\-\-transfer\-timeout <arg>
.RS 4
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)\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  transfer\-timeout = arg
.fi
.if n \{\
.RE
.\}
.PP
\-\-throttle <arg>
.RS 4
Do not exceed the specified transfer rate (Ki/s)\&. If
\fIarg\fR
is 0 (default), the throttling will be disabled\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  throttle = arg
.fi
.if n \{\
.RE
.\}
.SS "Deprecated"
.PP
\-f, \-\-format <ID>
.RS 4
Identical to \-\-stream\&. Deprecated as of 0\&.7\&.12\&.
.RE
.PP
\-F, \-\-query\-formats
.RS 4
Identical to \-\-print\-streams\&. Deprecated as of 0\&.7\&.12\&.
.RE
.PP
\-\-regexp <arg>
.RS 4
Specify the regular expression pattern to cleanup the media title before it is used to format the media file name\&. The specifiers
\fIg\fR
and
\fIi\fR
are supported\&. Use \-\-tr, instead\&.
.RE
.PP
\-\-subst <arg>
.RS 4
Replace the matched occurences in the media file name\&. This option may not be specified multiple times: to specify multiple substitutions, separate each regular expression pattern with a whitespace\&. The specifiers
\fIg\fR
and
\fIi\fR
are supported\&. Use \-\-tr, instead\&.

Supported delimiters: <> {} () /

Note that
\fIs/old/new/\fR
is invalid, whereas
\fIs/old//new/\fR
is accepted\&.
.RE
.SH "EXAMPLES"
.sp
As a general rule of thumb: always put the URLs inside quotes\&. You can find more examples at \fIhttp://cclive\&.sourceforge\&.net/\fR\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Typical use:
.sp
.if n \{\
.RS 4
.\}
.nf
$ cclive "URL"
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Query the available media streams:
.sp
.if n \{\
.RS 4
.\}
.nf
$ cclive \-S "URL"
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Download the best quality media stream:
.sp
.if n \{\
.RS 4
.\}
.nf
$ cclive \-s best "URL"
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Get the YouTube itag 43 format whenever possible:
.sp
.if n \{\
.RS 4
.\}
.nf
# Save \*(Aqprefer\-format\*(Aq permanently to ~/\&.ccliverc file\&.
$ echo "prefer\-format = ^\&.*youtube\&.*\e\&.com:fmt43_360p" \e
          >> ~/\&.ccliverc"

# The above would cause the program to try to get fmt43_360p
# with media  URLs of http://youtube\&.com/ if available\&.
$ cclive "YOUTUBE_URL"

# Using of \-\-stream will override the \-\-prefer\-format
# setting\&.  Get fmt22_720p (if available)\&.
$ cclive \-s fmt22_720p "YOUTUBE_URL"
.fi
.if n \{\
.RE
.\}
.RE
.sp
See also the section called \(lqSTREAMS\(rq\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Replace all occurences of
\fIfoo\fR
with
\fIbar\fR
in the media title before it is used in the media file name:
.sp
.if n \{\
.RS 4
.\}
.nf
$ cclive \-t \*(Aqs/foo/bar/g\*(Aq "URL"
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Go to background, redirect output to
\fIfoo\&.log\fR
file:
.sp
.if n \{\
.RS 4
.\}
.nf
$ cclive \-b \-\-log\-file foo\&.log "URL"
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Interrupt the current transfer of all of the matching processes, this (USR1) will cause cclive to move onto the next URL in the batch:
.sp
.if n \{\
.RS 4
.\}
.nf
$ pkill \-USR1 cclive
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Print the path to the downloaded media file using
\fBecho\fR(1)
and open the media file in
\fBtotem\fR(1):
.sp
.if n \{\
.RS 4
.\}
.nf
$ cclive \-\-exec \*(Aqecho "%f"\*(Aq \-\-exec \*(Aqtotem "%f"\*(Aq "URL"
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Process a batch of media URLs:
.sp
.if n \{\
.RS 4
.\}
.nf
$ cat URLs
http://foo
http://bar
http://baz
http://qux
$ cat URLs | cclive
$ cclive < URLs
$ cclive URLs
.fi
.if n \{\
.RE
.\}
.RE
.SH "FILES"
.PP
~/\&.ccliverc
.RS 4
The program will read this location by default\&. A different location may be defined with \-\-config\-file\&.
.RE
.SS "Example"
.sp
.if n \{\
.RS 4
.\}
.nf
prefer\-format = ^\&.*youtube\&.*\e\&.com:fmt43_360p
prefer\-format = dailym:best
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
filename\-format = %i_(%t)\&.%s
tr = /(\ew)/g
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
progressbar = simple
continue = true
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
proxy = http://foo:1234
no\-resolve = false
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
exec = /usr/bin/totem %f
.fi
.if n \{\
.RE
.\}
.SH "STREAMS"
.sp
The availability and the identification of the media streams is determined by \fBlibquvi\fR(3) and \fBlibquvi-scripts\fR(7)\&.
.SS "YouTube"
.sp
\fBlibquvi-scripts\fR(7) returns the media stream IDs containing the \fIitag\fR 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\&.
.PP
libquvi\-scripts 0\&.4
.RS 4
The
\fIfmt\fR
prefix is used to identify the streams\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
itag: 22
quvi: fmt22_720p
.fi
.if n \{\
.RE
.\}
.RE
.sp
For more information about the YouTube video quality and codecs, visit http://en\&.wikipedia\&.org/wiki/YouTube#Quality_and_codecs\&.
.SH "EXIT STATUS"
.sp
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\&.
.SH "FURTHER RESOURCES"
.sp
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\&.
.SH "AUTHORS"
.PP
Toni Gundogdu <legatvs@gmail\&.com>
.RS 4
Author\&.
.RE
.SH "REPORTING BUGS"
.sp
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\&.
.SH "LICENSE"
.sp
cclive is Free Software licensed under the GNU GPLv3+
.SH "SEE ALSO"
.sp
\fBlibquvi-scripts\fR(7), \fBlibquvi\fR(3)