Welcome to the ModScripter documentation

• Introduction
• Generating a modulation signal
• Custom parameters
• MIDI Note Input
• Sidechain
• Script functions
• Host functions
• MIDI mapping

Introduction

ModScripter is a versatile modulator that offers boundless possibilities for creating or manipulating modulation signals.

JavaScript is the programming language used to create scripts for ModScripter. The utilized interpreter adheres to the ECMAScript E5/E5.1 specification.

Generating a modulation signal

The primary function of a modulator is to generate a signal that modulates other parameters, such as volume or cutoff frequencies of other plug-ins. To generate a modulation signal using ModScripter, the script must implement the processModulation function and return the signal as a numerical value within the range of zero to one, commonly referred to as a normalized value.

The most basic script is:

processModulation = function (inputValue) {
    return inputValue;
}

This produces a modulation output signal identical to the input value. The input value is a generic parameter that can itself be modulated by another modulator or automated via MIDI Control Change Messages.

In addition, a script can utilize up to eight custom parameters, a sidechain audio signal, and MIDI note events to generate the final modulation signal.

Furthermore, the script can utilize all the functions defined by the ECMAScript E5/E5.1 specification.

Custom parameters

A script can declare up to eight custom parameters. To handle a parameter, a script must implement at least two functions:

• getParamTitle
• onParamChange

By implementing the getParamTitle function, the user interface of the modulator incorporates elements that enable the modification of parameter values.

getParamTitle = function (paramIndex) {
    if (paramIndex === 1) {
        return "My Parameter";
    }
};

This introduces a new UI element labeled as "My Parameter". Upon user modification of this element, the script's onParamChange function is triggered, receiving the updated value of the parameter.

onParamChange = function (paramIndex, newValue) {
    if (paramIndex === 1) {
        // the value of my parameter changed
    }
};

The remaining three functions are employed to enhance the user interface's representation of the normalized parameter value.

The paramValueToString function generates a string that is displayed in the user interface.

The stringToParamValue function converts any string that the user enters into the user interface to its normalized equivalent.

The getParamStepCount function is designed to retrieve the number of distinct intervals within a parameter's value range. For instance, if a parameter represents a sequence of five values, it has a step count of four distinct intervals between its minimum and maximum values.

If ModScripter is connected to a MIDI Input, the parameters can be controlled via MIDI Control Change Messages.

MIDI Note Input

Two functions, onNoteOnEvent and onNoteOffEvent, handle MIDI note input.

onNoteOnEvent = function (channel, pitch, velocity, tuning, noteID) {
}

onNoteOffEvent = function (channel, pitch, velocity, tuning, noteID) {
}

These functions are triggered either when a note is pressed or when it is released.

Please note that a connection to the MIDI Input port of ModScripter is required for this functionality to work.

Sidechain

ModScripter can receive an audio sidechain signal.

If such a signal is present, the script's processSidechain function is invoked, including the averages of the minimum and maximum audio sample values.

processSidechain = function (minSample, maxSample, absMinSample, absMaxSample, numSamples) {
}

Script functions

The following functions can be implemented by a script:

• processModulation [required]
• processSidechain [optional]
• onNoteOnEvent [optional]
• onNoteOffEvent [optional]
• onParamChange [optional]
• paramValueToString [optional]
• stringToParamValue [optional]
• getParamTitle [optional]
• getParamStepCount [optional]
• getDescription [optional]

Host functions

The following functions can be called from a script:

• getSampleRate
• getTempo
• getProjectTimeMusic
• getBarPositionMusic
• normalizedToPlain
• plainToNormalized
• normalizedToSteps
• stepsToNormalized
• log

Detailed script function documentation:

processModulation

function processModulation (inputValue, numSamples) -> {Number}

Arguments:

• inputValue
  • the value of the input parameter
• numSamples
  • number of samples to process

Returns:

• the modulation signal

This function is called from the host, to generate the modulation signal.

The implementation of this function is required.

processSidechain

function processSidechain (minSample, maxSample, absMinSample, absMaxSample, numSamples)

Arguments:

• minSample
  • the minimum sample value in the sidechain buffer [-1..1]
• maxSample
  • the maximum sample value in the sidechain buffer [-1..1]
• absMinSample
  • the absolute minimum sample value in the sidechain buffer [0..1]
• absMaxSample
  • the absolute maximum sample value in the sidechain buffer [0..1]
• numSamples
  • number of samples of the sidechain buffer

This function is called when the sidechain connection is established. The script can analyze the values and use this analysis in the processModulation function, to generate the modulation signal.

The implementation of this function is optional.

onNoteOnEvent

function onNoteOnEvent (channel, pitch, velocity, tuning, noteID)

Arguments:

• channel
  • the channel of the note event
• pitch
  • the pitch of the note event
• velocity
  • the velocity of the note event
• tuning
  • the tuning of the note event
• noteID
  • the noteID of the note event

This function is called when a note on event is received by the event input port of ModScripter.

The implementation of this function is optional.

onNoteOffEvent

function onNoteOffEvent (channel, pitch, velocity, tuning, noteID)

Arguments:

• channel
  • the channel of the note event
• pitch
  • the pitch of the note event
• velocity
  • the velocity of the note event
• tuning
  • the tuning of the note event
• noteID
  • the noteID of the note event

This function is called when a note off event is received by the event input port of ModScripter.

The implementation of this function is optional.

onParamChange

function onParamChange (paramIndex, newValue)

Arguments:

• paramIndex
  • the index of the parameter [1..8]
• newValue
  • the new normalized value of the parameter

This function is called whenever a parameter is modified, either by the user manually adjusting a knob in the user interface or by another modulation or automation source.

The implementation of this function is optional.

paramValueToString

function paramValueToString (paramIndex, paramValue) -> {String}

Arguments:

• paramIndex
  • the index of the parameter [1..8]
• paramValue
  • the normalized parameter value [0..1]

Returns:

• a string representing the parameter value

This function is called whenever the host needs to display the parameter value to the user. The script should return a user-friendly value representation of the parameter.

The implementation of this function is optional.

stringToParamValue

function stringToParamValue (paramIndex, string) -> {Number}

Arguments:

• paramIndex
  • the index of the parameter [1..8]
• string
  • the input string

Returns:

• a normalized value [0..1] from the input string

This function is called whenever the host needs to convert a user-edited string to the parameter value.

The implementation of this function is optional.

getParamTitle

function getParamTitle (paramIndex) -> {String}

Arguments:

• paramIndex
  • the index of the parameter [1..8]

Returns:

• the title of the parameter

This function is called whenever the host needs to display the name of the parameter to the user. When the script returns a name for a parameter, the corresponding user element is visible in the plug-in user interface.

The implementation of this function is optional.

getParamStepCount

function getParamStepCount (paramIndex) -> {Number}

Arguments:

• paramIndex
  • the index of the parameter [1..8]

Returns:

• the step count of the parameter

If a parameter has discrete steps, the script should return the number of steps here. The host may use a different user interface element that is easier to handle.

The implementation of this function is optional.

getDescription

function getDescription () -> {String}

Returns:

• a description of the script

The description of the script is shown in the main user interface.

The implementation of this function is optional.

Detailed host function documentation:

getSampleRate

function getSampleRate () -> {Number}

Returns:

• the current sample rate as a numeric value.

Note: Can be called at any time

getTempo

function getTempo () -> {Number}

Returns:

• the current tempo as a numeric value.

Note: Can only be called from inside the following functions: processModulation, processSidechain, onNoteOnEvent, onNoteOffEvent, onParamChange

getProjectTimeMusic

function getProjectTimeMusic () -> {Number}

Returns:

• the current musical position in quarter notes (1 equals 1 quarter note).

Note: Can only be called from inside the following functions: processModulation, processSidechain, onNoteOnEvent, onNoteOffEvent, onParamChange

getBarPositionMusic

function getBarPositionMusic () -> {Number}

Returns:

• the last bar start position, in quarter notes.

Note: Can only be called from inside the following functions: processModulation, processSidechain, onNoteOnEvent, onNoteOffEvent, onParamChange

normalizedToPlain

function normalizedToPlain (min, max, normValue) -> {Number}

Arguments:

• min
  • the minimum plain value
• max
  • the maximum plain value
• normValue
  • the normalized value to convert to a plain value

Returns:

• a plain value from a normalized value [0..1] mapped to the range [min..max].

plainToNormalized

function plainToNormalized (min, max, plainValue) -> {Number}

Arguments:

• min
  • the minimum plain value
• max
  • the maximum plain value
• plainValue
  • the plain value to convert to a normalized value

Returns:

• a normalized value [0..1] for the plain value within the range [min..max].

normalizedToSteps

function normalizedToSteps (normValue, numSteps, stepStart) -> {Number}

Arguments:

• normValue
  • the normalized value to convert to a step value
• numSteps
  • the number of steps
• stepStart
  • the start step value

Returns:

• the discrete step for the normalized value [0..1] normValue within the range [stepStart..stepStart+numSteps].

stepsToNormalized

function stepsToNormalized (stepValue, numSteps, stepStart) -> {Number}

Arguments:

• plainValue
  • the step value to convert to a normalized value
• numSteps
  • the number of steps
• stepStart
  • the start step value

Returns:

• the normalized value [0..1] for the plain value within the range [stepStart..stepStart+numSteps].

log

function log (...)

Write something into the logging console.

MIDI Mapping

The input and the eight custom parameters can be controlled via MIDI Control Change Messages.

The following table shows the mapping: