<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="cpstmid">
  <refmeta>
    <refentrytitle>cpstmid</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>cpstmid</refname>

    <refpurpose>
      Get a MIDI note number (allows customized micro-tuning scales).
      <indexterm id="IndexCpstmid"><primary>cpstmid</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      This unit is similar to <link linkend="cpsmidi"><citetitle>cpsmidi</citetitle></link>, but allows fully customized micro-tuning scales.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>icps <command>cpstmid</command> ifn</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ifn</emphasis> -- function table containing the parameters (<emphasis>numgrades</emphasis>, <emphasis>interval</emphasis>, <emphasis>basefreq</emphasis>, <emphasis>basekeymidi</emphasis>) and the tuning ratios.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
       Init-rate only
    </para>

    <para>
      <emphasis>cpsmid</emphasis> requires five parameters, the first, <emphasis>ifn</emphasis>, is the function table number of the tuning ratios, and the other parameters must be stored in the function table itself. The function table <emphasis>ifn</emphasis> should be generated by <link linkend="GEN02"><citetitle>GEN02</citetitle></link>, with normalization inhibited. The first four values stored in this function are:
      <orderedlist>
        <listitem><para><emphasis>numgrades</emphasis> -- the number of grades of the micro-tuning scale</para></listitem>
	<listitem><para><emphasis>interval</emphasis> -- the frequency range covered before repeating the grade ratios, for example 2 for one octave, 1.5 for a fifth etc.</para></listitem>
	<listitem><para><emphasis>basefreq</emphasis> -- the base frequency of the scale in Hz</para></listitem>
	<listitem><para><emphasis>basekeymidi</emphasis> -- the MIDI note number to which <emphasis>basefreq</emphasis> is assigned unmodified</para></listitem>
      </orderedlist>
    </para>

    <para>
      After these four values, the user can begin to insert the tuning ratios. For example, for a standard 12 note scale with the base frequency of 261 Hz assigned to the key number 60, the corresponding f-statement in the score to generate the table should be:
      <literallayout>
  ;          numgrades interval  basefreq basekeymidi tuning ratios (equal temp)   
  f1 0 64 -2   12       2        261        60         1  1.059463094359  1.122462048309  1.189207115003 ..etc...  
      </literallayout>
    </para>

    <para>
      Another example with a 24 note scale with a base frequency of 440 assigned to the key number 48, and a repetition interval of 1.5:
      <literallayout>
  ;           numgrades interval  basefreq basekeymidi tuning-ratios (equal temp)   
  f1 0 64 -2   24        1.5      440        48         1   1.01  1.02  1.03   ..etc...  
      </literallayout>
    </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the cpstmid opcode. It uses the files <ulink url="examples/cpstmid.orc"><citetitle>cpstmid.orc</citetitle></ulink> and <ulink url="examples/cpstmid.sco"><citetitle>cpstmid.sco</citetitle></ulink>.

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

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

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

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="cpsmidi"><citetitle>cpsmidi</citetitle></link>,
      <link linkend="GEN02"><citetitle>GEN02</citetitle></link>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: &namegabriel;</member>
        <member>Italy</member>
        <member>1998</member>
      </simplelist>
    </para>
    <para>Example written by &namekevin;.</para>

    <para>New in Csound version 3.492</para>
  </refsect1>
</refentry>
