3.21. UDP Client

3.21.1. Attributes

3.21.2. Description

This element defines the parameters of a UDP client.

OSC communication is used to exchange data between Virtual Choreographer and companion applications. Data input can consist of strings (fragments of scripts) or binary data (OSC encoding of addresses and arguments). Strings can be encoded as character arrays or as OSC bundles.

More explicitely, there are basically three types of communication:

• Plain: transmits strings, can be used to transfer XML tags.

• OSC bundles: transmits strings through OSC by embedding them in a bundle. This protocole is used to communicate with applications such as Max/MSP that use OSC as UDP communication protocole

• OSC messages: transmits binary data made of an OSC address followed by one or more arguments. This encoding has the advantage over the two preceding ones that the message is received as a structure and not a string by the external application. There no precision loss through encoding into char string, when compared with the preceding two applications.

OSC documentation is available from:

http://www.cnmat.berkeley.edu/OpenSoundControl/OSC-spec.html

The boolean value of the OSC_endian_reversal attribute defines whether the encoding of numbers has to be reversed upon OSC message emission. Depending on the system on which VC is compiled and on the encoding of numbers by the client application, the order of the bytes that encodes floats and integers may need to be reversed. The Linux and PC version of VC use little endian byte order: the low-order byte of the number is stored in memory at the lowest address, and the high-order byte at the highest address.

The string value of the send_format attribute defines the encoding format for output messages. In the Plain format, the message is made of the message string. In the OSC format the message is built as indicated by the two bottommost arrays in figure Figure 3-1, depending on whether it is made of a string or an OSC structured message (an adress and associated parameters). In order to take advantage of OSC structured messages, a VC scene can contain command aliases that convert these messages into VC commands. They are described in the aliasScript element.

The string value of the remote_ip and remote_port attributes define the IP address and remote port number of the UDP remote client.

The integer value of the output_message_stack_depth attribute defines the depth of the output message stack used to store output messages before their emission. The float value of the maximal_UDP_message_delay attribute defines the threshold delay above which unsent output UDP messages are discarded.

The string value of the send_prefix attribute defines the prefix string that is pre-concatenated to output messages. If the value of the boolean attribute send_ID is set to true, the prefix string of output messages is followed by a unique integer ID number. The integer value of the first_UDP_message_ number attribute defines the offset for output UDP message numbering.

The boolean value of the UDP_message_acknowledgement attribute defines whether acknowledgement messages are sent by the UDP client to acknowledge the reception of messages. If it is set to true, a message is only sent if the preceding message has been acknowledged by the client (if a message has been received with an acknowledgement prefix and the same ID as the preceding message).

If the boolean attribute sound_spatialization of the sound_play element is true, initializations and updates of sonified media objects are automatically sent to the clients whose listen_sound_messages attribute is true.

If the boolean value of the UDP_message_trace attribute enables the output of emitted messages to the console.

3.21.3. Expected content

None.

3.21.4. Example

The example below defines a connection with a UDP client at IP address 190.157.175.32, port 1979. Messages are emitted without waiting for an acknowledgement of the previous message by the remote client. UDP message numbering starts from 0. Messages that cannot be sent within a delay of 0.1 are discarded. Output message content is displayed on the console. Input message stack can contain up to 500 messages. Send format is OSC. Output message strings are prefixed by the string sound. Output messages are emitted with a unique integer ID following the sound prefix. (IDs begin from 0.) This client is entitled to receive sound messages for sound synthesis.

>udp_remote_client id="spatializer"
  remote_ip="129.175.157.97" remote_port="1979" 
  UDP_message_acknowledgement="false" first_UDP_message_number="0" 
  maximal_UDP_message_delay="0.10000" UDP_message_trace="true"
  output_message_stack_depth="500" send_format="OSC" send_prefix="sound"
  send_ID="true" listen_sound_messages="true" />