Add --export-format, depr. --json, --csv
[umph.git] / doc / man1 / umph.1.pod
blobafb998d10b7bafa44593b359cb39f3f925007107
2 =head1 NAME
4 umph - Command line tool for parsing YouTube feeds
6 =head1 SYNOPSIS
8 umph [-q] [-i] [--export-format=E<lt>valueE<gt>] [--type=E<lt>valueE<gt>]
9      [[--all | [--start-index=E<lt>valueE<gt>] [--max-results=E<lt>valueE<gt>]]
10      [--proxy=E<lt>addrE<gt> | --no-proxy] [--help]
11      E<lt>playlist_idE<gt> | E<lt>usernameE<gt>
13 =head1 DESCRIPTION
15 umph is a command line tool for parsing YouTube feeds. It can parse
16 playlists, favorite lists, and user upload lists.
18 umph prints the found URLs to the standard output, each URL separated
19 with a newline. It can be used to select the feed items by using the
20 C<--interactive> prompt.
22 =head1 OPTIONS
24 =over 4
26 =item B<-h, --help>
28 Print help and exit.
30 =item B<-v, --version>
32 Print version and exit.
34 =item B<-q, --quiet>
36 Turn off output to stderr, e.g. status changes. Warnings and errors are
37 still printed.
39 =item B<-t, --type> I<arg> (=p)
41 Specifies the feed type to get. I<arg> can be one of the following:
43  p, playlist  (arg0 will be treated as playlist ID)
44  f, favorites (arg0 will be treated as username)
45  u, uploads   (ditto)
47 See also L</EXAMPLES>.
49 =item B<-s, --start-index> I<arg> (=1)
51 "The start-index parameter specifies the index of the first matching result
52 that should be included in the result set. This parameter uses a one-based
53 index, meaning the first result is 1, the second result is 2 and so forth.
55 This parameter works in conjunction with the C<--max-results> parameter to
56 determine which results to return. For example, to request the second set
57 of 10 results, i.e. results 11-20, set the start-index parameter to 11
58 and the max-results parameter to 10." -- E<lt>http://is.gd/l4wDNfE<gt>
60 C<--all> causes umph to ignore the value set with this option.
62 =item B<-m, --max-results> I<arg> (=25)
64 "The max-results parameter specifies the maximum number of results that
65 should be included in the result set.
67 This parameter works in conjunction with the C<--start-index>  parameter
68 to determine which results to return. For example, to request the second
69 set of 10 results, i.e. results 11-20, set the max-results parameter
70 to 10 and the start-index parameter to 11.
72 The default value of this parameter is 25, and the maximum value is 50.
73 However, for displaying lists of videos, we recommend that you set the
74 max-results parameter to 10." -- E<lt>http://is.gd/OcSjwUE<gt>
76 C<--all> causes umph to ignore the value set with this option.
78 =item B<-a, --all>
80 Get all feed items.
82 =item B<-i, --interactive>
84 Open the interactive prompt which can be used to select the items.
85 umph selects I<all> feed items by default. See also L</INTERACTIVE PROMPT>.
87 =item B<-d, --export-format> I<arg>
89 Set the interchange format in which the data is to be printed.
90 Possible values:
92  json .. Print in JSON
93  csv  .. Print in CSV
95 By default, umph prints out each media URL separated by a newline.
97 =item B<--json> (depr.)
99 Print details in JSON. Negates --csv.
100 This option is deprecated since 0.2.2, use C<--export-format>, instead.
102 =item B<--csv> (depr.)
104 Print details in CSV.
105 This option is deprecated since 0.2.2, use C<--export-format>, instead.
107 =item B<--proxy> I<arg>
109 Use I<arg> for HTTP proxy, e.g. "http://foo:1234". Overrides the http_proxy
110 environment setting.
112 =item B<--no-proxy>
114 Disable use of HTTP proxy. Overrides both C<--proxy> and http_proxy
115 environment settings.
117 =back
119 =head1 INTERACTIVE PROMPT
121 Use the C<--interactive> switch to open the prompt. Note that umph
122 uses (as of 0.2.0) the Umph::Prompt module for this. Once the prompt
123 opens, type "help" to get a list of commands available to the prompt.
125 =head1 EXAMPLES
127 =head2 umph AAF3A1D0CA1E304F
129 Get playlist "AAF3A1D0CA1E304F".
131 =head2 umph --json AAF3A1D0CA1E304F
133 Same as above, but print the details in JSON.
135 =head2 umph -s 11 -m 10 AAF3A1D0CA1E304F
137 Same as above but get the items 11-20 from the playlist.
139 =head2 umph -a AAF3A1D0CA1E304F
141 Similar but get I<all> of the items in the playlist. By default, umph gets
142 only the items 1-25 from the list. See also C<--start-index> and
143 C<--max-results>.
145 =head2 umph -t f foo
147 Get favorites for user "foo".
149 =head2 umph -t u foo
151 Get uploads for user "foo".
153 =head2 umph AAF3A1D0CA1E304F | cclive
155 Download the found items with C<cclive(1)>.
157 =head1 EXIT STATUS
159 Exits 0 on success, otherwise 1.
161 =head1 FILES
163 =head2 ~/.umphrc
165 =head3 Example:
167  echo "--interactive" >> ~/.umphrc
169 =head1 NOTES
171 =over 4
173 =item B<http_proxy>
175 umph depends on XML::DOM which uses LWP::UserAgent to fetch the data
176 over the network. LWP::UserAgent reads the http_proxy environment
177 setting. e.g.:
179  env http_proxy=http://foo:1234 umph AAF3A1D0CA1E304F
181 =item B<Unavailable feeds>
183 umph cannot parse "private" lists.
185 =back
187 =head1 WWW
189  Home  : <http://umph.googlecode.com/>
190  gitweb: <http://repo.or.cz/w/umph.git>
192 =head1 LICENSE
194 umph is free software, licensed under the GPLv3+.
196 =head1 SEE ALSO
198 C<cclive(1)>
200 =head1 AUTHOR
202 Toni Gundogdu <legatvs at sign cpan org>