OSC

OSC offers you the ultimate control over every aspect of Resolume.

OSC stands for Open Sound Control. You can read more about its origins.

The important things to know is that you can send OSC over a network, and you have much finer control than via MIDI or DMX. You enable OSC in Resolume in the OSC tab of the Preferences.

OSC Addresses

Every item in the Resolume can be controlled via its OSC address. Instead of clicking with the mouse, you control things by sending messages to a control's address. It's essentially a way of sending an email to Resolume, telling it to set a certain control to a certain value.

The addresses are all fixed and set up already. This means that with OSC, you can start controlling everything right away. Unlike MIDI and keyboard shortcuts, that require you to first link a control to a specific shortcut.

For instance, if you would like to set the opacity of layer 1 to 25%, you send an OSC message to the address "/composition/layers/1/video/opacity", while specifying 0.25 as a value.

/composition/layers/1/video/opacity 0.25

That's it! That's all you need to do. There's no need to assign any shortcuts or load presets. You can always use this OSC message to set the opacity of layer one. On every computer running Resolume. All the time.

You can control every UI item the same way. 

Let's say we want to set the playhead of clip 8 in layer 2 to the beginning of the clip. We can do that by sending the following message:

/composition/layers/2/clips/8/transport/position 0.0

So how do you figure out what the address is for a particular control? Although there is a certain logic to it, it's easiest to just enter OSC Shortcut mode (Shortcuts > Edit OSC), and click the desired control.

The Shortcuts panel will show you the correct address. You can click the address itself, ready for copypasta goodness.

"But Resolume, why don't you have a list of every OSC address in Resolume? That would be super handy! "

Yeah, kind of, but not really when you think about it. The list of addresses changes depending on how you have your composition set up. Also, it adds up quickly. Like, really quickly. To give you an idea, here's a list with the OSC addresses for a composition with only one clip in only one layer, without any effects. Enjoy.

Multiple Addresses

Some controls can be accessed by more than one address. For instance, below are the two addresses by which you can access the Speed parameter of a Goo effect on Layer one.

Which one you need depends on how you want to use it.

The first one is what we call the absolute address. It controls the Goo effect in the first layer, and the first layer only.

The second one is the relative address. It always controls the Goo effect, but on a different layer, depending on which layer is currently selected. So if you have Goo effects on every layer, you can control each of them with the same OSC address. You just need to switch the selected layer first.

If there is no Goo effect on the currently selected layer, it's still perfectly safe to send something to this address. It just won't do anything.

Type Tags and Range

When you select a UI item, you can also see its Type Tag. Type Tag is a fancy term for what values you can send to an address and what the result will be.

Float

For instance, /composition/video/effects/transform/scale has the type tag Float 0.0 - 1.0 (range 0.0 - 1000.0). 

This means that you can send fractional values between 0 and 1, to set the scale of the composition to a value between 0% and 1000%. So sending 0 will set it to 0%, sending 0.1 will set to 100%, 0.5 to 500% and 1.0 to 1000%.

Similarly, /composition/video/effects/transform/rotationz has the Type Tag Float 0.0 - 1.0 (range -180.0 - 180.0). This means that the values range from rotated 180 degree counterclockwise, to 180 degrees clockwise. Sending 0.5 will put it smack dab in the center.

Int

Some address have Int as a type tag.

For instance, the layer one blend mode can be reached at /composition/layers/1/video/mixer/blendmode. And you can send it a whole number between 0 and 50.

Each whole number will select one of the 51 available blend modes. 

"Wait. 51? But you said whole numbers to 50?"

Yes. Us computer types like to start counting at 0, so that gives 51 in total. I know, it's a silly thing to do, but humour us, please.

Nerd Alert! If you're so inclined, you can still send a float value to addresses that specify an int. This will result in a linear translation of the the float value between 0.0 and 1.0 to the range of the parameter you're addressing.

Color

As a special case, you can send an OSC color value to color pickers.

OSC color values have the type tag r followed by an unsigned integer representing a 32 bit RGBA color. You can write a color as an int by bitshifting its RGBA values.  If that all sounds very nerdy, you can check out Vezer, which does all the hard work for you.

String

You can send text to text inputs. This way you can dynamically update the Text Block and Text Animator sources.

Strings have the type tag s followed by the text itself.

Absolute values

"Hold up, Resolume. This whole type tag thing sounds needlessly complex. Why I gotta do all this math and looking up which blend mode is what number. And who in their right mind starts counting at 0 or writes a color by shifting bits? This is super geeky! Can't I just say what I need like a normal person?"

Good point, and yes, you can. Well, you're a VJ, so by definition you're not a normal person. But yeah, you can just say what you need. Just not like a normal person.

For instance, for blend modes, you can just send the name of the blend mode you want to use as a string.

/composition/selectedlayer/video/mixer/blendmode "Alpha"

This will set the blend mode of the selected layer to alpha.

If the application that you use to send OSC will let you send multiple arguments, you can do a similar thing for absolute values. 

This makes a lot of sense if you want to position a clip on a specific x and y pixel value. You can do this by first specifying that you want to use the absolute value. You do this by using "a" as the first argument after the address, followed by the absolute value itself.

/composition/layers/1/clips/1/video/effects/transform/positionx "a" 320

This will set clip 1 in layer 1 to 320 pixels along the x-axis.

Relative values

It gets even better! You can specify relative changes to a value. 

For instance, you can use a "+", "-", or "*" to respectively add, subtract or multiply the current value with the incoming one:

/composition/layers/1/video/effects/transform/positionx "+" 50

Will move your layer one by 50 pixels to the right.

Sending OSC to Resolume

Okay, so by now you probably understood the concept of how OSC works in Resolume. But how do you actually send OSC?

Good question! There are a looooot of applications that can send OSC. 

The most famous one is TouchOSC, which is available for most devices. TouchOSC let's you create your own custom interfaces, making them an ideal pairing with Resolume's fixed addresses. It means anyone can load up an interface you've created, and it will work out of the box.

On OSX, there is the amazing Vezer. Vezer is wicked because it lets you create complex keyframe animation, which can then in turn be used to control every item of Resolume's UI.

And Resolume power user Zoltan Palffy has created his own application which adds functionality to make Resolume more suited for theater show control.

OSC really shines when used in combination with a creative programming language. This will let you create your own logic or extract data from various processes, and pipe it to Resolume.

Processing, openFrameworks, Arduino, TouchDesigner, JUCE, Max/MSP and tons of others all have libraries to support sending and receiving OSC messages. You can use Max4Live to send OSC from Ableton Live. There's even javascript libraries to send OSC right from the browser.
Finally there is our own creative programming language Resolume Wire

The options are pretty much endless. To get you started, here are two examples of how you could use OSC in TouchOSC and Processing.

Making Connections

OSC messages get sent over a network. If you want to use OSC between two computers, you first have to make sure they are connected to the same network. OSC messages are pretty small, so if you're not sending 1000s of messages per second, a WIFI network can be fine. 

Tip! The strength of a WIFI network goes down considerably when 5000 people start snapchatting during a party.

If you want to send OSC from one computer to another, the sender first needs to know where to send its messages. When you enable OSC input in Resolume, it will let other computers know where they can send their messages. It does this via a protocol called ZeroConf, also known as Bonjour on a Mac.  If your sender application has support for this, Resolume will pop right up as a destination.

If your sender application doesn't support ZeroConf/Bonjour, you will need to fill out the IP address and port number manually.

IP addresses are basically a string of numbers that let computers know where they can find each other. Resolume will let you know the IP address of the computer it's running on in the top of the OSC Preferences.

Every application can specify the port number on which it would like to receive its OSC messages. By default, in Resolume this is port number 7000. You can change it to whatever you like.

The OSC Preferences tab has a fold out window to see the last 200 OSC messages that Resolume has received or sent. This is a great way to check if you are actually receiving anything, and what the messages actually are.

OSC Output

Aside from listening to OSC messages, Resolume can also talk back via OSC. OSC Output can be enabled via the Preferences as well.

There's a few ways that you can manage what messages Resolume sends. The easiest is using OSC Shortcut presets.

Go into OSC Shortcut mode via Shortcuts > Edit OSC. The Shortcuts panel will appear. Here you can check your current OSC output setup, and switch between a few presets.

By selecting the "Output All OSC Messages" preset, Resolume will output ALL the OSC messages. Doh-doi.

This means that everything that changes in the interface will be sent out. Clip triggers, mouse and midi input, parameter automation, clip playhead position. For everything. On all the addresses. Absolute and relative.

This is great, because this way, you can monitor the current state of Resolume. For instance, you could be designing an application that takes a particular action based on clip triggers. Using the Output All preset, you can quite easily filter the incoming data for the addresses you're interested in and base your logic on that.

It also means that things can add up quickly. When sending messages over a shifty wireless connection, it's quite possible you lose a few messages here and there.

To make sure you get the data you need and just the data you need, you can create your own preset. You do this by selecting New... from the Preset dropdown. After giving it a good name (I like "Leia". Because she's the princess of presets), you can selectively go through all UI elements that you'd like to send OSC output for. 

Let's say you're only interested in knowing whether the master bypass is enabled. For instance to let your control application know that it's safe to make certain changes when Resolume is bypassed.

To do this, find the Master Bypass button in the top left. By right clicking, you can enable OSC output for this and only this button. Alternatively, you can also enable OSC output for a UI item in the OSC Shortcuts panel.

By selectively enabling output for just the items you're interested in, you can greatly cut down on network traffic.

Wildcards

But hold up, Resolume. I'm interested in the opacity of each of my 12 layers, and clip triggers for all 472 clips in my deck. I'm not going to sit there and click each of these items. I've got better things to do with my life. Like binge watching every season of Rick and Morty.

Yeah, I feel you. That szechuan sauce is important. That's why we introduced wildcards. For clips, layers and groups, you can enable OSC outputs for all items at the same time.

Let's say we're interested in the video opacity of every layer. After creating an OSC Output Shortcut for just one layer, we can change the scope to 'All Layers'.

Boom. In one fell swoop, we've enabled output for the video opacity of all your layers. You can do the same thing for clip triggers, even clips that haven't been added yet.

Custom OSC Messages

Sometimes you're not interested in the state of Resolume's interface. Sometimes you just want to send a little message to another application. Maybe you want to trigger a cue in Vezer when you trigger a certain clip in Resolume. Maybe you want to link the playhead of a clip in Resolume to the physics in a Processing sketch. 

I don't know if these are good examples or not. You're supposed to be the creative mind here. I never get to do anything cool with OSC anymore because I'm stuck in an office writing a manual that no-one reads.

This is possible via a Custom Address.

After creating OSC Output for something you can select this via the dropdown.

Resolume will fill out the current address for you, but you can change it whatever you want. Resolume will then send the value the item has in the Resolume interface, but to the new address instead of the fixed one.

Destinations

Just like other applications need to specifically send OSC to Resolume, OSC output from Resolume needs to have a destination as well.

In the OSC Preferences, you can select all the applications on your network that announce themselves via ZeroConf/Bonjour.

You can also choose to send to just this computer (Localhost) or to all computers on your network (Broadcast).

If you want to send to an application that doesn't support ZeroConf/Bonjour, you can also set the IP Address manually.

In the case of Localhost, Broadcast and manual IP, you also need to set the Outgoing port. This should of course be the input port of the other application.

To Bundle or not to Bundle

Toggling Use Bundles packs all your messages together and sends them in one big bundle. Most OSC applications don't really care whether you send bundles or not, but some will prefer having it on or off.

Polling

You can also ask Resolume what a certain parameter is set to. This is great when building complex control mechanisms, that have different views depending on what's going on in Resolume. 

Instead of constantly monitoring what's coming out of Resolume, you can just ask it for the info you need, when you need it.

You do this by sending a "?" to the address that you want to know about.

For instance, when sending 

/composition/layers/1/video/mixer/blendmode "?"

to Resolume, you'll get a reply on the same address with the int value of the current blend mode of layer 1. Pretty awesome.

Related Articles