CLIVE(1)                                                              CLIVE(1)



NAME
       clive - video extraction tool


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

DESCRIPTION
       clive is a command line tool for extracting videos from Youtube, Google
       Video, Dailymotion, Guba (free), Stage6  and  Metacafe  websites.   The
       program  is written entirely in Python programming language making it a
       cross-platform tool.

       clive was originally written for Linux systems without the flash player
       plugin.  The  program can be chained with other tools like ‘ffmpeg’ and
       ‘vlc’ allowing subsequent video re-encoding and playing.

       Main features:

           - Video extraction
           - Integration and re-encoding with ‘ffmpeg’
           - Player integration with a 3rd party software


USAGE
       Basic extraction:

           % clive URL

       For example:

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

       You can also feed clive with multiple URLs at a time. This can be  done
       on command line, e.g.:

           % clive "http://..." "http://..."

       Or with Unix pipes, e.g.:

           % clive < file-containing-list-of-urls

       Or:

           % cat file-containing-list-of-urls | clive

       If  you feed clive with pipes, be sure to separate each URL with a new‐
       line, for example:

           http://youtube.com/watch?v=...
           http://video.google.com/videoplay?docid=...
           http://www.dailymotion.com/...
           http://www.guba.com/watch/...
           http://stage6.com/...

       It is possible to start clive without any URLs. This will switch  clive
       to  read standard input. While in this mode, you can enter URLs as long
       as you separate them with a newline. The console commands are available
       while in this mode, for a complete list of commands, type "help".

       clive  can  also  be integrated with system clipboard using the ‘xclip’
       command which may not be available on all systems by default. E.g.:

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

       As with pipes, be sure to separate each URL with a  newline.  Also,  be
       sure to use the "-o" option with ‘xclip’.


       Playback

       clive  can  be  chained  with  a  3rd  party software to play extracted
       videos, e.g.:

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

       The ‘--player’ defines a path to  a  player  program  executable  (e.g.
       ‘vlc’) with any program options. Please note that the "%i" (input file)
       identifier is required and replaced by clive.

       The ‘--play’ option tells clive to play the extracted video (src).


       Re-encoding

       clive can also be integrated with ‘ffmpeg’ to re-encode  the  extracted
       videos, e.g.:

           % clive --ffmpeg="/usr/bin/ffmpeg -y -i %i %o" --re-encode=mpg URL

       The  ‘--ffmpeg’  defines a path to ‘ffmpeg’ with any options. The above
       example would first extract the video from the URL and  then  re-encode
       it to MPEG format.

       The  use of the "-y" (overwrite existing output files) ffmpeg option is
       not needed but strongly recommended to avoid clive <->  ffmpeg  subpro‐
       cess hang ups.

       The  identifiers  "%i" (input file) and "%o" (output file) are required
       and replaced by clive.

       A more complete example of chaining clive features:

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

       The above chains all three features together:  extract,  re-encode  (to
       MPEG) and play (MPEG).


       Configuration file

       If  you  are running X, you may want to use the ‘--configure’ option to
       configure clive using the graphical user interface.

       ~/.clive/config.py:

       {
           "player":"/usr/bin/vlc %i",
           "play":"mpg",
           "ffmpeg":"/usr/bin/ffmpeg -y -i %i %o"

       }

       This would wrap the command line options we used earlier in the config‐
       uration file, allowing us to call:

           % clive URL

       Instead of:

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

       For  more details on the configuration file, please see the "CONFIG.PY"
       section of this document.


OPTIONS
       Standard output options:

       --quiet, -q
           Print messages to stdout only when absolutely needed.

       -e, --emit
           Print out a list of found video extraction URLs. Each URL
           line begins with "video:" which is followed by video details,
           each detail quoted and separated by a whitespace, e.g.:

               video: "url" "filename" "length"
               video: "url2" "filename2" "length2"
               ...

       --check-updates
           Check for updates. Will prompt for a download (source tarball)
           if a new version is available.

       --configure
           Configure using a graphical user interface. Uses the
           Tkinter module for Tk GUI toolkit.


       File output options:

       --overwrite, -o
           Overwrite already existing output files.

       --rename, -r
           Rename output file to be written if the file exists already.

       --prefix=PREFIX
           Write extracted video files to PREFIX. Defaults to the
           current directory.

       --output-file=FILE, -O FILE
           The videos will not be written to the appropriate files,
           but all will be written to FILE.

           Note that in batch mode with multiple URLs, an already
           existing file will be replaced by another.

       --output-mask=MASK
           Use regular expression (Python re.sub) to filter accepted
           characters in video page <title> to construct an output
           filename for the extracted video.

           The re.sub method documentation:
             http://docs.python.org/lib/node46.html

           For those interested, the re.sub method is called the
           following way:
             title = re.sub("[^%s]" % mask, "", title)

           clive defaults the "output mask" to "A-Za-z0-9" which translates
           roughly to: "accept only characters A..Z, a..z and 0..9 from the
           video page title". So for example, if the video page uses:

             ...
             <title>Uber video!!!! :))</title>
             ...

           The extracted video output filename would be: "Ubervideo.flv".

           User-defined output mask method

           While the default mask is often sufficient for most users,
           it also filters out many non-english characters from the
           output filenames. This may not always be suitable however.

           As of the release of 0.4.1 it is possible to write a user-defined
           output mask filtering method that will override the default
           behaviour.

           Step 1) Edit ~/.clive/userdef.py file (see examples below)
           Step 2) Call clive with --output-mask="<userdef>"

           ~/.clive/userdef.py: example

             # Return the title unchanged
             def userdef_output_mask(title):
                 return title

           ~/.clive/userdef.py: example #2

             # Incl. all but "!" and "?" characters in output filename
             import re

             def userdef_output_mask(title):
                 return re.sub("[!?]", "", title)

           There are not any other restrictions to the method than
           the name, the number of parameters and the returned value.

       --disable-mask, -M
           Disable output masking explicitly. This may often be the
           easiest way to keep the original video title intact.
           Beware of any O/S filename restrictions however.

       --output-fmt=FORMAT
           Set output filename format. Default is "%t.%e".
           The option supports the following string identifiers:

               %t = From page <title> after masking (see above)
               %e = Video file extension (e.g. ’flv’)
               %i = Video ID (e.g. ’grCTXGW3sxQ’)
               %h = Host (e.g. ’ytube’)


       Connection options:

       --proxy=PROXY
           Set PROXY as HTTP proxy. If this option is not used,
           the default environment settings (http_proxy environment
           variable) will be used instead.

           Example:
               --proxy=http://foo:1234

           Authentication information may be provided using
           normal URL constructs, e.g.:

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

       --user-agent=USER_AGENT
           Use AGENT as HTTP user-agent string.

           clive does not provide accurate HTTP user-agent header
           information. The string is randomly generated for each
           run-time of the program. You can use this option to
           override the default behaviour.

       --throttle=LIMIT
           Set transfer rate limit (KB/s), default is 0 (unlimited).

       --disable-gzip
           Disable gzip encoding for video page transfers.


       Playback options:

       --player=PATH
           Set PATH to player with any options.

           Example:
               --player="/usr/bin/vlc %i"

           NOTE: Be sure to use the "%i" (input file) identifier.
           clive will replace the identifier before calling the
           player executable.

       --play=PLAY, -p
           Play video (format) after extraction. Accepts "src"
           (extracted video), "mpg" and "avi". The last two values
           require ‘--ffmpeg’ option to be used.

       --disable-play
           Disable playback explicitly.


       Re-encoding options:

       --ffmpeg=PATH
           Set PATH to ffmpeg with any options. The use of ’-y’ option is
           strongly recommended.

           Example:
             --ffmpeg="/usr/bin/ffmpeg -y -i %i %o"

       --re-encode=FORMAT
           Re-encode video to FORMAT. Accepts "mpg" and "avi".

       --disable-encode
           Disable re-encoding explicitly.


       Clipboard options:

       --xclip=XCLIP
           Set path to xclip. The "-o" option must be used with xclip,
           for example:

             --xclip="/usr/bin/xclip -o"

       --from-clipb, -c
           Read/paste input from system clipboard. Requires the
           above option on unix systems.


       Logging options:

       --last, -l
           Recall URLs from the last run-time. Works only if
           logging was enabled previously. The last URL batch
           is saved as ~/.clive/last.log file. This option tells
           clive to read the URLs from that file.

       --history
           Browse extraction history using graphical user interface.
           Uses the Tkinter module for Tk GUI toolkit.

       --disable-log
           Disables all logging explicitly.

       --clear-logs
           Clears all log information from ~/.clive.


CONFIG.PY
       Example ~/.clive/config.py:

       {

         "verbose":0,
         "prefix":"/home/legatvs/videos",
         "overwrite":1,

         "proxy":"http://user:host@foo:1234",
         "user_agent":"foobar/1.0",
         "throttle":25,

         "player":"/usr/bin/vlc %i",
         "play":"src",

         "ffmpeg":"/usr/bin/ffmpeg -y -i %i %o",
         "re_encode":"mpg",

         "xclip":"/usr/bin/xclip -o",
         "from_clipb":0,

         "log":1,

       }

       You can get a complete list of supported variables by typing  "set"  in
       the console.

UPDATES
       For  the  latest  release  of  clive,  please use the ‘--check-updates’
       option or visit:

           http://home.gna.org/clive/

       The development trunk can be checked out with:

           % svn co svn://svn.gna.org/svn/clive/trunk clive

NOTES
       Supported websites

         - youtube.com [flv]
         - video.google.com (et al) [flv]
         - dailymotion.com [flv]
         - guba.com [flv]
         - stage6.com [avi]
         - metacafe.com [flv]


       URL "types"

         Video page URL

           Fed to clive which it will then visit looking for extraction
           URLs.

           Examples:
             http://youtube.com/watch?v=vt4X7zFfv4k
             http://www.guba.com/watch/3000003807
             http://video.google.com/videoplay?docid=-4505462782975458603

         Video extraction URL

           A direct download URL. Specific to a website. Irrelevant to
           an average clive user. You can use the ‘--emit’ option to
           print out these URLs.


       Resumed downloads

         This is website specific. Youtube and Google Video services
         ignore all standard HTTP requests to resume transfers. Other
         supported websites work with resumed transfers.

         clive will force the ‘--rename’ option for Youtube and
         Google Video websites due to the above HTTP restrictions.

         Please note that clive attempts to resume a transfer only if
         the local file length is less than the file length reported
         by the server.


       Print out extraction URLs

         The ‘--emit’ option may be used to print out the found video
         extraction URLs. The output is formatted accordingly:

           video: "extraction-url" "filename" "length"
           video: "extraction-url2" "filename2" "length2"
           (...)


       Youtube: flagged videos

         clive is currently unable to extract Youtube videos that
         have been flagged by users for their content and will
         only print out an "age verification" error if you attempt
         to extract them.


       Cookies

         clive does not accept any cookies from visited websites.
         This is also part of the reason why Youtube log in support
         was removed in the 0.3.0/nomad release.

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. For instance:

            - what operating system and version
            - what Python version
            - anything else you think is relevant

          * How to reproduce the bug

          * If the bug was a crash, the exact text that was printed
            out when the crash occurred

          * Further information such as the back trace if possible

COPYRIGHT
       Copyright (C) 2007-2008 Toni Gundogdu <legatvs@gmail.com>.

       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.



Toni Gundogdu                                                         CLIVE(1)
