OSClisten.xml

<refentry id="OSClisten">
<indexterm id="IndexOSClisten"><primary>OSClisten</primary></indexterm>
  <refentryinfo><title>OSC</title></refentryinfo>
  <refmeta>
    <refentrytitle>OSClisten</refentrytitle>
  </refmeta>

  <refnamediv>
    <refname>OSClisten</refname>
    <refpurpose>
      Listen for OSC messages to a particular path.
    </refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>
    <para>Plugin opcode in osc.</para>
    <para>
      On each k-cycle looks to see if an OSC message has been sent to
      a given path of a given type.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis>kans <command>OSClisten</command> ihandle, idest, itype [, xdata1, xdata2, ...]</synopsis>
    <synopsis>kans, kdata[] <command>OSClisten</command> ihandle, idest, itype</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ihandle</emphasis>
      -- a handle returned by an earlier call to OSCinit, to associate
      OSClisten with a particular port number.
    </para>
    <para>
      <emphasis>idest</emphasis>
      -- a string that is the destination address. This takes the
      form of a path prefixed with a forward slash, with optional subdirectories
      separated by forward slashes. Csound processes incoming messages that
      match this address.
    </para>

    <para>
      <emphasis>itype</emphasis> -- a string that indicates the types
      of the optional arguments that are to be read. The string can
      contain the characters "acdfhisAG" which stand for audio,
      character, double, float, 64-bit integer, 32-bit integer,
      string, scalar array and f-table. All types other than 'asA'
      require a k-rate variable; 's' requires a string variable, 'a' an audio
      variable and 'A' an i- or k- rate array. For type 'G', a variable
      or constant can be used.
    </para>

    <para> A handler is inserted into the listener (see OSCinit) to
      intercept messages that match this pattern.
    </para>

  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kans</emphasis> -- set to 1 if a new message was
      received, or 0 if not. If multiple messages are received in
      a single control period, the messages are buffered, and OSClisten
      can be called again until zero is returned.
    </para>

    <para>
      If there was a message the <emphasis>xdata</emphasis> variables
      are set to the incoming values, as interpretted by the
      <emphasis>itype</emphasis> parameter.
      Note that although the <emphasis>xdata</emphasis> variables are on
      the right of an operation, they are actually outputs, and so must be
      variables of type a, ga, k, gk, S, gS, k[] and gk[] and may need
      to be declared with init, or = in the case of string variables,
      before calling OSClisten. 
    </para>

    <para>
      Alternatively, if the message to be received is a series of values all of
      the same scalar numeric type (e.g., one of "dfhi"), then the
      return parameter <emphasis>kdata</emphasis> may be used in place of
      <emphasis>xdata</emphasis> variables. <emphasis>kdata</emphasis> must be an
      array, it must be declared with init before calling OSClisten,
      or used with the [] syntax.  It will be created to sufficient
      size if it is other that a one dimensional array of size greater
      or equal to length as the format string. If a message is received, this
      array will be filled with the incoming values. See below for an example of
      this usage.
    </para>  </refsect1>

  <refsect1>
    <title>Example</title>
    <para>
      This example shows a pair of floating point numbers being received
      on port 7770.
    </para>

      <informalexample>
        <programlisting>
  <emphasis role="ohdr">sr</emphasis> <emphasis role="op">=</emphasis> 44100
  <emphasis role="ohdr">ksmps</emphasis> <emphasis role="op">=</emphasis> 100
  <emphasis role="ohdr">nchnls</emphasis> <emphasis role="op">=</emphasis> 2

  gihandle <emphasis role="opc">OSCinit</emphasis> 7770

  <emphasis role="oblock">instr</emphasis>   1
    kf1 <emphasis role="opc">init</emphasis> 0
    kf2 <emphasis role="opc">init</emphasis> 0
nxtmsg:
    kk  <emphasis role="opc">OSClisten</emphasis> gihandle, &quot;/foo/bar&quot;, &quot;ff&quot;, kf1, kf2
if (kk <emphasis role="opc">==</emphasis> 0) goto ex
    <emphasis role="opc">printk</emphasis> 0,kf1
    <emphasis role="opc">printk</emphasis> 0,kf2
    <emphasis role="opc">kgoto</emphasis> nxtmsg
ex:
  <emphasis role="oblock">endin</emphasis>
        </programlisting>
      </informalexample>

     <para>
        This example shows use of the alternate form of the opcode, where an
        array is used to receive a list of scalar values. In this case, the
        OSC sender is simulating a set of radio buttons (as is done, for
        example by a Lemur "Switches" object set in this mode), where the
        button that is set will have value 1.0 and all other buttons will have
        value 0.0.
      </para>
        <informalexample>
          <programlisting>
    gihandle <emphasis role="opc">OSCinit</emphasis> 7770
    <emphasis role="oblock">instr</emphasis>   1
      ; the UI object behind the OSC sender has 5 buttons arranged as radio buttons
      kdata[] <emphasis role="opc">init</emphasis> 5
  nxtmsg:
      kk, kdata  <emphasis role="opc">OSClisten</emphasis> gihandle, &quot;/foo/bar&quot;, &quot;fffff&quot;
  if (kk <emphasis role="opc">==</emphasis> 0) goto ex
      ; the only button with a non-zero value will be the one that is set,
      ; so maxarray is used to get the index of that element
      kmax, kidx <emphasis role="opc">maxarray</emphasis> kdata
      <emphasis role="opc">printks</emphasis> &quot;button %d (zero-based) is set\n&quot;, 0, kidx
      <emphasis role="opc">kgoto</emphasis> nxtmsg
  ex:
    <emphasis role="oblock">endin</emphasis>
          </programlisting>
        </informalexample>
    <para>
      Below are two .csd files which demonstrate the usage of the OSC opcodes. They use the files <ulink url="examples/OSCmidisend.csd"><citetitle>OSCmidisend.csd</citetitle></ulink> and <ulink url="examples/OSCmidircv.csd"><citetitle>OSCmidircv.csd</citetitle></ulink>.

      <example>
        <title>Example of the OSC opcodes.</title>
        <para>The following two .csd files demonstrate the usage of the OSC opcodes in csound. The first file, <ulink url="examples/OSCmidisend.csd"><citetitle>OSCmidisend.csd</citetitle></ulink>, transforms received real-time MIDI messages into OSC data. The second file, <ulink url="examples/OSCmidircv.csd"><citetitle>OSCmidircv.csd</citetitle></ulink>, can take these OSC messages, and intrepret them to generate sound from note messages, and store controller values. It will use controller number 7 to control volume. Note that these files are designed to be on the same machine, but if a different host address (in the IPADDRESS macro) is used, they can be separate machines on a network, or connected through the internet.</para>
        <para>CSD file to send OSC messages:</para>
          <xi:include href="examples-xml/OSCmidisend.csd.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
        <para>CSD file to receive OSC messages:</para>
          <xi:include href="examples-xml/OSCmidircv.csd.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
      </example>
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
      <para>
        <link linkend="OSCsend"><citetitle>OSCsend</citetitle></link>,
        <link linkend="OSCinit"><citetitle>OSCinit</citetitle></link>
      </para>
               <para> More information on this opcode: <ulink url="http://www.youtube.com/watch?v=JX1C3TqP_9Y"><citetitle>http://www.youtube.com/watch?v=JX1C3TqP_9Y</citetitle></ulink>  , made by Andrés Cabrera </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: &namejohn;</member>
        <member>2005</member>
        <member>Examples by: David Akbari, &nameandres; and Jonathan Murphy 2007</member>
      </simplelist>
    </para>
    <para>
      <simplelist>
        <member>types aAG are new in Csound 6.07</member>
        <member>the use an an array for outputs is new in Csound 6.12</member>
      </simplelist>
    </para>
  </refsect1>
</refentry>