Skip to content

Home

Jump to bottom
Daryl edited this page Jul 29, 2026 · 3 revisions

xLightsAI — MP3 to xLights Sequencer

xLightsAI analyzes a song, groups your xLights layout into tiered "Power Groups," and generates a themed .xsq sequence ready to import into xLights — driven entirely by the audio, not manual effect placement.

What it does

  1. Audio analysis — 17 algorithms across 7 hierarchy levels (L0–L6) extract beats, onsets, chords, sections, energy curves, and stem separation (drums / bass / vocals / guitar / piano / other).
  2. Layout grouping — reads your xlights_rgbeffects.xml and auto-generates an 8-tier Power Group hierarchy (spatial, rhythmic, prop type, compound, heroes).
  3. Effect + variant library — dozens of cataloged xLights effects and 100+ pre-tuned variants tagged by energy, tier, section role, and genre.
  4. Theme engine — a set of composite lighting "looks" (e.g. Inferno, Aurora, Winter Wonderland), organized by mood, occasion, and genre.
  5. Song story — automatic section classification (verse / chorus / bridge / etc.) with lyric-anchored boundary refinement and energy arcs.
  6. Sequence generation — produces a .xsq file with effects placed by tier, energy, and theme, ready for xLights.
  7. Web UI — a browser dashboard covering the whole workflow: upload, analyze, review, theme, and export.

Get started

  • Getting Started — install with Docker and run your first song through the pipeline.
  • Review UI Guide — a walkthrough of every screen in the web dashboard, tab by tab.
  • Command Line Tools — the underlying xlight-analyze CLI, for scripting or working outside the web UI.

Project links

Contributing

Read CLAUDE.md in the repository root before making changes — it documents the coding conventions, the design-review gate for non-trivial changes to shared modules, and the pre-merge acceptance gate (xlight-evaluate gate). .devcontainer/ also works as a VS Code Dev Container for interactive development inside the same toolchain image used by docker compose up.

xLightsAI

Repository

Clone this wiki locally