Writing Note Handlers

When writing a note 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 noteprocessors > _template.py for a template for note processors.

Script requirements

NAME

The name of your note mode

DEFAULT_COLOUR

The colour used to represent your mode when in the selection menu

COLOUR

The colour used to represent your mode when it is active. You can update this while the processor is active

INIT_COMPLETE

Signifies whether the processor has completed its initialisation. Change this to True when the processor has all the required information to process notes. If your processor doesn't require initialisation, change it to True in its definition.

SILENT

Signifies whether the note mode should be unlisted in the note mode menu. It cannot be edited while the script is running.

FORWARD_NOTES

Signifies whether notes should be forwarded to the extended mode script to allow both scripts to receive the same notes. It is recommended to enable this during the setup of the input mode but to disable it when setup is complete to prevent doubled-up notes.

process()

This function processes events when the note mode 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. It may also be useful to create a function to process events specifically when the initialisation is incomplete.

# If the note processor isn't initialised, call the initialise function instead
if not INIT_COMPLETE:
    processInit(command)
    return

redraw()

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

activeStart()

This function is called when the note mode is set as active. Use it to perform any immediate set-up and to initialise internal variables if required.

activeEnd()

This function is called when the note mode is made inactive. Use it to reset any internal variables, or perform functions like setting extended modes.

Mapping to multiple notes

In order to map a single note to multiple notes, you can use the object internal.notesDown. This is particularly useful for chords.

noteOn()

This function is used to add a set of notes. It takes an ExtensibleNote object as an argument. Note that the root note of an ExtensibleNote object is not pressed, and thus should not be handled by the script (unless it is also included as an extended note).

noteOff()

This function is used to lift up any keys associated with a particular root note. It takes a RawEvent as an argument.

allNotesOff()

This function releases all keys that have been pressed by the script.

Adding your processor to the script

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