WLED xLights Christmas Realtime How-To

WLED and xLights: When You Need It, DDP Setup, and Getting Control Back

When WLED alone is enough and when xLights is worth it, how to send xLights to WLED over DDP or E1.31, and how WLED takes back control after a show.

By

Written by Jamie Conde, who builds WLED Max at MeowScript. WLED Max is an independent app and is not affiliated with or endorsed by the official WLED project.

Quick answer: WLED runs effects on its own; xLights is for shows sequenced to music across many props. They work together: xLights sends every pixel’s color over the network, and WLED just displays it. In xLights add the light as an Ethernet controller with vendor WLED and protocol DDP. WLED needs no setting for DDP. When xLights stops sending, WLED goes back to its own effect after 2.5 seconds.

Do you need xLights at all?

Most people with WLED don’t. A rule of thumb from the WLED forum sums it up: WLED handles a lot of LED displays by itself, and xLights is the tool when you want to control your whole yard as one show.

You wantUse
Nice effects on a roofline, tree or window, changing by scheduleWLED alone, with presets, playlists and timers
Holiday patterns like red and white or candy caneWLED alone, see Christmas patterns
Several lights showing the same effect in syncWLED alone, with UDP sync
Lights timed to a song, beat by beatxLights
A mega tree, matrix, arches and roofline acting as one displayxLights
A show that runs every night from a schedule without a computerxLights to make it, Falcon Player (FPP) on a Raspberry Pi to play it

xLights is free and powerful, and also a hobby of its own. Sequencing one song can take an evening. If you just want the house to look good in December, WLED alone gets you most of the way.

How the two fit together

In a show, WLED stops being the brain. xLights (or FPP playing the show) sends a stream of frames, each with the color of every pixel. WLED switches into realtime mode: it clears the strip, shows whatever arrives, and ignores its own effects, presets and timers until the stream stops.

That’s why the most common xLights question on the WLED forum is really “why does my WLED ignore the app?” See WLED stuck in realtime mode for that side.

DDP or E1.31?

WLED accepts three show protocols. DDP and E1.31 are on by default. Art-Net needs Type set to Art-Net under Network DMX input in Sync Interfaces, which moves the listener from port 5568 to 6454, so E1.31 and Art-Net can’t both be on at the same time.

DDPE1.31 (sACN)Art-Net
Port404855686454
Setting in WLEDnone, always onNetwork DMX input, DMX modethe same, Type Art-Net
Universesnone, just a pixel offset170 RGB pixels per universethe same as E1.31
RGBWyes in WLED, but xLights’ WLED upload refuses ityes, with DMX mode Multi RGBWyes
xLights default for WLEDyes

Use DDP unless you have a reason not to. It’s what xLights picks when it discovers a WLED controller, there are no universes to line up, and it’s efficient. Use E1.31 for RGBW pixels, or if your show is built around universes in FPP.

Set up WLED

For DDP there is almost nothing to do. Check these in Config›LED & Hardware (LED Preferences on 0.14 and 0.15):

  • The LED count and the order of outputs match the real wiring.
  • The light has a fixed address (a DHCP reservation in your router).

For E1.31, open Config›Sync Interfaces and find Network DMX input in the Realtime section:

  • Type: E1.31 (sACN).
  • Start universe: the first universe xLights sends to this light (1 by default).
  • DMX mode: Multi RGB for RGB pixels, Multi RGBW for RGBW. WLED’s docs call Multi RGB “the mode you want to use for xLights”.
  • Multicast: match whatever xLights sends. Unicast (off) is simpler on Wi-Fi.

The rest of the Realtime section matters for both protocols:

  • Timeout (2500 ms by default): how long WLED waits after the last frame before returning to its own effect.
  • Force max brightness: shows the stream at full brightness instead of your WLED brightness.
  • Use main segment only: the stream paints only the main segment while the others keep their WLED effects. With this on, WLED ignores the lor override described below.
  • Respect LED Maps (0.15 and newer): applies your LED map (ledmap.json) to the stream too.

In WLED Max on iPhone, the E1.31 settings and the timeout are under Device Settings, Sync Interfaces, in the E1.31 / DMX / Art-Net section. On Android it’s the same place: Device Settings, Sync Interfaces, E1.31 / DMX / Art-Net. The app’s timeout field counts in steps of 100 ms, so 25 there means 2500 ms.

Set up xLights

xLights has WLED built in as a controller vendor, with models for generic ESP8266 and ESP32 boards and several QuinLED boards.

  1. Open the Controllers tab and click Add Ethernet. (Or try Discover: it finds WLED lights on your network and fills in the rest.)
  2. Enter the light’s IP Address, set Vendor to WLED, then Model to WLED with Variant Generic ESP32 or Generic ESP8266, or pick your board as the Model (QuinLED Dig-Uno, Dig-Quad, Dig-Octa and others).
  3. Set Protocol to DDP. Leave Keep Channel Numbers off.
  4. Build your props on the Layout tab, then go back to the controller, click Visualise and drag each prop onto the port it’s wired to.
  5. With Auto Size on, xLights works out the channel count from the props. By hand it’s LEDs × 3 for RGB.
  6. Save, and turn on output to lights (the light bulb button in the toolbar).

Should you let xLights upload to WLED?

The Upload Output button writes the port setup (LED counts, GPIO pins, LED type, color order) into WLED and reboots the light. It’s handy for a fresh controller, but it overwrites WLED’s LED settings, and there are forum reports of it clearing GPIO settings. If your WLED is already set up and working, set the LED count in WLED yourself and skip the upload. Back up first either way: WLED backup and restore.

Two upload errors you might see, and what they mean:

  • “The DDP ‘Keep Channel Numbers’ option is not support with WLED”: turn that option off.
  • “Four Channel Pixles and DDP, do not work well in WLED”: your props are RGBW. Switch that controller to E1.31 and set WLED’s DMX mode to Multi RGBW.

Wi-Fi, frame rates and big shows

Streaming over Wi-Fi works for a few controllers. It gets harder as a show grows: every pixel of every frame goes over the air, and forum threads describe shows with a dozen Wi-Fi controllers dropping to a few frames per second.

  • Keep the computer or FPP that sends the show on a cable, so only the last hop is Wi-Fi.
  • Turn on Suppress Duplicate Frames on the controller in xLights, so frames that didn’t change aren’t sent again.
  • For E1.31, WLED’s docs recommend no more than 3 universes (510 RGB pixels) per light for a smooth 40 frames per second, and 9 universes at most on ESP8266.
  • WLED shows a new streamed frame at most once every 16 ms, which caps it at a little over 60 frames per second regardless of what you send.
  • For big displays, use ESP32 boards, and wired Ethernet boards where you can.

Getting control back after the show

When the stream stops, WLED waits for the timeout (2.5 s by default) and then goes back to exactly what it was doing: same effect, same brightness. Streaming doesn’t change any of WLED’s own settings.

When you turn off output in xLights, it sends one all-black frame first. So the lights go dark for the length of the timeout, then WLED’s effect comes back.

If WLED won’t come back, something is still sending. Find it from the light’s /json/info (the lip field shows the sender’s IP), or override it:

  • Send {"lor":1} to /json/state to ignore the stream until it stops, or {"lor":2} to ignore it until the next reboot.
  • Send {"live":false} to leave realtime mode right away. If the sender is still streaming, the next packet puts the light straight back into realtime mode, so stop the sender or use lor.

In WLED Max, the Control tab shows an External Control Active banner when a light is being driven by xLights or anything else (on Android in WLED Max 1.1.4 and later). Tap Take Control and choose Override Until Data Stops or Override Until Reboot. Those are the same two override values. On Android 1.1.2 and older, the banner names the sender (”… is controlling this device”) and the two buttons are Until Data Stops and Until Reboot.

To keep the last frame on the lights instead, set the timeout to 65000, which WLED treats as never.

FAQ

Do I need xLights for WLED? No. WLED runs effects, presets, playlists and timers on its own. xLights is for music-synced shows across many props.

Which port does xLights use for WLED? DDP on port 4048, E1.31 on 5568, Art-Net on 6454.

Do I have to enable DDP in WLED? No. WLED always listens for DDP. E1.31 and Art-Net are set in Sync Interfaces under Network DMX input: Type picks E1.31 or Art-Net, and DMX mode must not be Disabled.

Why does WLED stay dark after the show? xLights sent a black frame when you turned output off, and WLED shows it until the timeout ends. If it stays dark longer, another sender is still streaming.

Can I use WLED effects and xLights together? Yes, two ways: turn on Use main segment only, so the show runs on one segment and the others keep WLED effects, or let WLED run normally and switch to xLights only while the show plays.

Every feature in WLED Max, our WLED app for iOS and Android, is free for one light.