Debugging and Sharing

When Beat Link Trigger is running it reports events to a log file. As noted above, this includes full stack traces for compilation problems when you try to save an expression that isn’t quite right. If a problem occurs while trying to run your expression later, that will end up in the log too. So it can be a useful place to look when things are not working the way you expect. You can find the log file by choosing Help  Open Logs Folder.

Each time you launch Beat Link Trigger it creates a new log folder in a temporary directory, so that they can be cleaned up automatically sometime after it exits. It cycles through log files and limits their maximum length, which can be important if an error is being logged each time a packet comes in because of a problematic Enabled Filter expression.

Even if things are not crashing, you might want to log your own information to get a better understanding of what is happening inside one of your expressions. Beat Link Trigger uses timbre to perform its logging, and so can you.

For example, if you are trying to figure out exactly what you are receiving in your Beat expression, you could add this as its first line:

Suddenly your logs will be growing steadily, filling with lines like these:

If you run into trouble and it seems likely the problem is in Beat Link Trigger itself rather than one of your own expressions, you can use Help  Report Issue (email) to send an email to Deep Symmetry asking for help. The message will start out populated with some information about the version of Beat Link Trigger you are running, along with the Java version and operating system, but the more details you can provide in the initial report (along with relevant logs), the more likely we will be able to figure out what is going on.

The program may also offer to compose an issue pre-filled with details when it encounters unexpected messages sent by CDJs it is talking to.

If the problem turns out to be trickier than can be understood from just logs, follow-up questions and experimentation may be needed. In such cases thread dumps are often a valuable next step.

In addition to logging values to the log file, you can get a glimpse at what your expressions are up to by opening an inspector window on the Expression Globals or a particular trigger’s Expression Locals. The first is done by choosing Triggers  Inspect Expression Globals. This opens a window showing you all the keys and values that have been created in the globals atom shared by all triggers. Here is what that looks like after the example code shown in the Global Expressions section has run:

The inspector is a little messy, but right away you can see the three keys we created, and the corresponding Java objects stored under them. by clicking next to the blue diamond in the lower pane, you can expand each entry and dive down into the fields and values that make it up, which can be quite a powerful way to explore the objects.

Similarly, the locals for a trigger can be inspected by choosing Inspect Expression Locals from that trigger’s context menu. Here’s the result of drilling down a little into the :resolume OSC client object created in that example’s trigger:

The entire trigger configuration can be saved to a text file by choosing File  Save to File. That file can be sent to another machine, shared with a colleague, or just kept around for future use after you are done with a different project. As you would expect, File  Load from File replaces the current trigger configuration with one loaded from a save file.

If you are in a situation where it is important to keep detailed records of the music being played (for example, a radio station that needs to pay royalties), the built in Playlist Writer can help. It builds on the ideas described in the Matching Tracks Manually section to give you a robust, convenient solution.

Start by choosing File  Write Playlist. This will bring up the Playlist Writer window.

You can configure how long a track needs to be played for before it gets included in the playlist (the default is ten seconds) and whether you want to ignore players that are not reporting themselves as being on the air (very convenient to ignore DJs pre-screening tracks, as long as you are using a DJM mixer that supports this feature, and the players are configured and connected properly).

You can also specify that a new playlist file should be started if a track is played after all players have been stopped for a while, and configure how many minutes can pass with no player playing before such a new playlist file is created. The default threshold for this when the auto-split feature is enabled is 30 minutes. When creating new files because this New Playlist Threshold has been exceeded, the file names have timestamps added to them as described in the next section.

Once everything is set the way you want it, click Start and you will be prompted to choose where to save the file. Once you have done that, the window updates to show you that the playlist is being written:

From this point on, all tracks that play longer than your configured minimum time will be written to the playlist, in Comma-Separated Value format (for convenient use in spreadsheet programs). The playlist will include track titles, artists, albums (when this information is available), as well as the player they were played on, the source player and media type, when they started and stopped playing, and the total time they played.

When you are done recording the playlist you can either click Stop or close the window, and the file will be closed out.

The built in code editor gives you some basic help with writing Clojure, such as syntax coloring and parenthesis matching, but if you are going to write more than a few lines, or want help learning Clojure and testing ideas, you are much better off using a full-featured Clojure development environment, like Cursive or (if you already use the Emacs text editor) CIDER.

Much of the power of these environments comes from the way they interact with the live, running Clojure environment so that you can benefit from code-completion assistance, documentation popups, and even dive into the source code of your functions and the ones that make up Beat Link Trigger itself, making it easy to try things out, update your functions, examine values, and try again. This kind of instant feedback leads to a fertile learning experience and incredibly productive development workflow centered around the Clojure “REPL” (read-eval-print loop).

Beat Link Trigger has features to support working in these editors. At a basic level, the built-in code editor can save your expression or function code to an external text file, which you can edit in one of these environments, and then have the built-in editor load the results back in. But you will get the best results if you turn on a network REPL server inside BLT so the external IDE can connect to it and operate at full power.

To do this, choose Network  nREPL: Clojure IDE connection:

This will open a small window which allows you to configure and start the nREPL server the IDEs can use:

The default port number was chosen to be different from the Carabiner port (in case you are using that), and unlikely to be otherwise used. If for some reason port 17,001 is in use on your computer, you can pick a different port. You just need to tell the IDE which port you are using when you have it connect to the nREPL server.

If you are going to use Cursive, you can simply start the server by clicking the Run checkbox. If you are going to use CIDER, to make full use of CIDER’s powerful features, click the Inject checkbox first, which will configure the nREPL server to add special CIDER middleware. (If you forgot to do this, you can uncheck the Run checkbox to stop the server, check Inject, and then Run it again.)

Although it probably won’t hurt to inject the CIDER handler when using a different editor, it’s a little safer to leave it out of the loop if you don’t need it.