Triggers are ways to set up a script to be executed. In CoyoteMIDI there are currently 4 ways to trigger a script. translation executions, script events, script commands, and the “run” button in the script editor.
The “run” button
When you open a script in the built in script editor in CoyoteMIDI, you will be able to trigger the script to run by clicking the “run” option in the menu bar at the top of the window. Here you can run the script without any context by selecting “run”, or run it with a random note on, note off, or controlchange as context with the “run with…” options. The run options on the script editor page are only intended to be used for development.
Translations
Translations can be set up to execute a script every time a translation is triggered. In the advanced options of a translation, the action can be set to “Script”, which will reveal a “Script” text input field in which you can specify the name of the script as loaded by the scripting system. Both local scripts and scripts obtained from the Script Hub will be shown here, where scripts from the Script Hub won’t have the “.cy” file extension in the name. A dropdown menu can be opened to quickly scroll through all loaded scripts, and the browse button can be clicked to open the Script Hub to select a script directly from there.
A script that is triggered by a translation will have a built in script variable that provides context about the translation that triggered it. This variable comes in the form of a map object named $trigger with the following items inside of it: inputtype, keyaction, keys, midievent, note, velocity, controlnumber, controlvalue, pitchbend, program, and device. For more information on map operations check out this page. the values inside this map can be read individually like so:
- ($trigger inputtype) – The type of input for this translation. This could be either KEY or MIDI.
- ($trigger translationid) – The ID of this translation. This should remain consistent across app restarts, though when a translation gets deleted, a new translation might use the same ID.
- ($trigger keyaction) – the key action that triggered the translation. This can be either DOWN or UP.
- ($trigger keys) – The list of keys that had to be pressed to trigger the translation.
- ($trigger midievent) – The MIDI event type that triggered the translation, such as “NOTE” or “CONTROLCHANGE”.
- ($trigger note) – The note number of the MIDI event, in the case it was a NOTE event.
- ($trigger velocity) – The note velocity value of the MIDI event, in the case it was a NOTE event.
- ($trigger controlnumber) – The control change number, in case of a CONTROLCHANGE event.
- ($trigger controlvalue) – The control change value, in case of a CONTROLCHANGE event.
- ($trigger pitchbend) – The pitchbend value, if the MIDI event is a PITCHBEND event.
- ($trigger program) – The program value, if the MIDI event is a PROGRAMCHANGE event.
- ($trigger device) – The name of the MIDI device that triggered the translation.
- ($trigger channel) – The MIDI channel number of the MIDI event.
- ($trigger rawnumber) – The MIDI number of the MIDI event, dependent on the type of MIDI event it is. For notes, this will be the note number, for control change, this will be the control change number.
- ($trigger rawvalue) – The MIDI value of the MIDI event, dependent on the type of MIDI event it is. For notes, this will be the note velocity, for control change, this will be the control change value.
Events
It is possible to list events directly inside a script file. This will cause the following block of script to be executed whenever the event is triggered. In its most basic form, events can be listed in scripts in the syntax form of “event [<event name>]”.
Scripts executed by an event will include contextual information in a map object variable named $trigger, much like with translation triggers. Due to the varied nature of events, each event may have different variables inside the map.
Some of the events allow you to change the outcome of the event through the return command. With this command you can return a variable back to the internal event handler for it to use to modify the outcome of the event.
More information on script events can be found here.
RunScript command
Scripts can also be triggered to run with the RunScript command. This can be used for better organization and to create more dynamic scripts. Variables can be passed to the script that is being ran.