VRSL DMX: DMX via Audio

DMX via Audio refers to the new feature set released as a standalone add-on to VRSL that allows users to send DMX data through extra surround sound audio channels in a 5.1-enabled stream to control udon sharp scripts across multiple instances. The feature uses a very rudimentary version of amplitude modulation to convert DMX signals into different audio signals that can be detected as simple boolean (On/Off) states. It can either send 8 or 12 bits/booleans of DMX data.

The basic idea of this system is that DMX data is converted into simple wave forms at different frequencies that unity can detect. Those wave forms are sent down unused surround sound audio channels through a stream. The video player in VRChat then sends those signals to an audio source component where the data is processed into an udon script, where variables and functions can be appropriately called based on the changes of those wave forms.

As this addon is standalone, it does not need the full installation of VRSL into a unity project for it to work properly. The add-on .unitypackage file alone will suffice. It still will need, however, the VRSL Grid Node in order to generate the signals from DMX into their appropriate audio signals.

If you want to watch this tutorial in video format, you can watch it here.

Requirements

Here are the requirements to make DMX via Audio work:

• The VRSL Grid Node v2.3+

• At least 2 Virtual Audio Cables (We recommend cables A+B).|

• OBS

• Unity 2019.4+

• DMX Software of your choice (We're using QLC+ for this tutorial)

• USharp Video (For the Example Scenes and this tutorial only)

Setting up the Requirements

Virtual Audio Cables to Surround Sound Mode

After you've installed 2 virtual audio cables, you'll need to set one of them up to support 5.1 surround sound. By default, virtual audio cables only support stereo audio. To do this, first go to the sound settings page in Windows:

In the Playback tab, right-click on the audio cable you wish to use to send data to OBS. For this tutorial, we will use Audio Cable "B". Then, select Configure Speakers.

From there you will enter a wizard with a few options that allow you to choose the number of audio channels you want your audio cable to have. Go ahead and select 5.1 Surround.

Then just hit next through the next few sets of pages (make sure to leave everything "checked" on those pages that allow you to check them) and then hit finish once you hit the final page, hit finish.

Cable "B" is now set up to support surround sound audio.

Setting Up OBS to Surround Sound Mode

Since Audio DMX sends audio through surround sound channels on the stream, we need to set up OBS to be able to output 5.1 Surround Sound. To do this, open OBS and go to Settings then Audio:

And under the Channels dropdown, set it to 5.1 and make sure your Sample Rate is set to 48 kHz.

You'll also want to set your Desktop Audio 2 Device to be your designated surround sound virtual Audio Cable. For this tutorial, that will be Cable "B"

OBS will be prompting you to restart for the changes to take effect, so go ahead and hit Apply then Ok and then restart OBS.

OBS should now be set up for surround sound streaming!

Setting Up the VRSL Grid Node

With this update, the Grid Node will have changed quite a bit from the previous one. We'll go over the changes while also setting up Audio DMX to work with the example scene in Unity.

First, we'll go over the features in the top right corner:

• Target Audio Device - This is the surround sound audio device (Virtual Audio Cable) that the audio DMX signals will be traveling through to get to OBS. For this tutorial, we'll be setting this to Cable "B" which we've previously set up to be a surround-sound audio device.

• Dummy Audio Device - This is the stereo audio Device (Virtual Audio Cable) that the audio DMX signals will be traveling through to get to the Unity Editor. The audio travels through the left channel, where Unity can pick it up as a microphone device inside the editor. A script is set up in Unity to get these signals. For this tutorial, we'll be setting this to Cable "A", which should still be a stereo audio device by default.

• Enable Dummy Audio Output - This toggle simply enables or disables the Dummy Audio Device output. Disabling this can save some processing power if needed, but it is not recommended especially if you wish to use the Unity Editor to see your audio DMX changes in real time. This is enabled by default.

Next, we'll look at the center section:

• Enable ArtNet via AM - This button starts and stops the Audio DMX output. AM stands for "Amplitude Modulation" and Artnet is the DMX network protocol the grid node uses to grab DMX data.

• Target Audio Channel - This is the surround sound channel that the Audio DMX will be output from. By default, it is set to 2 which is the Center channel in windows. 0 and 1 are the standard stereo Left and Right channels so you generally don't want to output it to those channels as that is where standard audio would normally be outputted to. It is possible to use Audio DMX in conjunction with surround sound-up mixers as long as you are willing to sacrifice a channel for it (we recommend the center or subwoofer channel.) We'll be keeping the defaults for this tutorial.

• AM Target Universe - This is the DMX universe that the DMX data will be reading from. It will always read the first 12 channels of the selected universe. By default, it tries to read universe 10, as the first 9 universes are also being outputted to the standard pixel grid node. It can read any universe from 1-12. We'll be keeping the defaults for this tutorial.

Once you have everything set up, you can go ahead and hit the Enable ArtNet via AM to enable the system.

SideNote:

• 12-Bit Audio DMX - This tells what "mode" VRSL Audio DMX is in. There are two modes: 8-bit/Channel mode. and 12-bit/Channel mode. 12 Bit mode is the default mode and allows 12 channels of DMX to be sent through the audio signals. 8 Bit mode is a downscaled version of 12-bit mode and only allows 8 bits of DMX to be sent through. The advantage of 8 Bit mode is that due to there being fewer channels, there is less chance for harmonic interference between the channels which may cause data inaccuracies. It also reduces the load on the pc generating the signals. 12 Bit mode is still default as it is more than stable enough for the majority of scenarios and 8-bit mode should be used only if you don't need as many channels and are extremely concerned about performance. To change the mode in the VRSL Grid node, open the settings.properties file (located with the grid node .exe) in notepad and set the twelveBitMode property to false or true, save the changes, and restart the VRSL Grid node.

Connecting QLC+ To the Grid Node.

This tutorial will assume you have an idea of how Artnet and the grid node work with regards to that, so it will try to quickly just show the steps of getting QLC+ connected and ready to output audio DMX with the grid node.

1. Open QLC+ and add extra universes in the Input/Output tab until you hit universe 10.

2. Set Universe 10's Output to 127.0.0.1.

3. Go to the Simple Desk tab and set the Universe to 10

From there you can enter using the first 12 channels to control manually toggle the channels (This is good for testing purposes)

Setting Up With the Unity Editor

So let's go ahead and open the example scene. You can find the example scene here:

This scene has a simple scene with 3 doors, a counter, and a CO2 Particle Cannon hooked up to the two VRSL Audio DMX Scripts.

For Audio DMX, there are two separate scripts/prefabs, one called VRSL-AudioDMX-EDITOR and VRSL-AudioDMX-GAME.

• VRSL-AudioDMX-EDITOR is intended to be used inside of the Unity Editor and uses the microphone as input. Use this to test your Audio DMX settings locally or use it as a dummy rig for live performances so you can see your audio DMX reacting in real time vs relying on the stream.

• VRSL-AudioDMX-GAME is intended to be used inside of VRChat and uses the VRC AVPro Video Speaker component as input. With this, you use the VRC AVPro Video Speaker component to determine what audio channel the script should try to read DMX from as well as determine which AV Pro video player to observe.

Other than these two differences, these scripts are mostly identical both visually and functionally. However, only one needs to be active at a time. When you're running in Editor, you need to have the EDITOR version enabled, and when you are about to build/publish your world, you need to have the GAME version enabled. You can disable/enable them with this button at the top let corner of the prefab's inspector.

For making your own scenes, you can find the prefabs you need here:

The VRSL Audio DMX Scripts/Prefabs: The Main Settings

This is the EDITOR version of the Audio DMX Unity Script. For this section of the tutorial, we will be discussing how the script works as well as setting up sending DMX data to it through Unity's microphone class.

First, we'll look at the top section of the script and go over each parameter.

• Source - This is the audio source component the script is reading from. By default in the prefab, it is set to the audio source it comes with. You generally don't want to change this unless you want to move the script to a separate object for whatever reason. If you do change it, make sure to copy the settings from the prefab's version of the audio source component.

• Twelve Bit Mode - This is the toggle for 12/8 Bit mode on the Unity script side. As stated before, 12-bit mode is enabled by default and allows all 12 channels to be used. When it is disabled, the script is in 8-bit mode, only allowing the first 8 to be used. Again, as stated before, generally you don't want to go to 8-bit mode unless you REALLY need the extra performance and don't need as many channels.

• Update Rate - This is how often the script checks if the booleans have changed. Measure in seconds, this offers a bit of a buffer between updates as checking each frame causes some instability. You can increase and decrease the amount of time between each update to increase or decrease responsiveness with this slider. The default is 0.05 seconds.

• Threshold - This is the audio amplitude value that each channel must cross before the channel/bit is considered True, otherwise it assumes False. The actual unit Unity is measuring in is unknown, but 12 seems to be a good spot for the EDITOR script. 20 is the default for the GAME script. You can increase and decrease this value if needed.

• Multiplier - Sometimes the strength of the audio signals is a bit dull with the microphone class, so this multiplier allows you to boost the overall signal if needed. This does not seem to be the case for the GAME version of the script, so it is not needed for the sake of consistency. The default is 1, meaning it's not boosted at all.

• Editor Device ID - This is the microphone device ID that the script uses to determine which microphone device on your computer to start listening to n play mode. You can find out what IDs go with what device with the two buttons below.

• Populate Device List - This fills the "Devices" array (located below the button) with the names of all the microphone devices on your computer. Use their position in the array to determine which device you want to set in the Editor Device ID.

• Devices - This is a list of all the microphone device names on your computer and how Unity IDs them. Hit the button above to refresh the list if needed.

• Copy Channel Settings from Game/Editor Mode Version - This button copies all of the DMX channel settings from the GAME mode script into the EDITOR script. An inverse button exists on the GAME version of the script to grab the channel settings from the EDITOR version. Use these buttons to avoid having to constantly make changes between both scripts.

The VRSL Audio DMX Scripts/Prefabs: The DMX Channel Settings

There are 12 Channels of DMX, each with its own settings and values. You can show/hide channels in the inspector with the drop-down tabs.

• CURRENT STATE - This is the public boolean that represents the current state of the channel. As a boolean, it either displays as TRUE or FALSE. It becomes true when the audio value is >= the threshold value. If the script is referenced in another script, the boolean value can be accessed as dmxBoolx with x being the channel number.

• CURRENT VALUE - This is the current amplitude audio value of the channel. This value will always be 0 unless it detects that internally the value will be greater than the threshold.

• Entry Behaviour - When the state of the channel is changed to TRUE, a public function on the UdonSharp behavior in this field will be called. If you do not want a function to be called when the channel is changed to TRUE, leave this field empty.

• Entry Function - When the state of the channel is changed to TRUE, a public function on the UdonSharp behavior in the Entry Behaviour field will be called. This field holds the name of that function. Leave this field blank if you do not wish for a function to be called.

• Spam Entry Function? - When this is checked, the Entry Function will be repeatedly called while the state of the channel is set to TRUE and will only stop calling when the state is FALSE. It is not recommended to have this enabled except in very specific scenarios.

• Exit Behaviour - When the state of the channel is changed to FALSE, a public function on the UdonSharp behavior in this field will be called. If you do not want a function to be called when the channel is changed to FALSE, leave this field empty.

• Exit Function - When the state of the channel is changed to FALSE, a public function on the UdonSharp behavior in the Exit Behaviour field will be called. This field holds the name of that function. Leave this field blank if you do not wish for a function to be called.

• Exit Delay - Sustaining the TRUE state is difficult when VRChat/Unity becomes under load because the audio engine starts to skip or glitch out (causing the value to unintentionally drop below the threshold). This delay allows the TRUE state to avoid switching at the wrong time when the audio temporarily cuts out unexpectedly. This does cause switching to the FALSE to take longer though. You increase or decrease the amount of delay with the field. The default is 0.25 seconds, though 0.1 is nice if you need quicker response time but still have some sustain.

• Spam Exit Function? - When this is checked, the Exit Function will be repeatedly called while the state of the channel is set to FALSE and will only stop calling when the state is TRUE. It is not recommended to have this enabled except in very specific scenarios.

The function calls use the SendCustomEvent method on the UdonSharp Behaviours, so treat the Entry Function and Exit Function Fields like they are parameters for that method.

The VRSL Audio DMX Scripts/Prefabs: Using the EDITOR Version

Here are the steps to test VRSL Audio DMX inside of the editor using the EDITOR script in the example scene. Make sure you have the GAME version of the prefab disabled:

1. Click the Populate Device List button to populate the Devices array in the inspector with the names of the microphone devices on your computer.

2. Find the device that you listed as the Dummy Audio Device in the VRSL Grid Node. For this tutorial that would CABLE "A". Find the element number next to it and put that number inside of the Editor Device ID field.

3. Go ahead and hit the play button in the editor.

Assuming you have hit the Enable Artnet via AM button in the VRSL Grid Node and have it properly set up to receive DMX from your DMX software of choice, it should start working on the first 12 DMX Channels of the AM Target Universe.

• The first three channels open and close the 3 colored doors.
• The next four channels set the counter value via binary. The counter can go from 0-15.
• The 8th channel enables and disables the CO2 cannon.

The VRSL Audio DMX Scripts/Prefabs: Using the GAME Version

Here are the steps to test VRSL Audio DMX inside of VRChat with the example scene. Make sure you have the EDITOR version of the prefab disabled:

1. Ensure that the VRC AVPro Video Speaker component on the prefab is pointing to the correct surround sound channel that you will be sending your DMX Data down.

2. If needed, hit the Copy Channel Settings From Editor Mode Version button to copy your channel settings from the EDITOR version of the script to the GAME version. The GAME version inside of the example scene should already be identical to the Editor Version.

3. Go to the USharpVideo prefab in the hierarchy and set your VRCDN or Twitch stream you plan to test with as the default URL. The video player should already have stream mode set to default.

4. Start streaming, ensuring that you have OBS set up properly to stream with the correct device in 5.1 surround sound mode.

5. Hit the Build & Test in the VRChat SDK Control Panel and see if changing the DMX channels in your software affect the same functions. You'll see a UI panel that also displays the states of the channels and their values, similar to the ones in the inspector.

The VRSL Audio DMX Scripts/Prefabs: The Example Scene Extra Scripts.

There are 3 example scripts used in the example scene that are controlled by the VRSL Audio DMX Scripts.

• VRSL_AudioDMX_AnimationToggle - This allows you to flip a boolean parameter of your choice on a target animator. The function to flip the boolean to TRUE is _EnableAnimation. The function to flip the boolean to FALSE is _DisableAnimation.

• VRSL_AudioDMX_BasicCounter - This allows you to count up to 255 (8 bits) using 8 channels. The script returns a public integer value which you can use on animators and other scripts. There's also a text display so you can see what value it's currently sitting at in the game. You do not need to hook up all 8 channels to use this script. (The example scene only uses 4) You can also call a function each time the value is changed using the Target Behaviour and Target Function fields. They work similarly to how they work in the Audio DMX scripts.

  • You can flip a bit in the number to TRUE using _Enable1sPlace, _Enable2sPlace, _Enable4sPlace, _Enable8sPlace, _Enable16sPlace,_Enable32sPlace,_Enable64sPlace, and _Enable128sPlace respectively.

  • You can flip a bit in the number to FALSE using _Disable1sPlace, _Disable2sPlace, _Disable4sPlace, _Disable8sPlace, _Disable16sPlace,__Disable32sPlace,_Disable64sPlace, and _Disable128sPlace respectively.

• VRSL_AudioDMX_ParticleToggler - This allows you to start and stop a particle system. Use _EnableParticles to start the particle system and _DisableParticles to stop the particle system.