TheLightingController Node.js Client Library

TheLightingController is a software application, branded as ShowXpress for ChauvetDJ and QuickDmx for Showtec. It is developed by SweetLight, which also has a branded version called SweetLight Controller. Regardless of which application you use, other than some cosmetic changes and custom drivers for talking to proprietary DMX interfaces, the underlying software is the same.

Recently, The company released a Protocol Definition document outlining how external applications can talk to the live software. Using this specifications, we were able to create a software library for Node.js to enable software developers to write Javascript code to talk TheLightingController live software.

Library and Example Links

TheLightingControllerClient Node.js Client Library

Library for communicating to a LightingController instance. Full documentation is on the github project page, with all supported methods and events that can be triggered or received.

TheLightingControllerClient Example Application

Web-based application for connecting to a LightingController instance. Replicates the functionality of the Live Mobile iOS App.

Features

The Client Library has full support for all documented methods of the Protocol (and even two extras that we reverse-engineered from the Live Mobile application).

• Client Authentication.
• Activate/Deactivate any Live Button, including Scenes, Timelines, Macros, Pixel Mappings, or Audio/Video Tracks.
• Adjust all Faders and Speed Controls.
• Freeze and Unfreeze.
• BPM Setting methods for automatic BPM calculation for timed cues.
• Interface Update events for live-reloading the mapped buttons.

Potential Applications

The Example Application shows just one application. It replicates the Live Mobile Application and exposes it as a web service. The application can then connect to any TheLightingController instance open on the network. This allows any user with the correct login/password to connect and control TheLightingController software instances without needing to install the Live Mobile app. It also allows for a single web interface to service multiple TheLightingController instances, should you have multiple controllers and software instances (for example multi-room venues with separate DMX controllers).

Because the client is open source, there are a wide variety of other potential uses that could be developed (if you are looking for a project idea)!

• Auto-BPM calculations - Hook up BPM events from your DJ software to the client for synchronized button triggers.
• Visual Controls - Create custom styled software for controlling your LightingController instance, for example a display that an audience may see or interact with.
• Actor/Presenter Cues - Create a push-button activator from a phone or tablet to cycle through predefined button combinations, audio and lighting cues, or sequences. Give partial control to your talent - a scary idea, indeed!
• Multi-Client Dashboard - As an extension of the example, instead of controlling each instance independently, create a central control station for all instances.

Development Notes

In developing the client software, there were a few pitfalls. To begin, the protocol document, while relatively complete, is a bit sparse on details. We were able to implement most of the controls based on the socket message specification, but some required a bit of reverse engineering.

For this purpose, we created a Mock Server. This simulates the ShowXpress software, and allowed for connecting the official Live Mobile App to see the format for messages and features that were not documented. Using this, we were able to find the proper format for the undocumented FREEZE_ON, FREEZE_OFF, AUTO_BPM_ON, and AUTO_BPM_OFF events. It also resulted in the discovery of a few bugs! These are mostly related to multi-broadcast, where events will be sent from a client to the software, but are not rebroadcast to other clients. A full bug report can be found on TheLightingController Forums.

Mentions

• TheLightingControllerClient Node.js Client Library - Library for communicating to a LightingController instance.
• TheLightingControllerClient Example Application - Web-based application for connecting to a LightingController instance. Replicates the functionality of Live Mobile.
• ShowXpress - TheLightingController Software for ChauvetDJ.
• QuickDmx - TheLightingController Software for Showtec.
• SweetLight Controller - TheLightingController Software for SweetLight.
• Protocol Definition document - The software specification document for the protocol to talk to TheLightingController software.
• Node.js - Javascript runtime environment.
• Live Mobile iOS App - The official Live App.
• Mock Server - Used to simulate the ShowXpress software
• Bug Report on TheLightingController Forums - Protocol Issues discovered while developing the client library.