Forum: VirtualDJ Plugins

Use this forum if you have questions about plugins development, or if you want to talk with other developers.
Topic: The Advanced Freestyler integration thread - Page: 1
This guide is for advanced users, or users with enough technical knowledge to follow it. While I'll try to explain each step as best as I can and provide as much info as possible, if you don't understand what the guide is saying, please avoid to follow it on your system.

This guide provides a MIDI integration between Freestyler and VirtualDj. This means that this guide can be used only on Windows OS and that Freestyler has to be installed on the same machine. While it is possible with some tools to create a MIDI port over a local network, this solution has not being tested, and therefore at this time it's not recommended.
Why MIDI ?
MIDI communication is native to VirtualDJ, and it can provide 2 way communication with Freestyler. In other words, you can get feedback from Freestyler inside VirtualDj. Also this means that you can remap ANY device working with VirtualDj to control Freestyler. You can remap the entire device, or only a few buttons / sliders / encoders. It's up to you...
Finally: You can use VDJ Script in order to perform queries and control Freestyler much more dynamically, since you receive feedback from it!

What you'll need:
1) VirtualDj 8 with Pro Infinity or Pro Subscriber license. That's because we will install and use a custom device on our system.
2) Freestyler installed on the same PC with VirtualDj 8
3) A Virtual MIDI port creator app. I use "loopMIDI"
4) A custom device definition that you can download from add-ons area
5) A MIDI template for Freestyler (basically a template that assigns MIDI commands on Freestyler itself) which is included on custom device definition file
6) Optional: SBDJ Freestyler8 plug-in
7) Optional: Special Skin Window

Step 1 - Setup:
First, we want to setup and configure our Virtual MIDI port.
Download and install "loopMIDI"
When "loopMIDI" starts after installation you need to create your MIDI port

Enter "Freestyler" as the name of the port and press the plus button.

You should now have created your Virtual MIDI port and "loopMIDI" main window should look like this:

Click on advanced tab and disable Feedback detection:

Our Virtual MIDI port is now ready and configured.

Second, we need to install our custom device on VirtualDj.
Download and install "Freestyler MIDI Remote Control"

Finally, we need to import a MIDI template on Freestyler itself in order to understand the messages sent from VirtualDj and establish a 2 way communication:
a) Browse to Documents\VirtualDj\Devices
b) Open "Freestyler MIDI Remote Control" zip file and extract "VirtualDjMIDI.fms" file
c) Open Freestyler and select Setup Menu -> Freestyler Setup
d) Click on External Control -> Midi control
e) Click on Options menu and select Import.

f) Browse for the "VirtualDjMIDI.fms" file you've extracted previously and press ok.
Your Setup window should look like this:

g) Click on Midi Controller 1 Input menu and select Freestyler.
h) Click on Midi Controller 1 Output menu and select Freestyler.
i) Click on Start Button to enble MIDI control:

j) Finally, click on Options once more and make sure everything is like the picture below:

k) Press SAVE button to close Freestyler Setup.

Step 2 - Test that it works:
Open Freestyler (if it's not running already)
Open Freestyler Setup and check that it's using the correct MIDI port (Freestyler). If Freestyler is still open from previous steps you can skip this step
Open VirtualDj. Make sure that you are logged in the software.
If a detection Window appears like this:

Check the "Don't show again" checkbox and click Ok.

Right click on a custom button and enter this script: "set '$FS_SND_BLACKOUT' 1 while_pressed"

Close the custom button editor.
Press the button once.
Freestyler should toggle Blackout ON
Press the button one more time.
Freestyler should toggle Blackout OFF.

If everything went well on this test, you are now ready to start controlling Freestyler via your MIDI port!

Keep reading next posts in order to find out how!!

Inviato Wed 12 Jul 17 @ 11:35 am
Step 3 - Programming Buttons
In order to program Freestyler MIDI Remote Control with your controller / skin you need to understand how Freestyler MIDI Remote Control works.

In simple words, for any button you want to control on Freestyler, the Freestyler MIDI Remote Control plug-in reads and sets variables.

In our previous example we programmed a custom button to toggle BLACKOUT on/off
In order to do so we set a variable MOMENTARILY: set '$FS_SND_BLACKOUT' 1 while_pressed
The variables used by Freestyler MIDI Remote Control plug-in have all the same form.
They are global variables (start with an $ symbol) followed by FS (Freestyler) and then the direction of communication. SND stands for "Send" and RCV for "Receive"
Finally, the last part is the name of the button we want to control.

The above example of code that we used to toggle on/off Blackout on Freestyler works, but there's still an issue: We don't have a visual indication on VirtualDj if Blackout is on or off.
In order to have a visual indication we need to read the '$FS_RCV_BLACKOUT' variable.

Let's modify our button and use this script instead:
var_equal '$FS_RCV_BLACKOUT' 0 ? off & set '$FS_SND_BLACKOUT' 1 while_pressed : on & set '$FS_SND_BLACKOUT' 1 while_pressed

Press the custom button again.
Now the button should remain lit while Blackout is enabled on Freestyler!

For custom buttons, the code above is the only way to have feedback from Freestyler. It's a little bit complex, right ?
For controllers, skins, or custom pad pages though, we have the ability to control leds individually from button presses.
So, lets say we want to remap BUTTONX on our controller to toggle Blackout on/off. Remap the button elements as follows:

BUTTONX=set '$FS_SND_BLACKOUT' 1 while_pressed

The button should now work as desired. It toggles Blackout on/off, and the LED of the button turns on when Blackout is enabled.

For skin buttons (in case you design/modify your own skin) the code for the button is:
<button action="set '$FS_SND_BLACKOUT' 1 while_pressed" query="var_equal '$FS_RCV_BLACKOUT' 1">

Sending multiple commands at once:
Sending multiple commands at once is as easy as setting multiple variables at once. Let's say that we want to toggle both Blackout and Freeze at the same time:
set '$FS_SND_BLACKOUT' 1 while_pressed & set '$FS_SND_FREEZE' 1 while_pressed

Using queries:
Using queries in order to perform more complex commands is the same as querying variables in VirtualDj.
Let's say that we want a button that if pressed will toggle FREEZE on Freestyler, but ONLY if Blackout is active:
var_equal '$FS_RCV_BLACKOUT 1 ? set '$FS_SND_FREEZE' 1 while_pressed

Or let's say that when we toggle Blackout OFF, we also want to UNFREEZE Freestyler (in case it was frozen)
var_equal '$FS_RCV_BLACKOUT' 1 ? var_equal '$FS_RCV_FREEZE' 1 ? set '$FS_SND_BLACKOUT' 1 while_pressed & set '$FS_SND_FREEZE' 1 while_pressed : set '$FS_SND_BLACKOUT' 1 while_pressed : set '$FS_SND_BLACKOUT' 1 while_pressed

In the above example out button will basically toggle Blackout on/off, but if Freeze is enabled at the same time with Blackout, it will set both of them off!

Step 4 - Programming Sliders/Knobs
Sliders/Knobs in general work the same way as buttons, but with one MAJOR difference:
There's no direction involved!
This means that the variables for sliders look like this: '$FS_MASTER_INTENS'
This is necessary in order to have sliders inside VirtualDj change their position when they change inside Freestyler.

So, in order to program a fader / slider / knob in VirtualDj to control Master Intensity of lights we need to use this command:

In order to perform queries, unlike buttons, you can query the variable directly:
var_smaller '$FS_MASTER_INTENS' 0.5 ? set '$FS_MASTER_INTENS' 0 : set '$FS_MASTER_INTENS' 1

Inviato Sat 15 Jul 17 @ 12:07 pm
LIST OF VARIABLES USED BY Freestyler MIDI Remote Control

1) Master Intensity:

2) Master Speed

3) Fog/Hazer

4) General Control

5) Sound 2 Light & Sync Operations
@$FS_SEND_S2L_MULTIPLIER* (see post below about S2L control)

6) Overrides
$FS_SND_OVER_01 (up to 32)
$FS_SND_OVER_TAB_01 (up to 06)
$FS_SND_OVER_TAB_P (previous tab)
$FS_SND_OVER_TAB_N (next tab)

7) Cues
$FS_SND_CUE_01 (up to 32)
$FS_SND_CUE_TAB_01 (up to 06)
$FS_SND_CUE_TAB_P (previous tab)
$FS_SND_CUE_TAB_N (next tab)

8) Sequences
$FS_SEQ_SPEED_01 (up to 20)
$FS_SND_SEQ_RUN_01 (up to 20)
$FS_SND_SEQ_STOP_01 (up to 20)
$FS_SND_SEQ_TOGGLE_01 (up to 20)

9) Submasters
$FS_SUB_INTENS_01 (up to 20)
$FS_SUB_LIST_CH_01 (up to 20)
$FS_SND_SUB_RUN_01 (up to 20)
$FS_SND_SUB_STOP_01 (up to 20)
$FS_SND_SUB_GO_01 (up to 20)
$FS_SND_SUB_BACK_01 (up to 20)
$FS_SND_SUB_TOGGLE_01 (up to 20)
$FS_SND_SUB_TAB_P (previous tab)
$FS_SND_SUB_TAB_N (next tab)

Inviato Mon 17 Jul 17 @ 10:30 am
Sound 2 Light Configuration

Currently there are 2 ways to pass beat information (S2L) on Freestyler:
1) You can use SBDJ's Freestyler8 plugin or
2) You can use Freestyler MIDI Remote Control directly.

However please note that you should use ONLY ONE of the two methods, not both at the same time.

Freestyler MIDI Remote Control can play nicely among with Freestyler8 plug-in and you can have both of them activated and controlling Freestyler.
However only one of them should pass Sould 2 Light (S2L) data on Freestyler!

That being said, in case you want to pass S2L data to Freestyler from Freestyler MIDI Remote Control plug-in you should set a global persisted variable:
The possible values for this variable are:
0 -> Freestyler MIDI Remote Control won't send any S2L data
1 -> Freestyler MIDI Remote Control will trigger Freestyler every beat (based on masterdeck's CBG)
2 -> Freestyler MIDI Remote Control will trigger Freestyler every 2 beats
4 -> Freestyler MIDI Remote Control will trigger Freestyler every 4 beats
8 -> Freestyler MIDI Remote Control will trigger Freestyler every 8 beats
16 -> Freestyler MIDI Remote Control will trigger Freestyler every 16 beats

Every other value will result Freestyler MIDI Remote Control to not send S2L data at Freestyler at all (same as setting @$FS_SEND_S2L_MULTIPLIER to 0)

Inviato Mon 17 Jul 17 @ 11:01 am
Calling and using Special Skin Window

In order to use the special skin window, you need to download and install the skin file from
Since this is NOT a regular skin it won't install on your VirtualDj skins folder for obvious reasons.
Browse to Documents\VirtualDj\Skins\FreestylerMIDIRemoteControlUI folder.
Copy or move the file on your skins folder (Documents\VirtualDj\Skins)
Open VirtualDj and add the following action on a custom button:
show_window 'FreestylerMIDIRemoteControlUI'

Once you do so, you can use this button to open/close the Special Skin Window:

This skin offers just some basic functions as a case study on what can be done with "Freestyler MIDI Remote Control"
It offers access to all Override and Cuelists buttons, as well as on some basic performance control actions.
Also it includes a few programmable custom buttons to program your own macros!

Attention: The captions of the skin buttons are fixed! Unfortunately there's no way to get the text of the buttons via MIDI (Freestyler Limitation)
Therefore you'll have to edit the skin file in order to have your own override and cuelist names show up.

For this purpose the skin was designed to allow easy modification of button captions.

It's strongly recommended to use Notepad++, but any text editor will do:

1) Extract the XML file from the zip file
2) Open the file with Notepad++
3) On Notepad++ press ALT+0 on your keyboard to collapse all nodes.
4) Press the "plus (+)" icon on Notepad++ on the following nodes to start expanding them: Skin, Window, Group Definitions, Group Texts

From this point you can keep using the "+" and "-" icons to navigate the tree and edit the captions you need.
Let's edit Override labels for Tab 01:
5) Press "+" on Group Overidde Labels, Group Tab 01:

Here you can edit all captions for all override buttons of Tab 01!

In a similar way you can edit all captions for all buttons on all tabs!

Once you have finished, save the XML file and zip it back inside the skin file.

Override Flash buttons
Due to a restriction of Freestyler MIDI implementation, Override buttons that are set to FLASH mode instead of LATCH won't have their leds working while pressed.
If you wish to change that (and have visual feedback when you press an Override button that's set to FLASH mode), you need to instruct the skin on which buttons are FLASH ones.
In order to do so, you have to use the Options menu on top:

Inviato Tue 01 Aug 17 @ 9:27 am
Coming Soon: Remap a secondary controller to control your lights on Freestyler through VirtualDj!

Inviato Tue 01 Aug 17 @ 9:34 am

This is crazy good stuff!! Might have to make the switch!

Any chance of a mapping for an AKAI MINI?? Seems like it would be a perfect sub controller for this.

Also you can level this post to keep your thread clean, just wanted express how much I'm digging this even though I've never used it.

Inviato Tue 01 Aug 17 @ 3:36 pm
I'm actually going to remap an AKAI APC-40 MK2

Inviato Tue 01 Aug 17 @ 3:46 pm
Hahaa!! Nice!

Any chance of the mini when your done with that ;-p

Edit, in response to the post below.

Excellent !!

Inviato Tue 01 Aug 17 @ 4:29 pm
If you follow my guide for APC-40MK2 it should be almost the same for MINI as well... ;)

Inviato Tue 01 Aug 17 @ 4:35 pm
Christmas has come early - awesome information.

Inviato Wed 02 Aug 17 @ 9:20 am
rubydooPRO SubscriberMember since 2014
any chance of mapping theakai mpk mini mk2

Inviato Thu 03 Aug 17 @ 1:25 am
First of all this thread is about integrating Freestyler (a software that sends DMX data to light fixtures) with VirtualDj. It's not about supporting controllers.
Second, the MPK Mini MK2 is a MIDI keyboard, which I'm not sure what kind of usage could have inside VirtualDj. For simple tasks (like pressing a key and have a deck start playing) you could use the Simple MIDI Wrapper which is built-in VirtualDj.

For more info about this please start a new thread on Hardware Technical Support forum

Inviato Thu 03 Aug 17 @ 7:08 am
The "Remote Control" skin looks like it's got some new stuff in it, that's not in the skin SDK.

More info please.

Also, could this skin be run on the VDJ Remote for wireless use on an iPad (as a skin, not a window)? Maybe not as it is now, but seems like a good idea to me.

Inviato Mon 07 Aug 17 @ 8:52 pm
It's not in the SDK because it's meant for special cases for controllers and it's still experimental.
Once it's final the new stuff will be included on the SDK.
As for the skin yes it can be modified by changing about 10 lines to be used on VirtualDj Remote.

Inviato Mon 07 Aug 17 @ 9:52 pm
Hmm the iPad might be a better option then my APC Mini ;-p

Inviato Mon 07 Aug 17 @ 11:49 pm
Now we just need to know which lines to change. :-)

Or maybe George will be kind enough to upload a separate VDJ Remote version....

Inviato Tue 08 Aug 17 @ 4:39 pm
Sure I can upload a modified version for VirtualDj Remote once I return from vacations next week

Inviato Tue 08 Aug 17 @ 4:52 pm
Why can't Freestyler be made for Mac as well, :-(

I'm just gonna have to buy a better PC this year.....

Inviato Tue 08 Aug 17 @ 4:59 pm
This thread is great! PhantomDeejay, thank you for EVERYTHING you do! All the things you create along with djdad, and all the other DJ's are much appreciated. Thanks for all your hard work!

Inviato Wed 16 Aug 17 @ 3:52 am
Pagina : [>] [>>]