Scripting

Introduction

One of the design objectives was ability to export designs into a variety of ways. For example, the design may be exported as VST plugin or VST instrument, in-browser effect, for implementation on a small CPU (e.g. STM32). And, we don’t want to support different environments by having a virtual machine - this just doesn’t cut it in terms of performance, memory footprint, startup time etc.

In order to achieve these goals, components had to be written in such a way that allows the export function to work without having separate component implementations for every language and for every environment.

Scripting is not fully exposed to end users yet. We are working hard on this.

Component model

We use XML to define component model. There are essentially two kinds of things we need to define for a component.

1. Static component properties (e.g. name, description, icon, ports etc) are defined by XML elements.
2. Component code for initialisation, execution and de-initialisation is defined in the payload of the special init, exec and end XML elements.

It’s all wrapped in a single XML file. Let’s look at an example.

<?xml version="1.0" encoding="UTF-8" ?>
<component name="Noise" description="Noise generator" category="Primitives" package="dsp.graph.components.scripted">
  <outputs>
    <output label="Out" name="out" description="The noisy output "/>
  </outputs>
  <controls>
    <control displayMode="POT" label="Amp" max="1.0" min="0.0" name="amp" />
  </controls>
  <exec>
    $out = (float) ( $amp * (2 * #random() - 1) ); 
  </exec>
</component>

This defines the Noise component with a single output and a single control port. It has no data and no initialisation, and exec function does some calculation.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<component name="sample" description="sample component" package="dsp.script">
  <data>
	int $buffLen;
	float $someFloat;
	float[] $someFloatArray; 
  </data>
  <inputs>
    <input name="a" label="a" description="An input port"/>
    <input name="b"/>
  </inputs>
  <controls>
    <control displayMode="POT" label="Amp" max="1.0" min="0.0" name="amp" />
    <control displayMode="SWITCH" label="Range" max="2.0" min="0.0" name="range">
		<value val="0" label="Low"/>
		<value val="1" label="Mid"/>
		<value val="2" label="High"/>
		<change>
			switch($intValue) {
				case 0: {
					someFloat = 2;
				}
				case 1: {
					someFloat = 3;
				}
				default: {
					someFloat = 5;
				}
			}
		</change>
	</control>
  </controls>
  <outputs>
    <output label="a+b" name="out"/>
  </outputs>
  <init>
  	$someFloat = 1;
    $buffLen = (int)($sampleRate / 2);
	$someFloatArray = #makeFloat(32);
	$amp = 1;
  </init>
  <exec>
	$out = $amp * #math:sin(6.28 * ( $a + $b )); 
  </exec>
  <end>
  </end>
  
</component>

Component code - scripting

The philosophy behind the scripting “language” (it really isn’t a formal language) is that we use the lowest common denominator between Java, C, C++ and JavaScript. With the following quirks:

Data Types

Script variables can be primitive types common for C and Java - specifically int, float, double and array types int[] and float[]. Note - when translating to C, array references are automatically converted to pointers, and memory allocation is automatically handled.

In addition to above, function return can be void - meaning that function does not return a value. See functions documentation for more info.

So, supported data types are:

Additional types are built-in types for essential DSP data structures.

struct buffer {
	float* buffer;
	int len;
	int channels;
	int sampleRate;
}

Example:

 buffer $b = #makeBuffer();  
 $b.len = 32;
 $b.buffer = #makeFloat( $b.len );

struct buffer8 {
	uint8_t* data;
	long int len;
}

Example:

 buffer8 $b = #makeBuffer8();  

struct resource {
	int id;
	char name[256];
	uint8_t type;
	char resolved[256];
	int size;
}

Example:

resource $r = #makeResource();

/**
First test struct.

@member floatVal A float value
@member intVal An integer value
@member intArray An int array value
*/
struct test1 {
	float $floatVal;
	int $intVal;
	int[] $intArray;
}

Component code - declarations

The data section allows us to define variables in the scope of this component. Same rules apply as for scripts, however mind that you cannot initialise values here. These are just declarations, any initialisation should occur in the init section.

If we put this into the context of translated code, for Java, these delarations will be

Special variables

Following special variables are available in scripts.