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

       The  specifiers  "%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

       clive  reads the runtime configuration file when the program starts and
       the file exists. You can edit the file manually using a text editor.

       Users who want to edit the file manually, may want run clive  with  the
       ‘--conf-write’  option  (new  in 0.4.4) to write the configuration file
       with a complete list of supported variables/keys.

       Note that users running X may run the program  with  the  ‘--configure’
       option to edit the file using the graphical user interface instead.

       ~/.clive/config.py:

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

       }

       With the above configuration file, you could now call:

           % clive URL

       Instead of:

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

OPTIONS
       --simulate, -s
           Simulate only, do not extract any videos.

       --emit, -e
           Print out found extraction urls only. Be sure to
           read the NOTES section of this manual page for details.

       --quiet, -q
           Pipe down printing to stdout.

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

       --conf-write
           (Re)write configuration file ~/.clive/config.py with
           default program values. This may be useful for those
           users who prefer to edit the file manually as it lists
           also all of the supported configuration variables/keys.

       --check-updates
           Check for updates. Prompts to download the new source
           code tarball if a new release is available.


       Output

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

       --rename, -r
           Rename (give new) output filename if the file exists already.
           The format is: (title)-(random-string)-(timestamp).(extension)

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

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


           Customizing

           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.

           As of the release of 0.4.1 it is possible to write a user-defined
           output mask 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:

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

           ~/.clive/userdef.py:

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

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

           The only limitations to the method are the name of the
           method, the number of the parameters and the return value.

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

               %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’)

       --no-mask
           Explicitly turn off masking. Tells clive to use the video
           page <title> unfiltered, keeping the original title intact.
           Beware of any O/S filenaming restrictions.


       Connection

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

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

           Authentication information may be provided using
           normal URL constructs.

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

       --user-agent=USER_AGENT
           Set HTTP user-agent.

           Note that clive does not provide accurate user-agent information
           by default. The string is randomly generated for each runtime
           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).

       --no-gzip
           Explicitly turn off HTTP stream compression.

           Note that compression is enabled by default but used only
           if the server supports it. Using a proxy may alter the
           HTTP request headers.

       Playback

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

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

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

       --play=FORMAT, -p FORMAT
           Play video (format) after extraction. If format is set
           to anything else than "src" (extracted video), clive will
           call ffmpeg to re-encode the video to the specified format
           first. See also ‘--ffmpeg’.

           Examples:
             --play=src
             --play=mpg

       --no-play
           Explicitly turn off subsequent playback.


       Re-encode

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

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

       --re-encode=FORMAT
           Re-encode video to FORMAT. clive does not check
           the format value. As long as ffmpeg recognizes
           the format, you can use it.

           Examples:
             --re-encode=mpg
             --re-encode=avi

       --no-encode
           Explicitly turn off subsequent re-encoding.


       Clipboard

       --xclip=XCLIP
           Set path to xclip. The "-o" option must be used.

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

       --paste, -c
           Paste input from system clipboard. The ‘--xclip’ option
           needs to be used with this option on unix systems.


       Log

       --log-recall, -R
           Recall URL batch from last logged runtime. If logging
           is enabled, clive stores last URL batch to the file
           ~/.clive/last.log. This option tells clive to reuse
           the batch from that file.

       --log-clear, -L
           Clear all log information from ~/.clive.

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

       --no-log
           Explicitly turn off all logging.






CONFIG.PY
       The  runtime  configuration  file (~/.clive/config.py) is read when the
       program starts and the file exists.

       Users who want to edit the file manually, may want run clive  with  the
       ‘--conf-write’  option  (new  in 0.4.4) to write the configuration file
       with a complete list of supported variables/keys.

       Note that users running X may run the program  with  the  ‘--configure’
       option to edit the file using the graphical user interface instead.

NOTES
       Websites

         The following websites are supported:

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

         Note about last.fm:

           "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"
                   -- Seth W. (Jzalae) Klein


       URLs

         Video page URLs are fed to clive which it will then visit
         looking for an extraction URL for the video.

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

         Video extraction URLs are used to download the video file from
         the website, e.g. with ‘wget’. These URLs can be printed out with
         the ‘--emit’ option and are usually useless to most users.


       Resuming

         All but Youtube and Google Video websites support resumed file
         transfers.

         Note that clive attempts to resume a transfer only if the condition
         local_file < remote_file is true.


       Emitting

         The ‘--emit’ option can be used to print out the found video
         extraction URLs (see "URLs" above). Each URL line is formatted
         accordingly:

           video: "extraction-url" "filename" "length"


       Youtube

         Flagged videos that require users to log in cannot
         be extracted with clive. Any attempts to do so will result
         in "age verification" error.


       Cookies

         clive does not accept any cookies.

UPDATES
       For the latest release of clive visit:

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

       The development trunk can be checked out with:

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

       Note  that  clive  can also be run with the ‘--check-updates’ option to
       check if a new release is available.

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