Open Beat Control User Guide

This is an introduction to the Open Beat Control utility, describing the OSC messages you can use to interact with it. This guide 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 Beat Link Trigger Gitter chat room.

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 Open Beat Control. 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.

Startup

When you launch Open Beat Control, it does not display any visible user interface, it simply logs out informational messages to the console (or to the log file you have specified in the command-line arguments you provided). This is because, unlike the rich GUI of Beat Link Trigger, this project is intended to be used on less-powerful computers which often lack displays completely. The log can be viewed to troubleshoot issues when things are not working the way you expect, but your general interaction with the program will be by sending and receiving OSC messages.

Details of how to obtain Open Beat Control and the Java environment needed to run it can be found on the project page.

Assuming you have configured your command path so that the JDK’s java command is available, you can start Open Beat Control by simply typing the following command in a terminal session (or include it in a shell or command script):

java -jar open-beat-control.jar

This will log any informational and error messages to the terminal window in which you are running it.

You will see warnings about "illegal reflective access operations." This is normal and currently unavoidable, because several of the libraries used by Beat Link Trigger have not been updated to be compatible with the Java Module System introduced in Java 9. That may never happen; modules radically changed the rules, and the "future release" where these rules are enforced may never come.

If you are configuring your system startup scripts to run Open Beat Control, you probably also want to set up a log-file path, so that these messages are sent to a rotated log file in your standard system logs directory, along these lines:

java -jar open-beat-control.jar -L /var/log/open-beat-control.log

If you are running on a Mac, and want to avoid having a useless "java" dock icon appear, with a menubar that has no helpful content, you can tell Java that this is a background-only application with no user interface by adding -Dapple.awt.UIElement=true before the -jar section of the java invocation:

java -Dapple.awt.UIElement=true -jar open-beat-control.jar

There are other command-line options you can use as well.

Options

-o, --osc-port PORT        17002  Port number for OSC server
-r, --real-player                 Try to pose as a real CDJ (device #1-4)
-d, --device-number NUM           Use fixed device # (overrides -r)
-B, --bridge                      Use Carabiner to bridge to Ableton Link
-a, --ableton-master              When bridging, Ableton Link tempo wins
-b, --beat-align                  When bridging, sync to beats only, not bars
-c, --carabiner-port PORT  17000  When bridging, port # of Carabiner daemon
-l, --latency MS           20     How many milliseconds are we behind the CDJs
-L, --log-file PATH               Log to a rotated file instead of stdout
-h, --help                        Display help information and exit

By default, Open Beat Control listens for OSC messages on port 17002, so that is what you would configure your other software to talk to. If there is a reason you need to use a different port number instead (perhaps other software is already using port 17002), you can supply the -o or --osc-port option, along with a port number, to specify an alternate port for receiving OSC messages.

The normal mode of operation is for Open Beat Control to look and see what devices are already on the network, and pick an unused device number to avoid conflicts. If you want to tell it to use a specific device number instead, see Specifying a Device Number below.

Posing as a real CDJ

Unless you supply the -r or --real-player option, the Beat Link library will use an unused device number greater than 4. This means it can safely operate even when there are four real CDJs on the network (they will be using numbers 1 through 4). Thanks to a lot of clever research and trickery, we have figured out how to get most features working even when operating in this mode.

But some things are simply impossible: if you want to be able to control the tempo of the CDJs, then Beat Link needs to be using a real player number. Passing this option tells it to try; if you have four players on the network, you will have to turn one of them off before starting Open Beat Control for this to work.

Specifying a Device Number

If you always want Open Beat Control to use a specific device number, you can configure that by supplying the -d or --device-number option along with the number that you would like to use, which must be in the range 1 through 127 (although you should probably stick to the range 1-15 to avoid conflicting with rekordbox and mixers). When you do this, passing -r or --real-player has no effect: you can choose to use a number in the real player range (1 through 4) or not. It is your responsibility to be sure that no other device on the network is trying to use the same number.

If you tell Open Beat Control to use a specific device number, and there is an actual device using that number on the network, that device will defend its use of the number, and Open Beat Control will repeatedly fail to go online until the other device is disconnected or turned off. Or, if the other device is an XDJ-XZ, it does not properly implement the conflict resolution protocol, and you will end up with two devices on the same number, which will not work in any useful way. So only use this option if you really need to, and are careful about what you are doing.

If you’ve plugged Open Beat Control into a mixer ethernet port that is assigned to a particular channel, the mixer will tell Open Beat Control what channel to use, and this will override your attempt to specify a device number.

Bridging to Ableton Link

If you would like to allow the DJ Link network to control the tempo and beat alignment of an Ableton Link session (or vice versa), you can supply the -B or --bridge option.

As long as you are running Open Beat Control on one of the common operating systems and processor architectures that are supported by lib-carabiner, there is nothing else you need to install or run, and a built-in copy of Carabiner will be started when you need it. If you are on a different platform, you will need to build, install and run Carabiner on your own.

With either approach, Open Beat Control can tie into an Ableton Link session, so you can synchronize programs like Ableton Live, Traktor, and an increasing collection of others (as well as more and more hardware), to the tempo and beat grid established by the players.

If you don’t want Carabiner to communicate on its standard port number 17000, you can use the -c or --carabiner-port option to tell Open Beat Control which port to use for Carabiner (which will configure Carabiner itself if Open Beat Control is managing it, or just tell Open Beat Control where to find it if you are running your own copy.

By default, Open Beat Control will align the Ableton Link session timeline with the DJ Link tempo grid at the level of entire musical bars, so the down beats fall at the same time. If you don’t trust the down beat assignments of tracks on the CDJs, you can tell it to align at the level of individual beats instead, using the -b or --beat-align option.

If the beat alignment seems to be slightly off, you can tweak it by adjusting the latency value using the -l or --latency option.

The normal mode of operation is for Open Beat Control to tie the Ableton Link session to the player that is the Tempo Master on the DJ Link network. If you would like synchronization to happen in the other direction, so that the Pioneer players are synced to the Ableton Link session, you can use the -a or --ableton-master option, as long as Open Beat Control is posing as a real CDJ, or if you specified a device number it was in the range 1 through 4.

As long as you turned on bridging at startup (and as long as you are using an appropriate player number if you want Ableton Link to be the tempo master) you can change which network (and which player) is controlling the tempo at any time using OSC messages.

Learning More

Continue to Communicating

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 Beat Link Trigger Gitter chat!

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 Open Beat Control! I hope to hear from you.

Funding

Open Beat Control 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.

using Liberapay, or using PayPal

License

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

Used for communicating with the NFSv2 servers on players, licensed under the GNU Library General Public License, version 2.

The Kaitai Struct Java runtime

Used for parsing rekordbox exports and media analysis files, licensed under the MIT License.