man1/clive.1.pod

   1 =head1 NAME
   2
   3 clive - (c)ommand (li)ne (v)ideo (e)xtration tool
   4
   5 =head1 DESCRIPTION
   6
   7 clive is a command line video extraction tool for Youtube and other similar
   8 video websites that require Adobe Flash for viewing the videos.
   9
  10 =head1 HISTORY
  11
  12 In 2006 clive was a little more than a simple shell script that could be
  13 used to extract flash videos from Youtube for viewing them with an
  14 external player software. The primary motivation for writing clive was
  15 to work around the flash player plugin which, at the time, was less
  16 than a pleasant experience on Linux.
  17
  18 clive was rewritten in Python and released to the public in the
  19 early 2007. It was rewritten again in the late 2008, this time in
  20 Perl.
  21
  22 The development work of 2.3 started in the late 2010 as "gws" or
  23 "glorified wrapper script". The 2.3 was an attempt to make better
  24 use of the already existing tools, such as C<quvi(1)>.
  25
  26 =head1 GETTING STARTED
  27
  28 See L</FILES> for an example configuration file. You should consider
  29 setting at least L</--quvi> and L</--get-with> in your configuration
  30 file for seamless use.
  31
  32 The sections L</TROUBLESHOOTING> and L</EXAMPLES> contain invaluable
  33 information about using clive.
  34
  35 =head1 OPTIONS
  36
  37 =over 4
  38
  39 =item B<--help>
  40
  41 Print help and exit.
  42
  43 =item B<--version>
  44
  45 Print version and exit.
  46
  47 =item B<--license>
  48
  49 Print license and exit.
  50
  51 =item B<--quiet>
  52
  53 Turn off all I<clive> output excluding errors. Note that this switch has no
  54 effect on any of the third party commands that clive invokes.
  55
  56 =item B<-f, --format> I<arg>
  57
  58 Download I<arg> format of the video. I<arg> can also be C<help>.
  59
  60 =item B<-O, --output-file> I<arg>
  61
  62 Write video to I<arg>.
  63
  64 =item B<-n, --no-download>
  65
  66 Do not download the video, display video details only.
  67
  68 =item B<--config-file> I<arg>
  69
  70 Path to a file to read clive arguments from. See also L</FILES>.
  71
  72 =back
  73
  74 =head1 OPTIONS - CONFIGURATION
  75
  76 In addition to the command line, the options may also be read from the
  77 configuration file. See L</FILES>.
  78
  79 =over 4
  80
  81 =item B<--quvi> I<arg>
  82
  83 I<arg> to be invoked to start the C<quvi(1)> command which clive uses to
  84 parse the video details. This is typically a full path to C<quvi(1)> with
  85 any additional options.
  86
  87 The following specifiers can be used in the I<arg>:
  88
  89     %u .. Video URL
  90
  91 I<All> occurences of the specifier will be replaced. clive will
  92 automatically append C<--quiet> to I<arg>.
  93
  94 NOTE: If you use an HTTP proxy with C<quvi(1)>, you should do the same with
  95 C<--get-with> -- especially if the proxy masks your IP. Some websites may
  96 refuse connections originating from different IPs to (unique, generated)
  97 video download URLs.
  98
  99 =item B<--get-with> I<arg>
 100
 101 Path to a download command (e.g. C<wget(1)> or C<curl(1)>) with any additional
 102 arguments. clive invokes this command to download the video. The following
 103 specifiers are supported:
 104
 105     %u  Video download URL
 106     %f  Full path to video file
 107     %n  Video file name
 108
 109 Note that I<all> occurences of the specifier will be replaced. See also the
 110 note above about using an HTTP proxy with C<--quvi>.
 111
 112 =item B<--filename-format> I<arg>
 113
 114 Use I<arg> to specify the video output filename format. The default is "%t.%s".
 115 The following specifiers are supported:
 116
 117     %t  Video title (after applying --regexp)
 118     %i  Video ID
 119     %h  Video host ID (req. quvi 0.2.8+)
 120     %s  Video file suffix (parsed from server returned content-type)
 121
 122 Note that I<all> occurences of the specifier will be replaced.
 123
 124 =item B<--regexp> I<arg>
 125
 126 Use regular expression I<arg> to clean up the video title before
 127 it is used in the output filename. The default is "/(\w|\s)/g".
 128
 129 Note that the syntax supports both "i" (case-insensitive) and "g"
 130 (global or find all).
 131
 132 =item B<--exec> I<arg>
 133
 134 Invoke I<arg> after video download finishes. The following specifiers
 135 are supported:
 136
 137     %f  Full path to the downloaded video file
 138
 139 Note that I<all> occurences of the specifier will be replaced.
 140
 141 =back
 142
 143 =head1 TROUBLESHOOTING
 144
 145 =over 4
 146
 147 =item B<error: specify path to quvi(1) command with --quvi>
 148
 149 clive uses C<quvi(1)> to parse the video details. Use the C<--quvi> to specify
 150 the path. See also L</FILES>.
 151
 152 =item B<error: specify path to a download command with --get-with>
 153
 154 clive uses a 3rd party command to download the videos. Use the C<--get-with> to
 155 specify the path to such command. See also L</FILES>.
 156
 157 =back
 158
 159 =head1 FILES
 160
 161 =over 4
 162
 163 =item B<~/.cliverc>
 164
 165 Additional search paths:
 166
 167     ~/.clive/config
 168     ~/.config/clive/config
 169
 170 For a system-wide configuration:
 171
 172     /usr/local/share/clive/config
 173     /usr/share/clive/config
 174     /etc/clive/config
 175     /etc/xdg/clive/clive.conf
 176     /etc/xdg/clive.conf
 177
 178 You can also set CLIVE_CONFIG, e.g.:
 179
 180     env CLIVE_CONFIG=/path/to/config/file clive
 181
 182 Or use C<--config-file>, e.g.:
 183
 184     clive --config-file /path/to/config/file
 185
 186 A typical configuration file could look like:
 187
 188     --quvi "/usr/bin/quvi %u"
 189  # Recommended value for quvi 0.2.12+
 190  #  --quvi "/usr/bin/quvi --category-http %u"
 191     --get-with "/usr/bin/curl -L -C - -o %f %u"
 192     --filename-format "%t_%i.%s"
 193     --exec "/usr/bin/vlc %f"
 194
 195 If you are unsure, consider setting at least the C<--quvi> and
 196 C<--get-with> in your configuration file.
 197
 198 =back
 199
 200 =head1 EXAMPLES
 201
 202 These examples assume you have set C<--quvi> and C<--get-with> in the config
 203 file. See L</FILES> for an example config file.
 204
 205 =over 4
 206
 207 =item B<clive "http://www.youtube.com/watch?v=DUM1284TqFc">
 208
 209 Typical use.
 210
 211 =item B<clive "http://www.youtube.com/watch?v=DUM1284TqFc" -f mp4_360p>
 212
 213 Same but get the mp4_360p format of the video.
 214
 215 =item B<clive -f help>
 216
 217 Help on how you can use the C<--format> option.
 218
 219 =item B<clive -f list>
 220
 221 Lists all C<quvi(1)> supported websites with formats.
 222
 223 =item B<clive -f list dailymotion>
 224
 225 Lists dailymotion formats. The pattern is matched to C<quvi(1)>
 226 returned website domain strings. For example:
 227
 228 =item B<clive -f list dailym>
 229
 230 Would yield the same results.
 231
 232 =item B<clive "http://www.youtube.com/watch?v=DUM1284TqFc" -n>
 233
 234 Do not download the video. Print the video details only.
 235
 236 =item B<echo "http://www.youtube.com/watch?v=DUM1284TqFc" | clive>
 237
 238 A fancy way to feed clive an URL.
 239
 240 clive can handle multiple URLs in one go. One way to do this, is to
 241 specify each on the command line as arguments. An alternative source
 242 could be a file. For example:
 243
 244   cat >> urls.lst
 245   http://www.youtube.com/watch?v=DUM1284TqFc
 246   http://www.youtube.com/watch?v=TqgTz8ymZl8
 247   (CTRL+D)
 248   clive < urls.lst
 249
 250 Make a note that each URL must be separated with a newline character.
 251
 252 =back
 253
 254 =head1 EXIT STATUS
 255
 256 clive exits with 0 on success, otherwise the code is E<gt>0. Strictly clive
 257 exit statuses are 0 or 1. For example, if command line parsing fails, the exit
 258 status is 1.
 259
 260 When an error occurs in another command invoked by clive, e.g. C<quvi(1)>,
 261 clive exits with the exit status returned by the command.
 262
 263 If you are planning to use clive for anything more peculiar, you should feed
 264 it only one URL at a time. For example:
 265
 266     * You feed clive two URLs
 267     * The 1st one fails, quvi exits with a non-zero value
 268     * clive proceeds to the 2nd URL, quvi now exits with zero value
 269     * clive exits with the zero, even if the 1st URL failed
 270
 271 =head1 SEE ALSO
 272
 273 C<quvi(1)>  C<wget(1)>  C<curl(1)>
 274
 275 =head1 WWW
 276
 277 <http://clive.sourceforge.net/>
 278
 279 <http://quvi.sourceforge.net/>
 280
 281 =head1 AUTHOR
 282
 283 Toni Gundogdu <legatvs at sign gmail com>.
 284
 285 Thanks to all those who have contributed to the project by sending
 286 patches, reporting bugs and writing feedback. You know who you are.