<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="pinkish">
  <refmeta>
    <refentrytitle>pinkish</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>pinkish</refname>
    <refpurpose>
      Generates approximate pink noise.
      <indexterm id="IndexPinkish"><primary>pinkish</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Generates approximate pink noise (-3dB/oct response) by one of two different methods:
      <itemizedlist>
        <listitem>
          <para>a multirate noise generator after Moore, coded by Martin Gardner</para>
        </listitem>

        <listitem>
          <para>a filter bank designed by Paul Kellet</para>
        </listitem>
      </itemizedlist>
   </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>pinkish</command> xin [, imethod] [, inumbands] [, iseed] [, iskip]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>imethod</emphasis> (optional, default=0) -- selects filter method: 
      <itemizedlist>
        <listitem>
          <para>0 = Gardner method (default).</para>
        </listitem>

        <listitem>
          <para>1 = Kellet filter bank.</para>
        </listitem>

        <listitem>
          <para>2 = A somewhat faster filter bank by Kellet, with less accurate response.</para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      <emphasis>inumbands</emphasis> (optional) -- only effective with Gardner method. The number of noise bands to generate. Maximum is 32, minimum is 4. Higher levels give smoother spectrum, but above 20 bands there will be almost DC-like slow fluctuations.  Default value is 20.
    </para>

    <para>
      <emphasis>iseed</emphasis> (optional, default=0) -- only effective with Gardner method. If non-zero, seeds the random generator. If zero, the generator will be seeded from current time. Default is 0.
    </para>

    <para>
      <emphasis>iskip</emphasis> (optional, default=0) -- if non-zero, skip (re)initialization of internal state (useful for tied notes).  Default is 0.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>xin</emphasis> -- for Gardner method: k- or a-rate amplitude. For Kellet filters: normally a-rate uniform random noise from rand (31-bit) or unirand, but can be any a-rate signal. The output peak value varies widely (&plusmn;15%) even over long runs, and will usually be well below the input amplitude. Peak values may also occasionally overshoot input amplitude or noise.
    </para>

    <para>
      <emphasis>pinkish</emphasis> attempts to generate pink noise (i.e., noise with equal energy in each octave), by one of two different methods.
    </para>

    <para>
      The first method, by Moore &amp; Gardner, adds several (up to 32) signals of white noise, generated at octave rates (sr, sr/2, sr/4 etc). It obtains pseudo-random values from an internal 32-bit generator. This random generator is local to each opcode instance and seedable (similar to <emphasis>rand</emphasis>).
    </para>

    <para>
      The second method is a lowpass filter with a response approximating -3dB/oct. If the input is uniform white noise, it outputs pink noise. Any signal may be used as input for this method.  The high quality filter is slower, but has less ripple and a slightly wider operating frequency range than less computationally intense versions. With the Kellet filters, seeding is not used.
    </para>

    <para>
      The Gardner method output has some frequency response anomalies in the low-mid and high-mid frequency ranges. More low-frequency energy can be generated by increasing the number of bands. It is also a bit faster.  The refined Kellet filter has very smooth spectrum, but a more limited effective range. The level increases slightly at the high end of the spectrum.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the pinkish opcode. It uses the files <ulink url="examples/pinkish.orc"><citetitle>pinkish.orc</citetitle></ulink> and <ulink url="examples/pinkish.sco"><citetitle>pinkish.sco</citetitle></ulink>.

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

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

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

      Kellet-filtered noise for a tied note (<emphasis>iskip</emphasis> is non-zero).
    </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Authors: Phil Burk and &namejohn;</member>
        <member>University of Bath/Codemist Ltd.</member>
        <member>Bath, UK</member>
        <member>May 2000</member>
      </simplelist>
    </para>

    <para>New in Csound Version 4.07</para>

    <para>
      Adapted for Csound by &namerasmus;
    </para>

    <para>
      The noise bands method is due to F. R. Moore (or R. F. Voss), and was presented by Martin Gardner in an oft-cited article in Scientific American. The present version was coded by Phil Burk as the result of discussion on the music-dsp mailing list, with significant optimizations suggested by James McCartney.
    </para>

    <para>
      The filter bank was designed by Paul Kellet, posted to the music-dsp mailing list.
    </para>

    <para>
      The whole pink noise discussion was collected on a HTML page by Robin Whittle, which is currently available at <ulink url="http://www.firstpr.com.au/dsp/pink-noise/"><citetitle>http://www.firstpr.com.au/dsp/pink-noise/</citetitle></ulink>.
    </para>

    <para>Added notes by &namerasmus; on September 2002.</para>
  </refsect1>
</refentry>
