man1/quvi.1.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 quvi - query media tool
   6
   7 =head1 SYNOPSIS
   8
   9 quvi [options] [url...]
  10
  11 =head1 DESCRIPTION
  12
  13 quvi is a command line tool for parsing Adobe Flash media stream URLs. It
  14 supports many websites including YouTube and Dailymotion.
  15
  16 The parsed details are printed to standard output (in JSON), everything else
  17 is printed to standard error.
  18
  19 =head1 MOTIVATION
  20
  21 quvi parses Adobe Flash media stream URLs for third party applications. It
  22 originates from the idea of allowing users to view the videos without having
  23 to install or use Adobe Flash Player. quvi is not an "alternative" but rather
  24 a "workaround" to Adobe Flash Player.
  25
  26 Read also:
  27   * <http://en.wikipedia.org/wiki/Adobe_Flash#Performance>
  28   * <http://en.wikipedia.org/wiki/Adobe_Flash#Flash_client_security>
  29   * <http://en.wikipedia.org/wiki/Adobe_Flash#Alternatives_to_Flash>
  30
  31 =head1 OPTIONS
  32
  33 =over 4
  34
  35 =item B<-h, --help>
  36
  37 Print help and exit.
  38
  39 =item B<--version>
  40
  41 Print program version and exit.
  42
  43 =item B<--license>
  44
  45 Print license and exit.
  46
  47 =item B<--support>
  48
  49 Print supported hosts and exit. To check if an URL is supported, specify
  50 an URL as an argument to the program. See L</EXAMPLES>.
  51
  52 =item B<--xml>
  53
  54 Print the details in XML (instead of JSON). URLs are escaped (URL encoded,
  55 unlike in JSON). Encoding is always UTF-8 (like in JSON).
  56
  57 =item B<--old>
  58
  59 Print the details in the previously used default output format
  60 (0.2.3 and earlier).
  61
  62 =item B<-q, --quiet>
  63
  64 Turn off output to stderr (excl. errors, libcurl). Video details will
  65 be printed to stdout as they would be normally.
  66
  67 =item B<--verbose-libcurl>
  68
  69 Turn on libcurl verbose mode.
  70
  71 =item B<--exec> I<arg>
  72
  73 Invoke I<arg> for each (successfully) parsed media. You can use the following
  74 specifiers in I<arg>:
  75
  76     %u  Media URL
  77
  78 Note that I<all> occurences of the specifier will be replaced,
  79 and each new value will be quoted ("").
  80
  81 =item B<-s, --no-shortened>
  82
  83 Do not "decompress" shortened URLs before using them.
  84
  85 =item B<-n, --no-verify>
  86
  87 Do not verify media URL after parsing it. Normally this serves two
  88 purposes:
  89
  90  * Check that the URL works
  91  * Get content-length and content-type
  92
  93 If this switch used, the program will report invalid values for those
  94 details (e.g. 0 content length, empty string for content-type, etc.) but
  95 may save some bandwidth if those details are not needed.
  96
  97 Note that the URL is verified for HTTP only.
  98
  99 =item B<--category-http>
 100
 101 Enable category HTTP website scripts. This is the default category.
 102
 103 =item B<--category-mms>
 104
 105 Enable category MMS website scripts.
 106
 107 =item B<--category-rtsp>
 108
 109 Enable category RTSP website scripts.
 110
 111 =item B<--category-rtmp>
 112
 113 Enable category RTMP website scripts.
 114
 115 =item B<--category-all>
 116
 117 Enable all categories of website scripts.
 118
 119 =item B<--page-title> I<arg>
 120
 121 Check that the parsed page title matches the I<arg>.
 122 The libquvi tests typically make use of this option.
 123
 124 =item B<--media-id> I<arg>
 125
 126 Check that the parsed media ID matches the I<arg>.
 127 The libquvi tests typically make use of this option.
 128
 129 =item B<--file-length> I<length>
 130
 131 Check that the parsed media content length matches the I<arg>.
 132 The libquvi tests typically make use of this option.
 133
 134 =item B<--file-suffix> I<arg>
 135
 136 Check that the parsed media file suffix matches the I<arg>.
 137 The libquvi tests typically make use of this option.
 138
 139 =item B<--test-all>
 140
 141 Test all of the built-in (category QUVIPROTO_HTTP) URLs.
 142
 143 =item B<--dump>
 144
 145 Dump media details with C<--test-all>.
 146
 147 =item B<-t, --test> I<arg>
 148
 149 Match I<arg> to built-in (category QUVIPROTO_HTTP) test URLs, e.g.:
 150
 151     % quvi -t youtube
 152     % quvi -t yout
 153     % quvi -t livel
 154     % quvi -t liveleak
 155     % quvi -t col
 156     % quvi -t collegehumor
 157
 158 =item B<-f, --format> I<arg>
 159
 160 Query for I<arg> format. I<arg> can also be C<help>.
 161
 162 =item B<--agent> I<arg>
 163
 164 Identify quvi as I<arg> to servers. Default is "Mozilla/5.0".
 165
 166 =item B<--proxy> I<arg>
 167
 168 Use proxy for HTTP connections, e.g. "http://foo:1234".
 169 You can also define http_proxy environment setting to
 170 achieve the same.
 171
 172 =item B<--no-proxy>
 173
 174 Disable use of HTTP proxy completely. Proxy will not
 175 be used even if defined in http_proxy.
 176
 177 =item B<--connect-timeout> I<seconds>
 178
 179 Maximum seconds allowed connection to server take.
 180 Default is 30.
 181
 182 =back
 183
 184 =head1 EXAMPLES
 185
 186 =over 4
 187
 188 =item quvi URL
 189
 190 Test URL.
 191
 192 =item quvi --support
 193
 194 Dump all supported websites.
 195
 196 =item quvi --support URL
 197
 198 Check if URL is supported. Note that some of the shortened URLs will
 199 fail with this. quvi exit status will be the last exit status of the
 200 last checked URL. See also L</EXIT STATUS>.
 201
 202 =item quvi -a
 203
 204 Run all built-in host tests.
 205
 206 =item quvi -aqd --xml
 207
 208 Same but run in quiet mode. Print details in XML (to stdout).
 209
 210 =item quvi -t youtube
 211
 212 Match pattern "youtube" to a built-in media URL and test it.
 213
 214 =item quvi YOUTUBE_URL -f best
 215
 216 Query YOUTUBE_URL for "best" format.
 217
 218 Run quvi with C<--support> to get a list of the websites
 219 and which formats they support.
 220
 221 =item quvi -f list dailym
 222
 223 Print available formats for dailym(otion).
 224
 225 =back
 226
 227 =head1 FILES
 228
 229 =over 4
 230
 231 =item B<~/.quvirc>
 232
 233 You can define most of the command line options in the
 234 config file. For example:
 235
 236  agent = some_agent/1.0     # --agent
 237  proxy = http://foo:1234    # --proxy
 238  no-verify                  # --no-verify
 239  verbose-libcurl            # --verbose-libcurl
 240
 241 Note that you can also define $QUVI_HOME and use it instead of $HOME (~).
 242
 243 =back
 244
 245 =head1 ENVIRONMENT
 246
 247 =over 4
 248
 249 =item B<QUVI_HOME>
 250
 251 Path to the directory containing the configuration file (.quvirc).
 252 Mimics $HOME found on Unix-like systems. Note that using this
 253 overrides the use of $HOME.
 254
 255 =item B<QUVI_BASEDIR>
 256
 257 Exclusive path to the directory holding the essential libquvi files,
 258 or the Lua scripts.
 259
 260 Exlusivity here means that by setting this variable, the user
 261 can override all other built-in and default search paths.
 262
 263 Not to be confused with B<QUVI_HOME> which is strictly for
 264 C<quvi(1)>, whereas B<QUVI_BASEDIR> is for libquvi.
 265
 266 =item B<QUVI_SHOW_SCANDIR>
 267
 268 Set this variable if you need libquvi to report the scanned
 269 directory paths. Each scanned path is printed to stderr.
 270
 271 =back
 272
 273 =head1 EXIT STATUS
 274
 275 quvi exits with 0 on success and E<gt>0 if an error occurred.
 276
 277   QUVI_OK               = 0x00
 278   QUVI_MEM              = 0x01, Memory allocation failed
 279   QUVI_BADHANDLE        = 0x02, Bad session handle
 280   QUVI_INVARG           = 0x03, Invalid function argument
 281   QUVI_CURLINIT         = 0x04, libcurl initialization failed
 282   QUVI_LAST             = 0x05, Indicates end of list iteration
 283   QUVI_ABORTEDBYCALLBACK= 0x06, Aborted by callback function
 284   QUVI_LUAINIT          = 0x07, Lua initialization failure
 285   QUVI_NOLUAWEBSITE     = 0x08, Failed to find lua website scripts
 286   --
 287   QUVI_PCRE             = 0x40, libpcre error occurred, deprecated 0.2.9+
 288   QUVI_NOSUPPORT        = 0x41, libquvi does not support the host
 289   QUVI_CURL             = 0x42, libcurl error occurred
 290   QUVI_ICONV            = 0x43, libiconv error occurred
 291   QUVI_LUA              = 0x44, lua error occurred
 292
 293 =head1 DEBUGGING TIPS
 294
 295 =over 4
 296
 297 =item B<--verbose-libcurl>
 298
 299 You can use this switch to amp up libcurl verbosity.
 300
 301 =item B<Debug symbols>
 302
 303 Compile quvi with C<-g>, refer to C<gcc(1)> documentation for the
 304 details.
 305
 306 =item B<Other tools>
 307
 308 Make use of such tools as C<strace(1)>, C<gdb(1)> and C<valgrind(1)>.
 309 They may prove invaluable.
 310
 311 =back
 312
 313 =head1 WWW
 314
 315 E<lt>http://quvi.sourceforge.net/E<gt>
 316
 317 E<lt>http://repo.or.cz/w/quvi.gitE<gt>
 318
 319 =head1 CONTRIBUTE
 320
 321 E<lt>http://repo.or.cz/w/quvi.git/tree/HEAD:/docE<gt>
 322
 323 =head1 BACKGROUND
 324
 325 quvi or "(qu)ery (vi)deo" for historical reasons. As of 0.2.15
 326 a more suitable name would be qume or "(qu)ery (me)dia".
 327
 328 quvi was inspired by cclive. Embeddable LUA scripting was introduced
 329 in 0.2.0.
 330
 331 =head1 LICENSE
 332
 333 quvi and libquvi are free software, licensed under the LGPLv2.1+.
 334 The LUA scripts that quvi uses are considered as programs and using
 335 the LUA scripts is B<linking>.
 336
 337 =head1 AUTHOR
 338
 339 Toni Gundogdu E<lt>legatvs at sign gmail comE<gt>
 340
 341 Thanks to all those who have contributed to the project by sending patches,
 342 reporting bugs and writing feedback. You know who you are.
 343
 344 =cut