Skip to content

Unity package to make integrating with Resolume (a VJing software) easier

License

Notifications You must be signed in to change notification settings

stella3d/Resolink

Repository files navigation

Resolink

This package aims to make integrating a Unity app with a Resolume setup easier, by doing three things.

  1. Generate event handlers in a Unity scene based on the events you setup in Resolume

  2. Handle texture sharing from Unity -> Resolume

  3. Keeping time / tempo in sync

This is not an official product of either Unity or Resolume.

Table of Contents

Aknowledgements

Installation

Setup

Supported Data Types

Time Sync

Video Protocols

Options

Wildcard Routing

Current Limitations

Dependencies

Contact

Aknowledgements

This wouldn't be possible without the work of Keijiro Takahashi. All packages this depends on were developed by him.

Installation

To use Resolink, please download the .unitypackage for your platform from the Releases page.

You can also clone this repo directly into a Unity project, but you will get tests & dependencies your platform doesn't need.

Please note that Resolink has been tested only on Unity 2019.x, and may not work on earlier versions.

Setup

The process of generating event handlers in a Unity scene for a given Resolume setup has 3 main parts.

  1. Resolume OSC Setup

    Setup OSC output from Resolume as you would for any use.
    If you're unfamiliar with how this works, check out the documentation.
    For every control you want to send a message with, right-click and Create Shortcut. Make sure that OSC output is enabled for these controls as shown. Resolume OSC output indicator

When you're done, save these OSC settings somewhere - go to the Shortcuts panel in Resolume & select Save As from the dropdown.

Note the port number you've setup to send OSC to.

  1. Creating a Unity asset

In Unity, open the Resolink window: Window > Resolink > Map Parser. You should see a window like this.

Resolink unity window

Click the first button, Select Resolume OSC Map File, and select the file you saved out of Resolume earlier.

Once you've done that, click Create OSC Map Asset to create an asset in your project that has all the settings you exported from Resolume. It will be selected for you - look around in the inspector for the asset to learn more !

  1. Scene Setup

Now that you have a map asset, drag the "Resolink" prefab (located at Resolink/Runtime/Prefabs/) into your scene. Select it, and you should see this.

unity component generator

Assign your map asset to the Osc Map field, and click Generate Event Components.
For every address / control in your OSC map, a component will be added to the appropriate object within the Resolink prefab.

These components are where you hook up Unity Events to call when a message is received at each address.

Putting the Resolink prefab in your scene also sets up video sharing back to Resolume. If you look in the Sources panel in Resolume, you should see a Spout (on Windows) or Syphon (on Mac) server with the name of your Main Camera object. Assign this to one of your clip slots in resolume to use it as a video source.

resolume spout server

You should make sure the port number shown in the Osc Router component is the same as the OSC port you setup in Resolume.

Supported Data Types

Resolume natively sends the overwhelming majority of data over OSC as an int, float, or string.

Any Resolume control that has an OSC Type Tag of Int 0 or 1 is interpreted as a bool, where 0 is false.

All of these 4 types get components like this in Unity, which show the path to receive OSC at and the event to fire when a message is received.

unity float control

Resolume sends most floating point information as a number from 0 to 1, so it may be necessary to scale or interpolate these values to achieve your specific goal.

Compound Controls

Resolume has controls that send vectors and colors, but it sends the value of each member of these controls to a different OSC address. To support these controls as a single unit, we group them on the Unity side. Resolink should automatically detect these groups for you if grouping is enabled, as it is by default.

You can toggle grouping of controls off in the Preferences menu to get float handlers for these controls instead.

Compound control types include Vector2, Vector3, Quaternion, & Color.

Vectors

In Resolume, vector controls look like this.

resolume vector control

In Unity, you get a component like this associated with the Resolume control.

unity vector control

Rotations

In Resolume, rotation controls are represented as Euler angles.

resolume rotation control

In Unity, Euler angles are converted to a Quaternion, and you get a component like this associated with the Resolume control.

unity rotation control

A note about rotations - Depending on where you position the Unity camera, the rotation can appear to be different than it is in Resolume. I spent a while trying to work out a solution where it always looks the same, but i'm not sure if that exists. For now it just provides a direct transmission of the angles that you see in the resolume UI.

Colors

Color controls are currently supported by enabling the OSC output for all 4 RGBA values, as seen below. resolume color control

In Unity, you will get a component like this associated with that group of controls from Resolume. unity color control

Resolume can send color information over OSC as a single message in a special format, but this isn't supported yet.

Time Sync

There are two built-in behaviors for keeping time in sync. To disable either, either don't output the required OSC from resolume, or disable the associated component in Unity. You'll find everything related to time sync on the Tempo Controller object in the Resolink prefab.

Pause

When you press Pause in Resolume, Unity's time scale is set to 0, which pauses anything not using unscaled time.

When you un-pause, Unity's time scale is set back to its previous value.

This relies on having an OSC output setup for the Pause button in Resolume, shown below.

Resolume pause output

Resolume BPM -> Unity Time Scale

When you start a session & until you receive at least 2 tempo messages, the BPM you are at in Resolume is equivalent to a time scale of 1.

As you change BPM in Resolume, Unity's Time.timeScale will follow along.

This relies on having an OSC output setup for the BPM in Resolume, as shown below.

Resolume BPM output

Video Protocols

Via Klak packages, Resolink supports all the ways that Resolume does to share video between the two applications.

The protocol in use is controlled by the Render Sharing component on the Resolink prefab.

For sharing video on the same computer, use Spout / Syphon.

For sharing video between two computers, use NDI.

Wildcard Routing

Resolume lets you setup shortcuts that fire for any layer or clip via wildcards /*/ in the OSC address.

Resolink supports these wildcards via pattern matching.

Options

Resolink options can be found under Edit > Preferences > Project > Resolink.

You can disable the help boxes shown on most components, as well as enabling / disabling grouping of complex controls.

Current Limitations

There are some intentional limitations on this initial release, and planned future features.

  1. Sending OSC from Unity to Resolume is not yet implemented, but will be, sooner rather than later. This is because i haven't yet figured out some details of how that should work, and my personal use case is focused on driving Unity from Resolume.

  2. Syncing Unity to the initial state of a Resolume control will be implemented at the same time as general Unity -> Resolume communication. Until then, Unity isn't aware of the value for a control until Resolume sends a message for it.

  3. Arena-specific features aren't yet supported by the parser.
    This is just because I use Avenue - they will be implemented in future releases.

  4. No included runtime UI for configuration or debugging. It's intended to use the Editor to set everything up for now.

  5. Only tested on recent versions of the softwares - Unity 2019.x & Resolume 7.

Dependencies

For now, dependencies are bundled in the package.

OscJack for handling OSC messages

(on Windows) KlakSpout, which is an interface to Spout

(on Mac) KlakSyphon, which is an interface to Syphon

KlakNDI for NDI support

Contact

If something is broken, feel free to submit an issue. Feature requests, not yet please.

To get in touch in general, get at me on Twitter.

About

Unity package to make integrating with Resolume (a VJing software) easier

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages