Skip to content
Provides a subset of beat-link features over Open Sound Control.
Clojure
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Fix YAML (my nemesis!) Jan 17, 2020
doc Add Carabiner/Ableton Link integration. Dec 8, 2019
resources/open_beat_control Fix build! Nov 2, 2019
src/open_beat_control
.gitignore Support local Antora builds for faster iteration on user guide. Nov 2, 2019
CHANGELOG.md Fix link in stub changelog. [skip ci] Jan 17, 2020
CODE_OF_CONDUCT.md Start fleshing out documentation. Oct 30, 2019
CONTRIBUTING.md Start user guide. Oct 31, 2019
LICENSE Initial commit Oct 28, 2019
README.md
project.clj Update dependencies. Dec 30, 2019

README.md

open-beat-control

Provides a subset of beat-link features over Open Sound Control.

🚧 This project is at a very early stage of development and is not yet ready for widespread use.

Background

This project is intended for people who want to use the beat-link library to integrate with Pioneer DJ equipment, but are running in a non-JVM environment (like PureData or Max), or who need to run a lightweight headless process (that is, with no attached monitor, keyboard, and mouse for the GUI) on something like a Raspberry Pi, and thus are unable to take advantage of the features of Beat Link Trigger.

To begin with, only a few features were supported, but over time (and based on interest and requests) more are being added when practical approaches can be identified. The Carabiner integration previously provided by beat-carabiner was an early addition, and that project has become a library shared by both this project and Beat Link Trigger itself, to solve the problem of diverging features and stale code.

Why OSC?

Open Sound Control is a strange protocol, and makes some aspects of implementing an API awkward (there is no intrinsic support for requests with responses), but it is widely supported in the kind of experimental music environments that are most likely to benefit from a project like this.

Installation

Install a Java runtime, and the latest open-beat-control.jar from the releases page, on your target hardware.

🚧 There are no finished releases yet, but brave souls may a development build.

Java Runtime

You may be able to get by with Java 6, but a current release will perform better and have more recent security updates. We currently use Amazon Corretto 11 which is a free OpenJDK 11 distribution with long-term support.

If you are using Open Beat Control on a Raspberry Pi, we have not yet started testing this (and very much would like to hear reports from people who have), but it looks like Raspbian Buster includes OpenJDK 11 as well, so it should be a great starting point.

Usage

You can either start open-beat-control manually when you want to use it, or configure it to start when your system boots.

To start open-beat-control manually, run:

java -jar open-beat-control.jar

It will log to the terminal window in which you are running it. If you instead want to run it at system startup, you will probably also want to set a log-file path, so it logs to a rotated log file in your standard system logs directory, something like:

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

Other options allow you to specify the port number on which its OSC server listens, and there will be more to come.

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

For more information about these, please see the User Guide

User Guide

To learn how to communicate with Open Beat Control, and the OSC messages you can send and receive, please see the User Guide 📖.

Community

For the moment, discussion of Open Beat Control is taking place on Beat Link Trigger's Gitter channel. If enough people start using it and discussing issues that aren't interesting to Beat Link Trigger users, I will create a separate channel.

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 to offset 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

Compatibility

This is in no way a sanctioned implementation of the protocols. It should be clear, but:

⚠️ Use at your own risk! For example, there are reports that the XDJ-RX (and XDJ-RX2) crash when Beat Link starts, so don’t use it with one on your network. As Pioneer themselves explain, the XDJ-RX does not actually implement the protocol:

“The LINK on the RX [and RX2] is ONLY for linking to rekordbox on your computer or a router with WiFi to connect rekordbox mobile. It can not exchange LINK data with other CDJs or DJMs.”

While these techniques appear to work for us so far, there are many gaps in our knowledge, and things could change at any time with new releases of hardware or even firmware updates from Pioneer.

You should also not expect to be able to run Open Beat Control, or any project like it, on the same machine that you are running rekordbox, because they will compete over access to network ports.

Open Beat Control seems to work great with CDJ-2000 Nexus gear, and works fairly well (with less information available) with older CDJ-2000s. It has also been reported to work with XDJ-1000 gear. If you can try it with anything else, please let us know what you learn in the Beat Link Trigger Gitter chat room, or if you have worked out actionable details about something that could be improved, open an Issue or submit a pull request so we can all improve our understanding together.

If something isn’t working with your hardware and you don’t yet know the details why, but are willing to learn a little and help figure it out, look at the dysentery project, which is where we are organizing the research tools and results which made programs like Open Beat Control possible.

Startup Issues

If you downloaded the .jar version and are using a recent Java distribution, double-clicking doesn’t open up the application, so open a terminal window and run it from the command line:

java -jar open-beat-control.jar

If that does not work, at least you will be able to see a detailed report of what went wrong, which can help you troubleshoot the issue.

Make sure you have a current OpenJDK distribution installed (we build releases with Amazon Corretto 11).

Licenses

Deep Symmetry

Copyright © 2019 Deep Symmetry, LLC

Distributed under the Eclipse Public License either version 2.0 or (at your option) any later version. 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.

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.

Antora

Used to build the user guide, for embedding inside the application, and hosting on Netlify. Antora is licensed under the Mozilla Public License Version 2.0 (MPL-2.0).

You can’t perform that action at this time.