In the previous article we walked through the setup and creation of a basic controller script for Bitwig Studio. In this next installment we will implement freely mappable CCs so you can use any controller you have laying around to interact with Bitwig.
This is a pretty straightforward process and only involves a handful of lines of code. You can download the script HERE, or you can build it up from the script we previously created. Navigate to your MyController.control.js file (or whatever you happened to name your file last time), and open it up in your text editor, or development environment of choice. I would also open Bitwig, navigate to the help menu and pop open their documentation. In there you can explore all of the classes and functions available to us. There is a lot of information in there, but if you’re ever interested in a more in depth explanation of the functions and methods we use, you’ll want to get friendly with it.
First, let’s define the range of CC values that we will be using. You could use the whole range, but for the sake of demonstration let’s restrict it a bit using these values. Add these lines of code somewhere above your init() function:
This is how you create variables in javascript, and we will be referencing these numbers throughout the rest of the script. There are many advantages to using variables as opposed to just using these numbers when we need them. If we’d like to change this range in the future, we’ll just have to change the values of our variables. And these numbers can be available to any functions we use in our script. If we weren’t using variables we might have to comb through a ton of code to manually update functions, which is not a good time, and leaves you prone to errors.
Now that we have defined our range, we can create a bank of userControls. Each member of userControls is an object that will be associated with a CC in our range, and those userControls can then be attached to a parameter in Bitwig using the MIDI learn functionality. Add the code below somewhere inside your init() function.
This creates an array called userControls the length of our range of CC values (the difference between the highest and lowest, plus one). We then want to assign labels to each of these controls. We can do this by constructing a for loop:
For loops are used for iteration and to execute code repeatedly. You’ll find them all over the place, so it’s good to get to know them. If you’re unclear on their construction, and use, there are plenty of programming resources that would do a much better job of explaining it than I. Basically, for every CC in our range, we assign that CC to an index of our userControls.
Now that we have our bank of userControls, we need to tell them how to control the parameter that we assign to them. Remember that onMidiPort1 function that we left blank last time? Well we finally have some MIDI to process so, we will add our next bit of code inside of that function.It’s worth noting that Bitwig deals with MIDI in it’s most basic form. It uses the Status byte and two Data bytes to construct a MIDI message. If you’re coming from working simply with note numbers, and CC values, it might seem foreign, but it’s not too complicated and there are plenty of resources for learning more about MIDI, like midi.org. Every time this script receives a MIDI message it pass the status byte, and two data bytes in, and then executes all the code contained within the function.
Luckily, Bitwig has a built in method that checks for CC messages that we can take advantage of. Add the code to the right inside of the onMidiPort1() function. This is an ‘if’ statement, and they are used to check it what is contained within their parentheses evaluates to ‘true’ (or 1). This particular if statement tests the status byte to see if it is a CC, and if it is, the code inside the braces gets executed. The code that will be executed should check if the CC is within our defined range. If we send a CC outside of the range, nothing will happen, and frustration will ensue. The first data byte of a MIDI message is the CC number, and lies in the familiar range of 127. Let’s test for that with another ‘if’ statement. Our code block will now look like this:
All that’s left now is to set the parameter attached to that CC. We do that by getting the index of the CC (data1 is the CC number), and then setting it’s value to the incoming CC value (data2 will be the CC value)
We calculate an index based on what CC number we receive, we then call userControls.getControl() with the index, which returns the control at that index. We finally call a ‘set’ method on that control with a value of ‘data2’, and a resolution of ‘128’. (The resolution should generally be set to the entire range of values you will send it).
So there we have a basic, generic control script that can be used to interact with Bitwig Studio. We didn’t do anything fancy, but we introduced some important concepts. In the coming articles we will really start to dive into the API and begin interacting with the application on a much more intimate level. Transport controls, mixing controls, instrument and effect controls, and note manipulations are all right around the corner. Any questions/comments/concerns can be directed to evanbeta@keithmcmillen.com