How to Understand the Bitwig API Object Model

[Sam_K]

Hi Everyone,

I am new to Bitwig and Controller scripting. I am learning to write my controller scripts in Javascript since I have extensive knowledge of that language because that is the language I use at work. I have very little experience with Java. (I mention this only because it might help explain why I find the Javadocs for the API so confusing).

However, I am having a problem learning how to do controller scripting because there seems to be no explanation of the object model. The Javadoc provides a very detailed description of the Object Hierarchy, but not the Object Model. The Object Hierarchy describes how objects are composed, but an Object Model describes how different objects are related which is critical to understanding how they can be used together to achieve a goal.

Without a description of the Object Model, I am having great difficulty trying understand how to navigate the object model to get access to a particular object I am interested in manipulating. This is especially important because the docs state that the only object you have access to by default is the ControllerHost via the "host" global variable. Therefore everything else I want to get access to has to be found by "drilling down" through the object model starting at the Controller Host.

And so, I find myself spending the vast majority of my controller-scripting time trawling through the API Javadoc trying to "reverse engineer" an understanding of the Object Model from little tid bits of information sprinkled throughout the Object Hierarchy description.

This leaves me feeling like I am going about it all the wrong way, surely this is not how everyone else does it too? Maybe it is? Or maybe there is some important piece of missing information, or missing undertsanding on my part of how to use the Javadoc to understand the object model?

Perhaps it will help if I provide a worked example of me trying to understand something using the docs. I know this is a contrived example, but I think it still illustrates my point.

Let's say I want to create a controller script that monitors the indexes of the currently selected Track and Scene. First thing I do to try to discover how to do this is I go to the Javadocs for the ControllerHost object, and start looking for properties or methods that will give me access to information about Tracks and Scenes.

First thing I notice is that there are no methods or properties on the ControllerHost that give you access to an array of Tracks or Scenes. There is also no getSelectedTrack() or getSelectedScene() functions either. Hmmm...

(Sidebar: I do understand that for the sake of performance we want control scripts to be event driven and to not implement "polling" behaviours, which would likely happen too much if direct access were provided via arrays or iterators.)

After a lot of poking around, both in the docs and in this forum, I piece together that what I want is a CursorTrack that follows the user's selection, and so I am able to cobble together the following code to monitor the currently selected Track.

Code: Select all

loadAPI(10);
host.defineController("Hunting Mirages", "Example", "0.1", "b17da9f0-9c9e-11ea-ab12-0800200c9a66", "Vidamus");

function init() {

    cursorTrack = host.createCursorTrack("id", "name", 1, 8, true);

    cursorTrack.position().addValueObserver(function (pos) {
        println(`Selected track: ${pos+1}`);
    });

    println("Example initialized!");
}

Now when the currently selected Track changes, the index of the current track is printed in the script console. Yay!

This took a long time to figure out because (again AFAIK) there is very little description of what these objects are for, or how they relate to one another.

OK, so far so good. My next task is to do the same thing for the currently selected scene. OK, that means I need a CursorScene right?! I go back to the ControllerHost documentation and look for a createCursorScene() function.... Hmmm... there is no such object... I can see there is a Scene object in the API, but looking at the doc pages for these objects tells me nothing about how I can create one.

Since the ControllerHost does not have methods to get Scenes, and the Scene doc doesn't tell me where to get one, I am now playing "Where's Wally" across the entire Javadoc trying to find which object contains a method that returns a Scene.

(Sidebar: Frustratingly, I can only search the docs for objects or methods that begin with my search string, it doesn't find objects or methods that contain the string. So I have to guess what method names might start with)

Literally hours go by while I am doing this... and I still haven't figured it out as I write this. At this point I feel like I'm trying to drive a screw with a hammer. Surely I am missing something important here??!

Now, the point of this thread is not to ask you to provide me the specific info of how to get a Scene. While that would be nice, I am really hoping someone can "teach a man to fish" by explaining the right way to use the docs to understand how to navigate the object model to get at any given object.

So, please help me understand where am I going wrong in trying to learn how to use the object model? Or, is this just what everyone has to go through?

Many thanks for your time and thoughts on this.

Cheers,
Sam

[hydrogxn]

Feel your pain big time. Was super helpful to go thru all of mosses videos and type all the same code and build my understanding. Lots of hidden stuff there that is not in plain sight. Especially when you compare it to the julien bayle decompiled LOM output for Ableton.

All these things about getting selected scenes require cursor objects and having to set observers on them or mark interested in init. It’s covered in the tutorial vids.... had some big ah ha moments around vid 8 or so after going through them.

You figured this out already tho.

I share the same sentiments when it comes to the API. The worst is finding and sifting through all the deprecated functions. And also the ones that only partially implement values. Where you can get a value but not set it... not even sure how to pass issues like this to the bigwig team appropriately. Understandably they can’t hold everyone’s hand writing scripts but some stuff is straight up broken or could use some attention.

[cturner]

I'd download Moss's controller, and hook up an OSC connection to Bitwig. Ideally then use Moss's Max/MSP template (you could use Max in demo mode for a while), but you might be able to do something similar with Open Stage Control.

Tremendously helpful in seeing what Bitwig sends you unsolicited, and what of that you later don't have access to in certain modes.

Moss may not have implemented everything, and there may be unique aspects of control via OSC, but you can rapidly interact with Bitwig's interface, and get a visceral sense of how it works.

HTH