← Light Shows Guide

Getting started with xLights

Updated 27 October 2026

xLights is the free, open-source software we use to design and sequence every light show we build. It looks daunting the first time you open it, but the work breaks down into a few clear steps. This guide walks through them in the order we follow, from picking the songs to the show switching itself on every evening.

What you need

• A computer running Windows, macOS or Linux. xLights runs on all three, though big sequences render much faster on a reasonably modern machine.
• Pixels. Individually addressable LEDs, usually WS2811 strings with 12mm bullet pixels. Each pixel can be any colour and is controlled on its own, which is what makes the effects possible.
• A controller to turn the data from xLights into signals the pixels understand. For a first prop, a small Wi-Fi board running WLED is plenty. For a full display you'll want a dedicated pixel controller with more outputs.
• Power supplies sized for your pixel count, with fuses on every output.
• Music you have the right to play (more on that below).
• A player to run the show on its own once it's finished. Most people use Falcon Player (FPP) on a Raspberry Pi or a controller that has it built in.

You can download xLights from xlights.org, and the xLights manual covers every screen in detail.

Choosing the songs

Every show we build starts with the playlist, before a single pixel is mapped. The songs decide the mood, the length of the show and how much sequencing time you're signing up for.

What we look for:

• A clear, steady beat. Songs with strong drums and obvious changes (verse, chorus, drop) are far easier to sequence, and they look better because the audience can see the lights hit the music.
• Two to four minutes long. Longer tracks take hours more to sequence and lose people standing in the cold. If a song runs long, we trim it in Audacity before sequencing.
• Something for everyone. A family-friendly mix: a big recognisable opener, a couple of crowd favourites, something gentle in the middle and a strong finish.
• A show of about 10 to 20 minutes. That's enough for people to watch a full loop without losing interest, with a short static "pause" display between loops.

Our Christmas and Halloween shows were built exactly this way: we chose the songs first, put them in running order, then sequenced each one separately and joined them up in a playlist at the end.

A note on rights: playing music at your own home for passers-by is common, but a business, venue or public event usually needs a music licence. In the UK that's TheMusicLicence from PPL PRS. If in doubt, check before the switch-on.

Installing xLights and the show folder

When xLights starts for the first time, it asks for a show folder. Everything about your display lives in it: the controller setup, the layout, the sequences and the rendered show files. Make a dedicated folder (for example Christmas Show) and keep the music in a subfolder inside it.

Back the show folder up regularly. xLights keeps backups of its own when you save, but a copy somewhere else (cloud storage, a USB stick) has saved more than one season.

xLights has three main tabs, and you'll work through them left to right:

1. Controllers: what hardware you have and how to talk to it.
2. Layout: what your props are and where they sit.
3. Sequencer: what the lights do, and when.

Controllers

On the Controllers tab, add each controller in your display. Many controllers (including FPP, Falcon and WLED) can be found automatically with Discover. Otherwise, add them by hand as an Ethernet controller, with the IP address, protocol and how many channels it handles.

• Protocol: DDP is the simplest for WLED and FPP. E1.31 (sACN) and Art-Net also work, and are common on larger controllers.
• Channels: each RGB pixel uses three channels, so a 150-pixel prop needs 450.
• Give controllers fixed IP addresses on your router, so they don't move between shows.

Once your props are in the layout, use the controller's Visualise view to drag each prop onto the output port it's wired to. xLights then works out the start channels for you.

Planning your layout

A good show is mostly decided before you buy a single pixel. We plan every display as a picture first, in the xLights Layout tab, with a photo of the real house behind it. Here's the plan for our own house, with the photo dimmed so you can see the props:

How we go about it:

1. Photograph the house straight on. Stand where most people will watch from, usually the pavement opposite, and take the photo at dusk so the outline is clear. Use it as the layout's background image. Everything you place on top of it is then roughly where it will really be.

2. Start with the outline of the building. Window frames, door frames, the roofline and the corners give the house its shape in the dark. On our plan they're the single lines around both windows, the door and up each side of the house.

3. Add a few big features. The pieces people remember are the large ones: a mega tree, a matrix and big spinners. We have a mega tree on the left, two tall matrices either side of the front door for text and pictures, and a large spinner in the window above. Choose two or three focal points rather than many small ones.

Don't stop at the walls. The big V on our plan is two pixel strings hung like a garland, from each side of the house down to a single pole in the front garden. It pulls the display out towards the road, and it's a cheap way to make a show look much bigger.

4. Fill in with props, symmetrically. Snowflakes, stars, starbursts and arches fill the gaps. Mirroring them left and right of a centre line (our front door) makes the display look designed rather than collected, and lets effects bounce from side to side.

5. Think about how effects will move. xLights draws many effects across the whole layout, so props that line up make sweeps, waves and chases read clearly. Arches in a row, a line of snowflakes, floods running up both slopes of the roof, or garland strings running out to the pole all give an effect somewhere to travel.

6. Count pixels and plan the wiring. Once the plan looks right, note each prop's pixel count and which controller output it will use. Keep each run short, and plan where power will be injected on long runs. Some props here also need cable routes across the drive or the garden, so we plan those before anything goes up.

7. Use more than one preview. xLights can hold several layout previews. We keep one for Christmas and one for Halloween (the Preview box above the layout), so props that only appear in one season don't clutter the other.

Keep the plan 2D to begin with. Once the props are placed, xLights' 3D option lets you set depth for things like the mega tree and arches that stand out from the wall.

Laying out your props

The Layout tab is where you tell xLights what each prop is. Each prop is a model, and xLights has ready-made ones for the common shapes:

• Single line and poly line for rooflines, gutters and window outlines.
• Arches, candy canes, stars, circles and spinners.
• Matrices for flat grids of pixels that can show text, pictures and video.
• Trees for mega-trees and smaller pixel trees.
• Custom models for anything else, such as our spider and tombstone (see the next section).

Start by setting a photo of the front of the house as the background image, then place each model where it really sits. The closer the layout matches real life, the better effects that sweep across the display will look, because xLights draws them across the layout, not prop by prop.

If you buy commercial props, the makers usually supply an .xmodel file you can import, so you don't have to map them yourself.

Finally, put related props into groups (all the arches, all the windows, the whole house). You'll sequence groups far more often than single props.

Building props from 3D models

Custom props are where a display stops looking like a kit. We design ours in 3D first, whether the finished prop is cut from foam board or corrugated plastic, or 3D-printed.

1. Start from a model or a shape. Design the outline in a CAD tool such as Tinkercad (free and easy) or Fusion. Or start from an existing model on Printables or Thingiverse, checking that its licence allows what you're doing with it. Keep the shape bold and simple: fine detail disappears once it's lit.

2. Lay out the pixel holes. Bullet pixels need 12mm holes. Space them evenly along the lines you want lit. Around 25 to 50mm apart reads well from the street, and closer gives a smoother line. If you lay the holes out on a regular grid in the CAD model, the xLights mapping later is much simpler.

3. Make the prop.

• Flat props (like our spider and tombstone): print the outline and hole positions full-size as a template, stick it to foam board or coroplast, punch the holes and cut around the shape.
• 3D-printed props: split the model into pieces that fit your printer bed, with joining tabs or pins, and print in PETG or ASA if it will live outside. PLA softens in the sun. Diffusers, pixel clips and controller enclosures can be printed the same way.

4. Wire it in order. Push the pixels through in one continuous run, and note the order as you go. Pixel 1 is wherever the data enters. Our tombstone runs round the edge and then through the letters R, I and P, 146 pixels in total.

5. Map it in xLights. Add a Custom model and size its grid to match your hole layout. Load your CAD drawing or a photo of the prop as the model's background image. Then click each hole in wiring order to number the pixels 1, 2, 3 and so on. Check it with Wiring view in the model editor, then test it on the real prop. Running a simple chase effect shows straight away whether any pixel is out of order.

xLights can also place real 3D objects (.obj files) in the layout as mesh view objects. That's useful for seeing your house or a big set piece in 3D around the lit props, but the pixels themselves always come from the model.

You can see more of our props, from template to first light, in the build diary. Printed parts are covered on our 3D design & print page.

Sequencing a song

This is the fun part, and the part that takes the time. A rough guide: expect several hours per minute of music for your first few sequences, getting quicker as you build up habits and presets.

1. Create the sequence. Choose New Sequence, pick Musical sequence and select the song. Use 50ms frame timing (20 frames per second) to start. 25ms is smoother but makes heavier files.

2. Add timing tracks. Timing tracks are the marks you line effects up against. Add a track for the beat and another for the song's sections. You can generate beats and bars automatically from the audio, or play the song and tap along with the T key to drop marks by hand. Lyrics timing tracks drive singing faces if you have them.

3. Block out the song. Before adding detail, lay a simple effect on whole groups for each section: a colour wash in the verse, something bigger in the chorus. This gets the shape of the show right early.

4. Add the detail. Drag effects from the effects bar onto models and groups, snapping their edges to timing marks. The ones we use most:

• On, Color Wash and Twinkle for steady sections and quiet moments.
• Bars, Wave, Spirals and Butterfly for movement across matrices and trees.
• Shockwave, Fan and Meteors for hits and drops.
• Text, Pictures and Video on matrices.

Each effect has settings, and most can change over time with value curves (for example a spiral that speeds up into the chorus). Save combinations you like as presets so the next song is quicker.

5. Preview and render. Watch it in the House Preview as you go. When a section is done, render and play it back properly. Saving the sequence also produces the .fseq file that the player uses.

You don't have to sequence everything yourself. Sequence vendors sell finished sequences for popular songs, which xLights can map onto your own props. Even then, expect to spend time adjusting them to your layout.

Running the show

Your computer doesn't need to stay on all season. Once the sequences are finished:

1. Upload them to the player. FPP Connect in xLights sends the .fseq files and music straight to your FPP player.
2. Build a playlist in FPP: your songs in running order, with a static "pause" sequence between loops if you like.
3. Schedule it, for example 5pm to 10pm every evening from the first of December.
4. Sort out the sound. Speakers by the display work for small shows. For anything bigger, a low-power FM transmitter lets people listen in their cars, with a sign showing the frequency. Check the local rules on FM transmitters first.

Test the full playlist on the real display a few nights before the switch-on, ideally with someone watching from the road.

Tips we learned the hard way

• Map and test every prop before it goes outside. Fixing pixel order on the bench takes minutes. On a ladder in November, it takes an evening.
• Plan your power. Long pixel runs lose brightness and colour, so add power partway along. Never run more current than the fuse and cable are rated for.
• Keep the colour count down. Two or three colours per section looks deliberate. Every colour at once looks like a fault.
• Start small. One prop and one song, finished properly, teaches more than a whole house half done. Our first show was a spider and a tombstone.
• Save often and back up the show folder. Long sequences are a lot of work to lose.

If you'd rather skip the learning curve, we design, build, sequence and install complete displays. Tell us about your property and we'll sketch out some options.

Rather we built it for you?