Commit e6eff867 authored by Josh Coalson's avatar Josh Coalson
Browse files

update to match new getopt-based options in flac

parent bf3713ab
......@@ -3,12 +3,12 @@
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
.\" Please send any bug reports, improvements, comments, patches,
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "FLAC" "1" "02 July 2002" "" ""
.TH "FLAC" "1" "13 August 2002" "" ""
.SH NAME
flac \- Free Lossless Audio Codec
.SH SYNOPSIS
\fBflac\fR [ \fB\fIOPTION\fB\fR] \fB\fIinfile\fB\fR \fB\fI...\fB\fR
\fBflac\fR [ \fB\fIOPTION\fB\fR ] \fB\fIinfile\fB\fR \fB\fI...\fB\fR
.SH "DESCRIPTION"
.PP
......@@ -25,37 +25,39 @@ A summary of options is included below. For a complete
description, see the HTML documentation.
.SS "GENERIC OPTIONS"
.TP
\fB-H \fR
Show detailed help screen
\fB-h, --help \fR
Show basic usage and a list of all options
.TP
\fB-d \fR
Decode (default behavior is encode)
\fB-H, --explain \fR
Show detailed explanation of usage and all options
.TP
\fB-c \fR
Encode from standard input, or decode to
standard output
\fB-d, --decode \fR
Decode (the default behavior is to encode)
.TP
\fB-t \fR
\fB-t, --test \fR
Test a flac encoded file (same as -d
except no decoded file is written)
.TP
\fB-a \fR
\fB-a, --analyze \fR
Analyze a flac encoded file (same as -d
except an analysis file is written)
.TP
\fB-s \fR
\fB-c, --stdout \fR
Write output to stdout
.TP
\fB-s, --silent \fR
Silent mode (do not write runtime
encode/decode statistics to stdout)
encode/decode statistics to stderr)
.TP
\fB-o \fIfilename\fB\fR
\fB-o \fIfilename\fB, --output-name=\fIfilename\fB\fR
Force the output file name (usually flac just
changes the extension). May only be used when
encoding a single file. May not be used in
conjunction with --output-prefix.
.TP
\fB--output-prefix \fIstring\fB\fR
\fB--output-prefix=\fIstring\fB\fR
Prefix each output file name with the given
string. This can be useful for encoding/decoding
string. This can be useful for encoding or decoding
files to a different directory. Make sure if your
string is a path name that it ends with a trailing
`/' (slash).
......@@ -66,25 +68,25 @@ successful encode or decode. If there was an
error (including a verify error) the input file
is left intact.
.TP
\fB--skip \fIsamples\fB\fR
\fB--skip=\fI#\fB\fR
Skip the specified number of samples at the
beginning of the input file (can be used for both
encoding and decoding)
.SS "ANALYSIS OPTIONS"
.TP
\fB--a-rtext \fR
\fB--residual-text \fR
Includes the residual signal in the analysis
file. This will make the file very big, much
larger than even the decoded file.
.TP
\fB--a-rgp \fR
\fB--residual-gnuplot \fR
Generates a gnuplot file for every subframe;
each file will contain the residual distribution
of the subframe. This will create a lot of
files.
.SS "DECODING OPTIONS"
.TP
\fB-F \fR
\fB-F, --decode-through-errors \fR
By default flac stops decoding with an error
and removes the partially decoded file if it
encounters a bitstream error. With -F, errors are
......@@ -94,6 +96,11 @@ audio to be missing some samples or have silent
sections.
.SS "ENCODING OPTIONS"
.TP
\fB-V, --verify\fR
Verify a correct encoding by decoding the
output in parallel and comparing to the
original
.TP
\fB--ogg\fR
When encoding, generate Ogg-FLAC output instead
of native-FLAC. Ogg-FLAC streams are FLAC streams
......@@ -114,7 +121,7 @@ Align encoding of multiple CD format WAVE
files on sector boundaries. See the HTML
documentation for more information.
.TP
\fB-S \fI{ # | X | #x }\fB\fR
\fB-S {\fI#\fB|\fIX\fB|\fI#x\fB}, --seekpoint={\fI#\fB|\fIX\fB|\fI#x\fB}\fR
Include a point or points in a SEEKTABLE. Using #,
a seek point at that sample number is added. Using
X, a placeholder point is added at the end of a the
......@@ -131,7 +138,7 @@ point entered (if the input size is determinable
before encoding starts) or a placeholder point (if
input size is not determinable).
.TP
\fB-P \fIbytes\fB\fR
\fB-P \fI#\fB, --padding=\fI#\fB\fR
Tell the encoder to write a PADDING metadata
block of the given length (in bytes) after the
STREAMINFO block. This is useful if you plan to
......@@ -144,50 +151,51 @@ the length given because of the 4 metadata block
header bytes. You can force no PADDING block at
all to be written with -P-, which is the default.
.TP
\fB-b \fIblocksize\fB\fR
Default is 1152 for -l 0, else 4608; must be
192/576/1152/2304/4608/256/512/1024/2048/4096/8192/16384/32768
(unless --lax is used)
\fB-b \fI#\fB, --blocksize=\fI#\fB\fR
Specify the block size in samples. The
default is 1152 for -l 0, else 4608; must be one of
192, 576, 1152, 2304, 4608, 256, 512, 1024, 2048,
4096, 8192, 16384, or 32768 (unless --lax is used)
.TP
\fB-m\fR
\fB-m, --mid-side\fR
Try mid-side coding for each frame (stereo
input only)
.TP
\fB-M\fR
Loose mid-side coding for all frames (stereo
\fB-M, --adaptive-mid-side\fR
Adaptive mid-side coding for all frames (stereo
input only)
.TP
\fB-0..-8\fR
\fB-0..-8, --compression-level-0..--compression-level-8\fR
Fastest compression..highest compression
(default is -5). These are synonyms for other
options:
.RS
.TP
\fB-0\fR
\fB-0, --compression-level-0\fR
Synonymous with -l 0 -b 1152 -r 2,2
.TP
\fB-1\fR
\fB-1, --compression-level-1\fR
Synonymous with -l 0 -b 1152 -M -r 2,2
.TP
\fB-2\fR
\fB-2, --compression-level-2\fR
Synonymous with -l 0 -b 1152 -m -r 3
.TP
\fB-3\fR
\fB-3, --compression-level-3\fR
Synonymous with -l 6 -b 4608 -r 3,3
.TP
\fB-4\fR
\fB-4, --compression-level-4\fR
Synonymous with -l 8 -b 4608 -M -r 3,3
.TP
\fB-5\fR
\fB-5, --compression-level-5\fR
Synonymous with -l 8 -b 4608 -m -r 3,3
.TP
\fB-6\fR
\fB-6, --compression-level-6\fR
Synonymous with -l 8 -b 4608 -m -r 4
.TP
\fB-7\fR
\fB-7, --compression-level-7\fR
Synonymous with -l 8 -b 4608 -m -e -r 6
.TP
\fB-8\fR
\fB-8, --compression-level-8\fR
Synonymous with -l 12 -b 4608 -m -e -r 6
.RE
.TP
......@@ -199,66 +207,89 @@ synonymous with -0.
Highest compression. Currently
synonymous with -8.
.TP
\fB-e\fR
\fB-e, --exhaustive-model-search\fR
Do exhaustive model search
(expensive!)
.TP
\fB-E\fR
\fB-E, --escape-coding\fR
Do escape coding in the entropy coder. This
causes the encoder to use an unencoded representation
of the residual in a partition if it is smaller. It
increases the runtime and usually results in an
improvement of less than 1%.
.TP
\fB-l \fImax_lpc_order\fB\fR
0 => use only fixed predictors
\fB-l \fI#\fB, --max-lpc-order=\fI#\fB\fR
Set the maximum LPC order; 0 means use only the fixed predictors
.TP
\fB-p\fR
\fB-p, --qlp-coeff-precision-search\fR
Do exhaustive search of LP coefficient
quantization (expensive!). Overrides -q,
quantization (expensive!). Overrides -q;
does nothing if using -l 0
.TP
\fB-q \fIbits\fB\fR
\fB-q \fI#\fB, --qlp-coeff-precision=\fI#\fB\fR
Precision of the quantized linear-predictor
coefficients, 0 => let encoder decide (min is 5,
default is 0)
.TP
\fB-r \fI[level,]level\fB\fR
\fB-r [\fI#\fB,]\fI#\fB, --rice-partition-order=[\fI#\fB,]\fI#\fB\fR
Set the [min,]max residual partition order
(0..16). min defaults to 0 if unspecified. Default
is -r 3,3.
.TP
\fB-V\fR
Verify a correct encoding by decoding the
output in parallel and comparing to the
original
.TP
\fB-F- -S- -P- -m- -M- -e- -E- -p- -V- --delete-input-file- --lax- --ogg- \fR
These flags can be used to invert the sense
of the corresponding normal option.
.SS "FORMAT OPTIONS"
.TP
\fB-fb\fR
Big-endian byte order
\fB--endian={\fIbig\fB|\fIlittle\fB}\fR
Set the byte order for samples
.TP
\fB-fl\fR
Little-endian byte order
.TP
\fB-fc \fIchannels\fB\fR
\fB--channels=\fI#\fB\fR
Set number of channels.
.TP
\fB-fp \fIbits_per_sample\fB\fR
\fB--bps=\fI#\fB\fR
Set bits per sample.
.TP
\fB-fs \fIsample_rate\fB\fR
\fB--sample-rate=\fI#\fB\fR
Set sample rate (in Hz).
.TP
\fB-fu\fR
Unsigned samples (default is signed)
\fB--sign={\fIsigned\fB|\fIunsigned\fB}\fR
Set the sign of samples (the default is signed).
.TP
\fB-fr\fR
Force to raw format (even if filename ends
\fB--force-raw-input\fR
Force input to be treated as raw samples (even if filename ends
in \fI.wav\fR).
.SS "NEGATIVE OPTIONS"
.TP
\fB--no-adaptive-mid-side\fR
.TP
\fB--no-decode-through-errors\fR
.TP
\fB--no-delete-input-file\fR
.TP
\fB--no-escape-coding\fR
.TP
\fB--no-exhaustive-model-search\fR
.TP
\fB--no-lax\fR
.TP
\fB--no-mid-side\fR
.TP
\fB--no-ogg\fR
.TP
\fB--no-padding\fR
.TP
\fB--no-qlp-coeff-precision-search\fR
.TP
\fB--no-residual-gnuplot\fR
.TP
\fB--no-residual-text\fR
.TP
\fB--no-sector-align\fR
.TP
\fB--no-seektable\fR
.TP
\fB--no-silent\fR
.TP
\fB--no-verify\fR
These flags can be used to invert the sense
of the corresponding normal option.
.SH "SEE ALSO"
.PP
The programs are documented fully by HTML format
......
......@@ -4,7 +4,7 @@
<!ENTITY dhfirstname "<firstname>Matt</firstname>">
<!ENTITY dhsurname "<surname>Zimmerman</surname>">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY dhdate "<date>June 04, 2002</date>">
<!ENTITY dhdate "<date>August 13, 2002</date>">
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
allowed: see man(7), man(1). -->
<!ENTITY dhsection "<manvolnum>1</manvolnum>">
......@@ -74,32 +74,31 @@
<variablelist>
<varlistentry>
<term><option>-H</option>
<term><option>-h</option>, <option>--help</option>
</term>
<listitem>
<para>Show detailed help screen</para>
<para>Show basic usage and a list of all options</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>
<term><option>-H</option>, <option>--explain</option>
</term>
<listitem>
<para>Decode (default behavior is encode)</para>
<para>Show detailed explanation of usage and all options</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>
</term>
<listitem>
<para>Encode from standard input, or decode to
standard output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--decode</option>
</term>
<listitem>
<para>Decode (the default behavior is to encode)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option>
<term><option>-t</option>, <option>--test</option>
</term>
<listitem>
<para>Test a flac encoded file (same as -d
......@@ -108,7 +107,7 @@
</varlistentry>
<varlistentry>
<term><option>-a</option>
<term><option>-a</option>, <option>--analyze</option>
</term>
<listitem>
<para>Analyze a flac encoded file (same as -d
......@@ -116,17 +115,25 @@
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>, <option>--stdout</option>
</term>
<listitem>
<para>Write output to stdout</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>
<term><option>-s</option>, <option>--silent</option>
</term>
<listitem>
<para>Silent mode (do not write runtime
encode/decode statistics to stdout)</para>
encode/decode statistics to stderr)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o</option> <replaceable>filename</replaceable></term>
<term><option>-o</option> <replaceable>filename</replaceable>, <option>--output-name</option>=<replaceable>filename</replaceable></term>
<listitem>
<para>Force the output file name (usually flac just
changes the extension). May only be used when
......@@ -136,10 +143,10 @@
</varlistentry>
<varlistentry>
<term><option>--output-prefix</option> <replaceable>string</replaceable></term>
<term><option>--output-prefix</option>=<replaceable>string</replaceable></term>
<listitem>
<para>Prefix each output file name with the given
string. This can be useful for encoding/decoding
string. This can be useful for encoding or decoding
files to a different directory. Make sure if your
string is a path name that it ends with a trailing
`/' (slash).</para>
......@@ -158,7 +165,7 @@
</varlistentry>
<varlistentry>
<term><option>--skip</option> <replaceable>samples</replaceable></term>
<term><option>--skip</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Skip the specified number of samples at the
beginning of the input file (can be used for both
......@@ -174,7 +181,7 @@
<variablelist>
<varlistentry>
<term><option>--a-rtext</option>
<term><option>--residual-text</option>
</term>
<listitem>
<para>Includes the residual signal in the analysis
......@@ -184,7 +191,7 @@
</varlistentry>
<varlistentry>
<term><option>--a-rgp</option>
<term><option>--residual-gnuplot</option>
</term>
<listitem>
<para>Generates a gnuplot file for every subframe;
......@@ -202,7 +209,7 @@
<variablelist>
<varlistentry>
<term><option>-F</option>
<term><option>-F</option>, <option>--decode-through-errors</option>
</term>
<listitem>
<para>By default flac stops decoding with an error
......@@ -222,6 +229,16 @@
<title>Encoding Options</title>
<variablelist>
<varlistentry>
<term><option>-V</option>, <option>--verify</option></term>
<listitem>
<para>Verify a correct encoding by decoding the
output in parallel and comparing to the
original</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--ogg</option></term>
......@@ -257,7 +274,7 @@
</varlistentry>
<varlistentry>
<term><option>-S</option> <replaceable>{ # | X | #x }</replaceable></term>
<term><option>-S</option> {<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>}, <option>--seekpoint</option>={<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>}</term>
<listitem>
<para>
......@@ -280,7 +297,7 @@
</varlistentry>
<varlistentry>
<term><option>-P</option> <replaceable>bytes</replaceable></term>
<term><option>-P</option> <replaceable>#</replaceable>, <option>--padding</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Tell the encoder to write a PADDING metadata
......@@ -299,17 +316,18 @@
</varlistentry>
<varlistentry>
<term><option>-b</option> <replaceable>blocksize</replaceable></term>
<term><option>-b</option> <replaceable>#</replaceable>, <option>--blocksize</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Default is 1152 for -l 0, else 4608; must be
192/576/1152/2304/4608/256/512/1024/2048/4096/8192/16384/32768
(unless --lax is used)</para>
<para>Specify the block size in samples. The
default is 1152 for -l 0, else 4608; must be one of
192, 576, 1152, 2304, 4608, 256, 512, 1024, 2048,
4096, 8192, 16384, or 32768 (unless --lax is used)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-m</option></term>
<term><option>-m</option>, <option>--mid-side</option></term>
<listitem>
<para>Try mid-side coding for each frame (stereo
......@@ -318,16 +336,16 @@
</varlistentry>
<varlistentry>
<term><option>-M</option></term>
<term><option>-M</option>, <option>--adaptive-mid-side</option></term>
<listitem>
<para>Loose mid-side coding for all frames (stereo
<para>Adaptive mid-side coding for all frames (stereo
input only)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-0</option>..<option>-8</option></term>
<term><option>-0</option>..<option>-8</option>, <option>--compression-level-0</option>..<option>--compression-level-8</option></term>
<listitem>
<para>Fastest compression..highest compression
......@@ -336,7 +354,7 @@
<variablelist>
<varlistentry>
<term><option>-0</option></term>
<term><option>-0</option>, <option>--compression-level-0</option></term>
<listitem>
<para>Synonymous with -l 0 -b 1152 -r 2,2
......@@ -345,7 +363,7 @@
</varlistentry>
<varlistentry>
<term><option>-1</option></term>
<term><option>-1</option>, <option>--compression-level-1</option></term>
<listitem>
<para>Synonymous with -l 0 -b 1152 -M -r 2,2
......@@ -354,7 +372,7 @@
</varlistentry>
<varlistentry>
<term><option>-2</option></term>
<term><option>-2</option>, <option>--compression-level-2</option></term>
<listitem>
<para>Synonymous with -l 0 -b 1152 -m -r 3
......@@ -363,7 +381,7 @@
</varlistentry>
<varlistentry>
<term><option>-3</option></term>
<term><option>-3</option>, <option>--compression-level-3</option></term>
<listitem>
<para>Synonymous with -l 6 -b 4608 -r 3,3
......@@ -372,7 +390,7 @@
</varlistentry>
<varlistentry>
<term><option>-4</option></term>
<term><option>-4</option>, <option>--compression-level-4</option></term>
<listitem>
<para>Synonymous with -l 8 -b 4608 -M -r 3,3
......@@ -381,7 +399,7 @@
</varlistentry>
<varlistentry>
<term><option>-5</option></term>
<term><option>-5</option>, <option>--compression-level-5</option></term>
<listitem>
<para>Synonymous with -l 8 -b 4608 -m -r 3,3
......@@ -390,7 +408,7 @@
</varlistentry>
<varlistentry>
<term><option>-6</option></term>
<term><option>-6</option>, <option>--compression-level-6</option></term>
<listitem>
<para>Synonymous with -l 8 -b 4608 -m -r 4
......@@ -399,7 +417,7 @@
</varlistentry>
<varlistentry>
<term><option>-7</option></term>
<term><option>-7</option>, <option>--compression-level-7</option></term>
<listitem>
<para>Synonymous with -l 8 -b 4608 -m -e -r 6
......@@ -408,7 +426,7 @@
</varlistentry>
<varlistentry>
<term><option>-8</option></term>
<term><option>-8</option>, <option>--compression-level-8</option></term>
<listitem>
<para>Synonymous with -l 12 -b 4608 -m -e -r 6
......@@ -419,7 +437,6 @@
</listitem>
</varlistentry>
<varlistentry>
......@@ -441,7 +458,7 @@
</varlistentry>
<varlistentry>
<term><option>-e</option></term>
<term><option>-e</option>, <option>--exhaustive-model-search</option></term>
<listitem>
<para>Do exhaustive model search
......@@ -450,7 +467,7 @@
</varlistentry>
<varlistentry>
<term><option>-E</option></term>
<term><option>-E</option>, <option>--escape-coding</option></term>
<listitem>
<para>Do escape coding in the entropy coder. This
......@@ -462,25 +479,25 @@
</varlistentry>
<varlistentry>
<term><option>-l</option> <replaceable>max_lpc_order</replaceable></term>
<term><option>-l</option> <replaceable>#</replaceable>, <option>--max-lpc-order</option>=<replaceable>#</replaceable></term>
<listitem>
<para>0 => use only fixed predictors</para>
<para>Set the maximum LPC order; 0 means use only the fixed predictors</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option></term>
<term><option>-p</option>, <option>--qlp-coeff-precision-search</option></term>
<listitem>
<para>Do exhaustive search of LP coefficient
quantization (expensive!). Overrides -q,
quantization (expensive!). Overrides -q;
does nothing if using -l 0</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-q</option> <replaceable>bits</replaceable></term>
<term><option>-q</option> <replaceable>#</replaceable>, <option>--qlp-coeff-precision</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Precision of the quantized linear-predictor
......@@ -490,7 +507,7 @@
</varlistentry>
<varlistentry>
<term><option>-r</option> <replaceable>[level,]level</replaceable></term>
<term><option>-r</option> [<replaceable>#</replaceable>,]<replaceable>#</replaceable>, <option>--rice-partition-order</option>=[<replaceable>#</replaceable>,]<replaceable>#</replaceable></term>
<listitem>
<para>Set the [min,]max residual partition order
......@@ -499,25 +516,6 @@
</listitem>
</varlistentry>
<varlistentry>
<term><option>-V</option></term>
<listitem>
<para>Verify a correct encoding by decoding the
output in parallel and comparing to the
original</para>
</listitem>