add --until, --cuesheet, --force-aiff-format
[platform/upstream/flac.git] / doc / html / documentation.html
index 4003407..bfe750c 100644 (file)
                <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.
                <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;format-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;format-options&gt;</A></I>] [<I><A HREF="#format_options">&lt;format-options&gt;</A></I>] [FLACfile [...]]
                </LI>
                <LI>
-                       Testing: flac -t [-s] [inputfile [...]]
+                       Testing: flac -t [<I><A HREF="#general_options">&lt;format-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;format-options&gt;</A></I>] [<I><A HREF="#analysis_options">&lt;analysis-options&gt;</A></I>] [FLACfile [...]]
                </LI>
                </UL>
        </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.
+                               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 samples of the input
+                       </TD>
+               </TR>
+               <TR>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               <TT>--until={#|[+|-]mm:ss.ss}</TT>
+                       </TD>
+                       <TD>
+                               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 --until point is relative to the --skip point.  If a <TT>-</TT> sign is at the beginning, the --until 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 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>
                </TR>
                <TR>
                        <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
+                               <TT>--cuesheet=FILENAME</TT>
+                       </TD>
+                       <TD>
+                               Import the given cuesheet file and store it in a CUESHEET 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 SEEKTABLE unless --no-cued-seekpoints 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>
+                       <TD NOWRAP ALIGN="RIGHT" VALIGN="TOP" BGCOLOR="#F4F4CC">
                                <TT>--sector-align</TT>
                        </TD>
                        <TD>
                </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>