The OSC protocol is designed to send and receive messages that are sent over the network.

On a network a host is a computer or device¹⁾, and a port is a number identifying an “input gate” to the host. Such “input gate” that can listen to OSC messages is also called a OSC Server.

When OSCulator is launched and the main window is displayed, an OSC Server is running, enabling the reception of OSC messages. On the other hand, anything that sends OSC messages is called a OSC Client.

Thus, when the OSC Routing event is used, OSCulator also acts as a OSC Client.

Like previously explained, the host is referring to a devices that runs a OSC Server. It can either be the name or the computer (mymacintosh.local.) or an IP Address (192.168.0.1).

The computer which runs OSCulator has a special name localhost and a special IP address 127.0.0.1. You can use either of these if you want to send messages to the current computer itself. This is usually the case when you are running several OSC enabled software on the same computer. For example, OSCulator could listen to OSC messages on port 8000²⁾ and Max/MSP could listen on port 9000 with the udpreceive object. They have different port numbers, but the host is the same: localhost.

Note that a unique port number can't be shared by several OSC Servers. This is a limitation of the underlying network protocol which states that a server has one only port that he owns exclusively.

If you need to send messages to another computer, you will need to know its host name. To do this, open the System Preferences and click on the Sharing Preferences Pane item. The computer name is written under Computers on the local network can access your computer at: […].

Software like Max/MSP or Reaktor can also receive OSC data. This data is sent over the network, even if it is sent to the same computer that generates the messages.

If you want to control your third-party software, or make some special routing, you can use the OSC Routing event. With this very useful event type, you can route anything to another host and port, even outside on the Internet³⁾.

It is also possible to rewrite OSC messages in order to change their name and arguments during the routing.

Perform these actions while in the main window:

1. Select the OSC message you wish to route, and choose the OSC Routing Event Type
2. In the Value menu, choose the host you want to send the messages to.
   • This is list is populated with the OSC Servers are automatically found on the local network, if you want to send the data to a specific port or host, you must configure it in the Parameters window⁴⁾

Although the OSC Servers are automatically listed, you may need to manually configure them if you want to perform more complex routing.

With this panel, you can configure the hosts, ports and rewrite address of each destinations.

On this picture, we show five destinations. Two of them will route the OSC data to the host computer2 on port 9000 and two of them will route on the local computer. The difference between the two destination is their rewrite address.

The last one has no rewrite address, because it has been left blank.

OSC messages are composed of OSC arguments. You can choose to route the whole message with all its arguments, or you can choose to route only one argument.

This picture shows the configuration of a OSC message routing. Here, the message /foo/freq has two arguments.

The destination⁵⁾ will receive the OSC message /foo/freq with its two arguments.

Here, we chose to route only the first argument of the OSC message. In this case, the destination will receive a OSC message with a single argument at the address /foo/freq/0.

As you notice, the index of the argument is appended to the destination address. This is needed in order to avoid messages collisions.

When a rewrite address is provided for a destination, its name will appear with an arrow in the Values list:

This example shows that the message /methode.cc will be routed to host localhost on port 9000 and the address will be rewritten as /synth/cutoff.

If a routing is given a rewrite address, it doesn't matter wether it is the whole OSC message or only an argument that is routed: it destination address will always be the same.

The goal here is to create a OSC router which receives OSC messages on port 8000 and routes the /foo/freq messages to port 9000 of the local host or port 9000 of the host computer2, based on the state of a trigger OSC message, /methode.cc.

1. The /methode.cc message has been duplicated 3 times, in order to be able to trigger 4 actions when its value changes. This message is bound to the Toggled Enable event which changes the “enable” state of an OSC message listed in the table.
2. The first two arguments of the message /foo/freq have been duplicated, in order to assign the two different destinations. We also clicked on the Enable column of the two arguments, so that they will be enabled and disabled subsequently when /methode.cc is triggered.

OSCulator automatically publishes and discover the OSC port on which it is running. This is why the Value menu, always show the OSC destination corresponding to your computer host name and port.

If you choose to route messages to the same document that is sending the messages, an infinite loop will occur. This is not a bug, but a feature! The decision was made to not restrict this feature, which can be used to demultiplex OSC messages and then re-route them to the same document.

This is a special case of the routing to another host on the local network.

On the same scheme as the previous section, if you create a new document and work with two windows, you can route messages from one window to another.