Matching Tracks Without Metadata Requests

Even with a small number of tracks, there is a drawback to the expressions we are using: If you set them up in advance, and then during the performance, the DJ needs to put the media into a different player, you will need to go into each trigger’s Enabled Filter separately and correct the player that it is looking for. This is tedious and error-prone, and with more than a few triggers, frankly unmanageable. But there is a better way.

We can use the Global Setup expression to set up global configuration information about the media library or libraries our DJs are using. For example, If you have USB sticks named “Show 1” and “extra”, with different tracks on each, you can configure them like this:

This sets up a map in the expression globals that can track the player and slot into which these track collections have been inserted for a given show. To actually assign them, choose Triggers  Set Media Locations in the Triggers window menu:

Each player found on the network will have a row in this window, and using the menus you can assign any of the media libraries you configured with add-media to either of its slots, or you can indicate that a slot contains no known media.

If you used Triggers  Inspect Expression Globals after making these choices, you’d see that a :media-locations entry has been added to the expression globals, containing a map reflecting your choices like this:

With the media map properly configured for the current show, it can be used in each Enabled Filter expression, like this (but don’t panic if this expression looks complicated; it is just to explain the low-level workings, the idea is so useful that Beat Link Trigger offers a helper function to make it much easier, which will be explained next):

This uses Clojure’s map traversal get-in function with the :media-locations map to see what media key has been assigned to the player slot the track was loaded from. Once each Enabled Filter expression is written this way, as soon as you use the Set Media Locations window to move media around, all of the filter expressions immediately start watching for tracks loaded from the updated locations.

As mentioned, though, that’s a lot of code to type for what is likely to be a common desire! So Beat Link Trigger includes a convenience macro called track-matches which does it for you. Using it, we can transform the above code to this much simpler version:

As promised above, since looking up tracks this way is a commonly useful task, Beat Link Trigger includes another convenience macro to shorten the code you need to write. As long as you have structured your nested track map as described in this example, starting with its identifying keyword (:watched-tracks in our example), followed by the media library keyword and rekordbox ID as the nested keys to reach each track’s information map, you can perform the lookup by simply calling find-track with the keyword you used to store your track map in the globals. So we could shorten the expression above to be:

That helps—​the first line is a lot shorter and simpler now. But the middle part was still long enough that we felt like omitting it for brevity in this example…​ can we do better? Well, again, setting the track description based on some value that you have stored in your track map seems like a very common desire, so the find-track macro can do that for you too. All you need to do is pass it a second argument, telling it what keyword in the value it found in your map should be used to set the track description. In our case, we had :name strings that we wanted to use. So we can rewrite the entire Enabled Filter to this much simpler version:

Notice that since now find-track is taking care of setting the :track-description local to the value found at :name in the matched track map, as well as clearing it again if no track matches, we no longer need the “else” logic we were using to take care of cleaning up the description, so we can use a simpler when-let form rather than if-let. And the only thing we need to have in the body is whatever logic we want to use to decide when the trigger is enabled for a matched track.

This is now a very compact, focused, and easy-to-understand filter, so structuring the nested maps that you use to look up tracks in the way that find-track expects to find them is quite handy.

You can actually do more than pass a keyword as the second argument to find-track; what it actually takes is a function that it calls with the matching track map, and uses the result as the description. Keywords work because in Clojure a keyword is also a function that looks itself up in the map you pass it as an argument. Cool trick! But if you want to combine multiple pieces of the map, or do anything else, you can. As a small example, this is how you could limit the length of the description to at most ten characters, even if the track name is longer than that:

That syntax probably looks really strange; #(…​) is a compact way to write an anonymous function in Clojure, and % is the single argument that function was called with. If you want to avoid such terse and cryptic code, you can take the more readable approach of actually declaring a named function in your Global Setup expression, and then using it in your Enabled Filter expressions. So, adding this to Global Setup:

defines the function name-10-chars, which you can then use in your Enabled Filter:

Which brings us back to a concise, readable expression. And of course, your description format function can use more than one value from your track map, and have as much elaborate logic as you like.

Notice that in the screen shot above, as planned, each trigger is configured to watch a single player. They each have identical copies of the above Enabled filter installed, and are set to use it, which is why the loaded track names are showing up in the blue Player Status section. The first trigger is enabled, because that player is sitting at the beat mentioned in the track’s :beat-ccs map. As soon as that player starts playing, the trigger will activate. But how will it know which MIDI CC number it is supposed to send in its activation message? That’s taken care of by a custom Activation expression that has been installed:

This expression first checks that the trigger’s chosen MIDI Output can be found (to avoid throwing exceptions trying to send to a missing device), then looks for the value that the Enabled filter stored in the :activate-cc local. It then sends a MIDI CC message to that controller number, with the value 127, on the channel chosen by the trigger. (It calls dec because the MIDI protocol actually uses the numbers 0—​15 to refer to the channels described as 1—​16.)

In this example, the system being triggered only needs to know when the track reaches that point, so the enabled filter can disable the trigger as soon as the next beat is reached, and reactivate with a different CC when another beat of interest is reached (the Just a Gent remix of Best Day of my Life in this example sends CC 2 on beat 17, and CC 3 on beat 65, using :beat-ccs {17 2 65 3}).

If we need to send a CC to the same controller with the value 0 when the trigger deactivates, a very similar Deactivation expression can be installed:

And of course if you are using OSC to communicate rather than MIDI, you are already writing custom Activation and Deactivation expressions, and you can send much more information about the track that way: the name, the actual rekordbox ID number, or some other value that you add under a new key in the :watched-tracks map. You can structure this as richly as you need.

If you need the trigger to deactivate on specific beats, rather than always on the beat after it activates, that can be done with only slightly more code and tracking structures. I will leave it as an exercise to the reader, but if you get stuck or want to discuss your approach, please say so in the Gitter chat room.

As promised a ways back (the track matching section has become pretty big, and probably deserves to be moved to its own document), there is a way to avoid having to create big nested maps all at once. If you prefer, you can use the add-track macro to add them one at a time. It takes four required arguments followed by any additional keyword and value pairs you want to store about your track. The initial four arguments are:

Any additional arguments (there must be an even number) will be treated as key and value pairs to be included within the map describing the track you are adding. So here is how we could create the same example map we have been using, with add-track rather than explicitly:

Of course by changing the arguments you give, you can build maps for multiple media libraries, without having to worry about how to nest and indent your maps. And as noted above, the :beat-ccs key and values were invented for this example; you can store whatever keys and values you need for your own purposes in your track entries.

Finally, here is an example of using the Globals Inspector to dive into the structure we have created, illustrating its hierarchical nature: