man1/clive.1.pod

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