<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="hetro">
  <refmeta>
    <refentrytitle>hetro</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>hetro</refname>
    <refpurpose>
      Decomposes an input soundfile into component sinusoids.
      <indexterm id="IndexHetro"><primary>hetro</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Hetrodyne filter analysis for the Csound <link linkend="adsyn"><citetitle>adsyn</citetitle></link> generator.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis><command>csound -U hetro</command> [flags] infilename outfilename</synopsis>

    <synopsis><command>hetro</command> [flags] infilename outfilename</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>hetro</emphasis> takes an input soundfile, decomposes it into component sinusoids, and outputs a description of the components in the form of breakpoint amplitude and frequency tracks. Analysis is conditioned by the control flags below. A space is optional between flag and value.
    </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. Note that for <emphasis>adsyn</emphasis> synthesis the srate of the source file and the generating orchestra need not be the same.
    </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. Maximum length is 32.766 seconds.
    </para>

    <para>
      <emphasis>-f begfreq</emphasis> -- estimated starting frequency of the fundamental, necessary to initialize the filter analysis. The default is 100 (cps).
    </para>

    <para>
      <emphasis>-h partials</emphasis> -- number of harmonic partials sought in the audio file. Default is 10, maximum is a function of memory available.
    </para>

    <para>
      <emphasis>-M maxamp</emphasis> -- maximum amplitude summed across all concurrent tracks. The default is 32767.
    </para>

    <para>
      <emphasis>-m minamp</emphasis> -- amplitude threshold below which a single pair of amplitude/frequency tracks is considered dormant and will not contribute to output summation. Typical values: 128 (48 db down from full scale), 64 (54 db down), 32 (60 db down), 0 (no thresholding). The default threshold is 64 (54 db down).
    </para>

    <para>
      <emphasis>-n brkpts</emphasis> -- initial number of analysis breakpoints in each amplitude and frequency track, prior to thresholding (<emphasis>-m</emphasis>) and linear breakpoint consolidation. The initial points are spread evenly over the duration. The default is 256.
    </para>

    <para>
      <emphasis>-l cutfreq</emphasis> -- substitute a 3rd order Butterworth low-pass filter with cutoff frequency <emphasis>cutfreq</emphasis> (in Hz), in place of the default averaging comb filter. The default is 0 (don't use).
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      As of Csound 4.08, <emphasis>hetro</emphasis> can write SDIF ouput files if the output file name ends with &quot;.sdif&quot;. See the <link linkend="sdif2ad"><citetitle>sdif2ad utility</citetitle></link> for more information about the Csound's SDIF support.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      <informalexample>
        <programlisting>
<emphasis>hetro</emphasis> -s44100 -b.5 -d2.5 -h16 -M24000 audiofile.test adsynfile7
        </programlisting>
      </informalexample>

      This will analyze 2.5 seconds of channel 1 of a file &quot;audiofile.test&quot;, recorded at 44.1 kHz, beginning .5 seconds from the start, and place the result in a file &quot;adsynfile7&quot;. We request just the first 16 harmonics of the sound, with 256 initial breakpoint values per amplitude or frequency track, and a peak summation amplitude of 24000. The fundamental is estimated to begin at 100 Hz. Amplitude thresholding is at 54 db down.
    </para>

    <para>
      The Butterworth LPF is not enabled.
    </para>

    <refsect2 id="HetroFileFormat">
      <title>File Format</title>
      <para>
        The output file contains time-sequenced amplitude and frequency values for each partial of an additive complex audio source. The information is in the form of breakpoints (time, value, time, value, ....) using 16-bit integers in the range 0 - 32767. Time is given in milliseconds, and frequency in Hertz (cps). The breakpoint data is exclusively non-negative, and the values -1 and -2 uniquely signify the start of new amplitude and frequency tracks. A track is terminated by the value 32767. Before being written out, each track is data-reduced by amplitude thresholding and linear breakpoint consolidation.
      </para>

      <para>
        A component partial is defined by two breakpoint sets: an amplitude set, and a frequency set. Within a composite file these sets may appear in any order (amplitude, frequency, amplitude ....; or amplitude, amplitude..., then frequency, frequency,...). During <link linkend="adsyn"><citetitle>adsyn</citetitle></link> resynthesis the sets are automatically paired (amplitude, frequency) from the order in which they were found. There should be an equal number of each.
      </para>

      <para>
        A legal <emphasis>adsyn</emphasis> control file could have following format:
        <informalexample>
          <programlisting>
-1 time1 value1 ... timeK valueK 32767 ; amplitude breakpoints for partial 1
-2 time1 value1 ... timeL valueL 32767 ; frequency breakpoints for partial 1
-1 time1 value1 ... timeM valueM 32767 ; amplitude breakpoints for partial 2
-2 time1 value1 ... timeN valueN 32767 ; frequency breakpoints for partial 2
-2 time1 value1 ..........
-2 time1 value1 ..........             ; pairable tracks for partials 3 and 4
-1 time1 value1 ..........
-1 time2 value1 ..........
          </programlisting>
        </informalexample>
      </para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>
      October 2002. Thanks to &namerasmus;, added a note about the SDIF format.
    </para>
  </refsect1>
</refentry>
