From 50684425b130fc125dec62961e6dbb0649fb1abe Mon Sep 17 00:00:00 2001 From: Toni Gundogdu Date: Fri, 21 Oct 2011 23:57:25 +0300 Subject: [PATCH] Revise manual --- doc/man1/clive.1.pod | 263 +++++++++++++++++++++++++++++---------------------- 1 file changed, 152 insertions(+), 111 deletions(-) diff --git a/doc/man1/clive.1.pod b/doc/man1/clive.1.pod index 3965aa4..588cbf6 100644 --- a/doc/man1/clive.1.pod +++ b/doc/man1/clive.1.pod @@ -8,89 +8,106 @@ clive [EoptionsE] [EurlE | EfileE ...] =head1 DESCRIPTION -clive is a command line media extraction tool for Youtube and similar -websites that require Adobe Flash. +clive is a command line media extraction tool for YouTube and similar +websites that require flash. -=head1 HISTORY +=head2 Background -clive originates from the need to work around the Adobe Flash player -requirement with YouTube. It was originally a simple shell script -that parsed the media stream URLs and used a third party command -to download the media. +clive originates from a simple shell script that was cooked up to work +around the YouTube's flash requirement back in 2006. -=head1 GETTING STARTED +=head2 Getting started -clive attempts to detect the typical commands used with L and -L from the $PATH, and uses the predefined values with them. +=head3 Configuring -See L for an example configuration file. You should at least -define L and L in your configuration file for -seamless use. +=head4 Autodetection -The sections L and L contain invaluable -information about using clive. +clive will attempt to autodetect the required commands from the $PATH, +when they have not been defined in either config file or the command +line. -=head1 OPTIONS +=head4 Configuration file + +See L for an example configuration file. You may want to +consider adding at least the L and L there. -Unless an arg is specified in the command line, clive reads from the -stdin. The command line args may be either URLs or files to read. -If clive reads from either stdin or files, it expects each URL to be -separated by a newline character. +=head4 See also -=over 4 +L, L and L. + +=head1 OPTIONS -=item B<--help> +clive expects the URLs to be separated by a newline character when the +they are read from either stdin or files. + +=head2 --help Print help and exit. -=item B<--version> +=head2 --version Print version and exit. -=item B<--license> +=head2 --license Print license and exit. -=item B<-q, --quiet> +=head2 -q, --quiet Turn off all I output excluding errors. Note that this switch has no effect on any of the third party commands that clive invokes. -=item B<-F, --query-formats> +=head2 -F, --query-formats + +Query available formats to an URL. The returned string will contain +an array of I, each separated by the '|' character. +The array is created, by libquvi, from the data returned by the server. +You can use these I with C<--format>. + +See also L and C<--format>. -Query available formats. +=head2 -f, --format I (=default) -=item B<-f, --format> I (=default) +Download format I of the media. The I can also be C, +C, C or C. Note, however, that of these, the C and +the C are deprecated and will be removed in the later versions of +clive. -Download format I of the media. I can also be C or C. -The resulting format may be different from the I if the requested -format was not available. This is determined by libquvi, not clive. +The I value is used with all of the URLs fed to clive at runtime. If +the I is C, libquvi will determine the C format available +to an URL. -I C is deprecated and will be removed in the later versions. -Use C<--query-formats> instead. +If the I is C libquvi attempts to return an URL to whatever +was deemed to be the C format to the URL. libquvi will switch +to C format if the I was unregognized or the requested +I format was unavailable. -=item B<-O, --output-file> I +For the above reasons, the downloaded format may be different from the +requested I format. + +For details about the YouTube's "fmt" IDs, refer to: + http://en.wikipedia.org/wiki/YouTube#Quality_and_codecs + +See also L, C<--query-formats>. + +=head2 -O, --output-file I Write media to I. Overrides C<--filename-format>. -=item B<-n, --no-download> +=head2 -n, --no-download Do not download the media, print details only. -=item B<--config-file> I +=head2 --config-file I Path to a file to read clive arguments from. See also L. -=back - =head1 OPTIONS - CONFIGURATION -In addition to the command line, the options may also be read from the -configuration file. See L. - -=over 4 +The C options may be read from the config file. +See L. -=item B<--quvi> I +=head2 --quvi I I to be invoked to start the C command which clive uses to parse the media details. This is typically a full path to C with @@ -103,12 +120,7 @@ The following specifiers can be used in the I: I occurences of the specifier will be replaced. clive will automatically append C<--quiet> to I. -NOTE: If you use an HTTP proxy with C, you should do the same with -C<--get-with> -- especially if the proxy masks your (real) IP. Some websites -may refuse connections originating from different IPs to (unique, generated) -media stream URLs. - -=item B<--get-with> I +=head2 --get-with I Path to a download command (e.g. C or C) with any additional arguments. clive invokes this command to download the media. Overrides any @@ -116,149 +128,178 @@ value set by autodetection. The following specifiers are supported: + %n Media filename (after applying --regexp and --filename-format) + %f Path to downloaded media file (output path and %n) %u Media stream URL - %f Full path to media file - %n Media file name -I occurences of the specifier will be replaced. See also the -note above about using an HTTP proxy with C<--quvi>. +I occurences of the specifier will be replaced. -=item B<--filename-format> I (="%t.%s") +=head2 --filename-format I (="%t.%s") Use I to specify the media output filename format. The following specifiers are supported: %t Media title (after applying --regexp) + %h Media host ID + %s File suffix %i Media ID - %h Media host ID (req. quvi 0.2.8+) - %s Media file suffix (parsed from server returned content-type) I occurences of the specifier will be replaced. -=item B<--regexp> I (="/(\w|\s)/g") +=head2 --regexp I (="/(\w|\s)/g") Use regular expression I to clean up the media title before it is used in the filename. The syntax supports both "i" (case-insensitive) and "g" (global or "find all"). -=item B<--exec> I +=head2 --exec I Invoke I after media download finishes. The following specifiers are supported: - %f Full path to the downloaded media file + %f Path to the downloaded media file I occurences of the specifier will be replaced. -=back - =head1 TROUBLESHOOTING -=over 4 - -=item B +=head2 error: specify path to quvi(1) command with --quvi clive uses C to parse the media details. Use the C<--quvi> to specify the path. See also L. -=item B +=head2 error: specify path to a download command with --get-with clive uses a 3rd party command to download the media. Use the C<--get-with> to specify the path to such command. See also L. -=back +=head2 HTTP/1.0 500 Internal Server Error -=head1 FILES +Any number of reasons. Some have been tracked back to unacceptable +user-agent string value and mangled HTTP headers (e.g. a green-eyed +HTTP proxy). See also L. + +=head1 KNOWN ISSUES + +=head2 Resuming partially transferred files may fail + +Some websites are known to refuse to work with the HTTP requests to +resume a file transfer. + +=head3 Workaround + +None known. You will have to remove the existing file before you try +again. + +=head2 HTTP user-agent + +Some websites refuse to play nice with renegade user-agent strings. + +=head3 Recommendations + +Make sure both C and C use the same user-agent string. +Note that C uses "Mozilla/5.0" by default. See also +L for C. -=over 4 +=head2 HTTP proxy -=item B<~/.cliverc> +Generally OK, although some proxies may have been configured to +C the HTTP headers before they are sent back to the server. +This may sometimes lead to issues with the servers. -Additional search paths: +=head3 Recommendations - ~/.clive/config - ~/.config/clive/config +If you use an HTTP proxy, make sure you have configured all of the commands +that clive uses (e.g. C, C, etc.) to use the same proxy. -For a system-wide configuration: +=head2 Exit status - /usr/local/share/clive/config - /usr/share/clive/config - /etc/clive/config - /etc/xdg/clive/clive.conf - /etc/xdg/clive.conf +If you are planning to use clive for anything more peculiar, consider the +following example: + + * You feed clive two URLs + * The 1st one fails, quvi exits with a non-zero value + * clive proceeds to the 2nd URL, quvi now exits with zero value + * clive exits with the zero, even if the 1st URL failed + +=head3 Workaround + +Feed one URL at a time. + +=head1 FILES + +=head2 Local user + + * ~/.config/clive/config + * ~/.clive/config + * ~/.cliverc + +=head2 System wide + + * /usr/local/share/clive/config + * /etc/xdg/clive/clive.conf + * /usr/share/clive/config + * /etc/xdg/clive.conf + * /etc/clive/config + +=head2 CLIVE_CONFIG You can also set CLIVE_CONFIG, e.g.: env CLIVE_CONFIG=/path/to/config/file clive +=head2 --config-file + Or use C<--config-file>, e.g.: clive --config-file /path/to/config/file +=head2 Example config + A typical configuration file could look like: - --quvi "/usr/bin/quvi %u" - # Recommended value to be used with quvi 0.2.12+ - # --quvi "/usr/bin/quvi --category-http %u" - --get-with "/usr/bin/curl -L -C - -o %f %u" + --get-with "/usr/bin/curl -L -C - -o %f %u --user-agent Mozilla/5.0" + --quvi "/usr/bin/quvi --category-http %u" --filename-format "%t_%i.%s" --exec "/usr/bin/vlc %f" -You should set at very least L and L in your -configuration file for seamless use. - -=back - =head1 EXAMPLES -These examples assume you have set C<--quvi> and C<--get-with> in the config -file. See L for an example config file. +=head2 Note Put the URLs inside quotes when they are specified as the command line arguments to the program. This is the recommended practice. -=over 4 - -=item clive "URL" +=head2 clive "URL" Typical use. -=item clive -f best "URL" +=head2 clive -f best "URL" -Download the best available format of the media. This assumes E1 -formats are supported, otherwise will fallback to default format. +Download the best available format of the media. -=item clive -F "URL" +=head2 clive -F "URL" Query available formats to the URL. Use one of the returned format strings from this list with C<--format>. -=item clive -n "URL" +=head2 clive -n "URL" Do not download the media, print the details only. -=back - =head1 EXIT STATUS -clive exits with 0 on success, otherwise the code is E0. Strictly clive -exit statuses are 0 or 1. For example, if command line parsing fails, the exit -status is 1. +clive exits with 0 on success, otherwise the code is E0. For example, +if command line parsing fails, the exit status is 1. When an error occurs in another command invoked by clive, e.g. C, -clive exits with the exit status returned by the command. - -If you are planning to use clive for anything more peculiar, you should feed -it only one URL at a time. For example: +clive then exits with the exit status returned by that command. - * You feed clive two URLs - * The 1st one fails, quvi exits with a non-zero value - * clive proceeds to the 2nd URL, quvi now exits with zero value - * clive exits with the zero, even if the 1st URL failed +See also L for L. =head1 SEE ALSO -C C C +C C =head1 WWW -- 2.11.4.GIT