| blob | f9cbc40663a756d217288de3f16d3de59f099a0c |
1 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 . de IX
53 . tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 . nr % 0
56 . rr F
57 .\}
58 .el \{\
59 . de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
66 .if n \{\
67 . ds #H 0
68 . ds #V .8m
69 . ds #F .3m
70 . ds #[ \f1
71 . ds #] \fP
72 .\}
73 .if t \{\
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 . ds #V .6m
76 . ds #F 0
77 . ds #[ \&
78 . ds #] \&
79 .\}
80 . \" simple accents for nroff and troff
81 .if n \{\
82 . ds ' \&
83 . ds ` \&
84 . ds ^ \&
85 . ds , \&
86 . ds ~ ~
87 . ds /
88 .\}
89 .if t \{\
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 . ds : e
114 . ds 8 ss
115 . ds o a
116 . ds d- d\h'-1'\(ga
117 . ds D- D\h'-1'\(hy
118 . ds th \o'bp'
119 . ds Th \o'LP'
120 . ds ae ae
121 . ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "quvi 1"
127 .TH quvi 1 "2010-12-07" "0.2.9" "quvi manual"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 quvi \- query video tool
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 quvi [options] [url...]
137 .SH "DESCRIPTION"
138 .IX Header "DESCRIPTION"
139 quvi is a command line tool for parsing video download links.
140 It supports Youtube and other similar video websites.
141 .PP
142 The video details are printed to standard output (in \s-1JSON\s0),
143 everything else is printed to standard error.
144 .SH "OPTIONS"
145 .IX Header "OPTIONS"
146 .IP "\fB\-h, \-\-help\fR" 4
147 .IX Item "-h, --help"
148 Print help and exit.
149 .IP "\fB\-\-version\fR" 4
150 .IX Item "--version"
151 Print program version and exit.
152 .IP "\fB\-\-license\fR" 4
153 .IX Item "--license"
154 Print license and exit.
155 .IP "\fB\-\-support\fR" 4
156 .IX Item "--support"
157 Print supported hosts and exit. To check if an \s-1URL\s0 is supported, specify
158 an \s-1URL\s0 as an argument to the program. See \*(L"\s-1EXAMPLES\s0\*(R".
159 .IP "\fB\-\-xml\fR" 4
160 .IX Item "--xml"
161 Print the details in \s-1XML\s0 (instead of \s-1JSON\s0). URLs are escaped (\s-1URL\s0 encoded,
162 unlike in \s-1JSON\s0). Encoding is always \s-1UTF\-8\s0 (like in \s-1JSON\s0).
163 .IP "\fB\-\-old\fR" 4
164 .IX Item "--old"
165 Print the details in the previously used default output format
166 (0.2.3 and earlier).
167 .IP "\fB\-q, \-\-quiet\fR" 4
168 .IX Item "-q, --quiet"
169 Turn off output to stderr (excl. errors, libcurl). Video details will
170 be printed to stdout as they would be normally.
171 .IP "\fB\-\-verbose\-libcurl\fR" 4
172 .IX Item "--verbose-libcurl"
173 Turn on libcurl verbose mode.
174 .IP "\fB\-\-exec\fR \fIarg\fR" 4
175 .IX Item "--exec arg"
176 Invoke \fIarg\fR for each (successfully) parsed video. You can use the following
177 specifiers in \fIarg\fR:
178 .Sp
179 .Vb 1
180 \& %u Video download URL
181 .Ve
182 .Sp
183 Note that \fIall\fR occurences of the specifier will be replaced,
184 and each new value will be quoted ("").
185 .IP "\fB\-s, \-\-no\-shortened\fR" 4
186 .IX Item "-s, --no-shortened"
187 Do not \*(L"decompress\*(R" shortened URLs before using them.
188 .IP "\fB\-n, \-\-no\-verify\fR" 4
189 .IX Item "-n, --no-verify"
190 Do not verify video link after parsing it. Normally this serves two
191 purposes: check that the link actually works, and get content-length
192 as well as content-type for the video.
193 .Sp
194 If this switch used, the program will report invalid values for those
195 video details (e.g. 0 file length, empty string for content-type, etc.)
196 but saves some bandwidth if those details are not obligatory.
197 .IP "\fB\-\-page\-title\fR \fIarg\fR" 4
198 .IX Item "--page-title arg"
199 Check that the parsed video title matches the \fIarg\fR.
200 The libquvi tests typically make use of this option.
201 .IP "\fB\-\-video\-id\fR \fIarg\fR" 4
202 .IX Item "--video-id arg"
203 Check that the parsed video \s-1ID\s0 matches the \fIarg\fR.
204 The libquvi tests typically make use of this option.
205 .IP "\fB\-\-file\-length\fR \fIlength\fR" 4
206 .IX Item "--file-length length"
207 Check that the parsed video file length matches the \fIarg\fR.
208 The libquvi tests typically make use of this option.
209 .IP "\fB\-\-file\-suffix\fR \fIarg\fR" 4
210 .IX Item "--file-suffix arg"
211 Check that the parsed video file suffix matches the \fIarg\fR.
212 The libquvi tests typically make use of this option.
213 .IP "\fB\-a, \-\-test\-all\fR" 4
214 .IX Item "-a, --test-all"
215 quvi holds a number of built-in video URLs that can be tested
216 with this switch.
217 .IP "\fB\-d, \-\-dump\fR" 4
218 .IX Item "-d, --dump"
219 Dump video details while when running the program with \f(CW\*(C`\-\-test\-all\*(C'\fR.
220 .IP "\fB\-t, \-\-test\fR \fIarg\fR" 4
221 .IX Item "-t, --test arg"
222 quvi holds a number of built-in video URLs that can be matched
223 with this option. Some examples:
224 .Sp
225 .Vb 2
226 \& % quvi \-t youtube
227 \& % quvi \-t yout
228 .Ve
229 .Sp
230 Both would match the same built-in test \s-1URL\s0 for Youtube. Some
231 more examples:
232 % quvi \-t livel
233 % quvi \-t liveleak
234 % quvi \-t col
235 % quvi \-t collegehumor
236 .Sp
237 As long as the built-in \s-1URL\s0 contains the pattern, it can be
238 matched. Like \f(CW\*(C`\-\-page\-title\*(C'\fR and friends, this feature is
239 intended to be used by the libquvi package tests primarily.
240 .IP "\fB\-f, \-\-format\fR \fIarg\fR" 4
241 .IX Item "-f, --format arg"
242 Query for video format \fIarg\fR. You can get a list of the formats
243 that each website (should) support by running the program with
244 \&\f(CW\*(C`\-\-support\*(C'\fR.
245 .IP "\fB\-\-agent\fR \fIarg\fR" 4
246 .IX Item "--agent arg"
247 Identify quvi as \fIarg\fR to servers. Default is \*(L"Mozilla/5.0\*(R".
248 .IP "\fB\-\-proxy\fR \fIarg\fR" 4
249 .IX Item "--proxy arg"
250 Use proxy for \s-1HTTP\s0 connections, e.g. \*(L"http://foo:1234\*(R".
251 You can also define http_proxy environment setting to
252 achieve the same.
253 .IP "\fB\-\-no\-proxy\fR" 4
254 .IX Item "--no-proxy"
255 Disable use of \s-1HTTP\s0 proxy completely. Proxy will not
256 be used even if defined in http_proxy.
257 .IP "\fB\-\-connect\-timeout\fR \fIseconds\fR" 4
258 .IX Item "--connect-timeout seconds"
259 Maximum seconds allowed connection to server take.
260 Default is 30.
261 .SH "EXAMPLES"
262 .IX Header "EXAMPLES"
263 .IP "quvi \s-1URL\s0" 4
264 .IX Item "quvi URL"
265 Test \s-1URL\s0.
266 .IP "quvi \-\-support" 4
267 .IX Item "quvi --support"
268 Dump all supported websites.
269 .IP "quvi \-\-support \s-1URL\s0" 4
270 .IX Item "quvi --support URL"
271 Check if \s-1URL\s0 is supported. Note that some of the shortened URLs will
272 fail with this. quvi exit status will be the last exit status of the
273 last checked \s-1URL\s0. See also \*(L"\s-1EXIT\s0 \s-1STATUS\s0\*(R".
274 .IP "quvi \-a" 4
275 .IX Item "quvi -a"
276 Run all built-in host tests.
277 .IP "quvi \-aqd \-\-xml" 4
278 .IX Item "quvi -aqd --xml"
279 Same but run in quiet mode. Print video details in \s-1XML\s0 (to stdout).
280 .IP "quvi \-t youtube" 4
281 .IX Item "quvi -t youtube"
282 Match pattern \*(L"youtube\*(R" to a built-in video \s-1URL\s0 and test it.
283 .IP "quvi \s-1YOUTUBE_URL\s0 \-f best" 4
284 .IX Item "quvi YOUTUBE_URL -f best"
285 Query \s-1YOUTUBE_URL\s0 for \*(L"best\*(R" format of the video.
286 .Sp
287 Run quvi with \f(CW\*(C`\-\-support\*(C'\fR to get a list of the websites
288 and which formats they support.
289 .SH "FILES"
290 .IX Header "FILES"
291 .IP "\fB~/.quvirc\fR" 4
292 .IX Item "~/.quvirc"
293 You can define most of the command line options in the
294 config file. For example:
295 .Sp
296 .Vb 4
297 \& agent = some_agent/1.0 # \-\-agent
298 \& proxy = http://foo:1234 # \-\-proxy
299 \& no\-verify # \-\-no\-verify
300 \& verbose\-libcurl # \-\-verbose\-libcurl
301 .Ve
302 .Sp
303 Note that you can also define \f(CW$QUVI_HOME\fR and use it instead of \f(CW$HOME\fR (~).
304 .SH "ENVIRONMENT"
305 .IX Header "ENVIRONMENT"
306 .IP "\fB\s-1QUVI_HOME\s0\fR" 4
307 .IX Item "QUVI_HOME"
308 Path to the directory containing the configuration file (.quvirc).
309 Mimics \f(CW$HOME\fR found on Unix-like systems. Note that using this
310 overrides the use of \f(CW$HOME\fR.
311 .IP "\fB\s-1QUVI_BASEDIR\s0\fR" 4
312 .IX Item "QUVI_BASEDIR"
313 Exclusive path to the directory holding the essential libquvi files,
314 or the Lua scripts.
315 .Sp
316 Exlusivity here means that by setting this variable, the user
317 can override all other built-in and default search paths.
318 .Sp
319 Not to be confused with \fB\s-1QUVI_HOME\s0\fR which is strictly for
320 \&\f(CWquvi(1)\fR, whereas \fB\s-1QUVI_BASEDIR\s0\fR is for libquvi.
321 .IP "\fB\s-1QUVI_SHOW_SCANDIR\s0\fR" 4
322 .IX Item "QUVI_SHOW_SCANDIR"
323 Set this variable if you need libquvi to report the scanned
324 directory paths. Each scanned path is printed to stderr.
325 .SH "EXIT STATUS"
326 .IX Header "EXIT STATUS"
327 quvi exits with 0 on success and >0 if an error occurred.
328 .PP
329 .Vb 10
330 \& QUVI_OK = 0x00
331 \& QUVI_MEM = 0x01, Memory allocation failed
332 \& QUVI_BADHANDLE = 0x02, Bad session handle
333 \& QUVI_INVARG = 0x03, Invalid function argument
334 \& QUVI_CURLINIT = 0x04, libcurl initialization failed
335 \& QUVI_LAST = 0x05, Indicates end of list iteration
336 \& QUVI_ABORTEDBYCALLBACK= 0x06, Aborted by callback function
337 \& QUVI_LUAINIT = 0x07, Lua initialization failure
338 \& QUVI_NOLUAWEBSITE = 0x08, Failed to find lua website scripts
339 \& \-\-
340 \& QUVI_PCRE = 0x40, libpcre error occurred, deprecated 0.2.9+
341 \& QUVI_NOSUPPORT = 0x41, libquvi does not support the video host
342 \& QUVI_CURL = 0x42, libcurl error occurred
343 \& QUVI_ICONV = 0x43, libiconv error occurred
344 \& QUVI_LUA = 0x44, lua error occurred
345 .Ve
346 .SH "CONTRIBUTING"
347 .IX Header "CONTRIBUTING"
348 .IP "\fBAdd support for another website\fR" 4
349 .IX Item "Add support for another website"
350 On most systems you can find the READMEs and HOWTOs from \f(CW$prefix\fR/share/quvi
351 and \f(CW$prefix\fR/share/doc/quvi directories. You can find the same files in
352 release source tarballs, and at:
353 .Sp
354 .Vb 3
355 \& <http://repo.or.cz/w/quvi.git/tree/HEAD:/doc>
356 \& <http://repo.or.cz/w/quvi.git/tree/HEAD:/share/lua>
357 \& <http://repo.or.cz/w/quvi.git/tree/HEAD:/share/lua/website>
358 .Ve
359 .IP "\fBSubmitting patches\fR" 4
360 .IX Item "Submitting patches"
361 If you have cooked up a patch, please submit it to the tracker (see \*(L"\s-1BUGS\s0\*(R").
362 .Sp
363 If you are working with git and you have established a repo from which
364 we can pull the changes from, you can use the same tracker for leaving
365 pull requests.
366 .SH "BUGS"
367 .IX Header "BUGS"
368 .IP "\fBTrackers\fR" 4
369 .IX Item "Trackers"
370 Bugs, support, patches, etc. trackers for these can be found at:
371 <http://sourceforge.net/projects/quvi/support>
372 .SH "DEBUGGING TIPS"
373 .IX Header "DEBUGGING TIPS"
374 .IP "\fB\-\-verbose\-libcurl\fR" 4
375 .IX Item "--verbose-libcurl"
376 You can use this switch to amp up libcurl verbosity.
377 .IP "\fBDebug symbols\fR" 4
378 .IX Item "Debug symbols"
379 Compile quvi with \f(CW\*(C`\-g\*(C'\fR (see \f(CW\*(C`g++(1)\*(C'\fR) for debug symbols.
380 .IP "\fBOther tools\fR" 4
381 .IX Item "Other tools"
382 Make use of such tools as \f(CWstrace(1)\fR, \f(CWgdb(1)\fR and \f(CWvalgrind(1)\fR.
383 They may prove invaluable.
384 .SH "OTHER"
385 .IX Header "OTHER"
386 .IP "\fB\s-1WWW\s0\fR" 4
387 .IX Item "WWW"
388 <http://quvi.sourceforge.net/>
389 .SH "AUTHOR"
390 .IX Header "AUTHOR"
391 Toni Gundogdu <legatvs at sign gmail com>.
392 .PP
393 Thanks to all those who have contributed to the project
394 by sending patches, reporting bugs and writing feedback.
395 You know who you are.
396 .PP
397 See also \*(L"\s-1BUGS\s0\*(R", \*(L"\s-1DEBUGGING\s0 \s-1TIPS\s0\*(R" and \*(L"\s-1CONTRIBUTING\s0\*(R".