<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="vpvoc">
  <refmeta>
    <refentrytitle>vpvoc</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>vpvoc</refname>
    <refpurpose>
      Implements signal reconstruction using an fft-based phase vocoder and an extra envelope.
      <indexterm id="IndexVpvoc"><primary>vpvoc</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Implements signal reconstruction using an fft-based phase vocoder and an extra envelope.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>vpvoc</command> ktimpnt, kfmod, ifile [, ispecwp] [, ifn]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ifile</emphasis> -- the pvoc number (n in pvoc.n) or the name in quotes of the analysis file made using pvanal. (See <link linkend="pvoc"><citetitle>pvoc</citetitle></link>.)
    </para>

    <para>
      <emphasis>ispecwp</emphasis> (optional, default=0) -- if non-zero, attempts to preserve the spectral envelope while its frequency content is varied by <emphasis>kfmod</emphasis>. The default value is zero.
    </para>

    <para>
      <emphasis>ifn</emphasis> (optional, default=0) -- optional function table containing control information for vpvoc. If <emphasis>ifn</emphasis> = 0, control is derived internally from a previous <emphasis>tableseg</emphasis> or <emphasis>tablexseg</emphasis> unit. Default is 0. (New in Csound version 3.59)
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>ktimpnt</emphasis> -- The passage of time, in seconds, through the analysis file. <emphasis>ktimpnt</emphasis> must always be positive, but can move forwards or backwards in time, be stationary or discontinuous, as a pointer into the analysis file. 
    </para>

    <para>
      <emphasis>kfmod</emphasis> -- a control-rate transposition factor: a value of 1 incurs no transposition, 1.5 transposes up a perfect fifth, and .5 down an octave.
    </para>

    <para>
      This implementation of <emphasis>pvoc</emphasis> was orignally written by Dan Ellis. It is based in part on the system of Mark Dolson, but the pre-analysis concept is new. The  spectral extraction and amplitude gating (new in Csound version 3.56) were added by Richard Karpen based on functions in SoundHack by Tom Erbe.
    </para>

    <para>
      <emphasis>vpvoc</emphasis> is identical to <link linkend="pvoc"><citetitle>pvoc</citetitle></link> except that it takes the result of a previous <link linkend="tableseg"><citetitle>tableseg</citetitle></link> or <link linkend="tablexseg"><citetitle>tablexseg</citetitle></link> and uses the resulting function table (passed internally to the <emphasis>vpvoc</emphasis>), as an envelope over the magnitudes of the analysis data channels. Optionally, a table specified by <emphasis>ifn</emphasis> may be used. 
    </para>

    <para>
      The result is spectral enveloping. The function size used in the <emphasis>tableseg</emphasis> should be <emphasis>framesize/2,</emphasis> where framesize is the number of bins in the phase vocoder analysis file that is being used by the <emphasis>vpvoc</emphasis>. Each location in the table will be used to scale a single analysis bin. By using different functions for <emphasis>ifn1</emphasis>, <emphasis>ifn2</emphasis>, etc.. in the <emphasis>tableseg</emphasis>, the spectral envelope becomes a dynamically changing one. See also <link linkend="tableseg"><citetitle>tableseg</citetitle></link> and <link linkend="tablexseg"><citetitle>tablexseg</citetitle></link>.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      The following example, using <emphasis>vpvoc</emphasis>, shows the use of functions such as

      <informalexample>
        <programlisting>
<emphasis>f</emphasis> 1 0 256 5 .001 128 1 128 .001
<emphasis>f</emphasis> 2 0 256  5 1 128 .001 128 1
<emphasis>f</emphasis> 3 0 256  7 1 256 1
       </programlisting>
      </informalexample>

      to scale the amplitudes of the separate analysis bins.
    </para>

    <para>
      <informalexample>
        <programlisting>
ktime   <emphasis>line</emphasis>            0, p3,3 ; time pointer, in seconds, into file
        <emphasis>tablexseg</emphasis>       1, p3*.5, 2, p3*.5, 3
apv     <emphasis>vpvoc</emphasis>           ktime,1, &quot;pvoc.file&quot;
       </programlisting>
      </informalexample>
    </para>

    <para>
      The result would be a time-varying <quote>spectral envelope</quote> applied to the phase vocoder analysis data. Since this amplifies or attenuates the amount of signal at the frequencies that are paired with the amplitudes which are scaled by these functions, it has the effect of applying very accurate filters to the signal. In this example the first table would have the effect of a band-pass filter, gradually be band-rejected over half the note's duration, and then go towards no modification of the magnitudes over the second half.
   </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="pvoc"><citetitle>pvoc</citetitle></link>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Authors: Dan Ellis and Richard Karpen</member>
        <member>Seattle, WA USA</member>
        <member>1997</member>
      </simplelist>
    </para>
  </refsect1>
</refentry>
