<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="sfplaym">
  <refmeta>
    <refentrytitle>sfplaym</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>sfplaym</refname>
    <refpurpose>
      Plays a SoundFont2 (SF2) sample preset, generating a mono sound.
      <indexterm id="IndexSfplaym"><primary>sfplaym</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Plays a SoundFont2 (SF2) sample preset, generating a mono sound. These opcodes allow management the sample-structure of SF2 files. In order to understand the usage of these opcodes, the user must have some knowledge of the SF2 format, so a brief description of this format can be found in the <link linkend="MiscSf2"><citetitle>SoundFont2 File Format Appendix</citetitle></link>.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>sfplaym</command> ivel, inotenum, xamp, xfreq, ipreindex [, iflag] [, ioffset]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ivel</emphasis> -- velocity value
    </para>

    <para>
      <emphasis>inotenum</emphasis> -- MIDI note number value
    </para>

    <para>
      <emphasis>ipreindex</emphasis> -- preset index
    </para>

    <para>
      <emphasis>iflag</emphasis> (optional) -- flag regarding the behavior of <emphasis>xfreq</emphasis> and <emphasis>inotenum</emphasis>
    </para>

    <para>
      <emphasis>ioffset</emphasis> (optional) -- start playing at offset, in samples.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>xamp</emphasis> -- amplitude correction factor
    </para>

    <para>
      <emphasis>xfreq</emphasis> -- frequency value or frequency multiplier, depending by <emphasis>iflag</emphasis>. When <emphasis>iflag</emphasis> = 0, <emphasis>xfreq</emphasis> is a multiplier of a the default frequency, assigned by SF2 preset to the <emphasis>inotenum</emphasis> value. When <emphasis>iflag</emphasis> = 1, <emphasis>xfreq</emphasis> is the absolute frequency of the output sound, in Hz. Default is 0.
    </para>

    <para>
      When <emphasis>iflag</emphasis> = 0, <emphasis>inotenum</emphasis> sets the frequency of the output according to the MIDI note number used, and <emphasis>xfreq</emphasis> is used as a multiplier. When <emphasis>iflag</emphasis> = 1, the frequency of the output, is set directly by <emphasis>xfreq</emphasis>. This allows the user to use any kind of micro-tuning based scales. However, this method is designed to work correctly only with presets tuned to the default equal temperament. Attempts to use this method with a preset already having non-standard tunings, or with drum-kit-based presets, could give unexpected results.
    </para>

    <para>
      Adjustment of the amplitude can be done by varying the <emphasis>xamp</emphasis> argument, which acts as a multiplier.
    </para>

    <para>
      Notice that both <emphasis>xamp</emphasis> and <emphasis>xfreq</emphasis> can use k-rate as well as a-rate signals. Both arguments must use variables of the same rate, or <emphasis>sfplay</emphasis> will not work correctly. <emphasis>ipreindex</emphasis> must contain the number of a previously assigned preset, or Csound will crash.
    </para>

    <para>
      The <emphasis>ioffset</emphasis> parameter allows the sound to start from a sample different than the first one. The user should make sure that its value is within the length of the specific sound. Otherwise, Csound will probably crash.
    </para>

    <para>
      <emphasis>sfplaym</emphasis> is a mono version of <link linkend="sfplay"><citetitle>sfplay</citetitle></link>. It should be used with mono preset, or with the stereo presets in which stereo output is not required. It is faster than <emphasis>sfplay</emphasis>.
    </para>

    <para>
      These opcodes only support the sample structure of SF2 files. The modulator structure of the SoundFont2 format is not supported in Csound. Any modulation or processing to the sample data is left to the Csound user, bypassing all restrictions forced by the SF2 standard.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="sfilist"><citetitle>sfilist</citetitle></link>,
      <link linkend="sfinstr"><citetitle>sfinstr</citetitle></link>,
      <link linkend="sfinstrm"><citetitle>sfinstrm</citetitle></link>,
      <link linkend="sfload"><citetitle>sfload</citetitle></link>,
      <link linkend="sfpassign"><citetitle>sfpassign</citetitle></link>,
      <link linkend="sfplay"><citetitle>sfplay</citetitle></link>,
      <link linkend="sfplist"><citetitle>sfplist</citetitle></link>,
      <link linkend="sfpreset"><citetitle>sfpreset</citetitle></link>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: &namegabriel;</member>
        <member>Italy</member>
        <member>May 2000</member>
      </simplelist>
    </para>

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