Beat Link Trigger User Guide

This is an introduction to the Beat Link Trigger interface and expression programming environment. It shows some ways you can use it, but as an open-ended environment, the possibilities are endless. If you have questions or other approaches you’d like to share, please post to the Zulip stream.

To keep page sizes manageable, this guide is split into several pages. It is worth reading through this whole guide once if you are new to Beat Link Trigger. Once you know what you are looking for, you can also dive right into it by jumping to the page you want using the navigation menu on the left.

Versions

You are looking at version 7.4.1 of the User Guide, which corresponds to that release of the software.

To look at a different version (including the main branch, which reflects ongoing development that is available as a preview release but not yet officially released), choose it in the versions menu either at the top right (just before the Edit this Page link), or at the bottom left.

Startup

When you first open Beat Link Trigger, it tries to find the Pro DJ Link devices that you want it to monitor. While it is watching the network for them, it displays a window like this:

Looking for devices

If you just wanted to work on setting up your triggers, expressions, or shows, and don’t have any actual players handy, you can click Continue Offline to work in an offline mode. Your triggers won’t actually fire, but you can do all the configuration and editing that you need, and you can load tracks into your shows using rekordbox USB and SD media.

If no DJ Link devices can be found after about twenty seconds of searching, it probably means something is misconfigured on your network, so Beat Link Trigger will replace the window with a troubleshooting version that looks like this:

No devices found

If you were expecting to find devices, double-check that they are powered on, and properly networked with your computer (and that any hub or wireless router you are using is also properly turned on and configured). The window shows all network interfaces that were found in your computer, along with the IP address and net mask assigned to your computer on that interface. The devices will only be able to communicate with you if they have compatible IPv4 addresses. If you are not on a network with a DHCP server, for example, the players will assign themselves addresses of the form 169.254.x.y/16, so if none of your addresses match that pattern, you will not be able to communicate with them.

While you work on making sure your network interfaces and cables are configured properly. Beat Link Trigger is continuing to watch for devices, so as soon as you get the issue sorted out, it will go online. And as noted above, if that isn’t going to happen, you can click Continue Offline to work in an offline mode, or you can click Quit to give up and try again later, perhaps in a different setting.

Once a device is found, or you choose to continue offline, the Triggers window opens, in the same configuration that you left it the last time you used the program, and any Show files you had open will be reopened as well.

Command-Line Arguments

If you launch BLT from a shell (either because you are using the Jar file with your own Java installation, or by running the launcher embedded in the application) you can control what it does at startup. Giving it the argument -h or --help causes it to print out all the available options and quit:

java -jar beat-link-trigger.jar --help
Beat Link Trigger 7.2.2 Sun Oct 01 18:39:28 CDT 2023

Options:
  -o, --offline        Start in offline mode
  -s, --show FILE      Open addtitional show after startup
  -S, --suppress       Do not reopen shows from previous run
      --reset FILE     Write saved configuration to file and clear it
  -c, --config FILE    Use specified configuration file
  -h, --help           Display help information and exit

Please see https://github.com/Deep-Symmetry/beat-link-trigger for user guide.

The -o or --offline option allows you to skip the attempt to find a DJ Link network, and go right into offline editing mode. You can connect later as described below if desired.

The -s or --show option can be combined with the path to a show file to tell BLT to open that show as well as any of the shows that were open when you last used it. You can use this option as many times as you like to open multiple new shows.

If you don’t want the shows that were open during the last session to be reopened, you can prevent that by supplying the -S or ‑‑suppress option. (This works whether or not you are listing shows that you do want opened.)

If there is a problem with your saved configuration that is preventing BLT from starting properly, you can use the ‑‑reset option along with a file path to tell BLT to write that configuration to the specified file (whose name must end with .blt), and then start up with an blank configuration. You can either try to manually edit the exported configuration file to fix the problem (it is saved as EDN, a text format), extract expressions and elements you want to save, or reopen it unchanged later if there is a fix to BLT itself that solves the problem.

Finally, if you want to start with a different configuration (which includes all your triggers, global expressions and shared functions, as well as window positions and set of open shows), you can use the -c or ‑‑config option to specify the path to the exported configuration file you want to use. This will replace the current configuration, so if there is anything you want to preserve in that, be sure to do that with the ‑‑reset option, unless you have already saved it from within BLT.

If you are using the Mac application version of Beat Link Trigger, you can still give it command line arguments by opening a Terminal window and executing commands like:

Beat\ Link\ Trigger.app/Contents/MacOS/Beat\ Link\ Trigger --offline

You can also use the macOS open command to achieve this without having to specify the path to and through the .app bundle, but this approach prevents any of the application’s text output from appearing in the terminal:

open -a "Beat Link Trigger" --args --offline

In Windows you can pass command-line arguments by using the Command Prompt window to invoke Beat Link Trigger.exe as the command, adding any arguments you’d like after that. As with the macOS open command, however, you will not be able to see any output that BLT writes back to you.

Connecting Later

If you connect to a DJ Link network after a period of working on your shows and triggers in offline mode, you can take Beat Link Trigger online by checking Network  Online?

Going Online

You can also go offline at any time by un-checking the menu option.

If there has been a disruption to the network, and you seem to have lost contact with the players, taking Beat Link Trigger offline and then going back online can often solve the problem. It will generally try to do this for you automatically when it loses contact with the last DJ Link device.

Checking your Player Number

Once you have successfully taken Beat Link Trigger online, you can see what Player Number it is using by looking at the Network  Online? menu option without toggling it again. Whenever it is checked, the Player Number being used by Beat Link is shown there.

Ableton Link: Carabiner Connection menu

Most of the time you will want to be using the self-assigned device number Player 7, as shown here, because that is compatible with big shows where there are four real players in use (or even six, if they are all CDJ-3000s). However, if you want to do things like letting an Ableton Link session become the Tempo Master and control the speed and beat sync of the players, or display metadata for CD and other non-rekordbox tracks, you will need to use a real player number in the range 1–4, which may require you to turn off one of the other players.

Fixing Network Problems

If Beat Link Trigger reports that it can’t find any DJ Link devices when you try to take it online, this means there is a problem with your network. People often ask for a connection diagram, but there is really nothing to diagram: as long as you have your players and the computer running BLT on the same LAN, it will work.

That could mean anything from plugging a single player directly into the LAN adapter of your computer (with a modern Ethernet adapter with Auto-MDI-X), to plugging everything into a fast hub, switch (which most things called “hubs” really are today), or router.

By far the most common problems involve configuration issues with the network adapter on the computer running Beat Link Trigger. So here is a list of things to think about and watch out for.

If you are still stuck after following this advice, you can ask for help on the Zulip stream.

Use a Separate Network for your DJ gear

The best scenario is to have a completely separate switch for only your DJ gear, and a secondary network adapter on the computer running BLT. Connect all the DJ gear and that network adapter to that one switch. Make sure that switch isn’t connected to other switches/routers, this can make the Pro-DJ Link traffic go bananas.

Do not use WiFi for any of your network segments. I thought everyone would know this, but I end up spending a lot of time helping people in the discussion community who are trying to figure out why nothing is working well, and who turn out to be using WiFi. You just can’t do that with DJ Link. WiFi has latency and collision issues that destroy the ability to reliably interact with DJ gear. Don’t try, especially not if you are performing with an audience. Use a good gigabit network switch and quality Ethernet cables.

If you still want to be able to access the Internet from the computer running Beat Link Trigger, you can do so by connecting its primary network adapter to another switch or router that is connected to the Internet. This way you can use the primary network adapter on your BLT computer to do anything that requires global connectivity, and the secondary adapter for BLT and the DJ Link network.

If your computer has only one network adapter, then it is best not to attempt Internet connectivity, and connect only to the DJ gear network while running shows.

IP Address Assignment

The next major thing that needs to be correct for the players and Beat Link Trigger to be able to talk to each other is for them to have a shared understanding of what network they are on, and IP addresses and net masks that are mutually compatible.

Of course, you should check that the adapter is active at all, it might have been disabled at the OS level, or there may be a problem with the hardware or the cable.

Self-Assigned Addresses (APIPA, auto-IP)

In the simplest case there is no DHCP server on the DJ gear network, so the players will self-assign a Link-Local Address (further details in RFC-3927). This is an address of the form 169.254.x.y, and if you have left the network adapter settings at their default DHCP mode in macOS or Windows (and probably Linux), it will self-assign a compatible address in the same range. Windows calls this APIPA. You can verify this has happened by looking at the list of networks that Beat Link Trigger displays when it is reporting it can’t find DJ Link devices. If the network adapter is not using an address that is in this range, then you’ll need to fix its configuration.

  • If the adapter is configured to a hard-coded address, either change that address and net mask to match the Link-local network, or change it to use DHCP so that it will fall back to using link-local addressing when it finds no DHCP server.

  • If it is already configured to use DHCP, tell it to try to renew its lease. (In Windows, ipconfig /release followed by ipconfig /renew. In macOS, here are Apple’s instructions and a nice osXdaily article. In Linux, you’ll generally want to use dhclient.)

DHCP Managed Networks

If you want to have more control over the IP address assignments and network parameters of your DJ network, and are running your own DHCP server, you will already know most of this information and troubleshooting steps. But:

  • Make sure the DHCP server has plenty of time to boot, and was ready to respond before you power on the CDJs or attach the computer’s network adapter. Otherwise they may time out waiting for the server and self-assign IP addresses as described above.

  • Turning the CDJ off for a few seconds and then back on once you know the DHCP server is ready will give the player a chance to get the address you intended for it.

  • If the network adapter doesn’t show the correct address in Beat Link Trigger’s troubleshooting window, follow the instructions in the previous section for releasing and renewing your DHCP lease.

Firewall and Anti-Virus Software

You need to be sure that there is no firewall or anti-virus software on the host computer blocking Beat Link Trigger from communicating on the network adapter. Either of those things can prevent it from joining the DJ Link network.

Other DJ Link Software (like rekordbox)

Because of fundamental limitations in the design of the DJ Link protocol, only one program can connect to the DJ Link network on a given network adapter. So it is impossible to run Beat Link Trigger on the same computer as rekordbox, or any other software that wants to communicate with the DJ Link network.

Other Port Conflicts

If you are running any software that happens to randomly use the same ports as the DJ Link protocol (one culprit in Windows turns out to be the AnyDesk remote desktop software) this will also prevent Beat Link Trigger (or rekordbox) from starting up properly. You will want to look for conflicts on ports 50000, 50001, and 50002 (and remember you need to check the UDP protocol, not just TCP).

  • On macOS and Linux you can use, for example, lsof -i :50000 to see the process using port 50000. (You may need to install lsof using your preferred package manager on Linux; it is preinstalled on macOS. Other Linux alternatives are described here.)

  • On Windows you can use the Resource Monitor GUI: Start menu  All Programs  Accessories  System Tools  Resource Monitor (or run resmon.exe). Remember to look for both UDP and TCP listeners and connections.

Learning More

What Next?

Hopefully this guide has been enough to get you started, and thinking about interesting ways you can synchronize your CDJs with other elements of your show. (If you have not yet read the other pages in the guide, please do so, either using the “Learning More” links in each page—like the one right above—or by exploring the navigation menu on the left.)

If you have any thoughts, questions, your own integration examples, or even crazy ideas, please share them in the Zulip stream or project Wiki!

If you find what seems to be an actual problem with the software, please open an Issue, or at least check whether someone else already has.

Thanks for reading this, and have fun with Beat Link Trigger! I hope to hear from you.

Funding

Beat Link Trigger is, and will remain, completely free and open-source. If it has helped you, taught you something, or pleased you, let us know and share some of your discoveries and code as described above. If you’d like to financially support its ongoing development, you are welcome (but by no means obligated) to donate towards the hundreds of hours of research, development, and writing that have already been invested. Or perhaps to facilitate future efforts, tools, toys, and time to explore.

Donate using Liberapay using Liberapay, or Donate using PayPal

If enough people jump on board, we may even be able to get a newer CDJ to experiment with, although that’s an unlikely stretch goal.

License

Deep Symmetry logo Copyright © 2016–2024 Deep Symmetry, LLC

Distributed under the Eclipse Public License 2.0. By using this software in any fashion, you are agreeing to be bound by the terms of this license. You must not remove this notice, or any other, from this software. A copy of the license can be found in LICENSE within this project.

Library Licenses

Remote Tea

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

Kaitai Struct

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

RSyntaxtTextArea

RSyntaxtTextArea is used for editing Clojure expression code.

Copyright © 2019, Robert Futrell. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

RSTAUI

Provides find/replace and other extended features to RSyntaxTextArea when editing Clojure expression code.

Copyright © 2012, Robert Futrell. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

inspector-jay

Supports inspection of the atoms that store local and global values for trigger and show expressions.

Copyright © 2013-2015 Tim Molderez. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the inspector-jay developer team nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INSPECTOR-JAY DEVELOPER TEAM BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

radiance

Provides the cool dark look-and-feel for the graphical user interface.

Copyright © 2005-2019, Kirill Grouchnikov. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.