'\" t
.\"     Title: cclive
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 11/23/2013
.\"    Manual: cclive Manual
.\"    Source: cclive 0.9.3
.\"  Language: English
.\"
.TH "CCLIVE" "1" "11/23/2013" "cclive 0\&.9\&.3" "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 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\&.
.SH "OPTIONS"
.SS "Core"
.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
\-F, \-\-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
\-c, \-\-continue
.RS 4
Resume partially downloaded media\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  continue = {true|false}
.fi
.if n \{\
.RE
.\}
.PP
\-e, \-\-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
\-s, \-\-stream <ID>
.RS 4
Download the specified media stream\&. By default the program will get the
\fIdefault\fR
stream\&. The stream selection with
\fBlibquvi\fR(3)
0\&.4 is basic at most, whereas
\fBlibquvi\fR(3)
0\&.9+ provides a more advanced facility for this\&.

\fBlibquvi\fR(3)
0\&.9+ treats the ID value as a regex PATTERN and matches it against the
\fBlibquvi-scripts\fR(7)
returned media stream IDs\&. Additionally, the value of ID may be a
\fIcomma\-separated list\fR
of regex PATTERNs\&.

In comparison,
\fBlibquvi\fR(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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fIcroak\fR
\- tell
\fBlibquvi\fR(3)
(0\&.9+) to exit with an error when reached
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fIbest\fR
\- tell
\fBlibquvi\fR(3)
to choose the best quality stream
.RE
.sp
The
\fIbest\fR
quality is determined by
\fBlibquvi-scripts\fR(7)\&. The method varies, depending on the
\fBlibquvi\fR(3)
version and the website\&.
.sp
For example,
\fBlibquvi-scripts\fR(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\&.
.sp
See the \-\-version output to confirm whether cclive was built with
\fBlibquvi\fR(3)
0\&.9 or later\&. See also
the section called \(lqEXAMPLES\(rq\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  stream = arg
.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
.\}
.SS "Informative"
.PP
\-h, \-\-help
.RS 4
Print help and exit\&.
.RE
.PP
\-S, \-\-print\-streams
.RS 4
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
\fBlibquvi\fR(3)
and
\fBlibquvi-scripts\fR(7)\&.
.RE
.PP
\-D, \-\-print\-config
.RS 4
Print the value of all defined configuration options to stdout\&.
.RE
.PP
\-u, \-\-support
.RS 4
Print the supported website domains and exit\&.
.RE
.PP
\-v, \-\-version
.RS 4
Print the program version and exit\&.
.RE
.SS "Output"
.PP
\-f, \-\-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
\-l, \-\-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
\-d, \-\-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
\-W, \-\-overwrite
.RS 4
Overwrite existing media files\&.
.RE
.PP
\-R, \-\-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
\-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
\-i, \-\-update\-interval <arg>
.RS 4
Specify the progressbar update interval in seconds\&. The default value is 1\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  update\-interval = arg
.fi
.if n \{\
.RE
.\}
.PP
\-B, \-\-verbose\-libcurl
.RS 4
Enable libcURL verbose output\&.
.RE
.SS "Network"
.PP
\-a, \-\-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
\-C, \-\-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
\-A, \-\-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
\-m, \-\-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
\-X, \-\-no\-proxy
.RS 4
Disable use of HTTP proxy\&. Overrides \-\-proxy and http_proxy environment settings\&.
.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\&.

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+\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  no\-resolve = {true|false}
.fi
.if n \{\
.RE
.\}
.PP
\-x, \-\-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
\-w, \-\-retry\-wait <arg>
.RS 4
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\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
config:
  retry\-wait = arg
.fi
.if n \{\
.RE
.\}
.PP
\-H, \-\-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
.\}
.PP
\-T, \-\-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
.\}
.SS "Deprecated"
.sp
These options will be removed eventually in the later versions of cclive\&.
.PP
\-p, \-\-prefer\-format <arg>
.RS 4
The
\fI\-\-stream\fR
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
the section called \(lqEXAMPLES\(rq\&.

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

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
.\}
.SH "EXAMPLES"
.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
.\}
With
\fBlibquvi\fR(3)
0\&.9+, you can pass a list of stream ID patterns to match:
.sp
.if n \{\
.RS 4
.\}
.nf
$ cclive \-s foo,baz,best "URL"
.fi
.if n \{\
.RE
.\}
.sp
See the \-\-stream description for more details\&.
.RE
.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
.PP
libquvi\-scripts 0\&.9 and later
.RS 4
The
\fIiXX\fR
prefix is used in the media stream IDs\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
itag: 22
quvi: hd720_mp4_i22_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 Affero GPLv3+\&.
.SH "SEE ALSO"
.sp
\fBlibquvi-scripts\fR(7), \fBlibquvi\fR(3)