Skip to content

OSC

NOTE: OSC is only available for users with a Synesthesia Pro license. Check out our upgrades page if you'd like to go Pro.

Overview

OSC opens up a powerful channel of communication between Synesthesia and other software. It stands for Open Sound Control, and it's a networking protocol. You can think of it like an alternative to MIDI that is much more powerful and flexible and can be sent over a network (learn more).

You can use OSC to control Synesthesia from other apps on your machine, from a different computer on the same network, and even from your phone or tablet. You can build custom interfaces and tools for Synesthesia, expanding its functionality however you like.

It also enables you to harness the Synesthesia Audio Engine in other software, sending out audio analysis data in real-time.

In order to send or receive OSC messages, you'll need to use OSC-compatible software. There are tons of options — here are some great ones:

OSC Audio Variable Output

One of Synesthesia's core features is the Audio Engine, which analyzes music in real-time and outputs a host of data to the scenes (see the audio uniforms page for reference). You can output all of this data over OSC, allowing you to create audio reactive content in other software.

To set up OSC Output, go to the Settings tab and find the "OSC" section. There are three settings related to OSC Output:

  • Output Audio Variables. When this is on, all of the Synesthesia Audio Engine's data will be outputted to the specified address and port.
  • Output Address. This is the IP address that Synesthesia will send OSC to.
    • 127.0.0.1 is the special "localhost" address. Use this to send messages to other software running on the same machine.
    • 255.255.255.255 is the special "broadcast" address. When this address is selected, Synesthesia will send to all machines on the local network.
    • To target specific machines on your network, you need to determine the local IP address of that machine. Here's a tutorial to find your local IP address on Mac or Windows.
  • Output Port. This is the networking port to send to. This port must match the incoming port selected in the receiving software. You can choose any integer up to 65535.

OSC Input

Setup

To set up OSC Input, go to the Settings tab and find the "OSC" section. There are two settings related to OSC Input:

  • Input. Turn OSC input on or off.
  • Input Port. This is the networking port on which Synesthesia will listen for incoming messages. You can choose any integer up to 65535.

Controls

Setting Controls

You can update control values using a set of fixed OSC addresses — no need to set up any mappings.

Set a control's value by sending numbers to the address /controls/controlName. The control name is insensitive to case and spacing characters like "_" and "-", so you don't have to be exact; "/controls/my_slider", "/controls/MySlider", and "/controls/m-Y-s-L-i-D-e-R" would all update the same slider.

You can pass in up to three float arguments with this message depending on the control type. Here are some examples messages:

  • /controls/brightness 0. — set the brightness meta control to 0
  • /controls/xy1 0.5 0.5 — set xy1 to the position 0.5, 0.5
  • /controls/high_color 0.0 1.0 1.0 — set high_color to cyan

Setting by Dimension

You can set a specific dimension of a multidimensional control by specifying the component in the address, sending messages like /controls/controlName/component. Valid component names are "x", "y", "r", "g", "b", "red", "green", and "blue".

  • /controls/xy1/x 0.5 — set the x-axis of xy1 to 0.5
  • /controls/high_color/r 1.0 — set the red channel of high_color to 1.0
  • /controls/high_color/green 0.0 — set the green channel of high_color to 0.0

Global Controls

Selecting controls by their name can be a bit limiting. If you wanted to build an OSC controller for Synesthesia, you'd need to create a separate interface for each scene with its specific controls.

To get around this, a control can be updated using a global address. You can use the same set of addresses to update scene controls for any scene, based on the type and order of control: the first slider, the second bang, the third toggle etc. If you've used MIDI to control Synesthesia, you're probably familiar with this idea of global mappings.

Set controls globally using an address like /controls/globalAddress. These global control addresses take the form scene-[controlType]-[controlIndex].

  • controlType is the type of control — slider, knob, toggle, bang, xy, color, or dropdown
  • controlIndex specifies the position of the control within the scene controls, starting at 0

Here are some examples:

  • /controls/scene-slider-0 controls the first slider
  • /controls/sceneSlider0 also controls the first slider (spacing characters and case don't matter)
  • /controls/scene-bang-1 controls the second bang
  • /controls/scene-toggle-2 controls the third toggle
  • /controls/scene-xy-0/x controls the x dimension of the first xy

Random and Default

You can randomize a control or set it to its default value by sending special arguments to the control's address. "Random" or "r" will set the control to a random value, while "default" or "d" will set it to default.

  • /controls/high_color "random" — set high_color to a random color
  • /controls/brightness "d" — return brightness to its default value

Scenes

You can use OSC to launch any scene loaded in Synesthesia by sending the message /scenes sceneName, using the name of the scene as the argument. As with control names, the scene name is flexible -- both /scenes "alien_cavern" and /scenes "AlienCavern" would launch Alien Cavern.