add link to hans' comparison page
[flac.git] / doc / html / documentation.html
index 8b2c4c3..df69ea3 100644 (file)
@@ -1,5 +1,5 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<!-- Copyright (c)  2000,2001,2002  Josh Coalson -->
+<!-- Copyright (c)  2000,2001,2002,2003  Josh Coalson -->
 <!-- Permission is granted to copy, distribute and/or modify this document -->
 <!-- under the terms of the GNU Free Documentation License, Version 1.1 -->
 <!-- or any later version published by the Free Software Foundation; -->
@@ -14,7 +14,7 @@
 
 <TABLE BORDER=0 WIDTH="100%" CELLPADDING=1 CELLSPACING=0>
        <TR>
-               <TD ALIGN="CENTER" BGCOLOR="#000000"><A HREF="http://flac.sourceforge.net/"><IMG SRC="images/logo.jpg" ALIGN=CENTER ALT="FLAC Logo" BORDER=0 HSPACE=0></a></TD>
+               <TD ALIGN="CENTER" BGCOLOR="#000000"><A HREF="http://flac.sourceforge.net/"><IMG SRC="images/logo130.gif" ALIGN=CENTER ALT="FLAC Logo" BORDER=0 HSPACE=0></a></TD>
        </TR>
 </TABLE>
 
@@ -28,6 +28,7 @@
                        <TABLE CELLPADDING=0 CELLSPACING=0 BORDER=0>
                                <TR>
                                        <TD HEIGHT=22 BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="index.html">home</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
+                                       <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="faq.html">faq</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
                                        <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="news.html">news</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
                                        <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="download.html">download</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
                                        <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="features.html">features</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
                <B>METADATA</B>
        </P>
        <P>
-               FLAC defines several types of metadata blocks (see the <A HREF="format.html">format</A> page for the complete list.  Metadata blocks can be any length and new ones can be defined.  A decoder is allowed to skip any metadata types it does not understand.  Only one is mandatory: the STREAMINFO block.  This block has information like the sample rate, number of channels, etc., and data that can help the decoder manage its buffers, like the minimum and maximum data rate and minimum and maximum block size.  Also included in the STREAMINFO block is the MD5 signature of the <I>unencoded</I> audio data.  This is useful for checking an entire stream for transmission errors.
+               FLAC defines several types of metadata blocks (see the <A HREF="format.html">format</A> page for the complete list).  Metadata blocks can be any length and new ones can be defined.  A decoder is allowed to skip any metadata types it does not understand.  Only one is mandatory: the STREAMINFO block.  This block has information like the sample rate, number of channels, etc., and data that can help the decoder manage its buffers, like the minimum and maximum data rate and minimum and maximum block size.  Also included in the STREAMINFO block is the MD5 signature of the <I>unencoded</I> audio data.  This is useful for checking an entire stream for transmission errors.
        </P>
        <P>
-               Other blocks allow for padding, seek tables, and application-specific data.  You can see <B><TT>flac</TT></B> options below for adding PADDING blocks or specifying seek points.  FLAC does not require seek points for seeking but they can speed up seeks, or be used for cueing in editing applications.
+               Other blocks allow for padding, seek tables, tags, cuesheets, and application-specific data.  You can see <B><TT>flac</TT></B> options below for adding PADDING blocks or specifying seek points.  FLAC does not require seek points for seeking but they can speed up seeks, or be used for cueing in editing applications.
        <P>
        </P>
                Also, if you have a need of a custom metadata block, you can define your own and request an ID <A HREF="id.html">here</A>.  Then you can reserve a PADDING block of the correct size when encoding, and overwrite the padding block with your APPLICATION block after encoding.  The resulting stream will be FLAC compatible; decoders that are aware of your metadata can use it and the rest will safely ignore it.
                <B>MISCELLANEOUS</B>
        </P>
        <P>
-               In order to support come common types of metadata, the reference decoder knows how to skip ID3V1 and ID3V2 tags so it is safe to tag FLAC files in this way.  ID3V2 tags must come at the beginning of the file (before the "fLaC" marker) and ID3V1 tags must come at the end of the file.
+               In order to support come common types of metadata, the reference decoder knows how to skip <A HREF="http://www.id3.org/">ID3v1 and ID3v2 tags</A>.  Note however that the FLAC specification does not require compliant implementations to support ID3 in any form.  The XMMS and Winamp plugins support them out of convenience but other applications need not.
        </P>
        <P>
                <B><TT>flac</TT></B> has a verify option <TT>-V</TT> that verifies the output while encoding.  With this option, a decoder is run in parallel to the encoder and its output is compared against the original input.  If a difference is found <B><TT>flac</TT></B> will stop with an error.
                <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 #] [-V] [<I><A HREF="#format_options">&lt;format-options&gt;</A></I>] [<I><A HREF="#encoding_options">&lt;encoding options&gt;</A></I>] [inputfile [...]]
+                       Encoding: flac [<I><A HREF="#general_options">&lt;general-options&gt;</A></I>] [<I><A HREF="#format_options">&lt;format-options&gt;</A></I>] [<I><A HREF="#encoding_options">&lt;encoding options&gt;</A></I>] [inputfile [...]]
                </LI>
                <LI>
-                       Decoding: flac -d [-s] [--skip #] [-F] [<I><A HREF="#format_options">&lt;format-options&gt;</A></I>] [inputfile [...]]
+                       Decoding: flac -d [<I><A HREF="#general_options">&lt;general-options&gt;</A></I>] [<I><A HREF="#format_options">&lt;format-options&gt;</A></I>] [<I><A HREF="#decoding_options">&lt;decoding options&gt;</A></I>]  [FLACfile [...]]
                </LI>
                <LI>
-                       Testing: flac -t [-s] [inputfile [...]]
+                       Testing: flac -t [<I><A HREF="#general_options">&lt;general-options&gt;</A></I>] [FLACfile [...]]
                </LI>
                <LI>
-                       Analyzing: flac -a [-s] [--skip #] [<I><A HREF="#analysis_options">&lt;analysis-options&gt;</A></I>] [inputfile [...]]
+                       Analyzing: flac -a [<I><A HREF="#general_options">&lt;general-options&gt;</A></I>] [<I><A HREF="#analysis_options">&lt;analysis-options&gt;</A></I>] [FLACfile [...]]
                </LI>
                </UL>
        </P>
        <P>
                Also, you can force output data to go to stdout using <TT>-c</TT>.
        </P>
+       <P>
+               To encode or decode files that start with a dash, use <TT>--</TT> to signal the end of options, to keep the filenames themselves from being treated as options:
+               <UL>
+               <LI>
+                       <TT>flac -V -- -01-filename.wav</TT>
+               </LI>
+               </UL>
+       </P>
        <P>The encoding options affect the compression ratio and encoding speed.  The format options are used to tell <B><TT>flac</TT></B> the arrangement of samples if the input file (or output file when decoding) is a raw file.  If it is a RIFF WAVE or AIFF file the format options are not needed since they are read from the AIFF/WAVE header.
        </P>
        <P>
                </TR>
                <TR>
                        <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
-                               <TT>--skip=#</TT>
+                               <TT>--skip={#|mm:ss.ss}</TT>
+                       </TD>
+                       <TD>
+                               Skip over the first # of samples of the input.  This works for both encoding and decoding, but not testing.  The alternative form <TT>mm:ss.ss</TT> can be used to specify minutes, seconds, and fractions of a second.<P>
+                               Examples:<P>
+                               <TT>--skip=123</TT> : skip the first 123 samples of the input<P>
+                               <TT>--skip=1:23.45</TT> : skip the first 1 minute and 23.45 seconds of the input
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               <TT>--until={#|[+|-]mm:ss.ss}</TT>
                        </TD>
                        <TD>
-                               Skip over the first # of samples of the input.  This works for both encoding and decoding, but not testing.
+                               Stop at the given sample number for each input file.  This works for both encoding and decoding, but not testing.  The given sample number is not included in the decoded output.  The alternative form <TT>mm:ss.ss</TT> can be used to specify minutes, seconds, and fractions of a second.  If a <TT>+</TT> sign is at the beginning, the <TT>--until</TT> point is relative to the <TT>--skip</TT> point.  If a <TT>-</TT> sign is at the beginning, the <TT>--until</TT> point is relative to end of the audio.<P>
+                               Examples:<P>
+                               <TT>--until=123</TT> : decode only the first 123 samples of the input (samples 0-122, stopping at 123)<P>
+                               <TT>--until=1:23.45</TT> : decode only the first 1 minute and 23.45 seconds of the input<P>
+                               <TT>--skip=1:00 --until=+1:23.45</TT> : decode 1:00.00 to 2:23.45<P>
+                               <TT>--until=-1:23.45</TT> : decode everything except the last 1 minute and 23.45 seconds<P>
+                               <TT>--until=-0:00</TT> : decode until the end of the input (the same as not specifying <TT>--until</TT>)
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               <TT>--ogg</TT>
+                       </TD>
+                       <TD>
+                               When encoding, generate Ogg-FLAC output instead of native-FLAC.  Ogg-FLAC streams are FLAC streams wrapped in an Ogg transport layer.  The resulting file should have an '.ogg' extension and will still be decodable by <TT><B>flac</B></TT>.<P>
+                               When decoding, force the input to be treated as Ogg-FLAC.  This is useful when piping input from stdin or when the filename does not end in '.ogg'.
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               <TT>--serial-number=#</TT>
+                       </TD>
+                       <TD>
+                               When used with --ogg, specifies the serial number to use the for the FLAC stream.  When encoding and no serial number is given, flac uses '0'.  When decoding and no number is given, flac uses the serial number of the first page.<P>
                        </TD>
                </TR>
        </TABLE>
                </TR>
                <TR>
                        <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
-                               <TT>--ogg</TT>
+                               <TT>--lax</TT>
                        </TD>
                        <TD>
-                               When encoding, generate Ogg-FLAC output instead of native-FLAC.  Ogg-FLAC streams are FLAC streams wrapped in an Ogg transport layer.  The resulting file should have an '.ogg' extension and will still be decodable by <TT><B>flac</B></TT>.<P>
-                               When decoding, force the input to be treated as Ogg-FLAC.  This is useful when piping input from stdin or when the filename does not end in '.ogg'.
+                               Allow encoder to generate non-<A HREF="format.html#subset">Subset</A> files.  The resulting FLAC file may not be streamable, so you should only use this option in combination with custom encoding options meant for archival.  File decoders will still be able play (and seek in) such files.
                        </TD>
                </TR>
                <TR>
                        <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
-                               <TT>--lax</TT>
+                               <TT>--replay-gain</TT>
+                       </TD>
+                       <TD>
+                               Calculate <A HREF="http://www.replaygain.org/">ReplayGain</A> values and store in Vorbis comments, similar to <A HREF="http://packages.qa.debian.org/v/vorbisgain.html">VorbisGain</A>.  Title gains/peaks will be computed for each input file, and an album gain/peak will be computed for all files.  All input files must have the same resolution, sample rate, and number of channels.  Only mono and stereo files are allowed, and the sample rate must be one of 8, 11.025, 12, 16, 22.05, 24, 32, 44.1, or 48 kHz.  Also note that this option may leave a few extra bytes in a PADDING block as the exact size of the tags is not known until all files are processed.<P>
+                               Note that this option cannot be used when encoding to standard output (stdout).
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               <TT>--cuesheet=FILENAME</TT>
                        </TD>
                        <TD>
-                               Allow encoder to generate non-Subset files.  The resulting FLAC file may not be streamable, so you should only use this option in combination with custom encoding options meant for archival.  File decoders will still be able play (and seek in) such files.
+                               Import the given cuesheet file and store it in a <A HREF="format.html#def_CUESHEET">CUESHEET</A> metadata block.  This option may only be used when encoding a single file.  A seekpoint will be added for each index point in the cuesheet to the <A HREF="format.html#def_SEEKTABLE">SEEKTABLE</A> unless <TT>--no-cued-seekpoints</TT> is specified.<P>
+                               The cuesheet file must be of the sort written by <A HREF="http://www.goldenhawk.com/cdrwin.htm">CDRwin</A>, <A HREF="http://www.dcsoft.com/prod03.htm">CDRcue</A>, <A HREF="http://www.exactaudiocopy.de/">EAC</A>, et al.
                        </TD>
                </TR>
                <TR>
                </TR>
                <TR>
                        <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
-                               <TT>-S {#|X|#x}</TT>,<BR><TT>--seekpoint={#|X|#x}</TT>
+                               <TT>-S {#|X|#x|#s}</TT>,<BR><TT>--seekpoint={#|X|#x|#s}</TT>
                        </TD>
                        <TD>
                                Include a point or points in a SEEKTABLE:<BR>
                                <LI>
                                        <TT>#x</TT> : # evenly spaced seekpoints, the first being at sample 0
                                </LI>
+                               <LI>
+                                       <TT>#s</TT> : a seekpoint every # seconds; # does not have to be a whole number, it can be, for example, <TT>9.5</TT>, meaning a seekpoint every 9.5 seconds
+                               </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>
-                               <B>NOTE:</B> -S #x will not work if the encoder can't determine the input size before starting.<BR>
-                               <B>NOTE:</B> 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>
+                               With no -S options, flac defaults to '-S 10s'.  Use --no-seektable for no SEEKTABLE.<BR>
+                               <B>NOTE:</B> -S #x and -S #s will not work if the encoder can't determine the input size before starting.<BR>
+                               <B>NOTE:</B> if you use -S # and # is &gt;= 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>
                                <TT>-P #</TT>, <TT>--padding=#</TT>
                        </TD>
                        <TD>
-                               Tell the encoder to write a <TT>PADDING</TT> metadata block of the given length (in bytes) after the <TT>STREAMINFO</TT> block.  This is useful if you plan to tag the file later with an <TT>APPLICATION</TT> block; instead of having to rewrite the entire file later just to insert your block, you can write directly over the <TT>PADDING</TT> block.  Note that the total length of the <TT>PADDING</TT> block will be 4 bytes longer than the length given because of the 4 metadata block header bytes.  You can force no <TT>PADDING</TT> block at all to be written with <TT>-P-</TT>, which is the default.
+                               Tell the encoder to write a <TT>PADDING</TT> metadata block of the given length (in bytes) after the <TT>STREAMINFO</TT> block.  This is useful if you plan to tag the file later with an <TT>APPLICATION</TT> block; instead of having to rewrite the entire file later just to insert your block, you can write directly over the <TT>PADDING</TT> block.  Note that the total length of the <TT>PADDING</TT> block will be 4 bytes longer than the length given because of the 4 metadata block header bytes.  You can force no <TT>PADDING</TT> block at all to be written with <TT>--no-padding</TT>.  The encoder writes a PADDING block of 4096 bytes by default.
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               <TT>-T FIELD=VALUE</TT>, <TT>--tag=FIELD=VALUE</TT>
+                       </TD>
+                       <TD>
+                               Add a Vorbis comment.  The comment must adhere to the Vorbis comment spec; i.e. the FIELD must contain only legal characters, terminated by an 'equals' sign.  Make sure to quote the comment if necessary.  This option may appear more than once to add several comments.  NOTE: all tags will be added to all encoded files.
                        </TD>
                </TR>
                <TR>
                                <TT>-m</TT>, <TT>--mid-side</TT>
                        </TD>
                        <TD>
-                               Enable mid-side coding (only for stereo streams).  Tends to increase compression by a few percent on average.  For each block both the stereo pair and mid-side versions of the block will be encoded, and smallest resulting frame will be stored.  Currently mid-side encoding is only available when bits-per-sample <= 16.
+                               Enable mid-side coding (only for stereo streams).  Tends to increase compression by a few percent on average.  For each block both the stereo pair and mid-side versions of the block will be encoded, and smallest resulting frame will be stored.  Currently mid-side encoding is only available when bits-per-sample &lt;= 16.
                        </TD>
                </TR>
                <TR>
                </TR>
                <TR>
                        <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
-                               <TT>-E</TT>, <TT>--escape-coding</TT>
-                       </TD>
-                       <TD>
-                               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%.
-                       </TD>
-               </TR>
-               <TR>
-                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
                                <TT>-l #</TT>, <TT>--max-lpc-order=#</TT>
                        </TD>
                        <TD>
-                               Specifies the maximum LPC order.  This number must be <= 32.  If 0, the encoder will not attempt generic linear prediction, and use only fixed predictors.  Using fixed predictors is faster but usually results in files being 5-10% larger.
+                               Specifies the maximum LPC order.  This number must be &lt;= 32.  If 0, the encoder will not attempt generic linear prediction, and use only fixed predictors.  Using fixed predictors is faster but usually results in files being 5-10% larger.
                        </TD>
                </TR>
                <TR>
                </TR>
                <TR>
                        <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               <TT>--force-aiff-format</TT>
+                       </TD>
+                       <TD>
+                               Force the decoder to output AIFF format.  This option is not needed if the output filename (as set by -o) ends with .aiff.  Also, this option has no effect when encoding since input AIFF is auto-detected.
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
                                <TT>--force-raw-format</TT>
                        </TD>
                        <TD>
                <B><TT>metaflac</TT></B> is the command-line <TT>.flac</TT> file metadata editor.  You can use it to list the contents of blocks, delete or insert blocks, and manage padding.
        </P>
        <P>
-               The documentation for <B><TT>metaflac</TT></B> is currently being rewritten, but the usage screen should explain it pretty well.  Do <TT>metaflac --help</TT> to see the full usage.
+               The HTML documentation for <B><TT>metaflac</TT></B> is currently being rewritten, but the usage screen should explain it pretty well, and there is a man page.  Do <TT>metaflac --help</TT> to see the full usage.
        </P>
        </FONT>
        </TD></TR>
                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, make sure and provide an email contact or use the Monitor feature.
        </P>
        <P>
-               The following are major known bugs in the current (1.0.3) release:
+               The following are major known bugs in the current (1.1.0) release:
        </P>
        <P>
                <UL>
                        <LI>
-                               The Winamp2 plugin has a bug where it shows a dialog "ERROR: invalid/missing FLAC metadata" for any .flac file.  This has been fixed; you can download the plugin <A HREF="http://sourceforge.net/project/shownotes.php?release_id=98266">here</A>.  The fixed source code is in CVS.
+                               If you change the FLAC configuration options in the XMMS plugin while a FLAC file is playing, it can cause a crash or other bad things to happen.
+                       </LI>
+               </UL>
+       </P>
+       <P>
+               The following are major known bugs in the 1.0.4:
+       </P>
+       <P>
+               <UL>
+                       <LI>
+                               All decoders prior to and including 1.0.4 have a bug that prevents them from skipping unknown metadata blocks properly.  A FLAC file created by flac 1.1.0 containing a CUESHEET metadata block will not decode in 1.0.x decoders.
+                       </LI>
+                       <LI>
+                               <B><TT>metaflac</TT></B> has a bug where, if --import-vc-from is used on a FLAC file that has no Vorbis comment block, the FLAC file can be corrupted.  All FLAC files generated by 1.0.4 have a Vorbis comment block added automatically but files from 1.0.3 and before do not.  This is fixed in CVS.
+                       </LI>
+                       <LI>
+                               There is an odd bug in <B><TT>metaflac</TT></B> such that you must always use the <TT>--dont-use-padding</TT> option with <TT>--add-padding</TT> or the padding block won't be written.  This is fixed in CVS.
                        </LI>
                </UL>
        </P>
 
 </CENTER>
 
-<P>&nbsp;Copyright (c) 2000,2001,2002 Josh Coalson</P>
+<P>&nbsp;Copyright (c) 2000,2001,2002,2003 Josh Coalson</P>
 
 </BODY>
 </HTML>