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 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 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.
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 Zulip 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.
License
Copyright © 2019–2020 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.