<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="loscil">
  <refmeta>
    <refentrytitle>loscil</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>loscil</refname> 
    <refpurpose>
      Read sampled sound from a table.
      <indexterm id="IndexLoscil"><primary>loscil</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Read sampled sound (mono or stereo) from a table, with optional sustain and release looping.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar [,ar2] <command>loscil</command> xamp, kcps, ifn [, ibas] [, imod1] [, ibeg1] [, iend1] [, imod2,] [, ibeg2] [, iend2]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ifn</emphasis> -- function table number, typically denoting an AIFF sampled sound segment with prescribed looping points. The source file may be mono or stereo.
    </para>

    <para>
      <emphasis>ibas</emphasis> (optional) -- base frequency in <emphasis>Hz</emphasis> of the recorded sound. This optionally overrides the frequency given in the AIFF file, but is required if the file did not contain one. The default value is 261.626 Hz, i.e. middle C. (New in Csound 4.03). 
    </para>

    <para>
      <emphasis>imod1, imod2</emphasis> (optional, default=-1) -- play modes for the sustain and release loops. A value of 1 denotes normal looping, 2 denotes forward &amp; backward looping, 0 denotes no looping. The default value (-1) will defer to the mode and the looping points given in the source file.
    </para>

    <para>
      <emphasis>ibeg1, iend1, ibeg2, iend2</emphasis> (optional, dependent on <emphasis>mod1, mod2</emphasis>) -- begin and end points of the sustain and release loops. These are measured in <emphasis>sample frames</emphasis> from the beginning of the file, so will look the same whether the sound segment is monaural or stereo.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>

    <para>
      <emphasis>ar1, ar2</emphasis> -- the output at audio-rate. There is just <emphasis>ar1</emphasis> for mono output. However, there is both <emphasis>ar1</emphasis> and <emphasis>ar2</emphasis> for stereo output.
    </para>

    <para>
      <emphasis>xamp</emphasis> -- the amplitude of the output signal.
    </para>

    <para>
      <emphasis>kcps</emphasis> -- the frequency of the output signal in cycles per second.
    </para>

    <para>
      <emphasis>loscil</emphasis> samples the ftable audio at a-rate determined by <emphasis>kcps</emphasis>, then multiplies the result by <emphasis>xamp</emphasis>. The sampling increment for <emphasis>kcps</emphasis> is dependent on the table's base-note frequency <emphasis>ibas</emphasis>, and is automatically adjusted if the orchestra <emphasis>sr</emphasis> value differs from that at which the source was recorded. In this unit, ftable is always sampled with interpolation.
    </para>

    <para>
      If sampling reaches the <emphasis>sustain loop</emphasis> endpoint and looping is in effect, the point of sampling will be modified and loscil will continue reading from within that loop segment. Once the instrument has received a <emphasis>turnoff</emphasis> signal (from the score or from a MIDI <link linkend="noteoff"><citetitle>noteoff</citetitle></link> event), the next sustain endpoint encountered will be ignored and sampling will continue towards the <emphasis>release loop</emphasis> end-point, or towards the last sample (henceforth to zeros).
    </para>

    <para>
      <emphasis>loscil</emphasis> is the basic unit for building a sampling synthesizer. Given a sufficient set of recorded piano tones, for example, this unit can resample them to simulate the missing tones. Locating the sound source nearest a desired pitch can be done via table lookup. Once a sampling instrument has begun, its <emphasis>turnoff</emphasis> point may be unpredictable and require an external <emphasis>release</emphasis> envelope; this is often done by gating the sampled audio with <link linkend="linenr"><citetitle>linenr</citetitle></link>, which will extend the duration of a turned-off instrument by a specific period while it implements a decay.
    </para>

    <note>
      <title>Note</title>
      <para>
        This is mono loscil:

        <informalexample>
          <programlisting>
a1 loscil 10000, 1, 1
          </programlisting>
        </informalexample>
 
        ...and this is stereo loscil:
 
        <informalexample>
          <programlisting>
a1, a2 loscil 10000, 1, 1
          </programlisting>
        </informalexample>
      </para>
    </note>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the loscil opcode. It uses the files <ulink url="examples/loscil.orc"><citetitle>loscil.orc</citetitle></ulink>, <ulink url="examples/loscil.sco"><citetitle>loscil.sco</citetitle></ulink>, and <ulink url="examples/beats.aiff"><citetitle>beats.aiff</citetitle></ulink>.

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

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

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

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="loscil3"><citetitle>loscil3</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>Note about the mono/stereo difference was contributed by &namerasmus;.</para>
    <para>Example written by &namekevin;.</para>
  </refsect1>
</refentry>
