This functor provides an interface to Open Sound Control (OSC), by using the UNIX programs sendOSC and dumpOSC: using these applications instead of a C/C++ library is less efficient, but more easy to implement ;-). See http://www.cnmat.berkeley.edu/OpenSoundControl/ for more details on OSC in general, and also for details about these two applications.

This functor provides a representation of OSC messages as Oz values in the following way. An OSC message is represented by an Oz tuple. The tuple label is the OSC Address Pattern (e.g., '/test'). 0 or more OSC arguments are represented by the contained tuple values. OSC arguments can be Oz integers, floats and virtual strings.

An OSC bundle is represented by an Oz list. Optionally, the first element is the time tag, followed by 0 or more OSC bundle elements (i.e. OSC messages or other bundles). Timetags can be specified in different formats, but must always be a number. The send method of the class SendOSC supports the user-definable transformation of timetags into different formats. By default, the number of milliseconds elapsed since midnight UTC of January 1, 1970 is expected (i.e. UNIX time multiplied by 1000), but other formats are possible (e.g., a float measuring in beats, where the time 0.0 is some user-defined UNIX time). Timetags in received bundles are obligarory, but may be 1 (meaning 'now'). Bundles can be nested (as sendOSC and dumpOSC support nested bundles). However, for sending bundles please note that some applications with OSC support don't support nested bundles (e.g. SuperCollider's synthesis server scsynth).

The following examples show the textual OSC representation used by sendOSC and the Oz representation alongside:

sendOSC:

/address "test string" 3.14 -42
[
/voices/0/tp/timbre_index 0
/voices/0/tm/goto 0.0
]

Oz:

'/address'("test string" 3.14 ~42)
['/voices/0/tp/timbre_index'(0) '/voices/0/tm/goto'(0.0)]
[{OSC.timeNow} '/test'(foo bar)]

Please note that this interface is only available for UNIX systems (e.g., MacOS and Linux), because sendOSC and dumpOSC are UNIX applications. Moreover, the original dumpOSC delays the printout of bundles (when called in a pipe as this interface does) and it is recommended to apply the dumpOSC patch available at ../others/dumpOSC/dumpOSC-patch.diff (or simply replace the original file dumpOSC.c with the already patched dumpOSC.c in the same directory before compiling dumpOSC).

This interface calls dumpOSC in a terminal (xterm), and sends its output to Oz with netcat via a socket. Starting dumpOSC in a terminal is necessary, because for unkown reasons dumpOSC refuses to output anything when called by Oz directly in a pipe (for details, see postings in the mailing lists osc_dev@create.ucsb.edu, and users@mozart-oz.org, on the 7 Septermber 2007 and following days). This interface relies thus on the following applications, which must be installed, and should be specified in the Strasheela environment (if they are not in the PATH): sendOSC, dumpOSC, xterm, and netcat (nc). On most Unixes, xterm is already there. On MacOS, however, X11 must be installed in order to make xterm available, and the location of X11.app must be specified in the Strasheela environment. The respective Strasheela environment variables are sendOSC (its default value is 'sendOSC'), dumpOSC (default 'dumpOSC'), xterm (default 'xterm'), netcat (default 'nc'), and 'X11.app' (default '/Applications/Utilities/X11.app').

Note that the netcat (nc) installed by default on MacOS version 10.5 (Leopard) does not work (it crashes with UDP). However, the the implementation ncat (http://sourceforge.net/projects/nmap-ncat/) has been tested successfully (remember also setting the Strasheela environment variable 'netcat' to this application).

Functor

OSC ("OSC.oz")

Import

• System
• OS
• Open
• GUtils at "x-ozlib://anders/strasheela/source/GeneralUtils.ozf"
• LUtils at "x-ozlib://anders/strasheela/source/ListUtils.ozf"
• Init at "x-ozlib://anders/strasheela/source/Init.ozf"
• Out at "x-ozlib://anders/strasheela/source/Output.ozf"
• OSC_Scanner at "source/OSC_Scanner.ozf"
• OSC_Parser at "source/OSC_Parser.ozf"

Export

• <C:SendOSC>
• <C:DumpOSC>
• <P/1:TimeNow>
• <C:Buffer>
• <P/2:HexToDecimal1000>
• <P/2:FormatHex>
• ntpToUnixTime1000:<P/2:NTPToUnixTime1000>
• <P/2:DecimalToHex_Int>
• <P/2:DecimalToHex_Frac>
• <P/2:FormatTimeTag>

Define

Implements Oz interface to the UNIX program sendOSC (using its interactive mode).

class SendOSC from Out.shell

• init(host:H port:P)
  
• send(Packet timeTagFormatter:TTFormatter)
  

end

Implements an Oz interface to dumpOSC for receiving OSC packets at a given port. Ineternally, the textual output of dumpOSC is parsed into Oz values, and a stream of OSC messages in the format described above is provided.
Please note that dumpOSC is called in a terminal (xterm), and its output is send by netcat via a socket to Oz (on MacOS X, X11 is started if not already running). See above for an explanation.
Also, note that several clients can send to dumpOSC, but no information who sends is transmitted (e.g., no sender IP). If knowing the sender is important, just include your sender in your OSC messages :)

class DumpOSC
   feat netcatPort pipe dumpOSC myScanner myParser oscs responders defaultResponderAddr

• init(port:Port)
  
• close()
  
• getOSCs($)
  
• addResponder(Address Proc)
  
• setResponder(Address Proc)
  
• removeResponder(Address)
  
• setDefaultResponder(Proc)
  
• setBundleResponder(Proc)
  
• ProcessResponders()
  
• ParseVS(Result VS)
  
• IncrCounter()
  
• DecrCounter()
  
• ExistsOpenBundle($)
  
• ParseAll($ prevLines:PrevLines)
  

end
fun{TimeNow }
Returns the milliseconds since midnight UTC of January 1, 1970, in other words UNIX time (see http://en.wikipedia.org/wiki/Unix_time) multiplied by 1000.
FIXME: presently, only plain seconds are output. Therefore, the returned value can be rather late already. For a more finegrained solution later, use e.g. gettimeofday (see http://www.penguin-soft.com/penguin/man/2/gettimeofday.html?manpath=/man/man2/gettimeofday.2.inc and http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/gettimeofday.2.html).



This class defines a buffer for any incoming data (e.g., OSC packets): arriving data is collected with the method put, and all data collected so far retrieved with the method getAll.

class Buffer

• init()
  
• put(X)
  
• getAll(Xs)
  

end
fun{HexToDecimal1000 HexChars}
[aux] Expects an hex number (string of exactly 16 ints/chars a-f, where the first 8 digits are greater 1 and the last 8 digits are less then 1, i.e. the last 8 digits are behind the dot) and returns the corresponding decimal integer times 1000.


fun{FormatHex Xs}
[aux] Transforms a list of integers representing a hexadecimal number (as returned by DecimalToHex) into a VS in the usual format.
The dumpOSC output format is created: lowercase letters are used with (however, sendOSC also understands uppercase letters and leading 0x).


fun{NTPToUnixTime1000 NTPTime1000}
[aux] NTPTime1000 (an int: NTP time in msecs) transformed into UNIX time in msecs (an int).


fun{DecimalToHex_Int X}
[aux] Outputs list of 'digits' for hexadecimal number of the decimal number X (an int).
NB: integers are used as figures: i.e. the decimal number 31 is represented as [1 15] instead of the usual 1F.


fun{DecimalToHex_Frac X}
[aux] Convert the fractional part. X is in [999, 0] msecs, corresponding to [0.999, 0.0] secs.


fun{FormatTimeTag UnixTime1000}
[aux] Outputs an OSC time tag for the given UnixTime1000 as a hexadecimal number (a VS). UnixTime1000 (an integer) are the milliseconds since midnight UTC of January 1, 1970, in other words UNIX time multiplied by 1000.



End