Getting Started

Getting Started

xLightsAI runs anywhere Docker does — Windows, macOS, or Linux. The only prerequisite is Docker Desktop (or Docker Engine on Linux): docker.com.

Install and run

git clone https://github.com/derwin12/xlights-autosequencer.git
cd xlights-autosequencer
docker compose up

Open http://localhost:5000.

The first run builds the toolchain image — the Vamp plugins compile from source, which is the slow step (easily 20–40 minutes, but fully unattended) — and installs the Python/JS packages. Later runs start fast. Your song library and cached analysis persist in named Docker volumes across restarts.

First-run workflow

Once the page loads:

1. Drop an MP3/WAV (or a video file — its audio track is extracted automatically) onto the Drop tab.
2. The xLights layout is fixed for the whole project — every song exports against the xlights_rgbeffects.xml and xlights_networks.xml committed under layout/ in the repo, so there's no per-song layout import step.
3. Walk the numbered tabs left to right (Library → Drop → Analyze → Timeline → Theme → Export) and finish with a Download Package on the Export tab.

See the Review UI Guide for a screen-by-screen walkthrough of that flow.

Your data

Everything you upload or generate — song library, cached stems/analysis, image library, custom themes — lives under ~/.xlight/ inside the container, backed by named Docker volumes. It survives restarts, container recreation, and image rebuilds, and is not tracked in git. To carry it to another machine, docker cp it out of/into the xlight-state volume.

Path	Contents
~/.xlight/library.json	Song library index
~/.xlight/custom_themes/*.json	Custom theme overrides
~/.xlight/custom_variants/*.json	Custom effect variants
~/.xlight/sweep_configs/	Parameter sweep configs
.stems/<md5>/	Cached stem separation output (adjacent to source audio)

Updating

The footer of every screen shows ui <commit> · built <date> · api <commit> — when either commit falls behind main, update like this:

git pull
docker compose exec xonset sh -c "cd src/review/frontend && npm run build"
docker compose restart

Then hard-refresh the browser (Ctrl+Shift+R).

• git pull — the app code runs from your checkout (bind-mounted into the container), so pulling covers most of the update.
• The npm run build step rebuilds the web UI. Only needed when frontend files changed (src/review/frontend/), but it's fast and always safe.
• docker compose restart — restarts the Python backend so pulled backend changes take effect (it does not hot-reload). Expect a couple of quiet minutes at [1/5] while pip re-checks dependencies.

Only rebuild the image (docker compose up -d --build) if .devcontainer/Dockerfile itself changed — a new system-level dependency, which is rare.

Output files

The UI workflow writes these next to the source MP3:

song.mp3
song/
├── song_hierarchy.json         # Analyzer output (L0–L6 hierarchy)
├── song_story.json             # Story builder output (sections, roles, moments)
└── song.xsq                    # Sequence to import into xLights
.stems/<md5>/                   # Cached Demucs stem separation (drums, bass, vocals, guitar, piano, other)

_hierarchy.json and _story.json are caches — re-running the pipeline reads them when nothing relevant has changed. .xsq is the deliverable.

Importing into xLights

In xLights: File → Open Sequence, point at song.xsq. The .xsq is self-contained; xLights resolves effects and timing from the file.

Known issues

Issue	Fix
TorchCodec is required warning	Harmless — can be ignored
Stem separation slow on first run	Normal — Demucs downloads a ~200 MB model. Cached after first run.
whisperx alignment model fails	docker compose exec xonset sh -c "pip install huggingface_hub && huggingface-cli login"

Running tests

docker compose exec xonset pytest tests/ -v