add link to hans' comparison page
[flac.git] / doc / html / documentation.html
index b8214d7..df69ea3 100644 (file)
@@ -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>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.
        <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>
                                <TT>--lax</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.
+                               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>
                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.4) release:
+               The following are major known bugs in the current (1.1.0) release:
+       </P>
+       <P>
+               <UL>
+                       <LI>
+                               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>