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. 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)
-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.

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.

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.

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

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.

Donate using Liberapay using Liberapay, or Donate using PayPal

License

Deep Symmetry logo Copyright © 2019 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

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.