Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CCLIVE(1)			 cclive	Manual			     CCLIVE(1)

       cclive -	media stream extraction	tool

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

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

       The program reads input from the	stdin by default. The arguments	may be
       either an URL or	a FILE.	When the input is read from either stdin or a
       FILE, the data is expected to be	a newline-separated list of URLs.

       --agent <arg>
	   Identify cclive as arg to the HTTP servers. The default value is

	     agent = arg

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

       -c, --continue
	   Resume partially downloaded media.

	     continue =	{true|false}

       -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

	       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.

	     timestamp = {true|false}

       --config-file <arg>
	   Read	the program arguments from the specified file instead of the
	   default ~/.ccliverc file. See also the section called "FILES".

       --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	the section called "EXAMPLES".

	   All occurences of the following sequences will be replaced in the

	     %f	 .. Full path to the downloaded	media file
	     %n	 .. Name of the	downloaded media file
	     %t	 .. Unfiltered media title

	     exec = arg

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

       -p, --prefer-format <arg>
	   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.	See also the
	   section called "EXAMPLES".

	   The arg is a	string pair separated by a colon. The string pair
	   consists of:

	   o   a regular expression pattern

	   o   format (media stream) to	download

	     prefer-format = arg

       -s,--stream <ID>
	   Download the	specified media	stream.	By default the program will
	   get the default stream. The ID may also be best, in which case
	   libquvi-scripts(7) will determine the best available	quality

       -h, --help
	   Print help and exit.

	   Print the license and exit.

       -S, --print-streams
	   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 libquvi(3) and libquvi-

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

	   o   dotline (also implied by	--background)

	   o   normal (default)

	   o   simple

	     progressbar = arg

	   Print the supported website domains and exit.

       --update-interval <arg>
	   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.

	     update-interval = arg

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

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

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

	     filename-format = arg

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

       --output-dir <arg>
	   Write downloaded media to the specified directory. By default, the
	   program will	write the media	to the current working directory.

	     output-dir	= arg

       -O, --output-file <arg>
	   Write media to the specified	file. Overrides	--filename-format.

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

       -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 the section called "EXAMPLES".

	     tr	= arg

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

       -W, --overwrite
	   Overwrite existing media files.

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

	     connect-time = arg

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

	     dns-cache-timeout = arg

	   Disable use of HTTP proxy. Overrides	--proxy	and http_proxy
	   environment settings.

       --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 libquvi(3) returned an
	   unrecoverable error (e.g. missing libquvi-scripts(7)).

	     max-retries = arg

       --retry-wait <arg>
	   Wait	the specified number of	seconds	before retrying	after a	failed
	   attempt. The	default	is 5.

	     retry-wait	= arg

       --proxy I<arg>
	   Use the specified proxy address (e.g.  http://foo:1234) for HTTP
	   connections.	By default, libcURL (which cclive and libquvi(3) use)
	   will	use the	value of http_proxy. Using this	option will override
	   the http_proxy environment value.

	   See curl(1) for more	information about the supported	environment

	     proxy = arg

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

	     no-resolve	= {true|false}

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

	     transfer-timeout =	arg

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

	     throttle =	arg

       -f, --format <ID>
	   Identical to	--stream. Deprecated as	of 0.7.12.

       -F, --query-formats
	   Identical to	--print-streams. Deprecated as of 0.7.12.

       --regexp	<arg>
	   Specify the regular expression pattern to cleanup the media title
	   before it is	used to	format the media file name. The	specifiers g
	   and i are supported.	Use --tr, instead.

       --subst <arg>
	   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 g	and i are supported. Use --tr,

	   Supported delimiters: <> {} () /

	   Note	that s/old/new/	is invalid, whereas s/old//new/	is accepted.

       As a general rule of thumb: always put the URLs inside quotes. You can
       find more examples at

       o   Typical use:

	       $ cclive	"URL"

       o   Query the available media streams:

	       $ cclive	-S "URL"

       o   Download the	best quality media stream:

	       $ cclive	-s best	"URL"

       o   Get the YouTube itag	43 format whenever possible:

	       # Save 'prefer-format' permanently to ~/.ccliverc file.
	       $ echo "prefer-format = ^.*youtube.*\.com:fmt43_360p" \
			 >> ~/.ccliverc"

	       # The above would cause the program to try to get fmt43_360p
	       # with media  URLs of 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"

       See also	the section called "STREAMS".

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

       o   Go to background, redirect output to	foo.log	file:

	       $ cclive	-b --log-file foo.log "URL"

       o   Interrupt the current transfer of all of the	matching processes,
	   this	(USR1) will cause cclive to move onto the next URL in the

	       $ pkill -USR1 cclive

       o   Print the path to the downloaded media file using echo(1) and open
	   the media file in totem(1):

	       $ cclive	--exec 'echo "%f"' --exec 'totem "%f"' "URL"

       o   Process a batch of media URLs:

	       $ cat URLs
	       $ cat URLs | cclive
	       $ cclive	< URLs
	       $ cclive	URLs

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

	   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

       The availability	and the	identification of the media streams is
       determined by libquvi(3)	and libquvi-scripts(7).

       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

       For more	information about the YouTube video quality and	codecs,	visit

       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

       The development code may	be cloned from git://
       The gitweb is accessible	at

       Toni Gundogdu <>

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

       cclive is Free Software licensed	under the GNU GPLv3+

       libquvi-scripts(7), libquvi(3)

cclive 0.7.16			  09/14/2013			     CCLIVE(1)


Want to link to this manual page? Use this URL:

home | help