Nick Krecklow

Light Sequencing

Table of contents:

I frequently tinker with light sequencing hardware/software/protocols/standards (e.g. DMX, xLights and Light-O-Rama/LOR) used for real-time synchronization of electrical systems in audio/visual shows. The goal of this page is to be a summarization of the results of my projects in this space and avoid fragmenting it amongst each (typically much) smaller project individually.

Context

Most of these “sequence and run” offerings have three primary systems/usage patterns under the hood:

  1. The sequencer, a tool used by people to generate the LED color/intensity show sequences, typically aligned to music, and export it for use by the player.
  2. The player, a program which ultimately controls the physical hardware and/or additional devices that further proxy/route any control statements.
  3. The scheduler, an optional program which enables user configuration of scheduled shows, playlists, etc and performs high-level control of the player.

There’s typically a tight relationship between these components, often using a bespoke file format or network protocol. LOR offers their own commercial solution for each of these, or you can DIY using open-source software like xLights (a sequencer and scheduler) and Falcon Player/FPP (a player, and also a scheduler) which share support for the .fseq (Falcon sequence) file format.

I find the DIY solutions (i.e. xLights and Falcon Player) to be very popular with hobbyists, and LOR with larger commercial installations. Anyways - they are two different camps for doing much of the same thing and are somewhat interoperable. xLights and Falcon Player do offer basic support for LOR hardware, however it is unable to take full advantage of the Light-O-Rama hardware (including parts of its undocumented protocol).

The fseq file format encodes frame-by-frame data rather than as a series of high-level instructions. As a result, translating sequences between the two is a lossy process, and even if done perfectly, the hardware capabilities are different. Translating the high-level xLights source sequence itself is doable, but that’s like maintaining a .docx/.odf converter; with neither program documenting or maintaining a consistent XML structure.

Bits are bits, and I enjoy developing interoperable player software and publishing the various components as libraries. There’s plenty of surface area to explore and details to obsess over, and there’s a subtle joy in extending compatibility between the two systems to get use out of beefy, commercial hardware.

Documentation

I have published documentation for the fseq 2.x file format used by Falcon Player and xLights.

I additionally reverse-engineered portions of the Light-O-Rama/LOR serial control protocol via trial and error and published what I learned — although it is generally better “documented as code” in the form of the libraries below than its current Markdown iteration.

Libraries

I published single-file header C99 libraries for both fseq 2.x file decoding (libtinyfseq) and encoding LOR control protocol requests (libtinylor). These two libraries are basic building block options available for anyone looking to develop a player program of their own in C or C++.

Programs

fplayer merges all of this documentation and assorted git repos together into a CLI program for the playback of a fseq 2.x sequence on Light-O-Rama hardware from Windows, macOS, Linux or FreeBSD with support for audio playback. Scheduling behavior is left up to the user. The repo includes two additional tools for generating test sequences and editing fseq file variables.