Event Manipulation

This page provides an overview of the methods available to manipulate MIDI events inside event processor modules. These can be used to integrate the script with plugins or FL Studio windows, as well as add note input modes.

-> Getting information about an event

-> Acting on events

-> Editing events

Object: ParsedEvent

This object represents a MIDI event as well as information about how it has been handled by the script. It is passed to process() functions inside event processor modules.

Getting information about an event

Don't edit these variables (or you'll break stuff).

ParsedEvent.type: The type of event (eg a drum pad, a fader, or some other type)

The types of events can be found in the module eventconsts as constants where the name begins with TYPE_

Example usage:

if command.type == eventconsts.TYPE_FADER_BUTTON:
    # The event is a fader button.
    pass

if command.type == eventconsts.TYPE_NOTE:
    # The event is a note.
    pass

ParsedEvent.id: The unique identifier of a particular event (eg the play button, the 3rd knob, or some other event)

The ids of events can be found in the module eventconsts. For the sake of simplicity, it is recommended to use other information to identify most events when possible.

Example usage:

if command.id == eventconsts.TRANSPORT_STOP:
    # The event is the stop button.
    pass

if command.id == eventconsts.PEDAL:
    # The event is a pedal event.
    pass

ParsedEvent.coord_X: The x coordinate of an event. Can be used for faders, fader buttons, knobs and drum pads.

Returns an integer index starting at zero.

if command.type == eventconsts.TYPE_FADER and command.coord_X == 0:
    # The event is the 1st fader.
    pass

if command.type == eventconsts.TYPE_PAD and command.coord_X == 8:
    # The event is a circular drum pad.
    pass

ParsedEvent.coord_Y: The y coordinate of an event. Can be used for drum pads.

Returns an integer index starting at zero.

if command.type == eventconsts.TYPE_PAD and command.coord_Y == 1:
    # The event is a bottom row drum pad.
    pass

if command.type == eventconsts.TYPE_PAD:
    if (command.coord_X, command.coord_Y) == (8, 0):
        # The event is the top circular drum pad.
        pass

ParsedEvent.status: The status byte of an event.

ParsedEvent.status_nibble: The first 4 bits of the status byte - indicates the type of MIDI event.

ParsedEvent.channel: The channel number of an event

Note that channels E (14) and F (15) are reserved for Omni Mode and internal events. Ranges from 0-15.

ParsedEvent.note: The note/control number of an event.

Ranges from 0-127.

ParsedEvent.value: The velocity/value of an event.

Ranges from 0 to 127.

ParsedEvent.is_lift: Returns true if a control is being lifted and false if it is being pressed.

Intended for use with buttons and drum pads.

ParsedEvent.getDataMIDI(): Returns the MIDI event as a single integer.

This integer fits the MIDI specification and can be dispatched as an event if required.

Acting on events

The following functions should be called when taking actions on events.

ParsedEvent.addProcessor(): Adds an event processor to the list of actions.

This should be done at the start of any process() functions in a script to help with debugging.

Arguments:

• name (string): The name of the new event processor.

ParsedEvent.handle(): Handle an event to prevent further processing in the script, and in FL Studio.

Arguments:

• action (string): The action taken.
• silent (bool): Whether the action should be set as a hint message. Defaults to False.

Example usage:

command.handle("Toggled keyswitch")

# This won't be shown as a hint message
command.handle("Enable secret function :)", True)

ParsedEvent.ignore(): Prevent further processing in the script, but allow the event to be handled in FL Studio.

Arguments and usage: same as ParsedEvent.handle()

ParsedEvent.act(): Add an action to the event, but allow further processing.

Arguments and usage: same as ParsedEvent.handle(), except silent defaults to True.

Editing events

Class: RawEvent

This class is used to create raw events from MIDI data. It is found in the module processorhelpers.

Constructor arguments:

• status: The status byte
• data1: The first data byte
• data2: the second data byte

ParsedEvent.edit(): Edits an event.

Arguments:

• event (RawEvent): Event to change to. Use RawEvent class.
• reason (string): Reason for the edit. This is logged as an action automatically.

Examples

# From pluginprocessors > fpc.py (at v2.0.0)
# Change pedals to kick
if command.id == eventconsts.PEDAL:
    command.edit(processorhelpers.RawEvent(0x89, eventconsts.BasicPads[1][1], command.value), "Remap pedal")

# From noteprocessors > omni.py (at v2.0.0)
# Changes note channels in order to make them trigger omni previews.
if command.type is eventconsts.TYPE_NOTE:
    # Set status byte to channel 15 (Omni preview channel)
    new_status = (command.status_nibble << 4) + internal.consts.OMNI_CHANNEL_STATUS
    command.edit(processorhelpers.RawEvent(new_status, command.note, command.value), "Remap for omni mode")