HelpSource/Guides/OSC_communication.schelp

   1 title:: OSC_communication
   2 categories:: OpenSoundControl
   3 summary:: OSC network communication
   4 related:: Classes/NetAddr, Classes/OSCresponderNode
   5
   6 OSC communication between programs is often done to send messages from one application to another, possibly with the applications running on different computers. In SuperCollider this communication is done by creating a link::Classes/NetAddr:: of the target application and creating an link::Classes/OSCresponderNode:: to listen to another application. The underlying protocol of OSC is either UDP or TCP.
   7
   8 section::Sending OSC to another application
   9
  10 To establish communication to another application, you need to know on which port that application is listening. For example if an application is listening on port 7771, we can create a NetAddr and send it a message:
  11 code::
  12 b = NetAddr.new("127.0.0.1", 7771);     // create the NetAddr
  13 b.sendMsg("/hello", "there");   // send the application the message "hello" with the parameter "there"
  14 ::
  15
  16 section::Receiving OSC from another application
  17
  18 To listen to another application, that application needs to send a message to the port SuperCollider is listening on. Normally the default port is 57120, but it could be something different if that port was already bound when SC started. The current default port can be retrieved with
  19 code::
  20 NetAddr.langPort;       // retrieve the current port SC is listening to
  21 ::
  22 Or you can retrieve both the IP and the port with:
  23 code::
  24 NetAddr.localAddr       // retrieve the current IP and port
  25 ::
  26
  27 You can open additional ports using link::Classes/Main#-openUDPPort::. This will return a link::Classes/Boolean:: indicating whether SC succeeded in opening the new port.
  28 code::
  29 thisProcess.openUDPPort(1121); // attempt to open 1121\rthisProcess.customPorts; // list all open custom ports
  30 ::
  31
  32 To listen to incoming messages, an link::Classes/OSCFunc:: needs to be created in SuperCollider. If the sending application strong::has a fixed port it sends message from::, you can set the OSCFunc to listen only to messages coming from that IP and port:
  33 code::
  34 n = NetAddr.new("127.0.0.1", 7771);     // create the NetAddr
  35 // create the OSCresponderNode
  36 o = OSCFunc({ arg msg, time, addr, recvPort; [msg, time, addr, recvPort].postln; }, '/goodbye', n);
  37 o.free; // remove the OSCFunc when you are done.
  38 ::
  39
  40 section::Receiving from an application that is sending from a variable port
  41
  42 Some applications (notably Pd and Max) do not send messages from a fixed port, but instead use a different port each time they send out a message. In that case the OSCFunc needs to be set up, so that it listens to messages coming from anywhere. You do this by passing nil as the srcID argument.
  43 code::
  44 o = OSCFunc({ arg msg, time, addr, recvPort; [msg, time, addr, recvPort].postln; }, '/goodbye'); // create the OSCresponderNode
  45 o.free; // remove the OSCresponderNode when you are done.
  46 ::
  47
  48 section::Testing incoming traffic
  49
  50 OSCFunc has a convenience method, link::Classes/OSCFunc#*trace:: which posts all incoming OSC messages:
  51 code::
  52 OSCFunc.trace(true); // Turn posting on
  53 OSCFunc.trace(false); // Turn posting off
  54 ::
  55
  56 section::Custom OSC message processing
  57
  58 All incoming OSC messages call the message recvOSCmessage, or recvOSCbundle in link::Classes/Main::. If needed, one can add a custom link::Classes/Function:: or other object to Main's recvOSCFunc variable. Although one can do this directly using the corresponding setter, it is better to use the link::Classes/Main#-addOSCFunc:: and link::Classes/Main#-removeOSCFunc:: to avoid overwriting any other functions that may have been added by class code.
  59 code::
  60 // this example is basically like OSCFunc.trace
  61 (
  62 f = { |time, addr, msg|
  63         if(msg[0] != '/status.reply') {
  64                 "time: % sender: %\nmessage: %\n".postf(time, addr, msg);
  65         }
  66 };
  67 thisProcess.addOSCFunc(f);
  68 );
  69
  70 // stop posting.
  71 thisProcess.removeOSCFunc(f);
  72 ::