OSC In CHOP

From TouchDesigner 088 Wiki

OSCInCHOP 16.jpg

Summary

The OSC In CHOP is used to accept Open Sound Control Messages. OSC In can be used to accept messages from either a 3rd party application which adheres to the Open Sound Control specification (http://www.cnmat.berkeley.edu/OpenSoundControl/). OSC In is based on a connection-less system, meaning that it can accept multiple messages for any number of sources at the same time. The user must specify a port number which OSC In will look for incoming messages. This port must not have anything running on it before OSC In attempts to use it. OSC CHOPs in TouchDesigner use the UDP transport protocol.

See also OSC In DAT, OSC Out CHOP, iOS and OSC, Touch In CHOP.

There are options which allow the user to adjust the default message queuing system to optimize it for their specific network conditions and usage needs. The Min/Max Target size specifies a range which the queue attempts to keep the buffer size at in seconds. Increasing the Queue Adjust Time will determine how long the queue can be outside that range before it tries to correct it.

If the user wishes to use OSC In to detect when messages are arriving, there is a Pulse Mode toggle which will read a single sample of any incoming message when it arrives and displays the pulse reset values any other time. This is useful for syncing beats between TouchDesigner and another applications.

PythonIcon.png oscinCHOP_Class

Technical Details

TouchDesigner's OSC In accepts bundled data based on the Open Sound Control specifications. Channel names are taken from the OSC-Method names given in the bundle. Currently OSC In only accepts floats, integers and 64 bit OSC-Time tags. TouchDesigner will flag a warning if any other data type arrives. If more than one piece of data is sent in an OSC-Method, they will be separated into two channels with a underscore followed by a number concatenated at the end, depending on the order they are defined in the OSC Message. Any OSC-Method names specified with spaces are automatically converted to underscores (_) on receipt in order to make valid channel names.

TouchDesigner either uses the time stamps provided in the OSC Bundle or Message. If a timestamp is provided in an OSC Message along side data, the time stamp must come before the data in the message. If a time stamp is not provided then TouchDesigner will stamp the message using the system time of when the message was received.

The OSC In CHOP will output something meaningful on any number of numeric arguments of any type (midi, rgb, etc). For example an OSC message of: /color (rgb-value) will now create channels: color1 color2 color3.

To analyze the timing of the messages coming in, attach an Info CHOP to the OSC In CHOP. It will show the internal queue size and whether it is dropping or missing data (queue_advanced_total and queue_retarded_total should not be increasing, and queue_length should not be zero).

Parameters - OSC In Page

Protocol protocol - The network protocol to use. Refer to the Network Protocols article for more information.

Network Address netaddress - When using Multicast, this is the address that OSC In will listen for packets on.

Network Port port - The port which OSC-In will accept packets on.

Active active - While on, the CHOP receives information sent to the network port. While Off, no updating occurs. Data sent to the port is lost.

Address Scope address - To reduce which channels are generated, you can use channel name patterns to include or exclude channels. For example, ^*accel* will exclude accelerometer channels coming in from an iPhone or iOS app like mrmr. See Pattern Matching for the syntax of the possible channel name patterns.

Use Global Rate useglobalrate - When on, the CHOP will sample at the global sample rate specified by TouchDesigner.

Default Sample Rate samplerate - When Use Global Rate is off, this parameter is used to determine the sample rate of this CHOP.

Minimum Target mintarget - The smallest amount of queue data (represented in seconds) allowed without adjusting sampling speed.

Maximum Target maxtarget - The largest amount of queue data (represented in seconds) allowed without adjusting sampling speed.

Maximum Queue maxqueue - The maximum allowed size of the queue (represented in seconds). If the maximum queue size is exceeded, data will be removed from the front of the queue.

Queue Adjust Time adjusttime - The maximum amount of time allowed for a queue to be above or below the maximum or minimum target without adjusting the sampling speed.

Delete Old Channels deleteold - delete channels that are old.

Reset Channels reset - Deletes all known channels and clears the queue.

Examples

Note: all data is sent in big endian format.

OSC-Message example

/channame (OSC-Method name)
,fi (OSC-Taglist, lists the types of data associated with this message)
0.234 (The value of the first piece of data)
1234 (The value of the second piece of data)

Description: This is a message which will create two channels named channame which contains the values. A float (0.234) and an integer (1234). Because there are two values for a single channel, _0 will be added to the end of the channel name containing the float (channame_0) and _1 will be added to the end of the channel containing the integer (channame_1).

OSC-Bundle example

#bundle (64-bit tag specifying this packet as a bundle)
000001 (64-bit time stamp associated with this bundle)
1st method
16 (32-bit integer, number of bytes containing the first method)\
/chan1 (OSC-Method name)
,f (OSC-Taglist, lists a single float as the types of data associated with this message)
0.12345

(32-bit float, the value of the data)

2nd method
32 (32-bit integer, Number of bytes contained the second method)
/chan2 (OSC-Method name)
,ft (OSC-Taglist, lists a float and an OSC-Timetag as the data for this message)
453.0324 (64-bit float, the value of the time tag)
0.65432 (32-bit float, the value of the float)

MAX/MSP example

Here's a Max patch for sending ints or floats to TouchDesigner. It works with a default OSC In CHOP.

<code>
----------begin_max5_patcher----------
429.3ocqTssaCBCC8Y3q.kmYcDnT51a66XZpJPRaSEjfBgN1p5+9RLPur0VP
SvCIxN1GexA6bv0AkJaXUHuW8d2yw4fqiC3x5voy1AUPZxxIUPXHQcQJSg7a
OZsTnEjBFbzaJNIu+jRhx3WyTqXBRZNDQP2YxZcNSq+pj0VYDWnQ9dnThXCx
6iKvth+MDCNbVexFBvElzA5fOUMc1VtXyJEKS2BZXrMGOLdgcKNvtFZVOgOm
BrVlt6oXzYvaIGfdn04QWW6h+X0G1mFD6wSyZ.5fpokULA0bQRlYHwLrGNv7
MrNNQpvKIv17jGICyusLDLcxPohUZkgmWKkCe2+Sexj2bDCMGIKejpDcaUA+
OTk04RCHS7viATxzO9DgWN5wmvgGefzP4bwuesAJs0+0xVkrVk0eC69K3ct3
TVklKHZtTbQLyuJlsbJkItT5n7JqZRueS8XYS3HXSz.rofSKklW95DjHyKCw
1QzX6V3B7Iqy0Yx3e7Dv+6wl1e0jxx8LUUGj.QLyB6jJq4BevjKZMg1Pjhsm
2GeL3gnLckZSKYspcHoY4BjqsNGc+APS1+ng
-----------end_max5_patcher-----------
</code>

Note: all messages are word aligned (4 bytes).

For more help understanding how to construct OSC messages, please consult the OSC Home page.

Standard Options and Local Variables

None.