Phrase Trigger Expressions

This is run when the Show file is opened, either because you explicitly opened it using the Triggers window File menu, or because Beat Link Trigger automatically reopened it at launch because you had it open the last time you used the program. You can use it to open network connections or set up other values for this phrase trigger and its cue expressions to use.

The basic concept of an Enabled Filter is described in the introduction to the Expressions section; phrase triggers use them in a similar way. If the phrase trigger’s Enabled menu is set to Custom, it will run its Enabled Filter Expression to decide what to do. If your expression returns a true value, this phrase trigger will be enabled as a candidate to activate during the current phrase; otherwise it will be disabled and not considered.

In cases where you want to enable the phrase trigger you can also determine the weight that should be used if it is a Solo phrase trigger in competition with other Solo phrase triggers to start playing (phrase triggers which are marked to Blend always activate when they are enabled, so weights do not matter for them). To do this, instead of simply returning true, return a number from 1 to 1000. The higher the number, the greater the chance that this phrase trigger will be chosen. (You can think of the weight value as the number of raffle tickets that the phrase trigger has purchased.) Returning true is equivalent to returning 1.

Disabled phrase triggers do not activate, and all of their configured cues are disabled.

In your Enabled Filter expression, if you want to build logic on top of the kind of decisions that the phrase trigger UI offers, there are some convenience variables made available to you (in phrase trigger expressions other than the Setup, Stopped and Shutdown) which describe the phrase that is currently playing:

This is called when the phrase trigger activates because it was enabled and chosen for a phrase that is playing. (The same phrase trigger might be activated for phrases that are playing on multiple players at the same time; this expression is called only when the first phrase activates it. The phrase trigger will continue to be considered playing until the final phrase it is activated for ends or stops playing or stops matching the Enabled Filter expression.)

The convenience variables listed above are available here as well.

As an example, here is a Playing Expression that would do the exact same thing as setting the phrase trigger’s Playing Message menu to Note:

The (when midi-output …) clause that wraps the midi-note-on call just protects against the situation where the chosen output can’t be found because it isn’t plugged in at the moment. Without this, the attempt to send the note will throw an exception that gets written at length to the log file. In the context of this Expression, the midi-output variable is set to the MIDI output device chosen for the phrase trigger, and will be nil if that device is not currently connected.

This uses the embedded MIDI library to send a Note On message to the phrase trigger’s chosen output device. The variable playing-note is set to the note number chosen for the phrase trigger’s Playing Message, 127 is the maximum MIDI note velocity, and playing-channel is set to the channel chosen for the phrase trigger, but since the user interface displays MIDI channel numbers in the traditional user-centric range from 1 to 16, and the actual protocol requires them to be sent in the 4-bit range 0-15, we need to subtract 1 from the variable value before sending it, which is what the dec (decrement) function does.

You can tweak this to send different notes (by substituting your own value or variable for playing-note) at different velocities (by replacing the 127) on different channels, or of course do something else completely. The Stopped discussion below shows what you would need to set up to emulate the other half of the Note mode using your own expressions.

Called whenever a beat packet is received from a player that is playing a phrase that activated this phrase trigger.

The convenience variables listed above are available here as well.

Called whenever a status update packet is received from a player that is playing a phrase that activated this phrase trigger, after the Enabled Filter Expression, if any, has had a chance to decide that the phrase trigger is enabled, and after the Playing expression, if appropriate.

The convenience variables listed above are available here as well.

This is called when the last player that had been playing a phrase that activated the phrase trigger stops, or moves past the phrase. (A phrase which activated this phrase trigger might be playing on multiple players at the same time; this expression is called only when the final player stops playing one, so it is no longer playing on any player.)

A phrase trigger will also report stopping if it becomes disabled while it was playing.

To complete the example introduced in the Playing Expression above, here is an expression that sends the same MIDI event when a phrase trigger stops that you get by setting the Playing Message menu to Note:

As described in the initial example above, this checks to be sure the MIDI output device that has been selected for the phrase trigger is currently connected before sending it a Note Off message for the configured note and channel. Again, you can tweak this to send different messages. For example, you might actually want to send a different Note On message when the phrase trigger stops playing; for that, you would use the same code shown in the Playing Expression section.

This is run when the Show file is closed, either because you closed the window, or because Beat Link Trigger is shutting down. You can use it to close any network connections or clean up any other resources your Setup Expression allocated.