Beginner guide
Your light show, step by step
How to load the sequence you bought into xLights, add the song, and
make it play on your house. Written for first-timers, with no sequencing
experience needed.
⏱ About 30 minutes the first time
🎶 Works with any layout
💻 xLights for Windows & Mac
Download the printable PDF
Part of the beginner series:
1. Build Your Display ·
2. Connect Your Controller ·
3. Load Your Sequence
The whole journey at a glance
Menu names in xLights can shift a little between
versions. If something on your screen looks slightly different, look for the same words close by.
Pictures on this page are simplified drawings, not exact screenshots.
Before you start
Make sure you have these four things
💻 xLights is installed
xLights is the free program that runs your show. Download it from xlights.org
if you haven't already. Use a recent version.
🏠 Your display is set up
Your own props (roofline, arches, trees...) are already drawn on the Layout
tab. Building a layout is a one-time job that this guide doesn't cover; the xLights manual and videos
explain it.
📦 Your sequence download
The .zip file from your
account downloads. You'll unzip it in Step 1.
🎵 The song (you'll buy it in Step 2)
The music is not included with the sequence. Music has its own copyright, so you buy
the song yourself. It costs about a dollar.
Words you'll see in this guide
| Word | What it means, in plain English |
|---|
| Show folder | The one folder on your computer where xLights keeps everything about your display: your layout, your controllers, your sequences. |
| Layout | The map of your display in xLights: every prop, where it sits on the house, and how many lights it has. |
| Model (or prop) | One thing that lights up: a roofline, an arch, a mega tree, a singing pumpkin. |
| Group | Several models bundled together so one effect can run across all of them. In these sequences, group names start with GRP_. |
| Sequence (.xsq) | The "choreography" file: which lights do what, at which moment of the song. |
| Effect | One lighting action on a prop, such as a chase, a twinkle, a colour wash or a sweep. |
| Timing track | Marks that follow the music (beats, bars, verse/chorus, lyrics). They line effects up with the song. |
| Mapping | Telling xLights which of your props should play which part of the designer's show. This is the heart of the whole process (Step 5). |
| Render | xLights working out every light's colour for every moment, so the show can play. |
| .fseq | The finished, rendered show that your player (FPP, the Falcon Player, or xSchedule) actually plays. xLights writes it when you save. |
How it works
The big idea
Every house is different. The sequence was designed on the designer's house, so its
effects are attached to the designer's props. Your job is simply to say which of
your props should play each part.
Why not just open the sequence file?
You can open it, but it would try to light the designer's props, which don't exist in your
layout, so your house would stay dark. Instead you will make a brand-new, empty sequence
for your own house with the song in it (Step 3), then import the designer's effects into
it, choosing where each part goes (Steps 4 and 5). The purchased file stays untouched, so you can always
start over.
Good news for your next sequence
Sequences made for the same display (Christmas or Halloween) use the same prop names. Once you've
matched them up and saved your mapping (Step 5), every future sequence for that display
imports in about a minute.
Fewer props than the designer? No problem.
You don't have to fill every match. Anything you leave out is simply skipped, and several of the
designer's parts can share one of your props.
1
Step one
Unzip into your show folder
- Find your show folder. In xLights, open the Controllers tab
(called Setup in older versions). The folder's location is shown at the top.
- In File Explorer (Finder on a Mac), open that folder and make a new folder for the song,
for example This Is Halloween.
- Unzip the download into that new folder: right-click the .zip
→ Extract All, and choose the song folder.
Never unzip straight into the show folder itself
The download includes the designer's layout file, xlights_rgbeffects.xml.
It's there for reference. Your show folder has a file with the same name, which is your layout.
Unzip into the song's own folder so yours is never replaced.
- Open Song_Links.txt from the download. It names the exact
recording the show was timed to, with links (Apple Music, Amazon Music, and the YouTube video it was made from).
- Buy the song from a music store: Amazon gives you an MP3; the iTunes Store
gives an .m4a file. xLights plays both.
- Save (or move) the song file into the song's folder from Step 1.
Buy it, don't stream it
A song "downloaded" inside a streaming subscription (Apple Music, Amazon Music Unlimited, Spotify) is locked
to that app, and xLights can't play it. You need a purchased copy.
It must be the same version
Same artist, same recording. Not a remix, radio edit, live or "extended" version. The lights are timed to a
few hundredths of a second; even a second of extra silence at the start makes the whole show run late.
3
Step three
Make your own sequence with the song
This creates an empty sequence for your house, with your song
loaded, ready to receive the effects.
- In xLights choose File → New Sequence (or press Ctrl+N).
- Choose Musical Sequence.
- Pick the song you bought in Step 2, from the song's folder.
- For timing, choose 25ms (40fps). These shows are built at 40 frames a second,
so every effect lands exactly where it was designed.
- Pick the view that shows all your props (usually the master view) and click Quick Start.
You'll land on the Sequencer tab: your props down the left, the song's waveform
across the top, no effects yet.
- Save it now with File → Save Sequence As.
Put it in the song's folder under a new name, such as
This Is Halloween - My House.xsq.
Don't save over the purchased file
Give your sequence its own name. Keep the purchased ..._house.xsq exactly as it
came, so you can always import from it again.
Chose the wrong timing by mistake?
The simplest fix is to repeat this step and make the sequence again. Nothing is lost: you haven't imported
anything yet.
4
Step four
Import the effects
- With your new sequence open, choose Import →
Import Effects from the menu bar.
- Browse to the song's folder and pick the purchased file, ..._house.xsq.
- The mapping window opens. That's Step 5.
5
Step five
Match the effects to your props
- Left side: your props, each with an empty Map To box.
Right side: the designer's props that hold effects.
- Drag a name from the right and drop it into the Map To
box of the prop that should play it. Rooflines to rooflines, matrix to matrix, and so on.
- Work down your list. Leave a box empty if nothing fits; that prop just stays out of this song.
- Timing tracks: in the timing-track list at the top of the window, tick the tracks you
want (beats, bars, sections, and the lyric track ending in _Vocal). They're
handy markers, and singing faces need the lyric track.
- Click Save Mapping and save the .xmap file in your
show folder, e.g. Christmas map.xmap. Next time, click
Load Mapping and it's all filled in.
- Click OK. The effects appear on your props in the Sequencer.
Mapping tips
★ Groups to groups
Most effects live on the designer's
groups (GRP_...). Map them to your matching groups for the fullest show.
★ Reuse freely
One of the designer's props can feed
several of yours: drop the same name into more than one box.
★ Shapes matter most
Match by shape: lines to lines (roofline,
fence, outline), round things to round things, flat panels to matrices.
★ Experiment
Not happy with a match? Just run
Import Effects again into a fresh sequence and try another.
6
Step six
Render, watch, and save
- Click Render All on the toolbar. The bar at the bottom shows progress; wait until it finishes.
- Press Play and watch the House Preview from beginning to end.
Every prop you mapped should come alive, in time with the music.
- Save with File → Save Sequence (Ctrl+S).
Saving also writes the .fseq file that your show player plays.
- Add the sequence to your show the way you normally do: upload the .fseq and the
song to FPP, or add it to an xSchedule playlist.
That's it. Enjoy the show!
The second song is much faster: unzip, buy the song, new sequence, Import Effects,
Load Mapping, OK, Render, Save.
Help
If something isn't right
| What you see | Why, and what to do |
|---|
| Lights are early or late compared to the music | The song isn't the exact same recording. Get the version listed in Song_Links.txt, then make the sequence again (Step 3) and import with Load Mapping. |
| A prop stays dark | It wasn't given a match in Step 5, or it isn't in the view you picked in Step 3. Run Import Effects again and map it. |
| My whole house is dark after import | Click Render All. If it's still dark, the mapping was probably left empty. Import again and drag names across before clicking OK. |
| No sound when I play | The song file was moved or renamed after Step 3. Put it back where it was, or make the sequence again with the song's new location. |
| My own layout disappeared | The designer's xlights_rgbeffects.xml was copied over yours. Restore yours from xLights' Backup folder inside your show folder, and unzip downloads only into a song folder (Step 1). |
| Singing face doesn't move | The _Vocal timing track wasn't ticked in Step 5, or your face prop uses a different face design. Select its Faces effects and pick your prop's face in the effect settings. |
| An effect looks squashed or stretched | Your prop has a different shape or size from the designer's. It still plays; try mapping it to a different prop. |
| My menus look different | xLights changes a little between versions. Look for the same words nearby: New Sequence, Import Effects, Map To, Render All. |
✓ Quick checklist for every new song
- Make a song folder inside your show folder
- Unzip the download into it
- Buy the exact song (Song_Links.txt), put it in the same folder
- New Sequence → Musical → your song → 25ms (40fps)
- Save As with your own name
- Import → Import Effects → ..._house.xsq
- Load Mapping (or drag & drop), tick timing tracks, OK
- Render All, play, Save
Your license, in short
This sequence is for your own display. Please don't share, resell or upload it. Music isn't
included; public or commercial shows may need separate music permission. The full terms are in
Digital_Content_License_ReadMe.pdf and our
Terms & Conditions.
Questions? Contact us
with the song name and your xLights version.
xLights is a separate, free program made by its own volunteer
team and is not affiliated with this content.