<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="pvadd">
  <refmeta>
    <refentrytitle>pvadd</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>pvadd</refname>
    <refpurpose>
      Reads from a <emphasis>pvoc</emphasis> file and uses the data to perform additive synthesis.
      <indexterm id="IndexPvadd"><primary>pvadd</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      <emphasis>pvadd</emphasis> reads from a <link linkend="pvoc"><citetitle>pvoc</citetitle></link> file and uses the data to perform additive synthesis using an internal array of interpolating oscillators. The user supplies the wave table (usually one period of a sine wave), and can choose which analysis bins will be used in the re-synthesis.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>pvadd</command> ktimpnt, kfmod, ifilcod, ifn, ibins [, ibinoffset] [, ibinincr] [, iextractmode] [, ifreqlim] [, igatefn]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ifilcod</emphasis> -- integer or character-string denoting a control-file derived from <link linkend="pvanal"><citetitle>pvanal</citetitle></link> analysis of an audio signal. An integer denotes the suffix of a file <emphasis>pvoc.m</emphasis>; a character-string (in double quotes) gives a filename, optionally a full pathname. If not fullpath, the file is sought first in the current directory, then in the one given by the environment variable <link linkend="OrchDirFiles"><citetitle>SADIR</citetitle></link> (if defined). <emphasis>pvoc</emphasis> control files contain data organized for fft resynthesis. Memory usage depends on the size of the files involved, which are read and held entirely in memory during computation but are shared by multiple calls (see also <link linkend="lpread"><citetitle>lpread</citetitle></link>).
    </para>

    <para>
      <emphasis>ifn</emphasis> -- table number of a stored function containing a sine wave.
    </para>

    <para>
      <emphasis>ibins</emphasis> -- number of bins that will be used in the resynthesis (each bin counts as one oscillator in the re-synthesis)
    </para>

    <para>
      <emphasis>ibinoffset</emphasis> (optional) -- is the first bin used (it is optional and defaults to 0).
    </para>

    <para>
      <emphasis>ibinincr</emphasis> (optional) -- sets an increment by which <emphasis>pvadd</emphasis> counts up from <emphasis>ibinoffset</emphasis> for <emphasis>ibins</emphasis> components in the re-synthesis (see below for a further explanation).
    </para>

    <para>
      <emphasis>iextractmode</emphasis> (optional) -- determines if spectral extraction will be carried out and if so whether components that have changes in frequency below <emphasis>ifreqlim</emphasis> or above <emphasis>ifreqlim</emphasis> will be discarded. A value for <emphasis>iextractmode</emphasis> of 1 will cause <emphasis>pvadd</emphasis> to synthesize only those components where the frequency difference between analysis frames is greater than <emphasis>ifreqlim</emphasis>. A value of 2 for <emphasis>iextractmode</emphasis> will cause <emphasis>pvadd</emphasis> to synthesize only those components where the frequency difference between frames is less than <emphasis>ifreqlim</emphasis>. The default values for <emphasis>iextractmode</emphasis> and <emphasis>ifreqlim</emphasis> are 0, in which case a simple resynthesis will be done. See examples below.
    </para>

    <para>
      <emphasis>igatefn</emphasis> (optional) -- is the number of a stored function which will be applied to the amplitudes of the analysis bins before resynthesis takes place. If <emphasis>igatefn</emphasis> is greater than 0 the amplitudes of each bin will be scaled by <emphasis>igatefn</emphasis> through a simple mapping process. First, the  amplitudes of all of the bins in all of the frames in the entire analysis file are compared to determine the maximum amplitude value. This value is then used create normalized amplitudes as indeces into the stored function <emphasis>igatefn</emphasis>. The maximum amplitude will map to the last point in the function. An amplitude of 0 will map to the first point in the function. Values between 0 and 1 will map accordingly to points along the function table.This will be made clearer in the examples below.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>ktimpnt</emphasis> and <emphasis>kfmod</emphasis> are used in the same way as in <emphasis>pvoc</emphasis>.
    </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      <informalexample>
        <programlisting>
ktime <command>line</command>  0, p3, p3
        </programlisting>
      </informalexample>
    </para>

    <para>
asig  <emphasis>pvadd</emphasis> ktime, 1, <quote>oboe.pvoc</quote>, 1, 100, 2
    </para>

    <para>
      In the above, <emphasis>ibins</emphasis> is 100 and <emphasis>ibinoffset</emphasis> is 2. Using these settings the resynthesis will contain 100 components beginning with bin #2 (bins are counted starting with 0). That is, resynthesis will be done using bins 2-101 inclusive. It is usually a good idea to begin with bin 1 or 2 since the 0th and often 1st bin have data that is neither necessary nor even helpful for creating good clean resynthesis.
    </para>

    <para>
      <informalexample>
        <programlisting>
ktime line  0, p3, p3
asig  pvadd ktime, 1, <quote>oboe.pvoc</quote>, 1, 100, 2, 2
        </programlisting>
      </informalexample>
    </para>

    <para>
      The above is the same as the previous example with the addition of the value 2 used for the optional <emphasis>ibinincr</emphasis> argument. This result will still result in 100 components in the resynthesis, but <emphasis>pvadd</emphasis> will count through the bins by 2 instead of by 1. It will use bins 2, 4, 6, 8, 10, and so on. For <emphasis>ibins</emphasis>=10, <emphasis>ibinoffset</emphasis>=10, and <emphasis>ibinincr</emphasis>=10, <emphasis>pvadd</emphasis> would use bins 10, 20, 30, 40, up to and including 100.
    </para>

    <para>
      Below is an example using spectral extraction. In this example <emphasis>iextractmode</emphasis> is one and <emphasis>ifreqlim</emphasis> is 9. This will cause pvadd to synthesize only those bins where the frequency deviation, averaged over 6 frames, is greater than 9.
    </para>

    <para>
      <informalexample>
        <programlisting>
ktime line  0, p3, p3
asig  pvadd ktime, 1,  <quote>oboe.pvoc</quote>, 1, 100, 2, 2, 1, 9
        </programlisting>
      </informalexample>
    </para>

    <para>
      If <emphasis>iextractmode</emphasis> were 2 in the above, then only those bins with an average frequency deviation of less than 9 would be synthesized. If tuned correctly, this technique can be used to separate the pitched parts of the spectrum from the noisy parts. In practice this depends greatly on the type of sound, the quality of the recording and digitization, and also on the analysis window size and frame increment.
    </para>

    <para>
      Next is an example using amplitude gating. The last 2 in the argument list stands for f2 in the score.
    </para>

    <para>
      <informalexample>
        <programlisting>
asig  pvadd ktime, 1,  <quote>oboe.pvoc</quote>, 1, 100, 2, 2, 0, 0, 2
        </programlisting>
      </informalexample>
    </para>

    <para>
      Suppose the score for the above were to contain:
    </para>

    <para>
      <informalexample>
        <programlisting>
f2 0 512 7 0 256 1 256 1
        </programlisting>
      </informalexample>
    </para>

    <para>
      Then those bins with amplitudes of 50% of the maximum or greater would be left unchanged, while those with amplitudes less than 50% of the maximum would be scaled down. In this case the lower the amplitude the more severe the scaling down would be. But suppose the score contains:
    </para>

    <para>
      <informalexample>
        <programlisting>
f2 0 512 5 1 512 .001
        </programlisting>
      </informalexample>
    </para>

    <para>
      In this case lower amplitudes will be left unchanged and greater ones will be scaled down, turning the sound <quote>upside-down</quote> in terms of the amplitude spectrum! Functions can be arbitrarily complex. Just remember that the normalized amplitude values of the analysis are themselves the indeces into the function.
    </para>

    <para>
      Finally, both spectral extraction and amplitude gating can be used together. The example below will synthesize only those components that with a frequency deviation of less than 5Hz per frame and it will scale the amplitudes according to F2.
    </para>

    <para>
      <informalexample>
        <programlisting>
asig  pvadd ktime, 1,  <quote>oboe.pvoc</quote>, 1, 100, 1, 1, 2, 5, 2
        </programlisting>
      </informalexample>
    </para>

    <note>
      <title>USEFUL HINTS</title>
      <para>
        By using several <emphasis>pvadd</emphasis> units together, one can gradually fade in different parts of the resynthesis, creating various <quote>filtering</quote> effects. The author uses <emphasis>pvadd</emphasis> to synthesis one bin at a time to have control over each separate component of the re-synthesis.
      </para>

      <para>
        If any combination of <emphasis>ibins</emphasis>, <emphasis>ibinoffset</emphasis>, and <emphasis>ibinincr</emphasis>, creates a situation where <emphasis>pvadd</emphasis> is asked to used a bin number greater than the number of bins in the analysis, it will just use all of the available bins, and give no complaint.  So to use every bin just make <emphasis>ibins</emphasis> a big number (ie. 2000).
      </para>

      <para>
        Expect to have to scale up the amplitudes by factors of 10-100, by the way.
      </para>
    </note>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: Richard Karpen</member>
        <member>Seattle, WA USA</member>
        <member>1998</member>
      </simplelist>
    </para>

    <para>New in Csound version 3.48, additional arguments version 3.56</para>
  </refsect1>
</refentry>
