CLIVE(1)

NAME
clive - Video extraction tool

SYNOPSIS
clive [OPTION]... [URL]...

DESCRIPTION
clive is a video extraction tool for user-uploaded video hosts such as Youtube, Google Video, Dailymotion, Guba and Metacafe. It can be chained with 3rd party tools for subsequent video re-encoding and playing.

GETTING STARTED
Typical use:

    % clive "http://youtube.com/watch?v=VlFGTtU65Xo"

URLs can also be fed to clive using UNIX pipes.

    % cat url.lst | clive

Or directly from the X clipboard with the help of the "xclip" program.

    % clive --xclip="/usr/bin/xclip -o" --paste

Note that when the URLs must be separated with newlines when they are being fed to clive.

Playing

    % clive --player="/usr/bin/vlc %i" --play=src URL

The above first extracts the video and plays it with vlc. Note the use of the "%i" specifier for "input file".

Re-encoding

    % clive --ffmpeg="/usr/bin/ffmpeg -y -i %i %o" \
    --reencode=mpg URL

Note the use of the "%i" and "%o" (output file) specifiers. The "-y" option is not required but recommended to avoid subprocess (STDIN) issues with ffmpeg.

Chaining

    % clive --player="/usr/bin/vlc %i" --play=mpg \
    --ffmpeg="/usr/bin/ffmpeg -y -i %i %o" URL

clive would first extract the video, call ffmpeg to re-encode it to MPEG and subprocess vlc to play the MPEG.

Configuration file

You can generate the ~/.clive/config file with the --write-conf option and then edit the file manually. For example:

~/.clive/config:
    play_format="mpg"
    path_player="/usr/bin/vlc %i"
    path_ffmpeg="/usr/bin/ffmpeg -y %i %o"

With the above configuration file, you could run:

    % clive URL

Instead of:

    % clive --player="/usr/bin/vlc %i" --play=mpg \
    --ffmpeg="/usr/bin/ffmpeg -y -i %i %o" URL

OPTIONS

--version
    This causes clive to print a version number to the standard output.

--help
    This causes clive to print out a verbose message describing its options, one per line.

-n, --no-extract
    clive will not actually download any videos but prints out the video output file name and length.

    config: enable_extract

-u, --check-update
    The program will check http://download.gna.org/clive for the latest release and prompts if a new version is available.

-w, --write-conf
    Generates a "template" configuration file (~/.clive/config) with some comments and a complete list of supported commands. Autodetects also some of the 3rd party programs such as ffmpeg.

-L, --low-quality
    Explicitly extract low quality videos even if better quality are available.

    config: enable_low_quality

-R, --no-recall
    Explicitly turn off writing the URL batch to ~/.clive/recall file which could otherwise be reused later with the -l option.

    config: enable_recall

-q, --quiet
    Be less verbose.

    config: enable_verbose

-e, --emit-csv
    Similar to --no-extract but prints out the video information in CSV format:

       OK: "url","extraction-url","output-filename","file-length" ERROR: "url","error-message"

-l, --recall
    Recall last saved URL batch from ~/.clive/recall file.

-C, --no-cache
    Explicitly turn off all caching features. clive will not read or write cache.

    clive stores information about visited video pages over time which it then attempts to reuse as needed (e.g. continuing an interrupted transfer). The data is collected to ~/.clive/cache file which is a SQLite database. This feature is turned off if the sqlite3 module is not found.

    Some hosts have their extraction URLs expire after awhile. For example Youtube URLs expire after about 1hr and 40min (at the time of writing this), whereas Dailymotion URLs expire after only 2min. clive attempts to keep track of the time and revisits the video page as needed.

    HTTP/410 or HTTP/403 errors may be indication of expired extraction URLs. To verify this, try disabling the cache (--no-cache).

    The cache can be cleared by removing the ~/.clive/cache file.

    config: enable_cache

-F, --rss
    Causes clive to treat the URLs as RSS/Atom feed URLs. Designed to be used with video host feeds. Parses and displays found videos available for extraction.

    config: url_feed

Output Options

-s PATH, --savedir=PATH
    Specifies the save directory for the downloaded video files.

    config: output_savedir

-a ACTION, --exist=ACTION [overwrite|rename]
    Action if local_file < remote_file or if the host does not support continuing partially downloaded files. clive will always attempt to continue a partially downloaded file first and if that fails only then fallback to the preferred "action".

    When "rename" is used, clive will generate a new output filename for the downloaded video rather than rename the existing file. The generated output file name will contain the original filename and a random string appended to it.

    config: output_if_file_exists

-o FILENAME, --output=FILENAME
    Specifies an output filename for the downloaded video file. Overrides the default file naming scheme. Should be used with only single video extractions.

-m MASK, --mask=MASK
    Specifies the mask used with the (Python) re.sub method which is used to filter out any "unwanted" characters from the video page <title> HTML tag. The filtered title will then be used to construct an output file name for the extracted video.

    Note that the re.sub method takes a regexp value. The default value used for this option is "A-Za-z0-9". To get a better idea how to use this option, please read the Python documentation for re.sub at:
    http://docs.python.org/lib/node46.html

    The method in question is being called in the clive source code like so:
    re.sub('[^%s]' % mask, '', title)

    You can also write your own method that overrides the default filter altogether. You will first need to create the file ~/.clive/custom.py and implement the method "custom_output_mask" in it. After this, you can run clive with the option "--mask=custom".

    Example ~/.clive/custom.py:

    import re def custom_output_mask(title):
        # Filter out all but A-Z, a-z from the title
        title = re.sub('[^A-Za-z]', '', title)
        # Then return the title in lower case
        return title.lower()

    config: output_title_mask

-f FORMAT, --format=FORMAT
    Specifies the output filename format. The default is "%t.%e". The available specifiers: "%t" (title), "%e" (extension), "%i" (video ID) and "%h" (host).

    config: output_filename_format

Connection Options

-y PROXY, --proxy=PROXY
    Sets the HTTP proxy. If this option is not used, the default environment settings (http_proxy variable) will be used instead. Authentication information may be provided using normal URL constructs:

    --proxy=http://user:host@foo:1234

    config: http_proxy

-t LIMIT, --throttle=LIMIT
    This causes clive to throttle down the bandwidth use for transfers. For example:

    % clive --throttle=100 URL

    Would limit the transfer rate to 100KB/s. The default is 0 (unlimited).

    config: http_throttle

-g STRING, --agent=STRING
    Sets HTTP user-agent string. Defaults to a random string generated for each runtime.

    config: http_agent

--youtube-user=USERNAME
    See below.

    config: youtube_id

--youtube-pass=PASSWORD
    When used together with the --youtube-user option, clive will log into Youtube.com. clive will also automatically confirm the user's age so that it is possible to extract also flagged video content from Youtube.

    Note that clive will not log in unless the URL batch contains a Youtube video page URL.

    Cache may sometimes interfere with this feature. Try disabling the cache if you are running into any odditities.

    config: youtube_password

--dmotion-user=USERNAME
    See below.

    config: dmotion_id

--dmotion-pass=PASSWORD
    Similar to the Youtube equivalent above but for Dailymotion.

    config: dmotion_password

Playback Options

--player=PATH
    Specifies path to a player program. The "%i" must be appended to the path. Any player options may be appended to the path string along with the specifier. For example:

    % clive --player="/usr/local/bin/vlc --fullscreen %i"

    config: path_player

-p FORMAT, --play=FORMAT
    Specifies the video format that clive should play. Apart from using "src" which refers to the original downloaded video file, it can be anything that ffmpeg recognizes. Some examples: "mpg", "avi", "mp4".

    Note that using anything else than "src" will require "--ffmpeg". The video is first re-encoded to the specified FORMAT and then played.

    config: play_format

Re-encoding Options

--ffmpeg=PATH
    Specifies the path to ffmpeg with any options you want to pass to it. For example:

    % clive --ffmpeg="/usr/local/bin/ffmpeg -y -i %i %o"

    Both "%i" and "%o" specifiers are required. The "-y" option is recommended to avoid any subprocess STDIN issues with ffmpeg.

    config: path_ffmpeg

-r FORMAT, --reencode=FORMAT
    This causes clive to call ffmpeg to re-encode the downloaded video to another FORMAT. The FORMAT can be anything as long as ffmpeg recognizes it.

    Note that if "--play" is being used and the value is other than "src", you don't need to use this option. For example:

    % clive --play=mpg URL

    config: reencode_format

Clipboard Options

--xclip=PATH
    Specifies the path to xclip program. Note that the "-o" option needs to be appended to the path. For example:

    % clive --xclip="/usr/bin/xclip -o" --paste

    config: path_xclip

-x, --paste
    This causes clive to read URLs from the clipboard using xclip.

    config: enable_paste

HOSTS

youtube.com
    Format: mp4/flv
    Resume: Yes (mp4 only)

clive defaults to extract the better quality video (480x270, mp4) but extracts the low quality video (flv) if mp4 is not found or if the --low-quality option is being used.

video.google.*
    Format: mp4/flv
    Resume: Yes (mp4 only)

clive defaults to extract the better quality video (mp4) but extracts the low quality (flv) if mp4 is not found or if the --low-quality option is being used.

dailymotion.com
    Format: varies
    Resume: Yes

clive defaults to the highest quality video available but extracts the 320x240 video (flv) if no better quality is found or if the --low-quality option is being used.

guba.com
    Format: flv
    Resume: Yes

metacafe.com
    Format: flv
    Resume: Yes

last.fm
    Format: (youtube.com)
    Resume: (youtube.com)

Jzalae: "Last.fm recently added a video feature which appears to be a simple wrapping of YouTube videos, and the YouTube id appears in the Last.fm URL. The attached patch finds it from URLs like http://www.last.fm/music/Sylver/+videos/+1-fVD2TfSGkaw"

UPDATES
Website: http://home.gna.org/clive/ Or
    % svn co svn://svn.gna.org/svn/clive/trunk

BUG REPORTS
Bugs should be reported to the clive bug tracking system at:

    https://gna.org/bugs/?func=additem&group=clive

In the bug report, please include:

    * Information about your system (O/S, Python, anything else)
    * How to reproduce the bug
    * If the bug was a crash, the exact text that was printed out
    * Further information such as the back trace if possible

COPYRIGHT
Copyright (C) 2007-2008 Toni Gundogdu <legatvsgmailcom>. clive comes with NO WARRANTY, to the extent permitted by law. You may redistribute copies of clive under the terms of the GNU General Public License. For more information about these matters, see the files named COPYING.