Feature Proposal for plugin support in Xlights

[focusedonsound]

Proposal: Plugin Architecture for XLights

Discussion Type: Feature Proposal
Author: Nick Scilingo (Focusedonsound)
Date: May 2026
Status: Open for Community Feedback

---

Overview

This proposal outlines a plugin architecture for XLights that would allow community developers to extend the software with new effects, output protocols, import/export formats, controller integrations, and sequencing tools — without requiring changes to the core codebase or waiting for a core maintainer to merge new features.

A plugin system would transform XLights from a single monolithic application into an extensible platform, enabling the community to contribute functionality independently and allowing the core team to focus on stability, performance, and foundational features.

I am volunteering to design and implement the initial plugin framework.

---

Motivation

XLights has grown into a remarkably capable piece of software, but growth creates tension: the more the community wants, the heavier the maintenance burden on a small group of core contributors. A plugin architecture addresses this directly by:

• Reducing PR bottlenecks. Contributors can ship plugins without going through core review cycles.
• Enabling experimentation. New ideas can be tested as plugins before being considered for core inclusion.
• Protecting stability. Plugins load in isolated contexts so a buggy plugin cannot crash the core application.
• Empowering the community. Advanced users with C++ or scripting skills can build tools tailored to their own shows and share them with others.
• Commercial opportunity (optional). Third-party developers could offer paid plugins (e.g. advanced visualizers, proprietary controller support) without requiring XLights to host or maintain them.

Projects like Audacity, OBS Studio, and Inkscape have demonstrated that a well-designed plugin system dramatically expands what a community can build without overwhelming core contributors.

---

Scope: What Can Be a Plugin?

The following categories are proposed as pluggable extension points:

1. Effect Plugins

New sequencing effects that appear in the effects panel alongside built-in effects. A plugin effect has full access to the model pixel grid and the timing/beat data for the sequence.

Examples: Custom pixel font renderer, advanced kaleidoscope effect, sports scoreboard overlay, AI-generated motion patterns.

2. Output / Protocol Plugins

New controller output protocols beyond the built-in E1.31, DDP, Artnet, DMX, etc. This allows support for proprietary or emerging protocols without modifying core networking code.

Examples: A new manufacturer's UDP protocol, a custom serial protocol for DIY controllers, a cloud-connected output bridge.

3. Import / Export Plugins

New sequence file format readers and writers. Currently adding import support for a new format (e.g. a competitor's sequence format) requires a core PR. A plugin can handle this independently.

Examples: Vixen 3 importer, Light-O-Rama LMS enhanced importer, custom CSV/JSON sequence exporter, cloud backup exporter.

4. Controller Configuration Plugins

Additional tabs or panels in the Controller Config / FPP Connect screen for controller brands not yet natively supported.

Examples: A new pixel controller brand's auto-upload tool, a custom WLED profile manager, a Raspberry Pi GPIO output configurator.

5. Sequencing Tool Plugins

Custom panels or dialog windows that assist with sequencing workflows. These appear as additional tools in the Tools menu or as floating panels.

Examples: AI-assisted beat detection, custom lyric synchronization tool, commercial sequence conversion wizard, show budget/power calculator.

6. Model Plugins

New model types beyond the built-in singles, matrices, arches, trees, etc.

Examples: Custom 3D sculpture shapes, stadium/arena layouts, animated prop models with articulated segments.

---

Plugin Architecture Design

Loading Model: Native Shared Libraries

Plugins are compiled as native shared libraries (.dll on Windows, .dylib on macOS, .so on Linux). XLights discovers them by scanning a designated plugins/ directory at startup.

This approach is consistent with how OBS Studio, Audacity, and most C++ desktop applications implement plugins. It provides:

• Full performance (no scripting overhead)
• Access to the same wxWidgets UI toolkit used by XLights core
• Strong type safety via a well-defined C ABI interface

Plugin Interface (C ABI)

Each plugin exposes a small set of standardized C-style functions that XLights calls to discover and interact with the plugin. Using a C ABI (rather than C++) avoids C++ ABI fragility across compiler versions:

// Every plugin must export these three functions:

// Returns metadata about the plugin
const XLightsPluginInfo* xlplugin_get_info();

// Called once when the plugin is loaded
bool xlplugin_initialize(XLightsHostAPI* host);

// Called once when the plugin is unloaded
void xlplugin_shutdown();

The XLightsHostAPI struct passed during initialization gives the plugin a stable set of function pointers to call back into XLights core — reading model data, queuing renders, accessing timing tracks, writing output data, etc.

Plugin Info Struct

typedef struct {
    int    api_version;       // Must match XLights plugin API version
    char*  name;              // "My Cool Effect"
    char*  author;            // "Jane Smith"
    char*  version;           // "1.2.0"
    char*  description;       // Short description shown in Plugin Manager
    char*  category;          // "effect" | "output" | "import" | "tool" | "model"
    char*  homepage_url;      // Optional: link to docs or source
    bool   is_open_source;    // Displayed in Plugin Manager for transparency
} XLightsPluginInfo;

Plugin Discovery & Loading Sequence

XLights starts
    ↓
Scans [XLights install dir]/plugins/ and [user documents]/xlights/plugins/
    ↓
For each .dll/.dylib/.so found:
    → Load the library
    → Call xlplugin_get_info() — check api_version compatibility
    → If compatible: call xlplugin_initialize(host) — register with XLights
    → If incompatible or error: log warning, skip plugin (do not crash)
    ↓
XLights finishes loading normally

Plugins that fail to load are skipped with a warning logged to the XLights log file. A single bad plugin cannot prevent XLights from starting.

Plugin Isolation & Safety

• Each plugin runs in the same process as XLights (full performance, no IPC overhead) but is loaded and unloaded independently
• The Host API is versioned — older plugins built against a previous API version continue to work until explicitly deprecated
• Plugins are sandboxed from each other — they cannot call into other plugins directly, only into the Host API
• A plugin that crashes (access violation, unhandled exception) will be caught by a top-level exception handler and disabled for the session with a user-visible warning
• Plugins do not have access to XLights internal data structures directly — only through the Host API, giving the core team control over what is exposed

---

Plugin Manager UI

A new Plugin Manager dialog (accessible from Help → Plugin Manager or Tools → Plugin Manager) provides:

• A list of all installed plugins with name, author, version, category, and open-source status
• Enable/disable toggles per plugin (takes effect on next restart)
• A link to the plugin's homepage or source repository
• One-click uninstall
• A future "Browse Community Plugins" tab that connects to a community plugin registry (see below)

---

Plugin Distribution & Discovery

Phase 1 — Manual Install

Users download a plugin .dll/.dylib/.so from a GitHub release, forum post, or developer's website, and place it in their plugins/ folder. XLights picks it up on next launch. Simple and requires no infrastructure.

Phase 2 — Community Plugin Registry (Future)

A GitHub repository (e.g. xlights-community/xlights-plugins) acts as a curated index of community plugins. Each plugin has a simple JSON metadata file:

{
  "name": "Advanced Beat Detector",
  "author": "community_dev",
  "version": "1.0.2",
  "category": "tool",
  "description": "Enhanced beat and phrase detection using onset analysis.",
  "download_url": "https://github.com/community_dev/xl-beatdetector/releases/latest",
  "source_url": "https://github.com/community_dev/xl-beatdetector",
  "is_open_source": true,
  "min_xlights_version": "2024.10",
  "platforms": ["windows", "macos", "linux"]
}

The Plugin Manager's "Browse" tab fetches this index and lets users install plugins with a single click — similar to how VS Code's extension marketplace works, but lightweight and GitHub-hosted.

---

Host API — Available to Plugins

The following is the initial proposed surface area of the XLights Host API that plugins can call into. This is deliberately conservative for the first release — it can be expanded based on community needs.

Read-Only Model Access

• Get list of models and model groups
• Get pixel count and dimensions for a model
• Get current model layout (pixel positions)

Sequence & Timing Data

• Get list of timing tracks
• Get beat/bar markers for the loaded audio
• Get current playback position

Effect Registration (Effect Plugins only)

• Register a new effect with a name, category, and icon
• Provide a render callback that receives a pixel buffer to fill

Output Registration (Output Plugins only)

• Register a new output protocol with a name and config UI callback
• Provide a send-frame callback that receives the resolved channel data

Import/Export Registration

• Register a file format with extension, description, and read/write callbacks

UI Helpers

• Show a standard XLights-styled dialog or panel
• Add a menu item to the Tools menu
• Log a message to the XLights log file
• Show a non-blocking status bar message

What Is Intentionally NOT in the Host API (v1)

• Direct memory access to internal XLights data structures
• Ability to modify preferences on behalf of the user
• Network access helpers (plugins use their own networking)
• Access to other loaded plugins

---

Versioning & Compatibility

The Host API will be versioned with an integer (XLIGHTS_PLUGIN_API_VERSION).

• Backwards compatibility: XLights will continue to support plugins built against older API versions for at least 2 major release cycles.
• Breaking changes: Any breaking change to the API increments the major version and is announced in the release notes with a migration guide for plugin developers.
• Deprecation warnings: Deprecated API functions will log a warning for one full release cycle before removal.

A plugin built for API version 1 will continue to load and run correctly in XLights versions that ship API version 2 or 3.

---

Security Considerations

Plugins are native code running in the same process as XLights. This means:

• A plugin has the same system access as XLights itself
• Users should only install plugins from sources they trust, just as they would any downloaded executable
• The Plugin Manager will clearly display whether a plugin is open source with a link to the source code
• The community plugin registry will require plugins to be open source to be listed (proprietary plugins can still be distributed directly by their authors)
• No code signing requirement is proposed for v1, but this can be revisited if the ecosystem grows

---

Developer Experience

Plugin SDK

A lightweight xlights-plugin-sdk repository will be published containing:

• The full XLightsPlugin.h header file defining the Host API
• A CMakeLists.txt template for building a plugin against the SDK
• Three example plugins: a minimal effect, a minimal output protocol, and a minimal tool panel
• Documentation covering the full Host API with examples

Build System

Plugins use CMake (matching XLights core) and can be built independently without a full XLights source checkout — only the SDK header is needed.

Documentation

Full API documentation will be published at a GitHub wiki or docs site, covering:

• Getting started: build your first effect plugin in under an hour
• Host API reference
• Plugin packaging and distribution guide
• Versioning and upgrade guide

---

Phased Implementation Plan

Phase 1 — Foundation (Core infrastructure, ~4–6 weeks)

• Plugin loader (shared library discovery, loading, unloading)
• XLightsPluginInfo and version checking
• XLightsHostAPI v1 with minimal surface area
• Plugin Manager UI (list, enable/disable, uninstall)
• Effect plugin type fully working end-to-end
• Plugin SDK repository with one example effect

Phase 2 — More Plugin Types (~3–4 weeks)

• Output/protocol plugin type
• Import/export plugin type
• Tool panel plugin type
• Expand Host API based on Phase 1 community feedback

Phase 3 — Community Registry (~2–3 weeks)

• Community plugin registry GitHub repository
• "Browse Community Plugins" tab in Plugin Manager
• Auto-update notification when a newer version of an installed plugin is available

Phase 4 — Model Plugins & Advanced API (~ongoing)

• Model plugin type
• Expanded Host API surface based on community demand
• Possible scripting layer (Lua or Python) for lower-barrier plugin development

---

My Commitment

I am volunteering to:

• Design and document the full XLightsHostAPI v1 in collaboration with core maintainers
• Implement the plugin loader and Plugin Manager UI
• Write the effect, output, and import plugin types
• Create the xlights-plugin-sdk repository with examples and documentation
• Set up the community plugin registry GitHub repository
• Build and maintain at least two example plugins to seed the ecosystem
• Respond to community feedback throughout and iterate on the design

I am not asking core maintainers to write the implementation — only to collaborate on the API design, review the PRs, and provide guidance on the internal architecture I'll be integrating with.

---

Open Questions for the Community

1. Native plugins vs. scripting? Native .dll/.so plugins offer full performance but require C++ knowledge. Would the community benefit from a scripting option (e.g. Lua or Python) for simpler tool plugins, even at the cost of a heavier runtime dependency?

2. Same-process vs. out-of-process? Running plugins in a separate process (via IPC) would make crashes completely safe but adds significant complexity and latency. Is the crash risk of same-process plugins acceptable?

3. Plugin signing/verification? Should XLights warn users when loading unsigned plugins? Should the community registry require code signing?

4. Priority of plugin categories? Which plugin types should be tackled first — effects, outputs, import/export, or tools? Community input on this will shape the Phase 1 scope.

5. Naming and branding? Should community plugins have a formal name ("XLights Extensions"? "XLights Add-ons"?) or just be called plugins?

6. Backwards compatibility commitment? How long should XLights commit to supporting older plugin API versions? One year? Two major releases?

---

I welcome all feedback on the design. My goal is to build something sustainable that reduces friction for core contributors while opening XLights up to the broader community of developers who want to contribute.

Thank you!

[jessica12ryan]

With a plugin system, it would be a good idea to have a way for xLights to load without plugins. Alternatively, it could be used to temporarily disable any user modifiable parts of xLights. This would be a big change but would be great for resolving issues.

I was thinking to have a "Safe Mode", and be able to launch xLights with a -s flag for safe mode. Have it as in option in the file menu "Open xLights in Safe Mode". In Windows, there could also be a shortcut for "xLights (Safe Mode)". If xLights throws an exception or error at startup, have it automatically fall back to safe mode so we can get into it and remove/disable plugins.

This would also assist zoom helpers to be able to diagnose issues better if/when plugins are introduced. One of the main questions on GitHub Issues and in the zoom room would become "Have you tried safe mode?" which would help determine if the user installed something to cause the issue or if it's an actual issue with xLights. Right now, if we have slow render times, issues with models, and other similar things we go digging. With plugins, we could instruct the user to open safe mode first, see if the issue persists, and that would keep us from hours of guessing to find out that it was a plugin causing the issue all along.

For plugin signing, I'd say have a dropdown in xLights Settings labelled "Allow unsigned plugins:" with options always, warn, or never - and is set to never by default. If a user tries to install an unsigned plugin and the warning is turned on, give them a big scary warning that it is unsigned and could have a negative effect, and give them the option to install anyway. That way, regular users can make sure they only install official plugins. Advanced users can have it set to warn so they know it's unsigned but can still install. Developers who frequently install or test unsigned plugins have the option to turn it off completely.