Expressions

Beat Link Trigger tries to protect against many kinds of things that can go wrong in your expressions. If one throws an exception, it will be logged so you can view it in the log file, and that instance of calling your expression will be abruptly cancelled, but the next expression or activity will get a chance to run.

The real problem is when your code does something that takes a long time, or even worse, gets stuck in an infinite loop. If that happens, nothing else that is supposed to respond to the event that caused your expression to run will get a chance to, and events can pile up behind your stuck expression, freezing user interface updates, and blocking the MIDI or other messages you are supposed to be sending. So watch for that, and remember which expressions you have changed recently if things go badly wrong.

If you legitimately need to do something in an expression that could take a long time, such as an HTTP request, or any other sort of round-trip network communication, you need to make it asynchronous by wrapping the potentially-slow operation in a Clojure (future …) block. This will run in a separate thread, so it will not slow down the expression, or the delivery of events to other triggers, shows, cues, or the user interface.

The tricky part about using future to run your code asynchronously is when you need to do something with whatever answer you got back from your long-running operation. You can’t just return it, like you would in a simple, direct expression, because the expression has already moved on, it did not wait for the answer. The easiest solution is to have your asynchronous code inside the future block record the answer into an expression local or global, and then other expressions (or even future invocations of this expression) can check the local or global to see if the answer is ready, and use it when it is. That is a quick operation. So as long as your code works (even if it doesn’t yet do anything) while the answer is still missing, it can use it without blocking other activity as soon as it becomes available in the expression local or global.

Also, note that it is only sending two-way network communications that you need to worry about. Sending MIDI messages and short one-way UDP messages (like OSC and some lighting controllers use) should be no problem without resorting to asynchronous code, and you will find examples of doing just that throughout this guide.

The expression you are first likely to want to use is the Enabled Filter, which is found in each trigger’s context menu. In fact, as soon as you set a trigger’s Enabled menu to Custom, Beat Link Trigger will pop open the editor for that expression for you, if you have not yet created it:

The editor window for each type of expression provides documentation about the purpose of the expression and guidance on how to write it. Most expression types have a variety of values that are available to help you in writing the expression, and those are described and explained in the help section as well.

Reading through the documentation, we see that the Enabled filter should return a true value to enable the filter, and has access to a lot of information about the watched player that it can use to decide. Suppose we want the trigger to be enabled when the player has track number 5 of a playlist or disc loaded, and has reached the fourth bar of music (which starts on beat 17, since there are four beats per bar, and the track starts with beat 1). With the help of Learn Clojure and the help text in the editor window, we come up with the following expression:

Try entering that as the Enabled Filter expression for your filter, set the Enabled menu to Custom, and watch the Trigger Status indicator as you load and play different tracks to confirm that it works!

This is run when Beat Link Trigger starts up, or when you open a new Trigger file, so it runs before any of your individual trigger expressions. As a simple example of what you might want to do, here is an expression opens the Player Status window:

Setting this as your Global Setup Expression will automatically open the Player Status window whenever Beat Link Trigger launches. (This also makes sure subsystems like the TimeFinder are running, which can be helpful if you are writing other expressions that depend on knowing the playback position of tracks.)

If you ever start up BLT in offline mode with this Global Setup Expression in place, however, you will be presented with an error dialog, complaining “Must be Online to show Player Status window.” To avoid being inconvenienced by that, we can make the expression smarter, so it only tries to open Player Status when already Online:

But there is an even better way to do this, now that version 0.5.4 has added the Came Online Expression which runs once Beat Link Trigger has successfully connected to a DJ Link network. Using that expression to show the Player Status window means it will always be safe to try, and — even better — the window will be reopened every time you go back online, not just when initially starting the program.

Here is an even more sophisticated example that creates a DatagramSocket for sending a remote trigger command to the ChamSys MagicQ lighting control software using its remote protocol:

This begins with a let binding which sets up some values that will be used later in the expression.

The Beat Expression below shows how these globals are actually used.

This is run whenever Beat Link Trigger has successfully connected to a DJ Link network, either at initial startup or when you have told it manually to go online. At initial startup, or whenever you open a new Triggers file, it will run after the Global Setup expression as long as you are online. It runs by itself when you choose Network  Online? to successfully transition from an offline to an online state.

You have access to the expression globals if you need to use anything in them.

This is the perfect place to take actions that can only succeed when Beat Link Trigger is online, such as opening the Player Status window. The simplest approach described above is safe to use in this expression, unlike in the Global Setup expression:

With this in place, every time you successfully go online, either at startup or using Network  Online?, the Player Status window will open for you.

Another example came up in the community chat room, from a user who wanted to set up a turn-key lighting system that automatically started Beat Link Trigger and Carabiner. If you are in a situation like that, and can be sure that Carabiner has already been started by the time Beat Link Triger launches, you can set up a Came Online Expression to automatically open the Carabiner window and connect to it:

This is run whenever Beat Link Trigger is online and you manually take it offline by choosing Network  Online?, exit the program, open a new Trigger file, or choose to delete all triggers. In any of the situations where you are doing more than just going offline, it runs right before the Global Shutdown expression. It gives you a chance to gracefully close any connections and release any system resources you allocated in your Came Online Expression.

You have access to the expression globals if you need to use anything in them.

This is run when Beat Link Trigger is exiting, or before it opens a new Trigger file (or when you choose to delete all triggers). It gives you a chance to close any connections and release any system resources that you allocated in your Global Setup Expression. Here is how we would do that for the ChamSys MagicQ example we started above:

This simply looks up the DatagramSocket that was created in the setup expression, and closes it. There is no need to remove the key/value pairs themselves from the globals atom because Beat Link Trigger will reset it to hold an empty map once the shutdown expression finishes.

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 5 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 5 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 5 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 below, 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.

Continuing our example, we can use a Tracked Update Expression to update the playback speed within Arena 5 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 any of the watched players 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 Any Player, and then within the Beat expression, we will react only to beat packets from the mixer, since it will always track the master player.

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 your Track and Cue expressions to use.

The basic concept of an Enabled Filter is described in the introduction to this section; shows use them in a similar way. Each Track that you are watching in the Show can be enabled separately. If the track’s Enabled menu is set to Default, that track will look to the show itself to decide whether it should be enabled. There is an Enabled Default menu at the top of the Show window that is used by all tracks whose Enabled mode is Default. If the Show’s Enabled Default is set to Custom, it will run your Default Enabled Filter Expression to decide what to do. If your expression returns a true value, all these tracks will be enabled; otherwise they will be disabled.

Disabled Tracks do not respond to being played, and all of their configured cues are disabled.

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 Global Setup Expression allocated.

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 Track and its Cue expressions to use.

The basic concept of an Enabled Filter is described in the introduction to this section; tracks use them in a similar way. If the track’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 tracks will be enabled; otherwise it will be disabled.

Disabled Tracks do not respond to being played, and all of their configured cues are disabled.

Note that you can also set the Enabled menu to Default in order to run the Show-level Default Enabled Filter as described above.

This is called when the track is first loaded into any player. (The same track might be loaded into multiple players at the same time; this expression is called only when the first player loads it. The track will continue to be considered loaded until the final player unloads it.)

This expression is only called when the track is enabled (disabled tracks are not considered loaded).

This is called when some player begins to play the track. (The same track might be playing on multiple players at the same time; this expression is called only when the first player starts playing it. The track will continue to be considered playing until the final player stops playing it.)

This expression is only called when the track is enabled (disabled tracks are not considered to be playing).

As an example, here is a Playing Expression that would do the exact same thing as setting the 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 Track, 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 Track’s chosen output device. The variable playing-note is set to the note number chosen for the Track’s Playing Message, 127 is the maximum MIDI note velocity, and playing-channel is set to the channel chosen for the Track, 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 Track 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 this track, as long as the track is enabled.

Called whenever a status update packet is received from a player that has this track loaded, after the Enabled Filter Expression, if any, has had a chance to decide if the track is enabled, and after the Loaded, Playing, Stopped, or Unloaded expression, if appropriate.

If the track is not enabled, this expression is not called.

This is called when the last player that had been playing the track stops. (The same track might be playing on multiple players at the same time; this expression is called only when the final player stops playing it, so it is no longer playing on any player.)

A track 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 track 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 track 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 track stops playing; for that, you would use the same code shown in the Playing Expression section.

This is called when the track is unloaded from the last player that had loaded it. (The same track might be loaded into multiple players at the same time; this expression is called only when the final player unloads it, so it is no longer loaded in any player.)

A track will also report unloading if it becomes disabled while it was loaded.

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.

Called when the cue’s track is enabled, and the first player moves inside the cue (in other words, the playback position of at least one player that has the cue’s track loaded is within the beat range that defines the cue).

There can be multiple players inside the cue at any given moment, but this expression will be called only when the first one enters it.

If the track is disabled, no players will be considered to be inside any of its cues.

Called when the first player that is playing the track moves into the cue, as long as it does so right at the beginning of the cue, and hits the start of the first beat that defines the cue.

There can be multiple players playing the cue at any given moment, but this expression will be called only when the first one enters it.

If the track is disabled, no players will be considered to be playing any of its cues.

Called when the first player that is playing the track moves into the cue, but misses the beginning of the cue, either because the DJ jumped into the middle of the cue, or because the player was paused somewhere in the middle of cue and then started playing, or because the Track was disabled when the cue was entered from the beginning and became enabled somewhere in the middle of the cue.

There can be multiple players playing the cue at any given moment, but this expression will be called only when the first one enters it.

If the track is disabled, no players will be considered to be playing any of its cues.

Called whenever a beat packet is received from a player that is playing inside this cue, as long as the track is enabled. (This is not called for the first beat of the cue; when that is played, the Started on-Beat expression is called instead.)

Called whenever a status update packet is received from a player whose playback position is inside this cue (as long as the track is enabled), after the Entered or Started expression, if appropriate.

Called when the last player that was playing the cue either leaves it or stops playing. There can be multiple players playing the cue at any given moment, and this expression will be called as soon as there are none left.

If the track becomes disabled while it was playing this cue, this expression will be called at that point as well.

Called when the last player that was inside the cue leaves it. There can be multiple players positioned in the cue at any given moment, and this expression will be called as soon as there are none left.

If the track becomes disabled while there were players positioned inside this cue, this expression will be called at that point as well.

Remote Tea, used for communicating with the NFSv2 servers on players, is licensed under the GNU Library General Public License, version 2.

The Kaitai Struct Java runtime, used for parsing rekordbox exports and media analysis files, is licensed under the MIT License.