<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="pvanal">
  <refmeta>
    <refentrytitle>pvanal</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>pvanal</refname>
    <refpurpose>
      Converts a soundfile into a series of short-time Fourier transform frames.
      <indexterm id="IndexPvanal"><primary>pvanal</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Fourier analysis for the Csound <link linkend="pvoc"><citetitle>pvoc</citetitle></link> generator
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis><command>csound -U pvanal</command> [flags] infilename outfilename</synopsis>

    <synopsis><command>pvanal</command> [flags] infilename outfilename</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Pvanal extension to create a PVOC-EX file.</title>
    <para>
      The standard Csound utility program pvanal has been extended to enable a PVOC-EX format file to be created, using the existing interface. To create a PVOC-EX file, the file name must be given the required extension, <quote>.pvx</quote>, e.g <quote>test.pvx</quote>. The requirement for the FFT size to be a power of two is here relaxed, and any positive value is accepted; odd numbers are rounded up internally. However, power-of-two sizes are still to be preferred for all normal applications.
    </para>

    <para>
      The channel select flags are ignored, and all source channels will be analysed and written to the output file, up to a compiler-set limit of eight channels. The analysis window size (iwinsize) is set internally to double the FFT size.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>pvanal</emphasis> converts a soundfile into a series of short-time Fourier transform (STFT) frames at regular timepoints (a frequency-domain representation). The output file can be used by <link linkend="pvoc"><citetitle>pvoc</citetitle></link> to generate audio fragments based on the original sample, with timescales and pitches arbitrarily and dynamically modified. Analysis is conditioned by the flags below. A space is optional between the flag and its argument.
    </para>

    <para>
      <emphasis>-s srate</emphasis> -- sampling rate of the audio input file. This will over-ride the srate of the soundfile header, which otherwise applies. If neither is present, the default is 10000.
    </para>

    <para>
      <emphasis>-c channel</emphasis> -- channel number sought. The default is 1.
    </para>

    <para>
      <emphasis>-b begin</emphasis> -- beginning time (in seconds) of the audio segment to be analyzed. The default is 0.0
    </para>

    <para>
      <emphasis>-d duration</emphasis> -- duration (in seconds) of the audio segment to be analyzed. The default of 0.0 means to the end of the file.
    </para>

    <para>
      <emphasis>-n frmsiz</emphasis> -- STFT frame size, the number of samples in each Fourier analysis frame. Must be a power of two, in the range 16 to 16384. For clean results, a frame must be larger than the longest pitch period of the sample. However, very long frames result in temporal &quot;smearing&quot; or reverberation. The bandwidth of each STFT bin is determined by sampling rate / frame size. The default framesize is the smallest power of two that corresponds to more than 20 milliseconds of the source (e.g. 256 points at 10 kHz sampling, giving a 25.6 ms frame).
    </para>

    <para>
      <emphasis>-w windfact</emphasis> -- Window overlap factor. This controls the number of Fourier transform frames per second. Csound's <link linkend="pvoc"><citetitle>pvoc</citetitle></link> will interpolate between frames, but too few frames will generate audible distortion; too many frames will result in a huge analysis file. A good compromise for windfact is 4, meaning that each input point occurs in 4 output windows, or conversely that the offset between successive STFT frames is framesize/4. The default value is 4. Do not use this flag with <emphasis>-h</emphasis>.
    </para>

    <para>
      <emphasis>-h hopsize</emphasis> -- STFT frame offset. Converse of above, specifying the increment in samples between successive frames of analysis (see also <link linkend="lpanal"><citetitle>lpanal</citetitle></link>). Do not use with <emphasis>-w</emphasis>.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      <informalexample>
        <programlisting>
<emphasis>pvanal</emphasis> asound pvfile
        </programlisting>
      </informalexample>

      will analyze the soundfile &quot;asound&quot; using the default frmsiz and windfact to produce the file &quot;pvfile&quot; suitable for use with pvoc.
    </para>

    <refsect2>
      <title>Files</title>
      <para>
        The output file has a special <emphasis>pvoc</emphasis> header containing details of the source audio file, the analysis frame rate and overlap. Frames of analysis data are stored as float, with the magnitude and <quote>frequency</quote> (in Hz) for the first N/2 + 1 Fourier bins of each frame in turn. <quote>Frequency</quote> encodes the phase increment in such a way that for strong harmonics it gives a good indication of the true frequency. For low amplitude or rapidly moving harmonics it is less meaningful.
      </para>
    </refsect2>

    <refsect2>
      <title>Diagnostics</title>
      <para>
        Prints total number of frames, and frames completed on every 20th.
      </para>
    </refsect2>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>Author: Dan Ellis</para>
    <para>MIT Media Lab</para>
    <para>Cambrige, Massachussetts</para>
    <para>1990</para>
  </refsect1>
</refentry>
