RNBO

RNBO is a new tool from Cycling 74 which allows you to export your Max/MSP patches into various different formats. You can now deploy Max-like patches to hardware and software targets like Raspberry Pi, VST and Audio Unit plugins. You can also export to C++ and JavaScript code for use in custom desktop applications and Web Audio contexts.

Integration of RNBO and Bela is now fully working but under active development so this page will be updated regularly with the latest developments and bugfixes.

Table of contents

  1. Taking Max patches into the wild
  2. Running a RNBO project on Bela
    1. Step 1: add custom project to Bela
    2. Step 2: export c++ code from Max / RNBO
    3. Step 3: copy generated code to Bela
  3. Parameter control from Bela’s hardware
    1. Viewing the available parameters
    2. Assigning Bela analog inputs to a parameter
    3. Assigning Bela digital inputs to a parameter
  4. Loading presets

Taking Max patches into the wild

Here’s an introduction to RNBO from Cycling 74 for those of you who are unfamiliar with it.

Note that we are using RNBO version 1.0.0 in this guide.

Running a RNBO project on Bela

Running a RNBO project on Bela is simple:

Step 1: add custom project to Bela

To begin download this repo as a .zip file. To download from Github click the green Code button and then select Download ZIP. Make sure your Bela board is connected and then add this project to Bela by simply dragging and dropping the .zip file on the IDE window.

Upon creating the new c++ project you will see an error in the console: 'RNBO.h' file not found column: 10, line: 2. This error will disappear after you build the project for the first time so can be ignored.

Click the Run button to build the project. This will take a good few minutes the first time you do it but will be much quicker on subsequent builds.

Step 2: export c++ code from Max / RNBO

We now need to generate c++ code from within the Max software. A good source of examples which run on Bela can be found in the RNBO Guitar Pedals Package. From within one of these patches double click on the [rnbo~] object to open the RNBO patcher (similar to Max but with objects outlined in blue). On the righthand side menu you will see an icon of a document to Show Export Sidebar. Click to open the below:

The first of the options is the one we want: C++ Source Code Export. The next window has various export options. We will leave them as default aside from defining the Output Directory.

Click Export to Selected Target in the bottom right to generate the files.

The important files from the export are rnbo_source.cpp which you may have renamed, and presets.json.

Step 3: copy generated code to Bela

Copy the rnbo_source.cpp file from the generated code to your project in the Bela IDE and build the project. You can set the name of this file in “Export name” in the RNBO export dialog to something else than rnbo_source.cpp. If you do so remember then to remove the other rnbo_XXXX_.cpp file that is already part of the Bela project, you should only have one file beginning with rnbo… in the sources folder of your project at a time.

After a few seconds your project should start running! There will be some warnings printed to the console while building but these can be ignored for now: we’re working on cutting them down.

Parameter control from Bela’s hardware

Viewing the available parameters

When you run your project you will see printed to the console a list of the available parameters you can control in your RNBO patch. Below is an example of the parameters printed to the console.

60 parameters available:
[0] input
[1] time
[2] scale
[3] color
[4] volume
[5] mix
[6] spread
[7] filter
[8] regen
[9] fb
+ 50 hidden parameters
...

You can see that each parameter has an index in the square brackets at the beginning. The first items on the list are from any [param] objects in your patch, which are the most immediately useful for controlling your patch.

Additionally there are hidden parameters which are any interface items in your patch (number boxes, toggles, bangs) which can also be mapped to when building the project. To view these additional parameters set bool showHiddenParameters = true.

Assigning Bela analog inputs to a parameter

At the top of render.cpp (part of your project files in the IDE) you will see an vector called parametersFromAnalog where you can enter the indexes of the parameters you want to control from your RNBO patch.

For example parametersFromAnalog = {0, 1, 2, 3, 4, 5, 6, 7}; will directly map the Bela’s 8 analog inputs to the first 8 available parameters on the list (remember that on Bela we use zero indexing). Once you run the project with parametersFromAnalog filled in you will see the mapping printed to the console.

[0] input - controlled by analog in 0
[1] time - controlled by analog in 1
[2] scale - controlled by analog in 2
[3] color - controlled by analog in 3
[4] volume - controlled by analog in 4
[5] mix - controlled by analog in 5
[6] spread - controlled by analog in 6
[7] filter - controlled by analog in 7

The analog input from Bela will automatically be rescaled to the full range of the parameter as defined in the RNBO patch and is sent unfiltered once per audio block.

Tip

To see the current range of a parameter within your RNBO patch, right click on the relevant [param] object and click "Inspector". Here you can see the minimum, maximum, initial value, and exponent of the parameter range.

Any remaining analog input channels are sent as extra audio ins. All analog out channels are used as extra audio outs. Further customisations of parameters (e.g.: controlling them via digital in/extracting them via analog out or digital out) can be achieved by customising the render.cpp file.

Assigning Bela digital inputs to a parameter

These work in exactly the same way: enter the indexes of the parameters you want to control in the vector parametersFromDigital. If you would like to skip an entry in the array, useful if you want to address digital in 7 for example without assigning the inputs beforehand, you can do so as follows.

static std::vector<unsigned int> parametersFromDigital = {
	kNoParam,
	kNoParam,
	kNoParam,
	kNoParam,
	kNoParam,
	kNoParam,
	4
};

The end result of the above will be that digital input 7 on Bela will be assigned to parameter 4 from the RNBO patch.

Loading presets

If you also copy presets.json to the project, presets will be read and the first one (by default) will be loaded. Note that any parameters set by the presets but also controlled by Bela’s analog inputs will be overridden by the analog inputs.

TODO

  • Calling setParameter() for every audio callback uses an excessive amount of CPU. We should use a filter and a quantiser with hysteresis and only update on changes to be ore efficient.