Trigger Expressions

This is like the Global Setup Expression described above, but it is used to set up the locals atom, which is shared only with other expressions on the same trigger. It is called when the trigger is loaded, and when Beat Link Trigger starts up, after the Global Setup Expression.

To illustrate how different expressions in a trigger can work together using locals, suppose you have a single trigger that wants to send pitch information to Resolume Arena so that a clip you are triggering runs at the same speed as the track playing on the CDJ. Beat Link Trigger embeds Project Overtone’s osc-clj library and aliases it to osc within the context of expressions to make it easy to send Open Sound Control messages. Assuming your copy of Arena is running on the same machine, and listening for OSC messages on port 9801, here is how you could set things up so your other expressions on this trigger can communicate with it:

This uses swap! to modify the map in locals by using assoc to add the key :resolume, which will hold an OSC client that can be used to send Open Sound Control messages to Arena on the local machine. See the Enabled Filter Expression below for how we use it. And keep this setup in mind, because it will be built on throughout the rest of this section.

This is used to release any system resources (open connections or files) that were allocated by the Setup Expression. It is called when the trigger is deleted, and when Beat Link Trigger is exiting, before the Global Shutdown Expression.

Continuing our example, here is how we would clean up the OSC client we created to talk to Resolume when the trigger is going away:

As described in the introduction to this section, this is used when you set a trigger’s Enabled menu to Custom. It is called whenever a status update packet is received from a watched player, and tells Beat Link Trigger if the trigger should be enabled or not. Often you will want a trigger to be enabled when a DJ has loaded a particular track, and a variety of strategies for achieving that are described in their own section, see that for lots of great ideas. Following some of its suggestions, our Resolume example could enable its trigger with a custom Enabled Filter along the lines of:

This is similar to the Enabled Filter Expression, but even when a trigger is configured to potentially watch multiple players, it is called only for the player that is currently being tracked, which will be the one that is considered “best” as described in the Watch Menu section above. Players which enable the trigger are better than ones that don’t; within that group, it is better to be playing, and as a tie-breaker the lowest numbered player is chosen.

As a simple standalone example, Netsky wanted to send a MIDI note to his lighting software whenever a different deck became tempo master, to switch to a different look for each new track in his mix. We accomplished that by setting up a trigger to watch the Master Player, with the following Tracked Update Expression:

Although it might seem strange, you want to leave this trigger’s Enabled setting at Never, because you don’t want it sending MIDI when a track starts or stops playing. That way, the only messages that get sent are the ones from the above expression, and so whenever a new deck becomes tempo master, the chosen message will be sent.

Continuing our more complex multi-expression Resolume example, we can also use a Tracked Update Expression to update the playback speed within Arena to stay synced with the current tempo of the CDJ. We want to send messages to Resolume only when the trigger is active—​which means it is enabled and the player it is watching is currently playing—​so we wrap our expression in a when clause like this:

There is one more improvement we can make, though. Our code as it stands sends an OSC message to Resolume for every status packet from the watched player, even when the pitch is not changing. That’s inefficient; it puts needless traffic on the network, and makes Resolume waste time processing messages that don’t change anything. By adding a little more sophistication to our Tracked Update Expression, we can keep track of the last value we sent to Resolume, and only send a new one when it is different. We will use a local named :resolume-pitch to keep track of the last value we sent:

If you want to watch this happening, you can add a log statement that will report the new pitch value each time it is sent, like this:

With this expression in place, when the trigger is active and you fiddle with the Pitch fader on the CDJ that is playing the track, you will see entries like this in the log file:

This is called when the trigger trips (in other words, when it would send a MIDI message reporting that its watched player has started to play). You can send additional MIDI messages here, or use the Clojure and Java networking infrastructure to send a different kind of message entirely. If this is all you want the trigger to do, you can set its Message menu to Custom, to suppress the default MIDI messages that it would otherwise send.

Continuing our Resolume example, here is an Activation expression that would use OSC to trigger the clip that our Tracked Update expression was adjusting the pitch for:

You can also use the Activation expression to send MIDI messages that differ from the ones available through the graphical interface. Beat Link Trigger embeds Project Overtone’s midi-clj library and aliases it to midi within the context of expressions to make it easy to send MIDI messages. The trigger’s chosen MIDI output is available as trigger-output (but may be nil if the device is currently not available). So as an example of how you could send a Note On message with velocity 42 on the note and channel chosen in the trigger window:

Note that the user-oriented channel number displayed in the Trigger’s Channel menu is actually one larger than the value you actually need to send in the MIDI protocol (Channel 1 is represented in protocol by the number 0, and Channel 16 by the number 15, so that the channel can fit into four bits). So you need to decrement the value of trigger-channel before passing it to the midi library, as shown above.

This is called when the player that the trigger is watching stops playing, or when the trigger becomes disabled if it had been active. (This is when a Note Off message, or Control Change with value zero, is sent.) You can send your own custom messages here, much like the Activation Expression.

This is called when the player currently being tracked reports the start of a new beat. Continuing the example started in the Global Setup Expression, here is how you could synchronize the BPM of your ChamSys MagicQ console to the beats coming from your CDJs. Set the trigger to watch the Master Player, and enter the following code in the Beat Expression editor:

Alternately, if you want to send a MIDI message whenever the master player plays a down beat (the first beat of a bar), you could use this Beat Expression:

This a bit more code than you might expect, but it allows the user to configure whether to send a Note or CC message, as well as the note/controller number and MIDI channel to send it on, using the normal Trigger window user interface elements. Depending on the settings, it sends the corresponding Note On message with a velocity of 127, followed immediately by a Note Off message, or it sends A CC with value 127 followed by another with value 0.

Although it might seem strange, you want to leave this trigger’s Enabled setting at Never, because you don’t want it sending MIDI when a track starts or stops playing. That way, the only messages that get sent are the ones from the above expression, which is whenever the master player plays the first beat of a measure.