libFLAC/lpc.c: Fix signed integer overflow
[flac.git] / doc / html / documentation_tools_flac.html
index c444e2e..8496aca 100644 (file)
@@ -1,11 +1,12 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Copyright (c) 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009  Josh Coalson -->
+<!-- Copyright (c) 2000-2009  Josh Coalson -->
+<!-- Copyright (c) 2011-2016  Xiph.Org Foundation -->
 <!-- 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; -->
 <!-- with no invariant sections. -->
 <!-- A copy of the license can be found at http://www.gnu.org/copyleft/fdl.html -->
-<html>
+<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
        <meta name="author" content="Josh Coalson" />
@@ -19,7 +20,7 @@
 <body>
 
 <div class="logo">
-       <a href="http://flac.sourceforge.net/"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a>
+       <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a>
 </div>
 
 <div class="above_nav"></div>
 <div class="navbar">
        &nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
        &nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
-       &nbsp;<a href="news.html">news</a>&nbsp;&nbsp;|
-       &nbsp;<a href="download.html">download</a>&nbsp;&nbsp;|
        &nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
-       &nbsp;<a href="comparison.html">comparison</a>&nbsp;&nbsp;|
+       &nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
        &nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
-       &nbsp;<a href="links.html">links</a>&nbsp;&nbsp;|
-       &nbsp;<a href="developers.html">developers</a>&nbsp;
-</div>
-
-<div class="langbar">
-       &nbsp;english&nbsp;&nbsp;|
-       &nbsp;<a href="ru/documentation.html">russian</a>&nbsp;
+       &nbsp;<a href="http://xiph.org/flac">more</a>
 </div>
 
 <div class="below_nav"></div>
                        <tr>
                                <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
                                        <a name="flac_options_skip" />
-                                       <span class="argument">--skip={#|mm:ss.ss}</span>
+                                       <span class="argument">--skip={#|mm:ss.ss}<br />--skip={#|mm:ss,ss}</span>
                                </td>
                                <td>
                                        Skip over the first # of samples of the input.  This works for both encoding and decoding, but not testing.  The alternative form <span class="argument">mm:ss.ss</span> can be used to specify minutes, seconds, and fractions of a second.<br />
                                        <br />
+                                       Note that the use of either a dot or a comma depends on the locale used for the system.<br />
+                                       <br />
                                        Examples:<br />
                                        <br />
                                        <span class="argument">--skip=123</span> : skip the first 123 samples of the input<br />
-                                       <span class="argument">--skip=1:23.45</span> : skip the first 1 minute and 23.45 seconds of the input
+                                       <span class="argument">--skip=1:23.45</span> : skip the first 1 minute and 23.45 seconds of the input, with a locale using the point as decimal separator<br />
+                                       <span class="argument">--skip=1:23,45</span> : skip the first 1 minute and 23.45 seconds of the input, with a locale using the comma as decimal separator
                                </td>
                        </tr>
                        <tr>
                                <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
                                        <a name="flac_options_until" />
-                                       <span class="argument">--until={#|[+|-]mm:ss.ss}</span>
+                                       <span class="argument">--until={#|[+|-]mm:ss.ss}<br />--until={#|[+|-]mm:ss,ss}</span>
                                </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 <span class="argument">mm:ss.ss</span> can be used to specify minutes, seconds, and fractions of a second.  If a <span class="argument">+</span> sign is at the beginning, the <span class="argument">--until</span> point is relative to the <span class="argument">--skip</span> point.  If a <span class="argument">-</span> sign is at the beginning, the <span class="argument">--until</span> point is relative to end of the audio.<br />
                                        <br />
+                                       Note that the use of either a dot or a comma depends on the locale used for the system.<br />
+                                       <br />
                                        Examples:<br />
                                        <br />
                                        <span class="argument">--until=123</span> : decode only the first 123 samples of the input (samples 0-122, stopping at 123)<br />
                                        <span class="argument">--until=1:23.45</span> : decode only the first 1 minute and 23.45 seconds of the input<br />
+                                       <span class="argument">--until=1:23,45</span> : decode only the first 1 minute and 23.45 seconds of the input, if your locale setting uses a comma as decimal separator<br />
                                        <span class="argument">--skip=1:00 --until=+1:23.45</span> : decode 1:00.00 to 2:23.45<br />
                                        <span class="argument">--until=-1:23.45</span> : decode everything except the last 1 minute and 23.45 seconds<br />
                                        <span class="argument">--until=-0:00</span> : decode until the end of the input (the same as not specifying <span class="argument">--until</span>)
                                        By default <span class="commandname">flac</span> stops decoding with an error and removes the partially decoded file if it encounters a bitstream error.  With <span class="argument">-F</span>, errors are still printed but <span class="commandname">flac</span> will continue decoding to completion.  Note that errors may cause the decoded audio to be missing some samples or have silent sections.
                                </td>
                        </tr>
-                       <!-- @@@ undocumented, also not in the man page yet
                        <tr>
                                <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
                                        <a name="flac_options_apply_replaygain_which_is_not_lossless" />
-                                       <span class="argument">-@@@-apply-replaygain-which-is-not-lossless[=&lt;specification&gt;]</span>
+                                       <span class="argument">--apply-replaygain-which-is-not-lossless[=&lt;specification&gt;]</span>
                                </td>
                                <td>
                                        Applies ReplayGain values while decoding.<br />
                                        </ul>
                                        For example, the default of <span class="argument">0aLn1</span> means 0dB preamp, use album gain, 6dB hard limit, low noise shaping.<br />
                                        <br />
-                                       <span class="argument">-@@@-apply-replaygain-which-is-not-lossless=3</span> means 3dB preamp, use album gain, no limiting, no noise shaping.<br />
+                                       <span class="argument">--apply-replaygain-which-is-not-lossless=3</span> means 3dB preamp, use album gain, no limiting, no noise shaping.<br />
                                        <br />
                                        <span class="commandname">flac</span> uses the ReplayGain tags for the calculation.  If a stream does not have the required tags or they can't be parsed, decoding will continue with a warning, and no ReplayGain is applied to that stream.
                                </td>
                        </tr>
-                       -->
                </table>
                </td></tr></table>
 
                                        <span class="argument">-V</span>, <span class="argument">--verify</span>
                                </td>
                                <td>
-                                       Verify the encoding process.  With this option, <span class="commandname">flac</span> will create a parallel decoder that decodes the output of the encoder and compares the result against the original.  It will abort immediately with an error if a mismatch occurs.  <span class="argument">-V</span> increases the total encoding time but is guaranteed to catch any unforseen bug in the encoding process.
+                                       Verify the encoding process.  With this option, <span class="commandname">flac</span> will create a parallel decoder that decodes the output of the encoder and compares the result against the original.  It will abort immediately with an error if a mismatch occurs.  <span class="argument">-V</span> increases the total encoding time but is guaranteed to catch any unforeseen bug in the encoding process.
                                </td>
                        </tr>
                        <tr>
                                        <span class="argument">--replay-gain</span>
                                </td>
                                <td>
-                                       Calculate <a href="http://www.replaygain.org/">ReplayGain</a> values and store them as FLAC tags, 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 <span class="code">PADDING</span> block as the exact size of the tags is not known until all files are processed.<br />
+                                       Calculate <a href="http://wiki.hydrogenaud.io/index.php?title=ReplayGain_specification">ReplayGain</a> values and store them as FLAC tags, 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 <span class="code">PADDING</span> block as the exact size of the tags is not known until all files are processed.<br />
                                        <br />
                                        Note that this option cannot be used when encoding to standard output (stdout).
                                </td>
                                        <br />
                                        <span class="argument">DESCRIPTION</span> is optional; the default is an empty string.<br />
                                        <br />
-                                       The next part specfies the resolution and color information.  If the <span class="argument">MIME-TYPE</span> is <tt>image/jpeg</tt>, <tt>image/png</tt>, or <tt>image/gif</tt>, you can usually leave this empty and they can be detected from the file.  Otherwise, you must specify the width in pixels, height in pixels, and color depth in bits-per-pixel.  If the image has indexed colors you should also specify the number of colors used.  When manually specified, it is not checked against the file for accuracy.<br />
+                                       The next part specifies the resolution and color information.  If the <span class="argument">MIME-TYPE</span> is <tt>image/jpeg</tt>, <tt>image/png</tt>, or <tt>image/gif</tt>, you can usually leave this empty and they can be detected from the file.  Otherwise, you must specify the width in pixels, height in pixels, and color depth in bits-per-pixel.  If the image has indexed colors you should also specify the number of colors used.  When manually specified, it is not checked against the file for accuracy.<br />
                                        <br />
                                        <span class="argument">FILE</span> is the path to the picture file to be imported, or the URL if MIME type is --&gt;<br />
                                        <br />
                                        <span class="argument">--ignore-chunk-sizes</span>
                                </td>
                                <td>
-                                       When encoding to flac, ignore the file size headers in WAV and AIFF files to attempt to work around problems with over-sized or malformed files.<br />
+                                       When encoding to <span class="commandname">flac</span>, ignore the file size headers in WAV and AIFF files to attempt to work around problems with over-sized or malformed files.<br />
                                        <br />
                                        WAV and AIFF files both have an unsigned 32 bit numbers in the file header which specifes the length of audio data. Since this number is unsigned 32 bits, that limits the size of a valid file to being just over 4 Gigabytes. Files larger than this are mal-formed, but should be read correctly using this option. <br />
                                        <br />
                                        <span class="argument">-6</span>, <span class="argument">--compression-level-6</span>
                                </td>
                                <td>
-                                       Synonymous with <span class="argument">-l 8 -b 4096 -m -r 6</span>
+                                       Synonymous with <span class="argument">-l 8 -b 4096 -m -r 6 -A tukey(0.5);partial_tukey(2)</span>
                                </td>
                        </tr>
                        <tr>
                                        <span class="argument">-7</span>, <span class="argument">--compression-level-7</span>
                                </td>
                                <td>
-                                       Synonymous with <span class="argument">-l 8 -b 4096 -m -e -r 6</span>
+                                       Synonymous with <span class="argument">-l 12 -b 4096 -m -r 6 -A tukey(0.5);partial_tukey(2)</span>
                                </td>
                        </tr>
                        <tr>
                                        <span class="argument">-8</span>, <span class="argument">--compression-level-8</span>
                                </td>
                                <td>
-                                       Synonymous with <span class="argument">-l 12 -b 4096 -m -e -r 6</span>
+                                       Synonymous with <span class="argument">-l 12 -b 4096 -m -r 6 -A tukey(0.5);partial_tukey(2);punchout_tukey(3)</span>
                                </td>
                        </tr>
                        <tr>
                                        <span class="argument">-A "function"</span>, <span class="argument">--apodization="function"</span>
                                </td>
                                <td>
-                                       Window audio data with given the apodization function.  The functions are: bartlett, bartlett_hann, blackman, blackman_harris_4term_92db, connes, flattop, gauss(STDDEV), hamming, hann, kaiser_bessel, nuttall, rectangle, triangle, tukey(P), welch.<br />
+                                       Window audio data with given the apodization function.  The functions are: bartlett, bartlett_hann, blackman, blackman_harris_4term_92db, connes, flattop, gauss(STDDEV), hamming, hann, kaiser_bessel, nuttall, rectangle, triangle, tukey(P), partial_tukey(n[/ov[/P]]), punchout_tukey(n[/ov[/P]]), welch.<br />
                                        For gauss(STDDEV), STDDEV is the standard deviation (0&lt;STDDEV&lt;=0.5).<br />
                                        For tukey(P), P specifies the fraction of the window that is tapered (0&lt;=P&lt;=1; P=0 corresponds to "rectangle" and P=1 corresponds to "hann").<br />
+                                       For partial_tukey(n) and punchout_tukey(n), n apodization functions are added that span different parts of each block. Values of 2 to 6 seem to yield sane results. If necessary, an overlap can be specified, as can be the taper parameter, for example partial_tukey(2/0.2) or partial_tukey(2/0.2/0.5). ov should be smaller than 1 and can be negative.<br />
+                                       Please note that P, STDDEV and ov are locale specific, so a comma as decimal separator might be required instead of a dot.<br />
                                        More than one -A option (up to 32) may be used.  Any function that is specified erroneously is silently dropped.  The encoder chooses suitable defaults in the absence of any -A options; any -A option specified replaces the default(s).<br />
                                        When more than one function is specified, then for every subframe the encoder will try each of them separately and choose the window that results in the smallest compressed subframe.  Multiple functions can greatly increase the encoding time.<br />
                                </td>
                                <td>
                                        Set the [min,]max residual partition order.  The min value defaults to 0 if unspecified.<br />
                                        <br />
-                                       By default the encoder uses a single Rice parameter for the subframe's entire residual.  With this option, the residual is iteratively partitioned into 2^min# .. 2^max# pieces, each with its own Rice parameter.  Higher values of max# yield diminishing returns.  The most bang for the buck is usually with <span class="argument">-r 2,2</span> (more for higher block sizes).  This usually shaves off about 1.5%.  The technique tends to peak out about when blocksize/(2^n)=128.  Use <span class="argument">-r 0,16</span> to force the highest degree of optimization.
+                                       By default the encoder uses a single Rice parameter for the subframe's entire residual.  With this option, the residual is iteratively partitioned into 2^min# .. 2^max# pieces, each with its own Rice parameter.  Higher values of max# yield diminishing returns.  The most bang for the buck is usually with <span class="argument">-r 2,2</span> (more for higher block sizes).  This usually shaves off about 1.5%.  The technique tends to peak out about when blocksize/(2^n)=128.  Use <span class="argument">-r 0,15</span> to force the highest degree of optimization.
                                </td>
                        </tr>
                </table>
                                        <span class="argument">--input-size=#</span>
                                </td>
                                <td>
-                                       Specify the size of the raw input in bytes.  If you are encoding raw samples from stdin, you must set this option in order to be able to use --skip, --until, --cue-sheet, or other options that need to know the size of the input beforehand.  If the size given is greater than what is found in the input stream, the encoder will complain about an unexpected end-of-file.  If the size given is less, samples will be truncated.
+                                       Specify the size of the raw input in bytes.  If you are encoding raw samples from stdin, you must set this option in order to be able to use --skip, --until, --cuesheet, or other options that need to know the size of the input beforehand.  If the size given is greater than what is found in the input stream, the encoder will complain about an unexpected end-of-file.  If the size given is less, samples will be truncated.
                                </td>
                        </tr>
                        <tr>
                        <tr>
                                <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
                                        <span class="argument">--no-adaptive-mid-side</span><br />
+                                       <span class="argument">--no-cued-seekpoints</span><br />
                                        <span class="argument">--no-decode-through-errors</span><br />
                                        <span class="argument">--no-delete-input-file</span><br />
                                        <span class="argument">--no-escape-coding</span><br />
                                        <span class="argument">--no-exhaustive-model-search</span><br />
+                                       <span class="argument">--no-ignore-chunk-sizes</span><br />
                                        <span class="argument">--no-lax</span><br />
                                        <span class="argument">--no-mid-side</span><br />
                                        <span class="argument">--no-ogg</span><br />
                                        <span class="argument">--no-padding</span><br />
-                                       <span class="argument">--no-qlp-coeff-precision-search</span><br />
+                                       <span class="argument">--no-preserve-modtime</span><br />
+                                       <span class="argument">--no-qlp-coeff-prec-search</span><br />
                                        <span class="argument">--no-residual-gnuplot</span><br />
                                        <span class="argument">--no-residual-text</span><br />
                                        <span class="argument">--no-sector-align</span><br />
-                                       <span class="argument">--no-ignore-chunk-sizes</span><br />
                                        <span class="argument">--no-seektable</span><br />
                                        <span class="argument">--no-silent</span><br />
                                        <span class="argument">--no-verify</span>
                <a href="#flac_options_adaptive_mid_side"><span class="argument">--adaptive-mid-side</span></a><br />
                <a href="#flac_options_analyze"><span class="argument">--analyze</span></a><br />
                <a href="#flac_options_apodization"><span class="argument">--apodization</span></a><br />
-               <!-- @@@ undocumented, also not in the man page yet
-               <a href="#flac_options_apply_replaygain_which_is_not_lossless"><span class="argument">-@@@-apply-replaygain-which-is-not-lossless</span></a><br />
-               -->
+               <a href="#flac_options_apply_replaygain_which_is_not_lossless"><span class="argument">--apply-replaygain-which-is-not-lossless</span></a><br />
                <a href="#flac_options_blocksize"><span class="argument">-b</span></a><br />
                <a href="#flac_options_best"><span class="argument">--best</span></a><br />
                <a href="#flac_options_blocksize"><span class="argument">--blocksize</span></a><br />
                <a href="#flac_options_explain"><span class="argument">-H</span></a><br />
                <a href="#flac_options_help"><span class="argument">-h</span></a><br />
                <a href="#flac_options_help"><span class="argument">--help</span></a><br />
+               <a href="#flac_options_ignore_chunk_sizes"><span class="argument">--ignore-chunk-sizes</span></a><br />
                <a href="#flac_options_input_size"><span class="argument">--input-size</span></a><br />
                <a href="#flac_options_keep_foreign_metadata"><span class="argument">--keep-foreign-metadata</span></a><br />
                <a href="#flac_options_max_lpc_order"><span class="argument">-l</span></a><br />
                <a href="#flac_options_max_lpc_order"><span class="argument">--max-lpc-order</span></a><br />
                <a href="#flac_options_mid_side"><span class="argument">--mid-side</span></a><br />
                <a href="#negative_options"><span class="argument">--no-adaptive-mid-side</span></a><br />
+               <a href="#negative_options"><span class="argument">--no-cued-seekpoints</span></a><br />
                <a href="#negative_options"><span class="argument">--no-decode-through-errors</span></a><br />
                <a href="#negative_options"><span class="argument">--no-delete-input-file</span></a><br />
                <a href="#negative_options"><span class="argument">--no-escape-coding</span></a><br />
                <a href="#negative_options"><span class="argument">--no-ogg</span></a><br />
                <a href="#negative_options"><span class="argument">--no-padding</span></a><br />
                <a href="#negative_options"><span class="argument">--no-preserve-modtime</span></a><br />
-               <a href="#negative_options"><span class="argument">--no-qlp-coeff-precision-search</span></a><br />
+               <a href="#negative_options"><span class="argument">--no-qlp-coeff-prec-search</span></a><br />
                <a href="#negative_options"><span class="argument">--no-residual-gnuplot</span></a><br />
                <a href="#negative_options"><span class="argument">--no-residual-text</span></a><br />
                <a href="#negative_options"><span class="argument">--no-sector-align</span></a><br />
                <a href="#flac_options_silent"><span class="argument">-s</span></a><br />
                <a href="#flac_options_sample_rate"><span class="argument">--sample-rate</span></a><br />
                <a href="#flac_options_sector_align"><span class="argument">--sector-align</span></a><br />
-               <a href="#flac_options_ignore_chunk_sizes"><span class="argument">--ignore-chunk-sizes</span></a><br />
                <a href="#flac_options_seekpoint"><span class="argument">--seekpoint</span></a><br />
                <a href="#flac_options_serial_number"><span class="argument">--serial-number</span></a><br />
                <a href="#flac_options_sign"><span class="argument">--sign</span></a><br />
        <table>
                <tr>
                        <td align="left">
-                               Copyright (c) 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009  Josh Coalson
-                       </td>
-                       <td width="1%" align="right">
-                               <a href="http://sourceforge.net"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=13478&amp;type=1" width="88" height="31" border="0" alt="SourceForge.net Logo" /></a>
-                       </td>
-                       <td width="1%" align="right">
-                               <a href="http://www.eff.org/cafe/"><img src="images/cafebug.gif" alt="CAFE Logo" border="0" /></a><br />
-                       </td>
-                       <td width="1%" align="right">
-                               <a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" border="0" hspace="0" /></a>
+                               Copyright (c) 2000-2009  Josh Coalson
+                               <br/>
+                               Copyright (c) 2011-2016  Xiph.Org Foundation
                        </td>
                </tr>
        </table>