<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="phaser2">
  <refmeta>
    <refentrytitle>phaser2</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>phaser2</refname>
    <refpurpose>
      Second-order allpass filters arranged in a series.
      <indexterm id="IndexPhaser2"><primary>phaser2</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      An implementation of <emphasis>iord</emphasis> number of second-order allpass filters in series.
   </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>phaser2</command> asig, kfreq, kq, kord, kmode, ksep, kfeedback</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>iskip</emphasis> (optional, default=0) -- used to control initial disposition of internal data space. Since filtering incorporates a feedback loop of previous output, the initial status of the storage space used is significant. A zero value will clear the space; a non-zero value will allow previous information to remain. The default value is 0.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kfreq</emphasis> -- frequency (in Hz) of the filter(s). This is the center frequency of the notch of the first allpass filter in the series. This frequency is used as the base frequency from which the frequencies of the other notches are derived.
    </para>

    <para>
      <emphasis>kq</emphasis> -- Q of each notch. Higher Q values result in narrow notches. A Q between 0.5 and 1 results in the strongest &quot;phasing&quot; effect, but higher Q values can be used for special effects.
    </para>

    <para>
      <emphasis>kord</emphasis> -- the number of allpass stages in series. These are second-order filters, and iord can range from 1 to 2499. With higher orders, the computation time increases.
    </para>

    <para>
      <emphasis>kfeedback</emphasis> -- amount of the output which is fed back into the input of the allpass chain. With larger amounts of feedback, more prominent notches appear in the spectrum of the output. <emphasis>kfeedback</emphasis> must be between -1 and +1. for stability.
    </para>

    <para>
      <emphasis>kmode</emphasis> -- used in calculation of notch frequencies.
    </para>

    <note>
      <title>Note</title>
      <para>
        Although <emphasis>kord</emphasis> and <emphasis>kmode</emphasis> are listed as k-rate, they are in fact accessed only at init-time. So if you are using k-rate arguments, they must be assigned with <link linkend="init"><citetitle>init</citetitle></link>.
      </para>
    </note>

    <para>
      ksep -- scaling factor used, in conjunction with <emphasis>imode</emphasis>, to determine the frequencies of the additional notches in the output spectrum.
    </para>

    <para>
      <emphasis>phaser2</emphasis> implements <emphasis>iord</emphasis> number of second-order allpass sections, connected in series. The use of second-order allpass sections allows for the precise placement of the frequency, width, and depth of notches in the frequency spectrum. <emphasis>iord</emphasis> is used to directly determine the number of notches in the spectrum; e.g. for <emphasis>iord</emphasis> = 6, there will be 6 notches in the output spectrum.
    </para>

    <para>
      There are two possible modes for determining the notch frequencies. When <emphasis>imode</emphasis> = 1, the notch frequencies are determined the following function:
      <literallayout>
frequency of notch N = kbf + (ksep * kbf * N-1)
      </literallayout>
    </para>

    <para>
      For example, with <emphasis>imode</emphasis> = 1 and <emphasis>ksep</emphasis> = 1, the notches will be in harmonic relationship with the notch frequency determined by <emphasis>kfreq</emphasis> (i.e. if there are 8 notches, with the first at 100 Hz, the next notches will be at 200, 300, 400, 500, 600, 700, and 800 Hz). This is useful for generating a &quot;comb filtering&quot; effect, with the number of notches determined by <emphasis>iord</emphasis>. Different values of <emphasis>ksep</emphasis> allow for inharmonic notch frequencies and other special effects. <emphasis>ksep</emphasis> can be swept to create an expansion or contraction of the notch frequencies. A useful visual analogy for the effect of sweeping <emphasis>ksep</emphasis> would be the bellows of an accordion as it is being played - the notches will be seperated, then compressed together, as <emphasis>ksep</emphasis> changes.
    </para>

    <para>
      When <emphasis>imode</emphasis> = 2, the subsequent notches are powers of the input parameter <emphasis>ksep</emphasis> times the initial notch frequency specified by <emphasis>kfreq</emphasis>. This can be used to set the notch frequencies to octaves and other musical intervals. For example, the following lines will generate 8 notches in the output spectrum, with the notches spaced at octaves of <emphasis>kfreq</emphasis>:
      <literallayout>
aphs    <emphasis>phaser2</emphasis>    ain, kfreq, 0.5, 8, 2, 2, 0
aout    <emphasis>=</emphasis>          ain + aphs
      </literallayout>
    </para>

    <para>
      When <emphasis>imode</emphasis> = 2, the value of <emphasis>ksep</emphasis> must be greater than 0. <emphasis>ksep</emphasis> can be swept to create a compression and expansion of notch frequencies (with more dramatic effects than when <emphasis>imode</emphasis> = 1).
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the phaser2 opcode. It uses the files <ulink url="examples/phaser2.orc"><citetitle>phaser2.orc</citetitle></ulink> and <ulink url="examples/phaser2.sco"><citetitle>phaser2.sco</citetitle></ulink>.

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

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

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

  <refsect1>
    <title>Technical History</title>
    <para>
      A general description of the differences between flanging and phasing can be found in Hartmann [1]. An early implementation of first-order allpass filters connected in series can be found in Beigel [2], where the bilinear z-transform is used for determining the phase shift frequency of each stage. Cronin [3] presents a similar implementation for a four-stage phase shifting network. Chamberlin [4] and Smith [5] both discuss using second-order allpass sections for greater control over notch depth, width, and frequency.
    </para>
  </refsect1>

  <refsect1>
    <title>References</title>
    <para>
      <orderedlist>
        <listitem>
          <para>
            Hartmann, W.M. &quot;Flanging and Phasers.&quot; Journal of the Audio Engineering Society, Vol. 26, No. 6, pp. 439-443, June 1978. 
          </para>
        </listitem>

        <listitem>
          <para>
            Beigel, Michael I. &quot;A Digital 'Phase Shifter' for Musical Applications, Using the Bell Labs (Alles-Fischer) Digital Filter Module.&quot; Journal of the Audio Engineering Society, Vol. 27, No. 9, pp. 673-676,September 1979. 
          </para>
        </listitem>

        <listitem>
          <para>
            Cronin, Dennis. &quot;Examining Audio DSP Algorithms.&quot; Dr. Dobb's Journal, July 1994, p. 78-83.
          </para>
        </listitem>

        <listitem>
          <para>
            Chamberlin, Hal. Musical Applications of Microprocessors. Second edition. Indianapolis, Indiana: Hayden Books, 1985.
          </para>
        </listitem>

        <listitem>
          <para>
            Smith, Julius O. &quot;An Allpass Approach to Digital Phasing and Flanging.&quot; Proceedings of the 1984 ICMC, p. 103-108.
          </para>
        </listitem>
      </orderedlist>
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="phaser1"><citetitle>phaser1</citetitle></link>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: &namesean;</member>
        <member>Seattle, Washington</member>
        <member>1999</member>
      </simplelist>
    </para>

    <para>November 2002. Added a note about the <emphasis>kord</emphasis> and <emphasis>kmode</emphasis> parameters, thanks to &namerasmus;.</para>
    <para>New in Csound version 4.0</para>
  </refsect1>
</refentry>
