OS2L is an open protocol to interface audio software with DMX software.

Objectives

OS2L satisfies two main objectives:

1) to allow better "automatic" lights synchronisation, by letting the DMX software get information about the speed and phase of the music.
2) to allow the user to perform quick changes in the lights directly from his audio software and/or hardware.

Network communication

OS2L communication is done over the local network (wifi or ethernet) using TCP/IP (or using the loopback network address if both applications are running on the same computer).
The connection between the audio software and the DMX software is done automatically and transparently, using DNS-SD automatic discovery (Apple's Bonjour, Microsoft's DNS-SD or Linux's Avahi).

The DMX software act as the service provider, and registers itself on DNS-SD as providing the "_os2l._tcp" service, then start listening for incoming connections on a port of its choice. The audio software uses DNS-SD to discover OS2L service providers, and start communicating on the TCP interface returned when one is found.
See the example below for implementation.

Messages format

Once a connection is established, the audio software sends messages to the DMX software, in the form of short JSON messages. Messages are sent either as a result of a user action (pressing a button on the audio hardware / software), or automatically on each beat in the music.

User messages can be either simple, and just send a button name, or can be complex (for advanced mappings) and send a numeric command ID and a percentage parameter.

Simple button messages should have the following syntax:
evt (string): "btn"
name (string): name of the button (will automatically activate any button with this name on the DMX software)
page (string): (optional) name of a page that contains the button. If empty, uses the master page. If set to "*", uses all pages. If set to "-", uses the page currently displayed in the DMX software
state (string): either "on" if the button is being pushed, or "off" if the button is being released

Example: {"evt":"btn","name":"blackout","state":"on"}

Complex command messages should have the following syntax:
evt (string): "cmd"
id (integer): command id, that should be mapped to a trigger on the DMX software (similar to a MIDI command)
param (double): command parameter, between 0 and 100%

Example: {"evt":"cmd","id":42,"param":100.0}

Optionaly, on receiving a button or a command event, the DMX software can reply with a feedback event, in order to visually turn the button on or off on the audio software/hardware (useful for buttons that activate/deactivate a state, rather than being push-release).
(Note: this message is sent FROM the DMX software, TO the audio software, unlike all other messages that are sent from the audio software to the DMX software).
evt (string): "feedback"
name (string): name of the button
page (string): (optional) name of a page that contains the button
state (string): either "on" to light the button on, or "off" to light it off

Example: {"evt":"feedback","name":"program1","state":"on"}

Once a connection is established between the audio and DMX software, the audio software will automatically send synchronisation messages on each beat position (even if there is no audible beat). The beat messages should have the following syntax:
evt (string): "beat"
change (bool): true if either the phase or the bpm changed since the last beat message
pos (integer): beat number (pos modulo 4 should be 0 on 4:4 measure boundaries, pos modulo 16 should be 0 on 16 beat phrases boundaries, etc)
bpm (double): number of beats per minute
strength (double): relative audible strenght of this beat compared to the strongest beat in the song (in percentage). (optional)

Example: {"evt":"beat","change":false,"pos":42,"bpm":120.0}

Usage

The 'btn' messages, are mostly intended to be used by users of the DJ software, that might not have programmed the DMX software themselves, and wouldn't have access or know how to configure its various mappings.
It lets the DJ simply read on the DMX software's screen the name of a button he wants to control, and enter it in his DJ software.

The 'cmd' messages, are more intended to be used by users who are both the DJ software and DMX software user, or just DMX software user, and want to use the more powerful mapping system provided by the DMX software.
They will be more similar to other existing mapping features like MIDI, OSC, etc.

Implementation

You can find an example of implementation (for a DMX software) here: