Intro to Controller Scripting - Bitwig Studio 1.0.x

[ThomasHelzle]

EDIT: This thread originally was started directly after Bitwig Studio 1.0 was released.

Many of the things mentioned here are no longer needed in BWS 1.1 and above, for instance: changing the name of a controller is now as simple as double-clicking on it in preferences.

But since some of the discussions are still valid and the basic principles still exist, I'll leave it here for reference.

Just be aware that Bitwig Studio 1.1 and above has a much improved and expanded API and API reference documentation, so many of the shortcomings are history and a lot of stuff has become much easier now.

Happy Scripting!

Tom


----------------------------------------------------------------------------

As many people found out, currently you can't have custom named Midi Devices if they aren't on the list of factory supported ones - all are called "Midi Keyboard".

The fix for this is very easy, but needs a bit of tinkering with Controller Scripts - but don't fear, no Voodoo required

It's dead easy in fact:

Here we go:

1.) Go to the BWS installation directory and locate the resources\controller\generic folder.

2.) In there you find the "Generic MIDI Keyboard.control.js"

3.) Create a copy of this file and name it like you want your Keyboard to be called, I'll use "Acme" in this example, so my Script is called "Acme Keyboard.control.js" now.

4.) Open the script in a text editor like notepad. Don't use a Software like Word or Libre Office, those will add formatting code and other weird stuff and may make the script unusable.

5.) At the top you find two lines:

Code: Select all

host.defineController("Generic", "MIDI Keyboard", "1.0", "6E55D132-1846-4C64-9F97-48041F2D9B96");
host.defineMidiPorts(1, 0);

The first line (may be wrapped into a second one here on KVR) defines the name of the Controller and it's unique Identifier, the second defines how many In- and Outputs it has, in this case One Input and Zero Outputs - "(1, 1) would be One In- and One Output.

6.) For the sake of this example, change it to something like the following:

Code: Select all

host.defineController("Acme", "Acme Keyboard", "1.0", "d84e03d0-b605-11e3-a5e2-0800200c9a66");
host.defineMidiPorts(1, 0);

The first entry in the parentheses is the "Folder Name" in which the script will show up in Bitwig Studio. Usually this is the company name.
The second entry is the name of the actual device.
the third is the version number, just leave it at "1.0".
And finally there is the "Universally Unique IDentifier", UUID for short, a number that is supposed to be unique even if you create millions of them.
But don't fear, simply go to this address:
http://www.famkruithof.net/uuid/uuidgen
And copy the UUID shown on top. Each time you go there a new one will be generated and shown, so even if you create a dozen, each will be unique if you refresh the page.

7.) Finally, look some lines further down for this one:

Code: Select all

host.getMidiInPort(0).createNoteInput("MIDI Keyboard");

This line defines the actual Name that is shown in the Track Input selector.

8.) Change it to:

Code: Select all

host.getMidiInPort(0).createNoteInput("Acme Keyboard");

And that's it.
If you save the file, BWS should find it and offer it to you in the Preferences/Controllers Tab Dropdown:



Here is the changed Script if you want it for reference:
Acme Keyboard Controller Script for Bitwig

Just create one for each of your Keyboards and if you want, upload them here for others to use them as well. Soon we should have a nice library.

If you have any questions, feel free to ask!

Cheers,

Tom

Edit: You can also find this and other Bitwig Tutorials on my Blog:
http://blog.thomashelzle.de/category/tutorials/

Edit 2: The generic factory scripts are very limited and some things don't work right (in version BWS 1.0.5) so I posted an enhanced generic script later in this thread:
http://www.kvraudio.com/forum/viewtopic ... 7#p5704951
But the same basic rules apply as explained above and in the following posts.

[ThomasHelzle]

Oh, I forgot: I have uploaded two of my own Controller Scripts to the following Thread:
http://www.kvraudio.com/forum/viewtopic ... 4#p5689492
One for the AKAI MPD 18 and one for the first two CopperLan VMidi channels...

Edit: Three actually, one for the Doepfer LMK3 as well (can be used for other Keyboards too).

Cheers,

Tom

[ThomasHelzle]

And if you want to drive it one step further:

Automatic Controller Detection!!!

Also dead easy to implement for most devices:

In the above lesson, we created the Acme Keyboard Script.
We changed some stuff in the first two lines.

Now we need to add a third line below those two:

Code: Select all

host.addDeviceNameBasedDiscoveryPair(["Akai MPD18"], ["Akai MPD18"]);

As you can see, this time I use my AKAI MPD 18 Script as an example, since in this case we need to work with real world Names. What this does, is simply looking at the names of Midi Devices on your machine: if Names match what is given in the Discovery Pair, it can automagically connect devices with the correct ports if you press "Detect available controllers" in the Preferences/Controllers Tab.

Instead of "Akai MPD18" you need to insert the EXACT names of YOUR Midi Input Device in the first brackets and of the Midi Output Device in the second brackets.

Here is my AKAI MPD18 Script for reference:
Toms MPD18 Controller Script for Bitwig



Of course this only works for USB connected devices usually, since they show the name of the actual device. Most Midi-connected Devices only show the Name of the Interface they are connected to, and that doesn't make much sense to use for autodetection.

There are more involved solutions even for that scenario (using SysEx identification sequences) but if you want to go down that road, it makes more sense you read the Control Surface API GUIDE in the docs.

I hope this was helpful and wish you a lot of fun with Bitwig Studio!

Cheers,

Tom

[UncleAge]

Thanks Tom!

[ThomasHelzle]

Thanks Tom!

You're very welcome

Cheers,

Tom

[Regnas]

Great, thank you.

By the way, you should work for Bitwig... hehehe.. How about that?

[billcarroll]

Here is a basic controller script for Arturia's "The Laboratory" keyboard. It will auto detect the keyboard if you have it attached and turned on, and select "Detect available controllers" in Options | Preferences | Controllers Tab.

http://cl.ly/1Q141B2a2i2W/Arturia_The_L ... rol.js.zip

I'm going to dig into the controller guide and see about adding aftertouch, along with whatever else might make sense.

The Controller Scripting guide says you can put your scripts into a directory outside the actual application package, but I haven't gotten that to work yet.



As I said, I haven't gotten the "official" location to work yet. (If you've figured this out, please let me know.) So, if you are on a Mac you can put the script into the following location:

Code: Select all

/Applications/Bitwig\ Studio.app/Contents/Resources/ControlSurfaceScripts/Arturia/Arturia_The_Laboratory.control.js

On the mac, go to your Applications folder and right click Bitwig Studio, then select "Show package Contents" and navigate to the location shown above. You will need to create the "Arturia" folder in the ControlSurfaceScripts folder. If you are lazy you can just drop the script in the Generic folder and it will work.

Another note, keep a copy of the script because it will be overwritten whenever Bitwig is updated. That's why having a location for the script outside the application package is important.

* NOTE: I've updated the script to add basic transport control, e.g., play, stop record, and so on.

[ThomasHelzle]

Great, thank you.

By the way, you should work for Bitwig... hehehe.. How about that?

Hey Renas,

well, ATM it's actually fun to spread some of the knowledge I collected while Betatesting.
I like both the people and the product and learn a lot in the process.
But who knows what the future will hold...

Great stuff Bill! and thanks for sharing!

You raise an interesting point here:

The user location works here on Windows 8.1, but there is a small bug ATM:
Scripts In the Program Location directly update/reload when you (re-)save them in a text editor (I use Komodo Edit BTW. - very good Editor and free http://komodoide.com/download/#edit ).

If you have the View -> "Show Control Script Console" open and the script you are working on selected, you can directly see if everything works or if there are errors and can also Print values to this window with commands like:

Code: Select all

printMidi(status, data1, data2);

in the Midi callback for instance. This helps a lot with debugging.

But if you save scripts in the user directory, it doesn't update automatically and you have to reload BWS, which isn't any fun. So while developing, I keep my scripts in the program directory and when finished, move them to the user directory.

EDIT: shadiradio has a better solution than re-loading BWS. See the next post after this one.

During the Beta I had my scripts in the program directory and they didn't get deleted when I updated. But this is on windows, I don't know if it is different on OSX with the packaging.
After installation I had to move them to the new directory by hand though.
But keeping a copy is definitely good advice anyway

Cheers and thanks again!

Tom

[shadiradio]

I believe the Mac location is a typo in the docs. It worked for me if I put them in:

~/Documents/Bitwig Studio/Controller Scripts

Also very handy is if you are developing a script and you bring up the console, you can work on your script, then type "restart" into the console to reload your changes. Helpful for fast iteration.

[ThomasHelzle]

I believe the Mac location is a typo in the docs. It worked for me if I put them in:

~/Documents/Bitwig Studio/Controller Scripts

Also very handy is if you are developing a script and you bring up the console, you can work on your script, then type "restart" into the console to reload your changes. Helpful for fast iteration.

So it doesn't auto-update when you save the script in the user location on Mac too?
Interesting.

I hope they can fix that soon, the autoupdate makes it so much easier...

Cheers,

Tom

[shadiradio]

Also not sure if this helps anyone, but it's a nice trick that I use with my Ableton Library and now with my Bitwig library. I copied the "Bitwig Studio" directory into a cloud drive (Google Drive, Dropbox, etc), then I symlinked that location to where Bitwig looks for (in ~/Documents/ on Mac). That way my presets/scripts/etc are synced on multiple computers. I have Bitwig authorized for a PC and Mac right now, and both point to the same directory of stuff, so I have my presets/etc available anywhere.

[shadiradio]

So it doesn't auto-update when you save the script in the user location on Mac too?
Interesting.

I hope they can fix that soon, the autoupdate makes it so much easier...

Cheers,

Tom

Hmm I'm not sure, but it wasn't reliable. I did notice that sometimes it would pick up my changes, but it didn't seem right away (or fast enough), so I got in the habit of leaving the console open and typing "restart" over and over.

[ThomasHelzle]

Hmm I'm not sure, but it wasn't reliable. I did notice that sometimes it would pick up my changes, but it didn't seem right away (or fast enough), so I got in the habit of leaving the console open and typing "restart" over and over.

On windows it's absolutely instant when the script is in the installation folder.
...\Bitwig Studio 1.0.2\resources\controllers\...

Well, I'm sure it will come with time.

Cheers,

Tom

[billcarroll]

Great stuff Bill! and thanks for sharing!

You raise an interesting point here:

The user location works here on Windows 8.1, but there is a small bug ATM:
Scripts In the Program Location directly update/reload when you (re-)save them in a text editor (I use Komodo Edit BTW. - very good Editor and free http://komodoide.com/download/#edit ).

If you have the View -> "Show Control Script Console" open and the script you are working on selected, you can directly see if everything works or if there are errors and can also Print values to this window with commands like:

Code: Select all

printMidi(status, data1, data2);

in the Midi callback for instance. This helps a lot with debugging.

But if you save scripts in the user directory, it doesn't update automatically and you have to reload BWS, which isn't any fun. So while developing, I keep my scripts in the program directory and when finished, move them to the user directory.

During the Beta I had my scripts in the program directory and they didn't get deleted when I updated. But this is on windows, I don't know if it is different on OSX with the packaging.

...

Tom

User location definitely not working here on OSX. I've just double checked on Bitwig 1.0.3.

I'll check out the Control Script Console and printing to it. Thanks for the tip!

On OSX the scripts will be deleted since installation is simply copying an app from a disk image and replacing the entire package in your applications directory.

FYI ... I've updated the Arturia "The Laboratory" keyboard script to add basic transport control, e.g., play, stop record, and so on.

http://cl.ly/1Q141B2a2i2W/Arturia_The_L ... rol.js.zip

It would be cool to have some central place to share and improve on these control scripts.

[shadiradio]

Bill - are you sure? The user location works for me on OS X and Windows *but* I noticed that the location in the doc is wrong. Try "~/Documents/Bitwig Studio/Controller Scripts" instead of "~/Bitwig Studio/Controller Scripts" on Mac.