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, either from a custom-defined
       OSC server or from the Csound UDP server.
    </refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>
    <para>Plugin opcode in osc; internal opcode (for UDP server)</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>

    <synopsis>kans, ... <command>OSClisten</command> idest, itype</synopsis>
   
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ihandle</emphasis>
      -- In the first two versions (overloads) of the opcode, a handle
      returned by an earlier call to OSCinit,
      to associate
      OSClisten with a particular port number. The third overload does
      not take a handle as it will listen for messages
      sent to the Csound <link linkend="udpserver"><citetitle>UDP server</citetitle></link>. 
    </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>

    <para>
     The third overload uses a different number of outputs of
     different types (k or S) to store messages matching address and
     type, which are coming into the UDP server. It only accepts
     scalar values ("dfhi")  or strings ("s"). 
    </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>

    <para>
      The next example demonstrates the usage of the third overload of
      the OSClisten opcode. It uses the fils <ulink url="examples/OSClistenex2.csd"><citetitle>OSClistenex2.csd</citetitle></ulink>.
    </para>

          <xi:include href="examples-xml/OSClistenex2.csd.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
    
  </refsect1>
  
     <refsect1>
        <title>See also</title>
        <para><link linkend="OSC"><citetitle>OSC (Open Sound Control)</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; Victor Lazzarini</member>
        <member>2005, 2024</member>
        <member>Examples by: David Akbari, &nameandres; and Jonathan
        Murphy 2007; Victor Lazzarini 2024</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>
        <member>UDP server support new in Csound 7.0</member>
      </simplelist>
    </para>
  </refsect1>
</refentry>