Nucli reference

New in MNodes 1.1.6

Older versions of MNodes do not have Nucli. A project that uses it will not work there until you update.

This page lists everything the code of a Nucli node can use, so you can look it up. How Nucli works, with examples, is on the Nucli page, and each part here links to where it is explained.

Inside MNodes, the Reference button on the node shows the same things in groups, each with a button that writes it where the cursor is.

At the top of the program

These declare what the program has. They go at the top, outside any { }. A history, a delay and a data can also go at the top of a function of your own, which then has its own.

Write	What it makes	Explained in
param cutoff = 1000 (20 .. 20000)	A setting: a row in the Inspector and a pin that takes Data or CV. The number after = is where it starts, the brackets its range. With no range it goes from 0 to 1 (further if its start is outside that). The code reads it but cannot change it. It takes a new value at the start of each block.	Params
param bits = 8 (1 .. 16 step 1)	A setting that moves in steps, counted from its lowest value: step 1 gives whole numbers. Every value it takes goes to the nearest step.	Params
history y = 0	A value kept from one sample to the next. Several on one line: history a = 0, b = 0.	Memory
delay echo(2 * samplerate)	A delay line that holds that many samples. Several on one line.	Delay lines
data wave(2048)	A table of that many values, all 0 to start.	Tables
init { ... }	Lines that run once, when the code starts and when Run starts the memory again.	Once at the start
latency 0.005 * samplerate	Tells MNodes how late the code makes the sound, in samples.	Effects that look ahead
spectral lp(1024, 4) { ... }	A block that works on the sound's frequencies.	Spectral blocks
function name(a, b) { ... }	Lines with a name, to use more than once.	Functions of your own

The size of a delay line or a table, and a latency, can use only numbers and samplerate, because they are fixed before the sound starts.

Inputs, outputs and constants

Name	What it is
in1 to in16	The sample arriving on each audio input, usually -1 to 1.
out1 to out16	What leaves each audio output: give it a value with =. One never written is silent.
samplerate	Samples a second, such as 48000.
pi, twopi, halfpi	π, 2π and π/2. Math.PI is π too.
Math.E	The number e, 2.718...
true, false	1 and 0.

The node has as many audio inputs and outputs as the highest ones the code uses.

Values and lines

Write	What it does
let x = in1 * 0.5	Names a value. const and var work the same way. A let lives for one sample.
x = ..., +=, -=, *=, /=	Gives a value a new one.
k++, k--	One more, one less.
if (a) ... else ...	Runs a line or a { } block when a is true, the other when it is not.
switch (x) { case 0: ... break default: ... }	Runs the case whose number is x, or default when none is. Each case ends with break but the last; case 1: case 2: share their lines. See One of several.
a ? b : c	b when a is true, c when not. Both sides are worked out every sample.
for (let k = 0; k < 8; k++) { ... }	A loop, as in JavaScript.
while (a) { ... }	Runs while a is true.
break, continue	Leaves a loop, or skips to its next turn.
return x	A function's value, on its last line. return low, high gives two, taken as let lo, hi = split(in1).
// ..., /* ... */	Comments.

A ; at the end of a line is not needed, but it does no harm.

Operators

Write	Means
+ - * /	Add, subtract, multiply, divide.
%	What is left after dividing.
**	To the power of: 2 ** 3 is 8.
< <= > >=	Compare: 1 when true, 0 when not.
== !=	Equal, not equal. === and !== are the same.
&& || !	And, or, not.
-x	The value turned negative.

Built-in functions

Each one can also be written the JavaScript way: Math.sin(x) is sin(x). Math.random is not there: use noise().

Function	Gives
sin(x), cos(x), tan(x)	Trigonometry, x in radians.
asin(x), acos(x), atan(x)	The angle back.
atan2(y, x)	The angle of the point x, y.
sinh(x), cosh(x), tanh(x)	Hyperbolic. tanh is also a smooth soft clip.
exp(x), exp2(x)	e to the x, 2 to the x.
log(x), log2(x), log10(x)	Logarithms.
pow(x, y)	x to the power of y.
sqrt(x)	The square root.
hypot(x, y)	The length from 0 to the point x, y.
abs(x)	x without its sign.
sign(x)	-1, 0 or 1.
floor(x), ceil(x), round(x), trunc(x)	Rounded down, up, to the nearest, toward 0.
fract(x)	The part after the point.
min(a, b, ...), max(a, b, ...)	The smallest or the largest, of two or more.
clamp(x, lo, hi)	x kept between lo and hi.
wrap(x, lo, hi)	x wrapped round into lo to hi.
fold(x, lo, hi)	x folded back into lo to hi.
mix(a, b, t)	From a (t = 0) to b (t = 1).
mtof(note), ftom(hz)	A MIDI note to hertz, and back.
dbtoa(db), atodb(gain)	Decibels to a gain, and back.

These have a memory of their own, so each one written is a separate oscillator or filter. In a function of your own, each call of the function has its own.

Function	Gives
phasor(freq)	A ramp from 0 to 1, freq times a second.
cycle(freq)	A sine wave.
noise()	White noise, from -1 to 1.
lowpass(x, freq), highpass(x, freq)	A gentle (one-pole) filter.
dcblock(x)	x without its offset.
delta(x)	How much x changed since the last sample.
sah(x, trigger)	Holds x each time trigger goes above 0.

Delay lines

delay echo(size) makes a delay line called echo that holds size samples. How to use one: Delay lines.

Write	What it does
echo.write(x)	Puts this sample in.
echo.read(t)	The sample from t samples ago. Between two samples it gives a value in between; past its size, its oldest sample.
echo.cubic(t)	The same through a smooth curve, for a time that moves: a chorus, a flanger, a vibrato.
echo.size	How many samples it holds.

Tables

data wave(size) makes a table called wave of size values. How to use one: Tables.

Write	What it does
wave.write(i, v)	Sets value number i (the first is 0).
wave.read(i)	Gives value number i back. An i past the end wraps round to the start, and one with a fraction is rounded down.
wave.lookup(phase)	Reads the table as one cycle of a wave: phase 0 is its start and 1 its end, with values in between.
wave.size	How many values it holds.

Spectral blocks

spectral name(frame, overlap) { ... } makes a block that runs its code once for every bin of every frame. name(in1) sends a sound through it and gives back the result. How to use one: Spectral effects.

Write	What it is
frame	Samples in a frame: 64, 128, 256, 512, 1024, 2048, 4096, 8192 or 16384.
overlap	4 or 8. 8 sounds smoother and costs twice as much.
bin	Inside the block: which bin this is, from 0 to bins - 1.
bins	Inside the block: how many bins there are.
freq	Inside the block: this bin's frequency, in hertz.
mag	Inside the block: how strong this frequency is. Change it to change the sound.
phase	Inside the block: where its wave is in its turn, -π to π. Change it to change the sound.

Inside a block the code sees the params and the tables, but not the inputs, the outputs, a history or a delay line. A block makes the sound one frame late, and says so to MNodes by itself.

Limits

What	How much
Audio inputs, audio outputs	Up to 16 each.
Params	Up to 32.
A delay line or a table	Up to 16,777,216 values: nearly six minutes at 48 kHz.
Loops	2048 turns a sample on average, shared by every loop of the node. A loop that uses them up stops there, and the status line says which.
Loops in init	About four million turns.
Functions of your own	One can call another, but not itself.