CCLIVE(1)

📦 version 0.9.3, in debian bookworm, ubuntu jammy, ubuntu noble

okay bestie, welcome to the cclive(1) manual, aka the cclive Manual. it’s giving “media stream extraction tool” and we’re obsessed. 💖✨

🌸 NAME 🌸

cclive — media stream extraction tool

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

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

🌈 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 the section called “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 the section called “EXAMPLES”.

All occurrences 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 libquvi(3) 0.4 is basic at most, whereas libquvi(3) 0.9+ provides a more advanced facility for this.

libquvi(3) 0.9+ treats the ID value as a regex PATTERN and matches it against the libquvi-scripts(7) returned media stream IDs. Additionally, the value of ID may be a comma-separated list of regex PATTERNs.

In comparison, 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 libquvi(3) (0.9+) to exit with an error when reached
best — tell libquvi(3) to choose the best quality stream

The best quality is determined by libquvi-scripts(7). The method varies, depending on the libquvi(3) version and the website.

For example, 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 libquvi(3) 0.9 or later. See also the section called “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 libquvi(3) and 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 occurrences 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 overwritten. 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 the section called “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 libquvi(3) returned an unrecoverable error (e.g. missing 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 <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 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 the section called “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 ✨💖

Okay bestie, let's get into the examples. These are literally the vibes you need. 🫶

Typical use: the most basic slay, no cap:

$ cclive "URL"

Query the available media streams: like, see what's on the menu before you commit:

$ cclive -S "URL"

Download the best quality media stream: because you deserve the best, periodt:

$ cclive -s best "URL"

With libquvi(3) 0.9+, you can pass a list of stream ID patterns to match: it's giving choose-your-own-adventure, and we're obsessed:

$ cclive -s foo,baz,best "URL"

See the --stream description for more details. (iykyk)

Replace all occurences of foo with bar in the media title before it is used in the media file name: note: "occurences" is spelled that way in the original, so we keep it, fr fr:

$ cclive -t 's/foo/bar/g' "URL"

Go to background, redirect output to foo.log file: main character energy but make it quiet:

$ 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: dramatic but useful, like a plot twist:

$ pkill -USR1 cclive

Print the path to the downloaded media file using echo(1) and open the media file in totem(1): two --exec flags, because why not? slay:

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

Process a batch of media URLs: the way that you can just pipe and go, it's giving productivity:

$ cat URLs
http://foo
http://bar
http://baz
http://qux
$ cat URLs | cclive
$ cclive < URLs
$ cclive URLs

FILES 🎀

~/.ccliverc — The program will read this location by default. A different location may be defined with --config-file. (so you can move it if you want, lowkey flexible)

Example ✨

Here's what a config file might look like, bestie. Keep it cute:

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 🌈

The availability and the identification of the media streams is determined by libquvi(3) and libquvi-scripts(7). (so like, they're the real MVPs, no cap)

YouTube 💅

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. (got it? good.)

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. (ngl, that's a whole rabbit hole, but go off)

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. (so like, 0 is good vibes, 1 is not. fr fr)

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. (go touch grass, or clone the repo, whatever feels right)

AUTHORS 👑

Toni Gundogdu <legatvs@gmail.com> — Author. (the icon, the legend, the moment, we stan)

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. (so like, don't be shy, bestie, they want your feedback)

LICENSE 🫶

cclive is Free Software, licensed under the GNU Affero GPLv3+. (periodt, that's the tea)