OSC Plugin Overview

An overview of how the Open Sound Control (OCS) plugin works within Unreal Engine.

Windows
MacOS
Linux

Open Sound Control (OSC) is an open protocol commonly used in many areas of the audio industry. It is primarily used to network generic audio data between clients, although it can also be used for non-audio data.

The OSC plugin provides an intuitive, type-safe Blueprint library that a developer can use to quickly iterate networked audio (and potentially other domain) data in Unreal Engine. When this plugin is enabled, you can send and receive OSC events through a simple API in either C++ or Blueprint. It supports sending and receiving messages and bundles, or combinations of bundles and messages.

The OSC plugin must be enabled to use this feature. Go to Edit > Plugins > Input Devices, then check the OSC (Open Sound Control) option to enable.

Root Types

OSC Server

The OSC Server (UOSCServer) acts as a listening endpoint for messages sent to the local instance of Unreal Engine. It supports multicast loopback, and parsing of both OSC messages and bundles. It also lets the server specifically state which IP addresses it will listen to (whitelisting).

A user can bind an event to receive messages from all OSC addresses using a provided address pattern (see Binding An Event to Address Patterns below), listen for all messages (see Binding An Event to All Messages below), or listen for all bundles (similar to Binding An Event to All Messages below but requiring unpacking a received bundle).

OSC Client

The OSC Client (UOSCClient) provides a way of sending of OSC messages and bundles.

FOSCAddress

An OSC Address (FOSCAddress) is a typed path that may or may not also be a valid pattern. As a valid path, it can be created, sent, and received as part of a message packet.

It contains an array of containers and a method in the form /Container1/Container2/Method, and can be queried for validity as either a path or a pattern, converted to or from a string, and manipulated with Blueprint calls. It can also be filtered against another OSC Address that is also a pattern when binding to the event BindEventToOnOSCAddressPatternMatchesPath.

OSC Bundle/Message

Both OSC Message (FOSCMessage) and OSC Bundle (FOSCBundle) are packet types that are received from the OSC Client, or sent with the OSC Server.

An OSC Message contains an address that is also a valid path, and that has a payload of supported OSC protocol types.

An OSC Bundle contains an array of packets of either other OSC Bundles or OSC Messages, or both.

Asset Classes

The OSC plugin does not require any asset classes. All of its required types are transient and expected to be created, managed, and destroyed with Blueprint.

Blueprint API

OSC Server

OnOsc(Bundle/Message)Received

An event that gets called when an OSC bundle/message is received.

SetWhitelistClientsEnabled

When set to true, the server will only process received messages from whitelisted clients.

(UnbindEvent/UnbindAllEvents/BindEventTo/Get)OnOSCAddressPattern(s)

Unbinds, binds, removes or gets event(s) to dispatch when an OSCAddressPattern is matched.

(Add/Remove/Clear/Get)WhitelistedClient(s)

Adds, removes, clears, or gets set of client IP Addresses as strings (IPv4) that are whitelisted.

OSC Client

(Get/Set)SendIPAddress

Gets the OSC Client IP address and port.

SendOSC(Bundle/Message)

Sends an OSC bundle/message to a specific address.

OSC Bundle/Message

Add(Bundle/Message)ToBundle

Adds provided bundle/message to bundle.

Get(Bundles/Messages)FromBundle

Returns the bundles/messages found in bundle.

(Add/Get) OSC Message (Strings/String at Index, Integer/Integer at Index, and so on)

Adds/gets POD type to or from OSCMessage. (List of types supported can be found here .)

Clear OSC (Message/Bundle)

Clears the message/bundle's payload.

Resources/Examples

OSC implementation is based on the OSC 1.0 protocol found on the OpenSoundControl.org website .

Click the Copy Node Graph button on each image below and paste the text into your Blueprint Graph to see the examples in action.

Sending an OSC Message

Copy Node Graph

SendingOSCMessage.png

Binding an Event to All Messages

Copy Node Graph

BindingToAnyMessage.png

Binding an Event to Address Patterns

Copy Node Graph

BindToAddressPattern.png

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback