<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="granule">
  <refmeta>
    <refentrytitle>granule</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>granule</refname>
    <refpurpose>
      A more complex granular synthesis texture generator.
      <indexterm id="IndexGranule"><primary>granule</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      The <emphasis>granule</emphasis> unit generator is more complex than <emphasis>grain</emphasis>, but does add new possibilities.
    </para>

    <para>
      <emphasis>granule</emphasis> is a Csound unit generator which employs a wavetable as input to produce granularly synthesized audio output. Wavetable data may be generated by any of the GEN subroutines such as <link linkend="GEN01"><citetitle>GEN01</citetitle></link> which reads an audio data file into a wavetable. This enable a sampled sound to be used as the source for the grains. Up to 128 voices are implemented internally. The maximum number of voices can be increased by redefining the variable MAXVOICE in the grain4.h file. <emphasis>granule</emphasis> has a build-in random number generator to handle all the random offset parameters. Thresholding is also implemented to scan the source function table at initialization stage. This facilitates features such as skipping silence passage between sentences.
    </para>

    <para>
      The characteristics of the synthesis are controlled by 22 parameters. <emphasis>xamp</emphasis> is the amplitude of the output and it can be either audio rate or control rate variable.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>granule</command> xamp, ivoice, iratio, imode, ithd, ifn, ipshift, igskip, igskip_os, ilength, kgap, igap_os, kgsize, igsize_os, iatt, idec [, iseed] [, ipitch1] [, ipitch2] [, ipitch3] [, ipitch4] [, ifnenv]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>xamp</emphasis> -- amplitude.
    </para>

    <para>
      <emphasis>ivoice</emphasis> -- number of voices.
    </para>

    <para>
      <emphasis>iratio</emphasis> -- ratio of the speed of the gskip pointer relative to output audio sample rate. eg. 0.5 will be half speed.
    </para>

    <para>
      <emphasis>imode</emphasis> -- +1 grain pointer move forward (same direction of the gskip pointer), -1 backward (oppose direction to the gskip pointer) or 0 for random.
    </para>

    <para>
      <emphasis>ithd</emphasis> -- threshold, if the sampled signal in the wavetable is smaller then <emphasis>ithd</emphasis>, it will be skipped.
    </para>

    <para>
      <emphasis>ifn</emphasis> -- function table number of sound source.
    </para>

    <para>
      <emphasis>ipshift</emphasis> -- pitch shift control. If <emphasis>ipshift</emphasis> is 0, pitch will be set randomly up and down an octave. If <emphasis>ipshift</emphasis> is 1, 2, 3 or 4, up to four different pitches can be set amount the number of voices defined in <emphasis>ivoice</emphasis>. The optional parameters <emphasis>ipitch1</emphasis>, <emphasis>ipitch2</emphasis>, <emphasis>ipitch3</emphasis> and <emphasis>ipitch4</emphasis> are used to quantify the pitch shifts.
    </para>

    <para>
      <emphasis>igskip</emphasis> -- initial skip from the beginning of the function table in sec.
    </para>

    <para>
      <emphasis>igskip_os</emphasis> -- gskip pointer random offset in sec, 0 will be no offset.
    </para>

    <para>
      <emphasis>ilength</emphasis> -- length of the table to be used starting from <emphasis>igskip</emphasis> in sec.
    </para>

    <para>
      <emphasis>kgap</emphasis> -- gap between grains in sec.
    </para>

    <para>
      <emphasis>igap_os</emphasis> -- gap random offset in % of the gap size, 0 gives no offset.
    </para>

    <para>
      <emphasis>kgsize</emphasis> -- grain size in sec.
    </para>

    <para>
      <emphasis>igsize_os</emphasis> -- grain size random offset in % of grain size, 0 gives no offset.
    </para>

    <para>
      <emphasis>iatt</emphasis> -- attack of the grain envelope in % of grain size.
    </para>

    <para>
      <emphasis>idec</emphasis> -- decade of the grain envelope in % of grain size.
    </para>

    <para>
      <emphasis>iseed</emphasis> (optional, default=0.5) -- seed for the random number generator.
    </para>

    <para>
      <emphasis>ipitch1, ipitch2, ipitch3, ipitch4</emphasis> (optional, default=1) -- pitch shift parameter, used when <emphasis>ipshift</emphasis> is set to 1, 2, 3 or 4. Time scaling technique is used in pitch shift with linear interpolation between data points. Default value is 1, the original pitch.
    </para>

    <para>
      <emphasis>ifnenv</emphasis> (optional, default=0) -- function table number to be used to generate the shape of the envelope.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the granule opcode. It uses the files <ulink url="examples/granule.orc"><citetitle>granule.orc</citetitle></ulink>, <ulink url="examples/granule.sco"><citetitle>granule.sco</citetitle></ulink>, and <ulink url="examples/mary.wav"><citetitle>mary.wav</citetitle></ulink>.

      <example>
        <title>Example of the granule opcode.</title>

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

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

   <para>
     The above example reads a sound file called <emphasis>mary.wav</emphasis> into wavetable number 1 with 262,144 samples. It generates 10 seconds of stereo audio output using the wavetable. In the orchestra file, all parameters required to control the synthesis are passed from the score file. A <emphasis>linseg</emphasis> function generator is used to generate an envelope with 0.5 second of linear attack and decay. Stereo effect is generated by using different seeds for the two <emphasis>granule</emphasis> function calls. In the example, 0.17 is added to p20 before passing into the second <emphasis>granule</emphasis> call to ensure that all of the random offset events are different from the first one.
   </para>

   <para>
     In the score file, the parameters are interpreted as:

     <informaltable frame="all">
       <tgroup cols="2" colsep="1" rowsep="1">
         <thead>
           <row>
             <entry>Parameter</entry>
             <entry>Interpreted As</entry>
           </row>
         </thead>

         <tbody>
           <row>
             <entry>p5 (<emphasis>ivoice</emphasis>)</entry>
             <entry>the number of voices is set to 64</entry>
           </row>

           <row>
             <entry>p6 (<emphasis>iratio</emphasis>)</entry>
             <entry>set to 0.5, it scans the wavetable at half of the speed of the audio output rate</entry>
           </row>

           <row>
             <entry>p7 (<emphasis>imode</emphasis>)</entry>
             <entry>set to 0, the grain pointer only move forward</entry>
           </row>

           <row>
             <entry>p8 (<emphasis>ithd</emphasis>)</entry>
             <entry>set to 0, skipping the thresholding process</entry>
           </row>

           <row>
             <entry>p9 (<emphasis>ifn</emphasis>)</entry>
             <entry>set to 1, function table number 1 is used</entry>
           </row>

           <row>
             <entry>p10 (<emphasis>ipshift</emphasis>)</entry>
             <entry>set to 4, four different pitches are going to be generated</entry>
           </row>

           <row>
             <entry>p11 (<emphasis>igskip</emphasis>)</entry>
             <entry>set to 0 and p12 (igskip_os) is set to 0.005, no skipping into the wavetable and a 5 mSec random offset is used</entry>
           </row>

           <row>
             <entry>p13 (<emphasis>ilength</emphasis>)</entry>
             <entry>set to 5, 5 seconds of the wavetable is to be used</entry>
           </row>

           <row>
             <entry>p14 (<emphasis>kgap</emphasis>)</entry>
             <entry>set to 0.01 and p15 (igap_os) is set to 50, 10 mSec gap with 50% random offset is to be used</entry>
           </row>

           <row>
             <entry>p16 (<emphasis>kgsize</emphasis>)</entry>
             <entry>set to 0.02 and p17 (igsize_os) is set to 50, 20 mSec grain with 50% random offset is used</entry>
           </row>

           <row>
             <entry>p18 (<emphasis>iatt</emphasis>) and p19 (<emphasis>idec</emphasis>)</entry>
             <entry>set to 30, 30% of linear attack and decade is applied to the grain</entry>
           </row>

           <row>
             <entry>p20 (<emphasis>iseed</emphasis>)</entry>
             <entry>seed for the random number generator is set to 0.39</entry>
           </row>

           <row>
             <entry>p21 - p24</entry>
             <entry>pitches set to 1 which is the original pitch, 1.42 which is a 5th up, 0.29 which is a 7th down and finally 2 which is an octave up.</entry>
           </row>
         </tbody>
       </tgroup>
     </informaltable>
   </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: Allan Lee</member>
        <member>Belfast</member>
        <member>1996</member>
      </simplelist>
    </para>
  </refsect1>
</refentry>
