Skip to content

OSClisten

Listen for OSC messages to a particular path, either from a custom-defined OSC server or from the Csound UDP server.

Plugin opcode in osc; internal opcode (for UDP server)

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

Syntax

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

Initialization

ihandle -- 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 UDP server.

idest -- 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.

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

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

Performance

kans -- 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.

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.

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 kdata may be used in place of xdata variables. kdata 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.

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").

Examples

This 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
nxtmsg:
    kk  OSClisten gihandle, "/foo/bar", "ff", kf1, kf2
if (kk == 0) goto ex
    printk 0,kf1
    printk 0,kf2
    kgoto nxtmsg
ex:
  endin

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.

    gihandle OSCinit 7770
    instr   1
      ; the UI object behind the OSC sender has 5 buttons arranged as radio buttons
      kdata[] init 5
  nxtmsg:
      kk, kdata  OSClisten gihandle, "/foo/bar", "fffff"
  if (kk == 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 maxarray kdata
      printks "button %d (zero-based) is set\n", 0, kidx
      kgoto nxtmsg
  ex:
    endin

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.

OSCmidisend.csd
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<CsoundSynthesizer>
<CsOptions>
; Select audio/midi flags here according to platform
; Audio out   Audio in
-odac           -iadc    ;;;RT audio I/O
</CsOptions>
<CsInstruments>

  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

    endin


</CsInstruments>
<CsScore>
f 0 3600  ;Dummy f-table
e
</CsScore>
</CsoundSynthesizer>
OSCmidircv.csd.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<CsoundSynthesizer>
; network_recv.csd
<CsOptions>
; Select audio/midi flags here according to platform
; Audio out   Audio in
-odac           -iadc    ;;;RT audio I/O
</CsOptions>
<CsInstruments>

  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

next:

  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
endif  

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
endif
endif

        kgoto   next  ;Process all events in queue

done:
    endin



    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
    endin


</CsInstruments>
<CsScore>
f 0 3600  ;Dummy f-table
e
</CsScore>
</CsoundSynthesizer>

The next example demonstrates the usage of the third overload of the OSClisten opcode. It uses the file OSClistenex2.csd.

OSClistenex2.csd
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<CsoundSynthesizer>
<CsOptions>
-odac --port=7000
</CsOptions>
<CsInstruments>

0dbfs = 1

instr 1
 freq:k chnget "freq"
 amp:k  chnget "amp"
    out oscili(0dbfs*amp, p4*freq)
 status:k, f:k, mess:S, n:k OSClisten "/in", "fsi"
 puts mess, status
 printk2 n
 printk2 f
 status, nums:k[] OSClisten "/ina", "fi"
 printk2 nums[0]
 printk2 nums[1] 
endin

instr 2
 OSCsend 0, "localhost", 7000, "/csound/event/instr", "ffff", 1, 0, 1, 300
 OSCsend 1, "localhost", 7000, "/csound/channel/freq/amp", "ff", p4, p5
 OSCsend 2, "localhost", 7000, "/in", "fsi", p5, "hello", p4
 OSCsend 3, "localhost", 7000, "/ina", "fi", p5, p4
 OSCsend 4, "localhost", 7000, "/csound/event", "s", "i3 4 1"
 OSCsend 5, "localhost", 7000, "/csound/compile", "s", "schedule 1,2,2,500"
endin

instr 3
 OSCsend 0, "localhost", 7000, "/csound/stop"
endin

</CsInstruments>
<CsScore>
i2 0 2 1 0.2
</CsScore>
</CsoundSynthesizer>

See also

OSC (Open Sound Control)

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

Credits

Author: John ffitch Victor Lazzarini
2005, 2024
Examples by: David Akbari, Andrés Cabrera and Jonathan Murphy 2007; Victor Lazzarini 2024

Types aAG are new in Csound 6.07
The use an an array for outputs is new in Csound 6.12
UDP server support new in Csound 7.0