ScriptModulationMatrix

This class provides programmatical access to the new matrix modulation system in HISE 5.0. It offers convenient methods to query modulation properties, be notified over connection events as well as programmatically perform connection changes.

In addition to these features, this class will also act as data management tool and automatically register itself to the user preset system so that all modulation connections are stored / restored in the user preset.

This class is just a simple wrapper around the functions available at different locations within HISE, so for a detailed overview of the entire matrix modulation system, please take a look at these sections:

• The Matrix Modulator module for a explanation of the (new) architecture that is powering the modulation matrix system.
• The ModulationMatrix and ModulationMatrixController floating tiles for a explanation of the available UI building blocks.

In order to use this class make sure to setup your system to work with matrix modulators:

1. Create a global modulator container and add modulation sources in there
2. Add Matrix modulators to every target that you want to modulate
3. Add / customize the floating tiles to display / edit the modulation connections
4. Create this object in the onInit callback with Engine.createModulationMatrix() and then register callbacks / perform operations on this object.

Note that this object was completely redesigned in HISE 5.0 with absolutely no attention paid to remaining backwards compatible to the API of older versions, so if you were using this object before, you will need to completely rewrite your modulation logic.

Class methods

canConnect

Checks whether the modulation connection can be made.

ScriptModulationMatrix.canConnect(String source, String target)

This method checks whether the source and target IDs are valid (= they exist) and are not connected.

• it returns true if both IDs are valid and there is no connection
• it returns false if one of the IDs are invalid or there is already a connection

Note that you don't need to call this method if you intend to call connect() , as this method performs this check internally too.

clearAllConnections

Removes all connections for the given target (or all connections if no target is specified).

ScriptModulationMatrix.clearAllConnections(String targetId)

This clears all connections for the given target ID or all connections if you pass in an empty string.

This action is fully undoable with Engine.undo() . Note that this will kill all voices and perform this operation on the scripting thread to avoid audio glitches.

connect

Adds (or removes) a connection from the source to the target.

ScriptModulationMatrix.connect(String sourceId, String targetId, bool addConnection)

This method allows you to programmatically connect modulators (just like using the UI functions). Calling this method connects / disconnects the given source modulator to the specified target and returns true if a connection was established. If there was already a connection or one of the IDs was invalid, it will return false.

This action is fully undoable with Engine.undo() . Note that this will kill all voices and perform this operation on the scripting thread to avoid audio glitches.

fromBase64

Loads the state from a previously exported Base64 string.

ScriptModulationMatrix.fromBase64(String b64)

This restores all modulation connections from a given Base64 string. Note that by default a ScriptModulationMatrix will register itself to the user preset system and automatically restore / save its connections into user presets, but this function alongside with ScriptModulationMatrix.toBase64() allows you to manually save / restore the modulation setup of your synth.

This action is fully undoable with Engine.undo() . Note that this will kill all voices and perform this operation on the scripting thread to avoid audio glitches.

getComponent

Get the component reference for the given modulation target ID.

ScriptModulationMatrix.getComponent(String targetId)

This function returns a reference to the first UI component that is assigned to a given modulation target.

Note that this does not return the ID but the component reference itself so you don't need to call Content.getComponent() afterwards.

getMatrixModulationProperties

Returns a JSON object with the current matrix modulation properties.

ScriptModulationMatrix.getMatrixModulationProperties()

This will return a JSON object with all the properties of the matrix modulation system. Usually you call this method, modify the object and then pass it back to ScriptModulationMatrix.setMatrixModulationProperties() to apply the changes in the onInit callback.

getSourceList

Return a list of all sources.

ScriptModulationMatrix.getSourceList()

This function returns a list of all available modulation sources, which are basically just the IDs of all modulators in the global modulator container.

getTargetId

Get the target ID (either ID of the matrix modulator or matrixTargetId property) for the given component.

ScriptModulationMatrix.getTargetId(var componentOrId)

This function returns the associated target ID for the given component. The argument can be either a ID (then it will search all UI component for the first match) or a direct reference to the UI element.

This is basically the reverse function to ScriptModulationMatrix.getComponent() .

getTargetList

Return a list of all targets.

ScriptModulationMatrix.getTargetList()

This function returns a list of all available modulation targets. This will be the ID of all matrix modulators as well as all ScriptSlider components that have the matrixTargetId property set (in that case it will not return the UI component's ID but the actual value string of the matrixTargetId property).

setConnectionCallback

Set a callback that will be executed whenever the matrix state changes.

ScriptModulationMatrix.setConnectionCallback(var updateFunction)

This function will be executed whenever a connection was added or removed. It expects a function / callable object with three parameters:

1. the source ID
2. the target ID
3. whether it was added or removed.

Note that this function will be executed for every connection, so if you clear all connection at once it will be executed multiple times. So if you use a broadcaster for the notification callback make sure you enable the queue with Broadcaster.setEnableQueue() , otherwise it will only fire with the last event.

const var m = Engine.createModulationMatrix("Global Modulator Container1");

// setup a connection callback
m.setConnectionCallback(function(source, target, wasAdded)
{
	// dump the event data
	Console.print(trace({
		source: source,
		target: target,
		wasAdded: wasAdded
	}));
});

// connect the LFO to the OSC1 Gain target
// It assumes that you have set this up!
m.connect("LFO", "OSC1 Gain", true);

// Clear the connection again
m.clearAllConnections("");;

Output:

Interface: {
  "source": "LFO",
  "target": "OSC1 Gain",
  "wasAdded": true
}
Interface: {
  "source": "LFO",
  "target": "OSC1 Gain",
  "wasAdded": false
}

setConnectionProperty

Sets the property of a modulation connection (with undo). Edit on GitHub

ScriptModulationMatrix.setConnectionProperty(String sourceId, String targetId, String propertyId, var value)

setCurrentlySelectedSource

Sets the currently selected source.

ScriptModulationMatrix.setCurrentlySelectedSource(String sourceId)

This method can be used to programatically change the currently selected source. Usually this is done automatically by the ModulationMatrixController , but if you are implementing a custom UI replacement for that UI component, you can use this functionality.

Note that whenever you call this function (or drag a dragger), it will automatically close all hover popups that are currently active.

This functionality can be disabled with the ScriptModulationMatrix.setMatrixModulationProperties() function.

setDragCallback

Attaches a callback to be notified wheneve a modulation connection is being dragged.

ScriptModulationMatrix.setDragCallback(var newDragCallback)

If you setup a UI component for dragging modulation connections on a target, you can attach a callback to drag events using that method. This function expects a callable object with 3 parameters:

1. The source modulator ID
2. The target ID if the user drags a connection over a modulatable knob
3. A string with the event type

This function will now get executed with the following string values as third event type parameter:

• "DragStart" whenever the user starts dragging a modulation connection with the ModulationMatrixController or via ScriptPanel.startInternalDrag() (if the drag data is connected to the modulation system). In that case the targetId parameter will be empty.
• "DragEnd" if the user stops dragging the source or is dropped on a illegal target.
  In that case the sourceId and
  targetId parameters will be empty.
• "Drop" whenever the user drops the modulation connection on a valid UI knob. In that case the targetId parameter will be the matrixTargetId of the hovered knob.

• "Hover" if the user drags the connection over a valid target knob (on hover).
  In that case the targetId parameter will be the matrixTargetId of the hovered knob.
• "DisabledHover" if the user drags the connection over an invalid target knob (eg. because it has already a connection to that source). In that case the targetId parameter will be the matrixTargetId of the hovered knob.

setEditCallback

Set a callback that will be executed when the user clicks on "Edit connections".

ScriptModulationMatrix.setEditCallback(var menuItems, var editFunction)

This function can be used to supply additional functions in the context menu of a modulatable UI component.

This method expects two arguments:

1. A single string or an array of strings for each menu item
2. a function or callable object with two parameters that will be executed when you click on said context menu item with the zero based index of the clicked item and the associated target ID of the UI component.

If you want to find out the component that was clicked just pass that into the ScriptModulationMatrix.getComponent() method.

const var m = Engine.createModulationMatrix("Global Modulator Container1");

m.setEditCallback(["funky", "noice"], function(idx, targetId)
{
	Console.print(idx); // 0 if you click funky, 1 if you click on noice...

	Console.print("TARGET: " + targetId);
	Console.print("COMPONENT: " + this.getComponent(targetId).get("id"));
});

The use cases for this method are pretty diverse:

• you can use it to "edit the connections" by showing a matrix component with all connections of the target
• you can use it to add a "clear all connections" function for the given component (or other data management functions like custom save / restore)
• you can use it to reset the intensity values
  

setMatrixModulationProperties

Sets the global properties for the matrix modulation system.

ScriptModulationMatrix.setMatrixModulationProperties(var newProperties)

This function can be used to modify the behaviour / properties of the entire matrix modulation system. Currently you can:

• Enable / Disable the exclusive source selection feature.
• Change the default intensity values and modulation mode for each target that are used when adding a new connection
• Change the range properties of every matrix modulator (this can also be achieved with Modulator.setMatrixProperties() ), however this function allows you to set all ranges in one go without having to fetch references to each modulator.

The best way to go about this is to fetch the current state with ScriptModulationMatrix.getModulationProperties() , modify that object and then call this method to ensure that the object layout is valid.

The JSON object will expect these properties:

Key	Type	Description
SelectableSources	bool	Defines whether to use the exclusive source feature. If this is true, then the callbacks that will fire when switching the currently selected source are disabled.
DefaultInitValues	JSON	Defines the initial intensity and modulation mode values for new connections for each target. This must be a JSON object with the target ID as key for each target you want to customize. (see below for a detailed description).
RangeProperties	JSON	Defines the range properties for each modulation target. This must be a JSON object with the target IDs as keys for each target you want to customize. Look here for a description of all properties of each item.

DefaultInitValues items

If the user adds a new connection from a modulation to a target source there is a sensible default for each target type:

• if the modulation target is Gain modulation, it will pick the "Scale" mode with 100% intensity.
• otherwise it will use 0% intensity and "Bipolar" modulation as default.

You can override this behaviour - eg. if you want to add a little bit of intensity so that there is an immediate effect when adding a modulation connection. In order to do so, just pass in a JSON object as DefaultInitValues key that defines a JSON object for each target. The properties you need to define here are:

Key	Type	Description
Intensity	double	The intensity value that should be initialised. The value domain of this is defined by the IsNormalized property explained below.
Mode	String	One of the following strings that define the mode: ["Scale", "Unipolar", "Bipolar"] .
IsNormalized	bool	Whether to convert the Intensity value from the input range of the target modulator. So eg. if you have a pitch modulator set to +-12 semitones and want to set the initial modulation intensity to 3 semitones, you would set this property to false and Intensity to 3.0 . By default this is deactivated so it will pickup the "raw" intensity value that will be applied to the modulation connection.

setSourceSelectionCallback

Attaches a callback to be notified whenever a new modulation source is selected.

ScriptModulationMatrix.setSourceSelectionCallback(var sourceSelectionCallback)

This function can be used to attach a callback to be notified when the currently selected modulation source is changed. This is caused by one of two events:

1. You click on a dragger from a ModulationMatrixController .
2. You call ScriptModulationMatrix.setCurrentlySelectedSource() (most likely because you're reimplementing something like the modulation matrix controller with a ScriptPanel).

This can now be used for different things, eg:

• changing the layout of the hover popup that shows all modulation connections of a given UI knob
• highlighting the modulator module on your UI

The function expects a callable object with a single parameter that will be called with the ID string of the source (= the modulator's ID).

Take a look at this snippet for an example use case (showing only the currently selected modulation connection when you hover over a knob).

toBase64

Creates a Base64 string of all connections. Edit on GitHub

ScriptModulationMatrix.toBase64()