Commit 6ed38094 authored by Erik de Castro Lopo's avatar Erik de Castro Lopo

Document --apply-replaygain-which-is-not-lossless command line option.

parent 03b9d5dd
......@@ -126,7 +126,9 @@
<li>
documentation:
<ul>
<li>Document <span class="argument"><a href="documentation_tools_flac.html#flac_options_ignore_chunk_sizes">--ignore-chunk-sizes</a></span> option for <span class="commandname">flac</span>.</li>
<li>Document <span class="argument"><a href="documentation_tools_flac.html#flac_options_ignore_chunk_sizes">--ignore-chunk-sizes</a></span>
and <span class="argument"><a href="documentation_tools_flac.html#flac_options_apply_replaygain_which_is_not_lossless">--apply-replaygain-which-is-not-lossless</a></span>
option for <span class="commandname">flac</span>.</li>
</ul>
</li>
<li>
......
......@@ -481,11 +481,10 @@
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 />
......@@ -517,12 +516,11 @@
</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>
......@@ -1060,9 +1058,7 @@
<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 />
......
......@@ -101,6 +101,37 @@ Set the beginning and ending cuepoints to decode. The optional first #.# is the
.TP
\fB-F, --decode-through-errors \fR
By default flac stops decoding with an error and removes the partially decoded file if it encounters a bitstream error. With -F, errors are still printed but flac will continue decoding to completion. Note that errors may cause the decoded audio to be missing some samples or have silent sections.
.TP
\fB--apply-replaygain-which-is-not-lossless[=<specification>] \fR
Applies ReplayGain values while decoding.
WARNING: THIS IS NOT LOSSLESS. DECODED AUDIO WILL NOT BE IDENTICAL TO THE ORIGINAL WITH THIS OPTION.
The equals sign and <specification> is optional. If omitted, the default is 0aLn1.
The <specification> is a shorthand notation for describing how to apply ReplayGain. All components are optional but order is important. '[]' means 'optional'. '|' means 'or'. '{}' means required. The format is:
[<preamp>][a|t][l|L][n{0|1|2|3}]
.RS
.TP
\fBpreamp\fR
A floating point number in dB. This is added to the existing gain value.
.TP
\fBa|t\fR
Specify 'a' to use the album gain, or 't' to use the track gain. If tags for the preferred kind (album/track) do not exist but tags for the other (track/album) do, those will be used instead.
.TP
\fBl|L\fR
Specify 'l' to peak-limit the output, so that the ReplayGain peak value is full-scale. Specify 'L' to use a 6dB hard limiter that kicks in when the signal approaches full-scale.
.TP
\fBn{0|1|2|3}\fR
Specify the amount of noise shaping. ReplayGain synthesis happens in floating point; the result is dithered before converting back to integer. This quantization adds noise. Noise shaping tries to move the noise where you won't hear it as much. 0 means no noise shaping, 1 means 'low', 2 means 'medium', 3 means 'high'.
.RE
For example, the default of 0aLn1 means 0dB preamp, use album gain, 6dB hard limit, low noise shaping.
--apply-replaygain-which-is-not-lossless=3 means 3dB preamp, use album gain, no limiting, no noise shaping.
flac 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.
.SS "ENCODING OPTIONS"
.TP
\fB-V, --verify\fR
......
......@@ -298,6 +298,52 @@
</listitem>
</varlistentry>
<varlistentry>
<term><option>--apply-replaygain-which-is-not-lossless[=&lt;specification&gt;]</option>
</term>
<listitem>
<para>Applies ReplayGain values while decoding.</para>
<para>WARNING: THIS IS NOT LOSSLESS. DECODED AUDIO WILL NOT BE IDENTICAL TO THE ORIGINAL WITH THIS OPTION.</para>
<para>The equals sign and &lt;specification&gt; is optional. If omitted, the default is 0aLn1.</para>
<para>The &lt;specification&gt; is a shorthand notation for describing how to apply ReplayGain. All components are optional but order is important. '[]' means 'optional'. '|' means 'or'. '{}' means required. The format is:</para>
<para>[&lt;preamp&gt;][a|t][l|L][n{0|1|2|3}]</para>
<variablelist>
<varlistentry>
<term><option>preamp</option></term>
<listitem>
<para>A floating point number in dB. This is added to the existing gain value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>a|t</option></term>
<listitem>
<para>Specify 'a' to use the album gain, or 't' to use the track gain. If tags for the preferred kind (album/track) do not exist but tags for the other (track/album) do, those will be used instead.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>l|L</option></term>
<listitem>
<para>Specify 'l' to peak-limit the output, so that the ReplayGain peak value is full-scale. Specify 'L' to use a 6dB hard limiter that kicks in when the signal approaches full-scale.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>n{0|1|2|3}</option></term>
<listitem>
<para>Specify the amount of noise shaping. ReplayGain synthesis happens in floating point; the result is dithered before converting back to integer. This quantization adds noise. Noise shaping tries to move the noise where you won't hear it as much. 0 means no noise shaping, 1 means 'low', 2 means 'medium', 3 means 'high'.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For example, the default of 0aLn1 means 0dB preamp, use album gain, 6dB hard limit, low noise shaping.</para>
<para>--apply-replaygain-which-is-not-lossless=3 means 3dB preamp, use album gain, no limiting, no noise shaping.</para>
<para>flac 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.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment