Node: OSC Input

Note that this node has slightly different behavior across different platforms due to fundamental differences in how *nix and Windows-based systems handle receiving broadcast messages. See Platform Dependent Networking Quirks for more information.

The OSC Input node allows you to receive OSC messages from devices on your network, and optionally process those messages as appropriate be defining a script that handles incoming messages.

Settings

	Expected Type	Details	Default
localInterface	LocalInterface	The local network adapter that will be used to UDP messages.	LocalInterface("0.0.0.0")
localPort	Number	The local port on which UDP messages will be received.	1234
syncOnBundles	Boolean	When enabled, receiving a message that is a bundle will replace all existing data with the contents of the bundle. This allows you to clear data that is not part of the latest bundle of messages. Non-bundle messages will add themselves to the available values until such time a bundle is received causing those values to be cleared.	true
addressPathFilter	String	A filter that is applied to the address path of all received OSC messages and bundles. Only messages whose address starts with the provided filter will be inserted into the values. The address path mapped into values will also have the filter portion removed, creating a more readable key for the value.	"/d3/showcontrol/"
callback	Any	A script in which a two additional variables are available. The first, address, will be a String that contains the address path with the filtered portion removed. The second, args, is a List<Any> of arguments sent as part of the message. This list can be of any size, including 0. This script will be executed every time a new message is received, allowing you to process things like transport-style messages as opposed to data-style messages.	print(address);

Parameters

In addition to the values output, each received message is processed by the script defined as the callback.

	Type	Details
values	Map<Any>	Note: The parameter is read-only. A Map of values received over OSC. This Map will be further nested as more maps to represent address paths, as in the example described below. This is done to simplify accessing nested values.

Example values for messages

Assume that the following messages are received in a bundle, and that the addressPathFilter is set to "/waltz/data/".

/waltz/data/dogs/buckeye "Basset Hound"
/waltz/data/dogs/slink "Slinky Dog"
/waltz/data/dogs/laura "Saint Bernard"
/waltz/data/turtles/chet "Box"
/waltz/data/animalTypes "Dogs" "Turtles"

will create the following structure of data (shown here as pseudo-JSON)

{
    dogs: {
        buckeye: "Basset Hound"
        slink: "Slinky Dog"
        laura: "Saint Bernard"
    },
    turtles: {
        chet: "Box"
    },
    animalTypes: [
        "Dogs",
        "Turtles"
    ]
}

This data is easily accessible as the following properties on an OSC Input node

Property	Value
$.oscInput.values.dogs.buckeye	"Basset Hound"
$.oscInput.values.dogs.slink	"Slinky Dog"
$.oscInput.values.dogs.laura	"Saint Bernard"
$.oscInput.values.turtles.chet	"Box"
$.oscInput.values.animalTypes[0]	"Dogs"
$.oscInput.values.animalTypes[1]	"Turtles"

Notice that the animalTypes property is a List because there were multiple arguments with that original OSC message, so those values can be accessed per the rules for the List type.

Functions

There are no functions exposed by this node.

Example Usage

Running a script when receiving a message

When you want to process a transport-style message that will be sent once to trigger some event, you can define a custom callback to handle messages.

Assume that the addressPathFilter is set to "/waltz/showcontrol/".

Assuming you want to run a script when a message is sent to /waltz/showcontrol/go with a single argument of 42, the following script as the callback can trigger a script function named goScript and pass it the number provided as the argument:

if (address == "go") {
    $.goScript.run(args[0]);
}

Take note that we don't check the full address path, because we have filtered by /waltz/showcontrol/, which means the address we are provided is only go.