Review UI Guide

Review UI Guide

The whole workflow lives in seven tabs across the top of every screen:

xLightsAI  1 Library   2 Import   3 Analyze   4 Timeline   5 Theme   6 Extras   7 Export

The numbers indicate the natural order — drop a song in, walk through the tabs left to right, finish with a .xsq ready for xLights. You can revisit any tab at any time.

1. Library — empty state

Where you start the very first time. Just a drop zone: drag an MP3/WAV file — or a video file (mp4/mov/avi/mkv/webm), whose audio track is extracted automatically — onto it, or click "or click to browse files" to open a native file picker. Both mono and stereo audio are accepted; ID3 metadata is read automatically.

2. Analyze — pipeline running

After you drop a file, the app jumps straight to Analyze and starts the pipeline.

• Title bar — "Analyzing... <slug> · <duration>" on the left, elapsed/ETA and a skip to timeline → escape hatch on the right (it appears once enough has been detected to render something).
• Artist / Title fields — read from the MP3's ID3 tags. Edit either to override what's used for the synced-lyrics lookup.
• Phase pills — seven logical phases (loading audio → separating stems → tracking beats → finding bars → segmenting structure → song story → assigning themes). The active phase is outlined; completed phases get a green checkmark.
• Detectors column (left) — every algorithm the pipeline runs, in execution order, with status, library tag (system / demucs / librosa / vamp / madmom), and progress.
• Stream column (middle) — live SSE log lines from the pipeline.
• Findings column (right) — overall progress %, ETA, high-level outputs (waveform, beats, bars, sections, themes), and a live-growing Sections list as the structure detector finds boundaries.
• Song rail (far left, collapsible) — songs you've imported, grouped by folder. Switch songs without leaving the screen.

3. Analyze — complete

Same screen, after the pipeline finishes (~60–90s on a typical song with cached stems).

• Title bar flips to "Analysis complete" with a ▶ review timeline → button.
• All seven phases show green checkmarks; detectors show a full count (e.g. librosa_beats · 288, aubio_onset (drums) · 700 marks).
• Findings show 100%, per-category counts, and the section list with role + duration (01 Verse · 20s, 02 Pre Chorus · 19s, ...).
• Re-analyze (bottom left) re-runs the pipeline from scratch, ignoring any cache — useful after editing artist/title (for a fresh synced-lyrics lookup) or after a schema bump.

4. Timeline — review and adjust

The most-used screen. Verifies the analysis matched what you hear.

• Transport — play/scrub controls, current position / total duration.
• Zoom controls — narrows the visible window so you can scrub onto a single beat.
• Waveform — full-mix audio as a stereo waveform with a time ruler; click anywhere to seek the playhead.
• Sections row — colored boxes per detected section, labeled by role (Verse, Pre Chorus, Chorus, Bridge, Outro, Interlude, etc.). Click "Edit sections" to adjust boundaries by dragging.
• Stem waveforms (collapsible) — drums / bass / vocals / guitar / piano / other, rendered on demand — useful for verifying stem separation looks right.
• Raw algorithm tracks — every individual detector's output as a flash-on-event tick row, toggleable per-row to declutter.
• Playhead inspector (right column) — current position as bar X · beat Y of Z, the current section's name/color, and its start / end / duration.
• Nudge buttons — −10 ms / +10 ms to micro-adjust the active section's start time (hold-and-drag for repeated nudges).
• Go to Theme → finishes timeline review and moves on.

5. Theme — assign a look per section

Pick a theme (composite lighting "look") for each section of the song. Themes encode color palette, effect choice, blend modes, and parameter mappings.

• Section navigator (top) — every detected section as a clickable pill; the active pill outlines orange.
• Accept All Defaults — auto-assigns theme defaults to every section using the song's energy/genre profile — a good starting point.
• Theme grid — each card shows a 5-color palette swatch, the theme name (e.g. Aurora, Inferno, Stellar Wind), mood tags (ETHEREAL, AGGRESSIVE, ROCK, DARK, ...), and a one-line description. Click a card to assign it to the active section.
• Section beat strip — visualizes the selected section's beat structure.
• Section parameters — four sliders that fine-tune this section's render of the chosen theme:
  • Brightness — global intensity (0–1)
  • Hit Strength — accent emphasis on beats (0–1)
  • Dwell Time — how long held effects last (0–1)
  • Color Shift — palette rotation (0–1)

Per-section overrides are remembered when you switch sections; Accept All Defaults resets them.

6. Extras — Pictures & Shadow Text words

Optional per-song lyric-word triggers for two effects: image accents on Matrix/Mega Tree props (Pictures), and a two-layer drop-shadow word effect (Shadow Text). Nothing here is required — skip straight to Export if you don't want either.

• Suggested topics — lyric words from this song that don't have a matching image in your shared image library yet. Per word:
  • Create image — opens a pre-filled AI image-generation prompt you can copy into Gemini (or any image generator), styled to match the catalog's flat-icon look.
  • Choose image — upload an image file directly for this word.
  • Shadow — tags the word for the Shadow Text effect (see below). Click again to untag (shows Shadow ✓ while active).
  • A previously unmapped word shows an "unmapped from <file>" note and a Restore match button instead.
• Already matched — words already resolved to a library image, shown as "word" → filename.png. Same Create image / Choose image / Shadow buttons, plus Unmap — suppresses the Pictures effect for that word in this song only (the library image itself isn't deleted, and stays available for other songs).
• Moving Head Triggers — a separate list of lyric words that fire a Moving Head accent when sung, independent of Pictures/Shadow. Three built-ins (shake, bounce, spin) are on by default; uncheck (Remove) to disable one for this song. Add your own word either from the "Add from this song's lyrics" picker or the custom-word box at the bottom, assigning it one of four motions: shake, bounce, spin, or flash (points every head straight up at full white).

What Pictures and Shadow actually do at generation time

• Pictures cycles catalog images in as an overlay on Matrix/Mega Tree props, timed to each lyric match, with a short pan and an occasional zoom/rotation flourish.
• Shadow Text renders the tagged word itself as two stacked layers on the same Matrix/Mega Tree props whenever it's sung — the word in the song's main palette color on top, a slightly offset copy in a second palette color directly behind it, producing a drop-shadow look — with the same pan/zoom/rotation movement Pictures bursts use.

Both are entirely optional accents layered on top of whatever the Theme tab already assigned; neither is required to generate a sequence.

7. Export — produce the .xsq

The terminal step. Generates the xLights .xsq sequence from the analyzed song + assigned themes + the repo's committed prop layout.

• Generate — produces the .xsq.
• Layout summary — number of models/groups/props detected from layout/xlights_rgbeffects.xml, and which 8-tier Power Groups were auto-generated (heroes, compounds, props, beats, etc.).
• Generation options — variation seed, repetition policy, palette restraint, duration scaling. Most users leave defaults.
• Download Package — bundles the generated .xsq with layout/xlights_rgbeffects.xml and layout/xlights_networks.xml into a single .xsqz (xLights' own zipped-sequence-package format) ready to import directly into xLights.

8. Library — populated state

Where you go to switch between songs once you've imported a few.

• Filter pills — All / Draft / Analyzed / Themed. Draft = imported but not analyzed; Analyzed = pipeline complete; Themed = at least one section has a theme assignment.
• Folder groups — songs are bucketed by folder_id (default unfiled); click the chevron to collapse/expand.
• Song row — title, artist (from ID3 or override), and a status badge. Click anywhere on the row to open it in whatever tab you visit next.
• Song rail — a permanent compact list across every screen, so you can switch songs without leaving the current step.