OSClisten — Listen for OSC messages to a particular path.


On each k-cycle looks to see if an OSC message has been send to a given path of a given type.


kans OSClisten ihandle, idest, itype [, xdata1, xdata2, ...]


ihandle -- a handle returned by an earlier call to OSCinit, to associate OSClisten with a particular port number.

idest -- a string that is the destination address. This takes the form of a file name with directories. Csound uses this address to decide if messages are meant for csound.

itype -- 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. Fot type 'G' a variable or constant can be used.

A handler is inserted into the listener (see OSCinit) to intercept messages of this pattern.


kans -- set to 1 if a new message was received, or zero 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.

If there was a message the xdata variables are set to the incoming values, as interpretted by the itype parameter. Note that although the xdata 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.


The example shows a pair of floating point numbers being received on port 7770.

  sr = 44100
  ksmps = 100
  nchnls = 2

  gihandle OSCinit 7770

  instr   1
    kf1 init 0
    kf2 init 0
    kk  OSClisten gihandle, "/foo/bar", "ff", kf1, kf2
if (kk == 0) goto ex
    printk 0,kf1
    printk 0,kf2
    kgoto nxtmsg

Below are two .csd files which demonstrate the usage of the OSC opcodes. They use the files OSCmidisend.csd and OSCmidircv.csd.

Example 599. Example of the OSC opcodes.

The following two .csd files demonstrate the usage of the OSC opcodes in csound. The first file, OSCmidisend.csd, transforms received real-time MIDI messages into OSC data. The second file, OSCmidircv.csd, 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.

CSD file to send OSC messages:

; Select audio/midi flags here according to platform
; Audio out   Audio in
-odac           -iadc    ;;;RT audio I/O

  sr	    =  44100
  ksmps	    =  128
  nchnls    =  1

; Example by David Akbari 2007
; Modified by Jonathan Murphy
; Use this file to generate OSC events for OSCmidircv.csd

#define IPADDRESS	# "localhost" #
#define PORT 		# 47120 #

turnon 1000

    instr	1000

  kst, kch, kd1, kd2  midiin

  OSCsend   kst+kch+kd1+kd2, $IPADDRESS, $PORT, "/midi", "iiii", kst, kch, kd1, kd2


f 0 3600  ;Dummy f-table

CSD file to receive OSC messages:

; Select audio/midi flags here according to platform
; Audio out   Audio in
-odac           -iadc    ;;;RT audio I/O

  sr	    =  44100
  ksmps	    =  128
  nchnls    =  1

; Example by Jonathan Murphy and Andres Cabrera 2007
; Use file OSCmidisend.csd to generate OSC events for this file

  0dbfs	    =  1

  gilisten  OSCinit   47120

  gisin	    ftgen     1, 0, 16384, 10, 1
  givel	    ftgen     2, 0, 128, -2, 0
  gicc	    ftgen     3, 0, 128, -7, 100, 128, 100  ;Default all controllers to 100
;Define scale tuning
  giji_12   ftgen     202, 0, 32, -2, 12, 2, 256, 60, 1, 16/15, 9/8, 6/5, 5/4, 4/3, 7/5, \
                               3/2, 8/5, 5/3, 9/5, 15/8, 2

#define DEST #"/midi"#
; Use controller number 7 for volume
#define VOL #7#

turnon 1000

    instr   1000

  kst	    init      0
  kch	    init      0
  kd1	    init      0
  kd2	    init      0


  kk	    OSClisten	gilisten, $DEST, "iiii", kst, kch, kd1, kd2

if (kk == 0) goto done

printks "kst = %i, kch = %i, kd1 = %i, kd2 = %i\\n", \
         0, kst, kch, kd1, kd2

if (kst == 176) then
;Store controller information in a table
	    tablew    kd2, kd1, gicc

if (kst == 144) then
;Process noteon and noteoff messages.
  kkey	    =  kd1
  kvel	    =  kd2
  kcps	    cpstun    kvel, kkey, giji_12
  kamp	    =  kvel/127

if (kvel == 0) then
	    turnoff2  1001, 4, 1
elseif (kvel > 0) then
	    event     "i", 1001, 0, -1, kcps, kamp

	kgoto	next  ;Process all events in queue


    instr 1001   ;Simple instrument

  icps	    init      p4
  kvol	    table     $VOL, gicc  ;Read MIDI volume from controller table
  kvol	    =  kvol/127

  aenv     linsegr    0, .003, p5, 0.03, p5 * 0.5, 0.3, 0
  aosc	    oscil     aenv, icps, gisin

	    out	      aosc * kvol

f 0 3600  ;Dummy f-table

See Also

OSCsend, OSCinit

More information on this opcode: http://www.youtube.com/watch?v=JX1C3TqP_9Y , made by Andrés Cabrera


Author: John ffitch
Examples by: David Akbari, Andrés Cabrera and Jonathan Murphy 2007

types aAG are new in Csound 6.07