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” button in the top right. This will cause the script to run without any context information.
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 file path of your script, starting at the CoyoteMIDI scripts folder. For example, if your script’s file path is “C:\Documents\CoyoteMIDI\scripts\MyScript.cy” the required input for the Script field would be “MyScript.cy”.
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: type, 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 type) – 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 theMIDI event.
Events
It is possible to list events directly inside a script file 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. More information on the RunScript command here.