Getting Started

A Device gives you access to its parameters by using the .parameters property, which will return an array of Parameter objects. You can read and update the values of each parameter in this array. Each parameter corresponds to a param object in rnbo~.

// Print the names of all the top-level parameters in the device.
device.parameters.forEach(parameter => {
    // Each parameter has an ID as well as a name. The ID will include
    // the full path to the parameter, including the names of any parent
    // patchers if the parameter is in a subpatcher. So if the path contains
    // any "/" characters, you know that it's not a top level parameter.

    // Uncomment this line to include only top level parameters.
    // if (parameter.id.includes("/")) return;

    console.log(parameter.id);
    console.log(parameter.name);
});

You can also access parameters sorted by id using the parametersById property.

Changing Parameter Values

All parameters have a value property that can be used to set and get the parameter value. So in order to set the value of a parameter in your Device, simply store the parameter in a new variable and set its value.

// param is of type Parameter
const param = device.parametersById.get("my_param");
param.value = 1;

Based on the type of Parameter there might be additional ways to alter its value. For example, a NumberParameter allows you to set the value as a normalizedValue in a range from (0-1) while an EnumParameter allows you to set the enumValue in addition to setting the value by index.

// here, nParam is of type NumberParameter
const nParam = device.parametersById.get("my_number_param");
console.log(nParam.min, nParam.max); // => 0, 10

nParam.normalizedValue = 0.2;
console.log(nParam.value); // => 2

nParam.value = 5;
console.log(nParam.normalizedValue); // => 0.5

// here, eParam is of type EnumParameter
const eParam = device.parametersById.get("my_enum_param");
console.log(eParam.enumValues); // => [2, 4, 8, 16];

eParam.enumValue = 16;
console.log(eParam.value); // => 3

eParam.value = 2;
console.log(eParam.enumValue); // => 8

Listening to Parameter Changes

The simplest way to register ParameterChange events is by listening to the top-level EventSubject on your device.

device.parameterChangeEvent.subscribe((param) => {
	// Called when param is updated / changed
});

Additionally, each parameter supports a changeEvent that emits when the value of the parameter changes.

// here, the type of the value is dependent on the type of the parameter
const param = device.parametersById.get("my_number_param");
param.changeEvent.subscribe((value) => {
	// Handle events here
});

Parameter Event Notification Levels

When creating a RNBO device, the parameterNotificationSetting option determines whether the device will post a notification due to value changes that are internal, external, or both. An external value change is one that comes from host code—in other words, the code that you write around your exported RNBO device. In general, these will be changes that look like param.value = <value>;. An internal value change is one that comes from the device itself.

const device = await createDevice({
	context: audioContext,
	options: {
		parameterNotificationSetting: ParameterNotificationSetting.All // also the default value
	}
	patcher: patcher
});

// Let's assume this exists in our patcher
const param = device.parametersById.get("my_number_param");

// With ParameterNotificationSetting.All, the device AND the parameter emit an event when we change the value
param.changeEvent.subscribe((v) => {
	console.log(`ChangeEvent: ${v}`);
});

device.parameterChangeEvent.subscribe((v) => {
	console.log(`ParameterChangeEvent: ${v}`);
});

// Change the value
param.value = 2;
// => both listeners will be called
// "ChangeEvent: 2" and "ParameterChangeEvent: 2" will be printed to the console

// Disable events for value changes from the "outside"
device.parameterNotificationSetting = ParameterNotificationSetting.Internal;

// Change the value
param.value = 3;
// No listener will be called. We will only get events when the device updates / corrects the value internally

Note that redundantly setting the value of a parameter will never trigger any of the aforementioned events.

param.value = 3; // triggers events with ParameterNotificationSetting.All as the option
param.value = 3; // will not trigger an event as we did not actually change the value

The API Documentation for all available options can be found here.

Parameter Scaling and Normalization

All RNBO parameters have a value and normalizedValue property. These properties allow you to get and set the values of a given parameter. The normalizedValue property uses a range between 0 and 1. Setting the normalizedValue of a parameter to 0 will set the parameter to its minimum value, and setting it to 1 will set the parameter to its maximum value.

Normalized RNBO parameters may utilize nonlinear scaling, either through a simple exponent or through a custom normalization expression as defined in the original RNBO patcher. If you want to use the normalization function bound to a parameter, the parameter class has two functions that you can use to convert to and from a normalized value.

* convertToNormalizedValue - A function to convert a real value to its normalized representation

* convertFromNormalizedValue - A function to convert a normalized value to its real counterpart

< Back

Next >