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