Codebox

The constant value used when converting from degrees to radians

degtorad

out1

halfpi

invpi

ln10

log10e

log2e

not supported in RNBO, will always return 1.

mc_channel

mc_channelcount

returns the maximum number value that the number system can represent

number_max

PI_OVER_2

PI_OVER_4

The constant value used when converting from radians to degrees

radtodeg

sqrt1_2

sqrt2

twopi

objects use a JavaScript-like scripting language to implement DSP and event code directly inside of RNBO. The syntax is similar to the

 in Gen, with some important differences.

Unline Gen, variables must be declared with 

 keyword. While this makes the RNBO codebox language 

 very similar to JavaScript, not all JavaScript features are supported. Overall, 

 object, rather than a replacement for the Max 

You can create and reference inlets and outlets using 

basic.png

bascic-dsp.png

 is sufficent to create a second inlet. When using

, any assignment to an outlet will cause an output on that outlet.

Screen Shot 2022-06-27 at 2.57.49 PM.png

This will print 4 and then 5 whenever the codebox receives input at its first inlet. The codebox will always have a first inlet. As is often the case in Max, only the leftmost inlet is "hot". Sending a value to the first inlet will trigger output, while sending a value to the other inlets will instead simply update the internal value of 

, all outlets are always signals, and will output a signal vector every audio frame.

list-basic.png

 identifiers to get accordingly typed inlets and outlets.

 to declare local variables. While you can re-assign the value of 

 variables, these updates will not persist between codebox calls—see 

 values in parameter declarations. This includes globally-defined 

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:

 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 

, are exposed as codebox-supported objects. These must be created with 

 method, which returns the object's output while advancing its internal state by one sample. So calling 

The cycle and phasor objects are very common:

phasor_cycle_02.png

 are not currently supported. Built-in functions and codebox-supported RNBO objects are listed on this page's lefthand sidebar as operators and stateful operators. 

Most of the control flow keywords from C++ and JavaScript are supported. The looping constructs 

However, language-specific paradigms like 

 are not currently supported. You can also use branching constructs like 

These keywords should follow the C++ and JavaScript specification, so refer to the documentation for those languages for a more thorough discussion of how to use these keywords.

Function declarations are supported using the 

function.png

A function can return multiple values by returning an array.

functions.png

The return type of a function is automatically deduced (it will be a list, if you use an array expression as a return type). Anonymous functions, like you might create with big-arrow notation in JavaScript or C++ lambdas, are not currently available.

There are currently three special functions:

Screenshot 2022-05-31 at 19.15.14.png

Sometimes you want a function to be called whenever data comes into one of the inlets that is not the first one. This can be achieved through an inlet function. In this example, the function is called whenever a list is received at the second inlet:

Screenshot 2022-05-31 at 19.28.30.png

 whenever the second inlet receives any input. This function will run in addition to setting the value of 

, so you can think of the function as a side effect of setting 

In order to re-use state after codebox has triggered some output, use the 

 decorator.  This will create state that persists across the lifetime of the codebox object.

state2.png

 keyword to declare variables that can be used during codebox execution, these are not reusable state variables. For example, something like this will not work:

Screen Shot 2022-06-27 at 3.50.57 PM.png

 decorator to introduce a state variable that can be set via a message:

Screen Shot 2022-06-28 at 2.05.51 PM.png

 decorator function is the only place in the codebox language that you can use a JavaScript-style object. The function takes as its one and only argument an object describing how the parameter should behave. It can take the keys 

 to define a range, or it can take the key 

, followed by a list of enumerated values. Enumerated parameters always start at index 0.

Following the decorator function, the parameter must be given a name and an initial value.

A codebox's state can also hold a reference to a buffer. This may be sized, unsized, named, or anonymous. For example, this creates a reference to a buffer "mybuf" defined outside of the codebox.

buffers.png

This will create an internal, anonymous buffer, that will always be twice the sample rate in size:

buffers2.png

 the only two supported operators in size expressions are 

 This will create a named buffer (which will also be available in Max) of size 44100:

buffers3.png

 to set and get sample values. Reading and writing in buffers does bound checking, so you cannot read or write out of bounds. As you can see, some built-in functions take a buffer as their argument. The list of operators in the left sidebar includes such functions.

It is possible to give a codebox variable an explicit type.

types.png

This is usually unnecessary, but sometimes necessary (for example) when strict typing requires that a number have an integer type.

Explicit types also allow you to declare a variable without setting it, if you want to. For example:

 is a number and will throw an error. Valid types include 

Finally, you may find that your codebox fails to compile sometimes in cases where you're using a custom function that returns a list. Sometimes the compiler can infer the return type of a function, and the explicit 

 type is unnecessary. However, you can always add the explicit return type to clear up the error if you're seeing a problem. 

 do not have a fixed size. Adding and removing elements from the list changes the size of the list. Sometimes it's convenient to work with fixed size arrays. These arrays are highly efficient, especially when it comes to setting and getting values from the array at a particular index. One thing that's particularly useful is that with fixed arrays, you can create multidimensional arrays that you can index along multiple dimensions. For example:

 that fills up an array with a sinusoid, 180 degrees out of phase in each channel.

The following types are supported for fixed size arrays:

Name ------------------ C Type --------------- Description
FixedInt8Array -------- int8_t --------------- Signed 8-bit integer
FixedUint8Array ------- uint8_t -------------- Unsigned 8-bit integer
FixedInt16Array ------- int16_t -------------- Signed 16-bit integer
FixedUint16Array ------ uint16_t ------------- Unsigned 16-bit integer
FixedInt32Array ------- int32_t -------------- Signed 32-bit integer
FixedUint32Array ------ uint32_t ------------- Unsigned 32-bit integer
FixedFloat32Array ----- float ---------------- 32-bit float
FixedFloat64Array ----- double --------------- 64-bit float
FixedBigInt64Array ---- int64_t -------------- Signed 64-bit integer
FixedBigUint64Array --- uint64_t ------------- Unsigned 64-bit integer
FixedSampleArray ------ float or double ------ The same type as an audio sample
FixedNumberArray ------ multiple ------------- Value may change depending on the 
                                               circumstances in which code is generated 
                                               and used. Use this if you don't need a 
                                               particular number type.
FixedIntArray --------- int ------------------ Signed integer, equivalent to C int
FixedFloatArray ------- float ---------------- Equivalent to C float
FixedDoubleArray ------ double --------------- Equivalent to C double

 object can also accept a number message at any of its inlets.

If only messages and no signals are connected to the inlet of a 

, then the inlet value (in1, in2, etc.) will only update once every signal vector. This is much more efficient, though it does mean that the value cannot change during the computation of an audio block.

List functions in RNBO fall into two categories: global list functions and methods on a list object.

Global list functions all have a RNBO object equivalent. For example, the object 

 is equivalent to the global codebox function 

. For all of these objects, the function inside codebox is simply the name of the RNBO object without the period after the word "list". 

The following is a list of methods on a list object. Some of these have a RNBO object equivalent, for example the 

 method is equivalent to the RNBO object 

. Many of the list functions that are currently supported are modeled after their JavaScript equivalent. Where possible, these are identical. For a full discussion of the behavior of each function, see the JavaScript documentation of that function.

codebox and codebox~ enable you to use rnboscript, a JavaScript-like scripting language, to implement DSP and event code directly inside of RNBO.

Codebox and Codebox~ Reference

C++ API

frequency

phase_offset

out2

reset

cycle

The buffername attribute followed by the name of a valid buffer will fill the cycle~ wavetable with the values from that buffer instead of the default wavetable.

buffername

Sets whether the cycle~ index is set using a frequency in hz or phase. * 0 = frequency (default) * 1 = phase. In this mode the left inlet controls the phase offset position and the right inlet does nothing.

index

Sets the interpolation mode for the internal buffer used by cycle~. * linear (default) * cubic * spline * cosine * step * none

interp

Performs the subtraction with the value currently stored.

The value in the right inlet is subtracted from this value and the result is sent out the outlet.

Compute the absolute difference between two inputs

absdiff

The absolute value of the difference between the two numbers received in the inlets.

acos

Input to the inverse hyperbolic cosine function.

acosh

The inverse hyperbolic cosine of the input.

Performs the operation with the value currently stored. If there is no argument, && initially holds `0`.

The value is compared to the value in the left inlet to determine output but only a value in the left inlet will trigger output.

If either the value in the left inlet or the value in the right inlet (or specified by the argument) is not `0`, then the output is `0`. Otherwise, the output is `1`.

The input number or list that will come before any appended values in the output list.

A number or list of numbers to append to the input.

append

Outputs a list composed of the input value(s) followed by the appended value(s).

asin

Input to the inverse hyperbolic sine function.

asinh

The inverse hyperbolic sine of the input.

arc tangent of the input (returns radians)

atan

atan2

The arc-tan of the divided input in radians.

Input to the inverse hyperbolic tan function.

atanh

atodb

The gain or attenuation from unity gain, expressed in decibels.

The number of beats (quarter notes) to be converted to the equivalent time in Hz using the tempo of the device transport.

beattime

convert beat time (quarter notes) to frequency (Hz)

beatstohz

The number of beats (quarter notes) to be converted to the equivalent time in milliseconds using the tempo of the device transport.

Convert beat time (quarter notes) to milliseconds.

beatstoms

The number of beats (quarter notes) to be converted to the equivalent time in samples using the tempo of the device transport and sample rate of the audio device.

Convert beat time (quarter notes) to samples.

beatstosamps

The number of beats (quarter notes) to be converted to the equivalent time in ticks.

Convert beat time (quarter notes) to ticks.

beatstoticks

offset

Report the current beat time at a specific sample offset.

beattimeatsample

The values to be windowed, bounded to the range 0. - 1.

blackman

The windowed output, bounded to the range 0. - 1.

boolnum

Outputs 1 for non-zero inputs and 0 if the input is zero

A float value sets the phase of the window.

phase

A value between 0.0 and 1.0 sets the shape of the window between the boxcar and the triangle window functions. A value of 1.0 sets a triangle window.

A variable shape window multiplier, from boxcar to triangle.

boxtotri

The float value of the window at the current phase.

buffer

bufferrate

The x coordinate of a Cartesian pair to be converted into a 			polar coordinate pair consisting of distance and angle values. When used 			in an audio context, the value represents the real part of a frequency domain 			value to be converted into a polar coordinate pair consisting of amplitude and 			phase values.

The y coordinate of a Cartesian pair to be converted into a polar 			coordinate pair consisting of distance and angle values. When used in an audio context, 			the value represents the imaginary part of a frequency domain value to be converted 			into a polar coordinate pair consisting of amplitude and phase values.

Convert Cartesian values to polar format. Angles are in radians.

cartopol

The distance portion of the polar coordinate pair. When used in 			an audio context, the value represents the magnitude (amplitude) of the 			frequency represented by the currently input.

The angle portion of the polar coordinate pair. When used in an audio 			context, the value represents the phase, expressed in radians, of the frequency 			represented by the current input. If only the left outlet is connected, the phase 			computation is not performed.

cbrt

Round an input value up to the next higher integer (toward positive infinity)

ceil

channels

Clip an input to a range within an upper and lower bound.

clamp

cond

cosh

In the leftmost inlet, this is the input value to be interpolated.

frac

Set's the value for the 'x' control point. This is the second value of cosineinterp.

Set's the value for the 'y' control point. This is the third value of cosineinterp.

cosineinterp

The output curve is the segment between the middle two points (x and y).

Input to the Taylor series approximation of cosine. Values outside of the 		range [-pi, pi] will begin to diverge towards negative and positive infinity.

8th order Taylor series approximation of the cosine function. Input must be in the range [-pi, pi] in order to approximate without divergence.

Codebox Guides

cycle

Options

Methods

next(frequency, phase_offset): [out1, out2]

Arguments

Returns

reset(): out1

Returns

Name	Type	Default	Description
buffername	symbol	RNBODefaultSinus	The buffername attribute followed by the name of a valid buffer will fill the cycle~ wavetable with the values from that buffer instead of the default wavetable.
index	enum	freq	Sets whether the cycle~ index is set using a frequency in hz or phase. * 0 = frequency (default) * 1 = phase. In this mode the left inlet controls the phase offset position and the right inlet does nothing. Enum Values: `freq \| phase \| both`
interp	enum	linear	Sets the interpolation mode for the internal buffer used by cycle~. * linear (default) * cubic * spline * cosine * step * none Enum Values: `linear \| cubic \| spline \| cosine \| step \| none`

Name	Type	Description
out1	number	Oscillator audio output.
out2	number	The oscillator phase output shows the current phase as it cycles through the internal buffer.