add info about MD5 and test mode
authorJosh Coalson <jcoalson@users.sourceforce.net>
Sat, 13 Jan 2001 00:32:32 +0000 (00:32 +0000)
committerJosh Coalson <jcoalson@users.sourceforce.net>
Sat, 13 Jan 2001 00:32:32 +0000 (00:32 +0000)
doc/documentation.html

index 7d12ee3..880a221 100644 (file)
                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.
        </P>
        <P>
-               <B><TT>flac</TT></B> will be invoked one of two ways, depending on whether you are encoding or decoding:
+               <B><TT>flac</TT></B> will be invoked one of three ways, depending on whether you are encoding, decoding, or testing:
                <UL>
                <LI>
                        Encoding: flac [-s] [--skip #] [&lt;format-options&gt;] [&lt;encoding options&gt;] inputfile outputfile
                <LI>
                        Decoding: flac -d [-s] [--skip #] [&lt;format-options&gt;] inputfile outputfile
                </LI>
+               <LI>
+                       Testing: flac -t [-s] inputfile
+               </LI>
                </UL>
        </P>
        <P>
-               In either case, inputfile may be "-" for stdin, and "-" for stdout.  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 file the format options are not needed since they are read from the WAVE header.
+               In either case, inputfile may be "-" for stdin, and the outputfile "-" for stdout.  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 file the format options are not needed since they are read from the WAVE header.
+       </P>
+       <P>
+               In test mode, <B><TT>flac</TT></B> acts just like in decode mode, except no output file is written.  Both decode and test modes detect errors in the stream, but they also detect when the MD5 signature of the decoded audio does not match the stored MD5 signature, even when the bitstream is valid.
        </P>
        <P>
        <TABLE WIDTH="100%" BORDER="0" CELLSPACING="0" CELLPADDING="0" BGCOLOR="#EEEED4"><TR><TD>
                                -d
                        </TD>
                        <TD>
-                               Decode (<B><TT>flac</TT></B> encodes by default).
+                               Decode (<B><TT>flac</TT></B> encodes by default).  <B><TT>flac</TT></B> will exit with an exit code of <TT>1</TT> (and print a message, even in silent mode) if there were any errors during decoding, including when the MD5 checksum does not match the decoded output.  Otherwise the exit code will be <TT>0</TT>.
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               -t
+                       </TD>
+                       <TD>
+                               Test (same as <B><TT>-d</TT></B> except no decoded file is written).  The exit codes are the same as in decode mode.
                        </TD>
                </TR>
                <TR>
                                --skip #
                        </TD>
                        <TD>
-                               Skip over the first # of samples of the input.  This works for both encoding and decoding.
+                               Skip over the first # of samples of the input.  This works for both encoding and decoding, but not testing.
                        </TD>
                </TR>
        </TABLE>