<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="dam">
  <refmeta>
    <refentrytitle>dam</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>dam</refname>
    <refpurpose>
      A dynamic compressor/expander.
      <indexterm id="IndexDam"><primary>dam</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      This opcode dynamically modifies a gain value applied to the input sound <emphasis>ain</emphasis> by comparing its power level to a given threshold level. The signal will be compressed/expanded with different factors regarding that it is over or under the threshold.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>dam</command> asig, kthreshold, icomp1, icomp2, irtime, iftime</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>icomp1</emphasis> -- compression ratio for upper zone.
    </para>

    <para>
      <emphasis>icomp2</emphasis> -- compression ratio for lower zone
    </para>

    <para>
      <emphasis>irtime</emphasis> -- gain rise time in seconds. Time over which the gain factor is allowed to raise of one unit.
    </para>

    <para>
      <emphasis>iftime</emphasis> -- gain fall time in seconds. Time over which the gain factor is allowed to decrease of one unit.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>asig</emphasis> -- input signal to be modified
    </para>

    <para>
      <emphasis>kthreshold</emphasis> -- level of input signal which acts as the threshold. Can be changed at k-time (e.g. for ducking)
    </para>

    <para>
      Note on the compression factors: A compression ratio of one leaves the sound unchanged. Setting the ratio to a value smaller than one will compress the signal (reduce its volume) while setting the ratio to a value greater than one will expand the signal (augment its volume).
    </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      Because the results of the <emphasis>dam</emphasis> opcode can be subtle, I recommend looking at them in a graphical audio editor program like <emphasis>audacity</emphasis>. <emphasis>audacity</emphasis> is available for Linux, Windows, and the MacOS and may be downloaded from <ulink url="http://audacity.sourceforge.net/"><citetitle>http://audacity.sourceforge.net</citetitle></ulink>.
    </para>

    <para>
      Here is an example of the dam opcode. It uses the files <ulink url="examples/dam.orc"><citetitle>dam.orc</citetitle></ulink>, <ulink url="examples/dam.sco"><citetitle>dam.sco</citetitle></ulink>, and <ulink url="examples/beats.wav"><citetitle>beats.wav</citetitle></ulink>.

      <example>
        <title>An example of the dam opcode compressing an audio signal.</title>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/dam.orc" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/dam.sco" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>
      </example>

      This example compresses the audio file <quote>beats.wav</quote>. You should hear a drum pattern repeat twice. The second time, the sound should be quieter (compressed) than the first. 
    </para>

    <para>
      Here is another example of the dam opcode. It uses the files <ulink url="examples/dam_expanded.orc"><citetitle>dam_expanded.orc</citetitle></ulink>, <ulink url="examples/dam_expanded.sco"><citetitle>dam_expanded.sco</citetitle></ulink>, and <ulink url="examples/mary.wav"><citetitle>mary.wav</citetitle></ulink>.

      <example>
        <title>An example of the dam opcode expanding an audio signal.</title>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/dam_expanded.orc" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/dam_expanded.sco" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>
      </example>

      This example expands the audio file <quote>mary.wav</quote>. You should hear a melody repeat twice. The second time, the sound should be louder (expanded) than the first. 
    </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: Marc Resibois</member>
        <member>Belgium</member>
        <member>1997</member>
      </simplelist>
    </para>
    <para>Examples written by &namekevin;.</para>
  </refsect1>
</refentry>
