Full Reference: Codebox and Codebox~ Reference

The codebox and codebox~ objects let you define RNBO functionality by writing text, rather than connecting objects together. This can be especially useful in situations involving complex logic, lots of math, or branching and looping. In these situations, a few lines of code can often replace a very large number of RNBO objects. To create a codebox and codebox~ object, just type the object name into a new RNBO object box.

The rnboscript Language

The actual code that goes into a RNBO codebox is very similar to, but not the same as, JavaScript. If you're comfortable with JavaScript, or with any C-like language, then rnboscript syntax should be very easy for you to pick up. The most important constructs, like if...else, while and for, are all supported.

Like JavaScript, you can declare mutable variables with let, var, and non-changing constants with const. However, if you want to declare some local state that will persist across calls to your codebox object, you should use the @state decorator. For example, if you want to create a counter, you might do it like this:

To get data from an inlet, use in1 for the first inlet, in2 for the second inlet, and so on. To send data to an outlet, assign to out1 for the first outlet, out2 for the second outlet, etc. Inlets and outlets can send and receive lists as well as numbers. In this case, use the form listin1 to get a list from the first inlet, and listout1 to send a list out of the first outlet.

Speaking of lists, rnboscript supports a list object that's very similar to a JavaScript array. You can store a list in a variable, push numbers into a list, retrieve elements from a list, and more. See Codebox and Codebox~ Reference for a full list of supported list methods. These are a subset of JavaScript Array methods, and have the same behavior.

Lastly, you can also give your codebox parameters with the @param decorator. This is basically a @state variable with two extra bits of structure: it can have a range, and it can be set with a message.

Built-in Functions and Objects

Codebox supports a subset of RNBO objects. Very simple objects, the ones that just wrap a stateless function call, are exposed as built-in functions in codebox. So one can write:

let car = cartopol(x, y);

This will have the same output as the cartopol object in RNBO. Some built-in functions return a number:

Others return multiple values as an array:

RNBO objects with some internal state, like a phasor~ or a cycle~, are exposed as codebox-supported objects. These must be created with new and given the @state decorator.

@state myPhasor = new phasor();

These objects all have a next method, which returns the object's output while advancing its internal state by one sample. So calling .next repeatedly on a phasor~ will advance its internal phase.

// Passing a 1 to the next method is the same as setting the phasor's frequency to 1
// At 44.1 kHz, this advances the internal phase by 0.000022675736961
myPhasor.next(1); // 0.000022675736961
myPhasor.next(1); // 0.000045351473923
myPhasor.next(1); // 0.000068027210884

More complex RNBO objects like granulator~ are not currently supported. Built-in functions and codebox-supported RNBO objects are listed as operators and stateful operators on the lefthand sidebar of the Codebox Reference.