Writing Plugin Handlers

When writing a plugin processor, there are some required variables and functions that need to be included in order for the processor to able to function.

You can copy pluginprocessors > _template.py for a template for plugin processors.

Script requirements

PLUGINS

This is the list of plugins that the processor can handle. For example, if my processor could handle events for the plugin Soundgoodizer, I would write PLUGINS = ["Soundgoodizer"]. You can include as many plugins as you like in this list.

Getting the active plugin name

If you need to determine between different plugins, you can use internal.window.active_plugin. For example:

if internal.window.active_plugin == "Soundgoodizer":
    # Do soundgoodizer stuff
    pass
elif internal.window.active_plugin == "Sausage Fattener":
    # Do sausage fattener stuff
    pass

process()

This function processes events when a plugin in the PLUGINS list is active. It receives a ParsedEvent as a parameter. You should do all of your processing of events in this function, or in subfunctions called by it.

redraw()

This function is called to redraw lights when a plugin in the PLUGINS list is active. It receives a LightMap as a parameter. You should do all your redrawing in this function, or in subfunctions called by it.

topPluginStart()

This function is called when a plugin in the PLUGINS list becomes the top-most plugin. Use it to set things such as extended modes, or to set internal variables used by your script.

topPluginEnd()

This function is called when a plugin in the PLUGINS list stops being the top-most plugin. Use it to do things such as revert extended modes, or to reset internal variables used by your script.

activeStart()

This function is called when a plugin in the PLUGINS list becomes the top-most window (including FL Studio windows). This implies (but doesn't guarantee) that the plugin's configuration window is open.

activeEnd()

This function is called when a plugin in the PLUGINS list stops being the top-most window (including FL Studio windows).

Interacting with plugins

In order to read and modify parameters in plugins, the pluginswrapper module should be imported. Note that although the same functionality can be achieved using the built-in `plugins module, the wrapper provides additional feature to ease development.

getParamIndexByName()

Returns the index of a parameter in a plugin given the name of the parameter.

Arguments:

• name (str): Name of the parameter to find.

• plugin_index (optional)

  • (int): Plugin index to search. Use -1 for currently-selected plugin's index.
  • (tuple: 2 ints): Respectively, mixer track and plugin index to search.

• expected_param_index (optional, int): index where the parameter is expected to be. It is searched first to increase efficiency

Returns:

• int: Index of parameter. -1 if not found.

setParamByName()

Sets a parameter in a plugin given the name of the parameter.

Arguments:

• name (str): Name of the parameter to find.

• value:

  • (float): Value to set the parameter to.
  • (int): MIDI value (0-127) to set the parameter to (will be converted to a float between 0 and 1).

• plugin_index (optional)

  • (int): Plugin index to search. Use -1 for currently-selected plugin's index.
  • (tuple: 2 ints): Respectively, mixer track and plugin index to search.

• expected_param_index (optional, int): index where the parameter is expected to be. It is searched first to increase efficiency

• command (ParsedEvent, optional): Command to add handling message to

Returns:

• int: parameter index changed

setParamByIndex()

Sets a parameter in a plugin given the name of the parameter.

Arguments:

• param_index (int): index where the parameter is.

• value:

  • (float): Value to set the parameter to.
  • (int): MIDI value to set the parameter to (will be converted to a float between 0 and 1).

• plugin_index (optional)

  • (int): Plugin index to search. Use -1 for currently-selected plugin's index.
  • (tuple: 2 ints): Respectively, mixer track and plugin index to search.

• command (ParsedEvent, optional): Command to add handling message to

setCCParam()

Sends a MIDI CC event to the specified plugin.

Arguments:

• ccNum (int): CC Number to set.

• value:

  • (float): Value to set the parameter to.
  • (int): MIDI value to set the parameter to (will be converted to a float between 0 and 1).

• plugin_index (optional)

  • (int): Plugin index to search. Use -1 for currently-selected plugin's index.
  • (tuple: 2 ints): Respectively, mixer track and plugin index to search.

• command (ParsedEvent, optional): Command to add handling message to

getParamByName()

Gets a parameter value in a plugin given the name of the parameter.

Arguments:

• name (str): Name of the parameter to find.

• plugin_index (optional)

  • (int): Plugin index to search. Use -1 for currently-selected plugin's index.
  • (tuple: 2 ints): Respectively, mixer track and plugin index to search.

• expected_param_index (optional, int): index where the parameter is expected to be. It is searched first to increase efficiency

Returns:

• int: parameter value

getParamByIndex()

Gets a parameter value in a plugin given the index of the parameter.

Arguments:

• param_index (int): index of the parameter.
• plugin_index (optional)
  • (int): Plugin index to search. Use -1 for currently-selected plugin's index.
  • (tuple: 2 ints): Respectively, mixer track and plugin index to search.

Returns:

• int: parameter value

getCCParam()

Gets a current MIDI CC value of a plugin.

Args:

• ccNum (int): MIDI CC number

• plugin_index (optional)

  • (int): Plugin index to search. Use -1 for currently-selected plugin's index.
  • (tuple: 2 ints): Respectively, mixer track and plugin index to search.

Returns:

• int: parameter value

Adding your processor to the script

To add your plugin processor to the script, open pluginprocessors > processplugins.py and add the name of your file (without the .py) to the imports list. Make sure the file is located within the pluginprocessors directory.