repository·master·Indexed 23 days ago
https://github.com/mcallegari/qlcplusAn open-source software suite for controlling lighting fixtures via DMX, Art-Net, sACN, MIDI, OSC, HID, and OS2L. Designed for live performance and architectural lighting, it supports Linux, Windows (10+), macOS (10.12+), and Raspberry Pi. The documentation covers core engine components including the Audio class for playback, the BeatTracker for tempo estimation, ChannelsGroup for DMX channel management, and the Collection class for managing sets of functions.
QLC+ is an open-source lighting control software designed for live shows, theatre, architectural installations, and venues. It provides a user-friendly interface to control a wide variety of lighting hardware using multiple protocols.
Supported Platforms:
The BeatTracker is a C++ implementation of a beat-tracking algorithm that adapts to QLC+'s AudioCapture contract. It processes interleaved int16 PCM input and provides two main outputs: a boolean indicating if a beat occurred (driving beatDetected()) and a BPM estimate via the bpm() getter.
The system consists of two main stages connected by an onset-strength stream:
BeatOnsetExtractor: Processes audio in 512-sample hops. It uses a 4096-sample Hann window FFT, analyzes energy increases across three frequency bands (low, mid, high), and applies per-band saturation to ensure backbeats (like kick/snare alternation) are detected reliably.AutoBpmDetector: Analyzes the onset stream every 2 seconds of audio time using an 8-second window. It uses unbiased autocorrelation and a harmonic comb score on a fractional BPM grid (50–240 BPM) to estimate tempo. A temporal belief filter and an 'octave-raise walk' are used to ensure stability and resolve octave ambiguities.Instead of reacting to individual onsets, the tracker emits beats based on a predicted beat grid, which ensures steady output even on syncopated material.
/*
Conceptual flow:
int16 PCM blocks -> BeatOnsetExtractor -> onset value per 512-sample hop
|
v
AutoBpmDetector -> BPM estimate,
confidence,
predicted beat grid
*/When integrating or using the BeatTracker, expect the following behaviors:
If you need help using QLC+, you can access the following resources:
SUPPORT.md in the repository for guidance on finding help.Before seeking assistance, follow these steps to find a solution faster:
Depending on your needs, use the following channels for support:
To ensure bugs are diagnosed and fixed quickly, include the following details when submitting a GitHub issue:
4.14.0)Windows 11, Ubuntu 22.04, macOS Ventura)Developers looking to compile QLC+ should refer to the GitHub Wiki for comprehensive compilation guides and platform-specific instructions.
Note for regular contributors: If you are frequently updating the source via git pull, you may occasionally encounter compiler warnings or unresolved symbols due to dependencies between objects. In such cases, a full package recompilation may be required rather than an incremental update.
The community welcomes contributions to improve QLC+.
Guidelines:
CONTRIBUTING.md file.RGBScript is a class used to implement advanced, programmable RGB lighting algorithms using JavaScript. It inherits from RGBAlgorithm and allows users to define complex color mapping logic via external script files.
load(fileName) to point to a JavaScript file.evaluate() to validate the script's contents and ensure it adheres to the expected interface.setProperty(propertyName, value) to pass configuration parameters to the script. These properties are exposed via the properties() method.rgbMap) to determine color outputs based on the provided size and step parameters.For an RGBScript to function correctly, the JavaScript file must implement specific functions that the engine calls:
rgbMap(size, rgb, step, map): The primary function for calculating color mappings.rgbMapStepCount(size): Returns the number of steps for the given size.rgbMapSetColors(colors)rgbMapGetColors()Note that RGBScript also supports XML serialization via loadXML and saveXML for integration with QLC+ project files.
The Show class is a specialized Function used to manage complex lighting performances. It acts as a container for multiple Track objects and ShowFunction objects, allowing for synchronized playback. A Show can be configured with different time divisions (e.g., standard time or musical BPM) to coordinate the timing of its components.
Key capabilities include:
Track objects.preRun, write, and postRun methods.TimeDivision.The Track class is used to manage sequences of lighting events, typically by associating a track with a Scene and a collection of ShowFunction objects. A track can be muted, renamed, and associated with a specific Show via a showId.
Key capabilities include:
ShowFunction objects.mute state to silence a track.Scene ID.