Learn Getting Started with Codebox

Getting Started

Welcome to RNBO

Quickstart

RNBO Basics

Key Differences

Why We Made RNBO

Coding Resources

Fundamentals

Audio IO

Messages to rnbo~

Using Parameters

MIDI in RNBO

Messages and Ports

Polyphony and Voice Control

Audio Files in RNBO

Using Buffers

Using the FFT

Export Targets

Export Targets Overview

VST/AudioUnit
Max External Target
Raspberry Pi Target
The Web Export Target
The C++ Source Code Target

Code Export

Working with JavaScript
Working with C++

Codebox

Getting Started with Codebox

Understanding Storage: let, const, @state, @param

Building a Note Controller with Codebox

Special Topics

Sample Accurate Patching
Scala and Custom Tuning

RNBO and Max for Live

RNBO Raspberry Pi OSCQuery Runner

Metadata

Export Description

Raspberry Pi GPIO

Updating the RNBO Package

Getting Started with Codebox

Codebox in RNBO. When to use Codebox. How to get the most out of it.

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.

intro-to-codebox.png

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.

loops-and-branches.png

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:

counting.png

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.

Screen Shot 2022-10-30 at 11.46.21 AM.png

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:

operators.png

Others return multiple values as an array:

operators-multi-return.png

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.