add baudline to the list of progs that use flac
[flac.git] / doc / documentation.html
index b769a9b..34c09e5 100644 (file)
        <TABLE CELLSPACING="0" CELLPADDING="3" WIDTH="100%" BORDER="0" BGCOLOR="#EEEED4">
        <TR><TD><FONT FACE="Lucida,Verdana,Helvetica,Arial">
        <P>
-               <B><TT>flac</TT></B> is the command-line file encoder/decoder.  The input to the encoder and the output to the decoder must either be RIFF WAVE format, or raw interleaved sample data.  <B><TT>flac</TT></B> only supports linear PCM samples (in other words, no A-LAW, uLAW, etc.).  Another restriction (hopefully short-term) is that the input must be 8 or 16 bits per sample.  This is not a limitation of the FLAC format, just the reference encoder.
+               <B><TT>flac</TT></B> is the command-line file encoder/decoder.  The input to the encoder and the output to the decoder must either be RIFF WAVE format, or raw interleaved sample data.  <B><TT>flac</TT></B> only supports linear PCM samples (in other words, no A-LAW, uLAW, etc.).  Another restriction (hopefully short-term) is that the input must be 8, 16, or 24 bits per sample.  This is not a limitation of the FLAC format, just the reference encoder.
        </P>
        <P>
                <B><TT>flac</TT></B> assumes that RIFF WAVE files will have the extension ".wav"; this may be overridden with a command-line option.  Other than this, <B><TT>flac</TT></B> makes no assumptions about file extensions, though the convention is that FLAC files have the extension ".flac" (or ".fla" on ancient file systems like FAT-16).
        </P>
        <P>
-               Before going into the full command-line description, two other things help to sort it out: 1) <B><TT>flac</TT></B> encodes by default, so you must use <B>-d</B> to decode; 2) the options <B><TT>-0</TT></B> .. <B><TT>-9</TT></B> that control the compression level actually are just synonyms for different groups of specific coding options (described later).  You can get the same effect by using the same options.
+               Before going into the full command-line description, two other things help to sort it out: 1) <B><TT>flac</TT></B> encodes by default, so you must use <B>-d</B> to decode; 2) the options <B><TT>-0</TT></B> .. <B><TT>-9</TT></B> that control the compression level actually are just synonyms for different groups of specific encoding options (described later).  You can get the same effect by using the same options.
        </P>
        <P>
                <B><TT>flac</TT></B> will be invoked one of four ways, depending on whether you are encoding, decoding, testing, or analyzing:
                <UL>
                <LI>
-                       Encoding: flac [-s] [--skip #] [&lt;format-options&gt;] [&lt;encoding options&gt;] inputfile outputfile
+                       Encoding: flac [-s] [--skip #] [<I><A HREF="#format_options">&lt;format-options&gt;</A></I>] [<I><A HREF="#encoding_options">&lt;encoding options&gt;</A></I>] inputfile outputfile
                </LI>
                <LI>
-                       Decoding: flac -d [-s] [--skip #] [&lt;format-options&gt;] inputfile outputfile
+                       Decoding: flac -d [-s] [--skip #] [<I><A HREF="#format_options">&lt;format-options&gt;</A></I>] inputfile outputfile
                </LI>
                <LI>
                        Testing: flac -t [-s] inputfile
                </LI>
                <LI>
-                       Analyzing: flac -a [-s] [--skip #] inputfile outputfile
+                       Analyzing: flac -a [-s] [--skip #] [<I><A HREF="#analysis_options">&lt;analysis-options&gt;</A></I>] inputfile outputfile
                </LI>
                </UL>
        </P>
        <TABLE WIDTH="100%" BORDER="1" BGCOLOR="#EEEED4">
                <TR>
                        <TD COLSPAN="2" BGCOLOR="#D3D4C5">
-                               <FONT SIZE="+1"><B>General Options</B></FONT>
+                               <A NAME="general_options"><FONT SIZE="+1"><B>General Options</B></FONT></A>
                        </TD>
                </TR>
                <TR>
        <TABLE WIDTH="100%" BORDER="1" BGCOLOR="#EEEED4">
                <TR>
                        <TD COLSPAN="2" BGCOLOR="#D3D4C5">
-                               <FONT SIZE="+1"><B>Encoding Options</B></FONT>
+                               <A NAME="analysis_options"><FONT SIZE="+1"><B>Analysis Options</B></FONT></A>
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               --a-rtext
+                       </TD>
+                       <TD>
+                               Includes the residual signal in the analysis file.  This will make the file <B>very</B> big, much larger than even the decoded file.
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               --a-rgp
+                       </TD>
+                       <TD>
+                               Generates a gnuplot file for every subframe; each file will contain the residual distribution of the subframe.  This will create a <B>lot</B> of files.
+                       </TD>
+               </TR>
+       </TABLE>
+       </TD></TR></TABLE>
+       </P>
+       <P>
+       <TABLE WIDTH="100%" BORDER="0" CELLSPACING="0" CELLPADDING="0" BGCOLOR="#EEEED4"><TR><TD>
+       <TABLE WIDTH="100%" BORDER="1" BGCOLOR="#EEEED4">
+               <TR>
+                       <TD COLSPAN="2" BGCOLOR="#D3D4C5">
+                               <A NAME="encoding_options"><FONT SIZE="+1"><B>Encoding Options</B></FONT></A>
                        </TD>
                </TR>
                <TR>
                </TR>
                <TR>
                        <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               -S { # | X | #x }
+                       </TD>
+                       <TD>
+                               Include a point or points in a SEEKTABLE:<BR>
+                               <UL>
+                               <LI>
+                                       <TT>#&nbsp;</TT> : a specific sample number for a seek point
+                               </LI>
+                               <LI>
+                                       <TT>X&nbsp;</TT> : a placeholder point (always goes at the end of the SEEKTABLE)
+                               </LI>
+                               <LI>
+                                       <TT>#x</TT> : # evenly spaced seekpoints, the first being at sample 0
+                               </LI>
+                               </UL>
+                               You may use many -S options; the resulting SEEKTABLE will be the unique-ified union of all such values.<BR>
+                               With no -S options, flac defaults to '-S 100x'.  Use -S- for no SEEKTABLE.<BR>
+                               NOTE: -S #x will not work if the encoder can't determine the input size before starting.<BR>
+                               NOTE: if you use -S # and # is >= samples in the input, there will be either no seek point entered (if the input size is determinable before encoding starts) or a placeholder point (if input size is not determinable)<BR>
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
                                -P #
                        </TD>
                        <TD>
                                -b #
                        </TD>
                        <TD>
-                               Set the blocksize.  The default is 1152 for -l 0, otherwise 4608.  Subset streams must use one of 192/576/1152/2304/4608.  The current encoder uses the same blocksize for the entire stream.
+                               Specify the blocksize in samples.  The default is 1152 for -l 0, otherwise 4608.  Subset streams must use one of 192/576/1152/2304/4608/256/512/1024/2048/4096/8192/16384/32768.  The current encoder uses the same blocksize for the entire stream.
                        </TD>
                </TR>
                <TR>
                                -0
                        </TD>
                        <TD>
-                               Synonymous with -l 0
+                               Synonymous with -l 0 -b 1152
                        </TD>
                </TR>
                <TR>
                                -1
                        </TD>
                        <TD>
-                               Synonymous with -l 0 -M
+                               Synonymous with -l 0 -b 1152 -M
                        </TD>
                </TR>
                <TR>
                                -2
                        </TD>
                        <TD>
-                               Synonymous with -l 0 -m -r # (where # is set based on the blocksize)
+                               Synonymous with -l 0 -b 1152 -m -r 2
                        </TD>
                </TR>
                <TR>
                                -4
                        </TD>
                        <TD>
-                               Synonymous with -l 8
+                               Synonymous with -l 8 -b 4608
                        </TD>
                </TR>
                <TR>
                                -5
                        </TD>
                        <TD>
-                               Synonymous with -l 8 -M
+                               Synonymous with -l 8 -b 4608 -M
                        </TD>
                </TR>
                <TR>
                                -6
                        </TD>
                        <TD>
-                               Synonymous with -l 8 -m -r # (where # is set based on the blocksize)
+                               Synonymous with -l 8 -b 4608 -m -r 4
                        </TD>
                </TR>
                <TR>
                                -8
                        </TD>
                        <TD>
-                               Synonymous with -l 32 -m -r # (where # is set based on the blocksize)
+                               Synonymous with -l 32 -b 4608 -m -r 4
                        </TD>
                </TR>
                <TR>
                                -9
                        </TD>
                        <TD>
-                               Synonymous with -l 32 -m -e -r 99 -p.  This is painfully slow but gives you the maximum compression <B><TT>flac</TT></B> can do for a given blocksize.
+                               Synonymous with -l 32 -b 4608 -m -e -r 99 -p.  This is painfully slow but gives you the maximum compression <B><TT>flac</TT></B> can do for a given blocksize.
                        </TD>
                </TR>
                <TR>
                        <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
                        </TD>
                        <TD>
-                               -m-, -e-, -p-, -V-, --lax- can all be used to turn off a particular option.
+                               -S-, -m-, -e-, -p-, -V-, --lax- can all be used to turn off a particular option.
                        </TD>
                </TR>
        </TABLE>
        <TABLE WIDTH="100%" BORDER="1" BGCOLOR="#EEEED4">
                <TR>
                        <TD COLSPAN="2" BGCOLOR="#D3D4C5">
-                               <FONT SIZE="+1"><B>Format Options</B></FONT>
+                               <A NAME="format_options"><FONT SIZE="+1"><B>Format Options</B></FONT></A>
                        </TD>
                </TR>
                <TR>
        <TABLE CELLSPACING="0" CELLPADDING="3" WIDTH="100%" BORDER="0" BGCOLOR="#EEEED4">
        <TR><TD><FONT FACE="Lucida,Verdana,Helvetica,Arial">
        <P>
-               Bug tracking is done on the Sourceforge project page <A HREF="http://sourceforge.net/bugs/?group_id=13478">here</A>.
+               Bug tracking is done on the Sourceforge project page <A HREF="http://sourceforge.net/bugs/?group_id=13478">here</A>.  If you submit a bug, please provide an email contact and/or use the Monitor feature.
        </P>
        </FONT>
        </TD></TR>