Description
xLights 2026.15 does not consistently maintain the configured output frame rate during sequence playback. In a 25 ms (40 FPS) sequence, actual DDP transmission can fall substantially below 40 FPS even though the sequence is configured for 40 FPS.
How it was verified
Initially this appeared to be a Wi-Fi/controller performance problem. Custom ESP8266 receiver diagnostics showed incoming DDP frame rates below 40 FPS. However, Wireshark captures on the xLights PC confirmed that the reduced frame rate was already present in the UDP/DDP traffic leaving xLights.
Investigation
Diagnostic instrumentation was added through the xLights output path, including xLightsTimer, TimerRgbSeq, OutputManager, and DDPOutput. This showed that frames were being lost before DDP transmission. OutputManager lock contention and UDP send failures were ruled out.
What appears to be happening
Two behaviors appear to interact. xLightsTimer::DoSendTimer() keeps _pending asserted while the wx timer notification is processed, allowing subsequent timer ticks to be discarded. Separately, TimerRgbSeq() suppresses callbacks when the calculated sequence frame has not advanced. Timer jitter can therefore produce a same-frame callback followed by a multi-frame jump, reducing actual output cadence.
Experimental fix
Two experimental changes were tested: clearing _pending before dispatching the queued wx timer notification, and allowing valid timer callbacks to reach output even when that means retransmitting the current sequence frame rather than suppressing the callback. These changes restored output to approximately the requested 40 FPS.
Validation
The modified 2026.15 build has subsequently been tested with 15 ESP8266 DDP controllers simultaneously. All remained near 40 FPS, including an overnight test in which one receiver accumulated approximately 2.8 million complete DDP frames with zero incomplete or rejected frames.
Supporting material
Attached is a ZIP containing the complete investigation report, diagnostic source changes, experimental source changes, diagnostic logs, and the exact compiled xLights executable used for the successful testing. The changes are provided as diagnostic/experimental work rather than a proposed final implementation; the maintainers can determine the appropriate architectural fix.
Reproduction sequence
An XSQ used during the original testing is also attached. It configures the test controllers/models for 800 pixels each to make the output-cadence problem easier to observe. The 800-pixel configuration is intentionally a stress/reproduction case; the later 15-controller validation used 28 pixels per controller.
xLights_40FPS_800Pixel_Reproduction.zip
xLights-2026.15-OutputTimer-DDP-BugReport-with-EXE.zip
Description
xLights 2026.15 does not consistently maintain the configured output frame rate during sequence playback. In a 25 ms (40 FPS) sequence, actual DDP transmission can fall substantially below 40 FPS even though the sequence is configured for 40 FPS.
How it was verified
Initially this appeared to be a Wi-Fi/controller performance problem. Custom ESP8266 receiver diagnostics showed incoming DDP frame rates below 40 FPS. However, Wireshark captures on the xLights PC confirmed that the reduced frame rate was already present in the UDP/DDP traffic leaving xLights.
Investigation
Diagnostic instrumentation was added through the xLights output path, including xLightsTimer, TimerRgbSeq, OutputManager, and DDPOutput. This showed that frames were being lost before DDP transmission. OutputManager lock contention and UDP send failures were ruled out.
What appears to be happening
Two behaviors appear to interact. xLightsTimer::DoSendTimer() keeps _pending asserted while the wx timer notification is processed, allowing subsequent timer ticks to be discarded. Separately, TimerRgbSeq() suppresses callbacks when the calculated sequence frame has not advanced. Timer jitter can therefore produce a same-frame callback followed by a multi-frame jump, reducing actual output cadence.
Experimental fix
Two experimental changes were tested: clearing _pending before dispatching the queued wx timer notification, and allowing valid timer callbacks to reach output even when that means retransmitting the current sequence frame rather than suppressing the callback. These changes restored output to approximately the requested 40 FPS.
Validation
The modified 2026.15 build has subsequently been tested with 15 ESP8266 DDP controllers simultaneously. All remained near 40 FPS, including an overnight test in which one receiver accumulated approximately 2.8 million complete DDP frames with zero incomplete or rejected frames.
Supporting material
Attached is a ZIP containing the complete investigation report, diagnostic source changes, experimental source changes, diagnostic logs, and the exact compiled xLights executable used for the successful testing. The changes are provided as diagnostic/experimental work rather than a proposed final implementation; the maintainers can determine the appropriate architectural fix.
Reproduction sequence
An XSQ used during the original testing is also attached. It configures the test controllers/models for 800 pixels each to make the output-cadence problem easier to observe. The 800-pixel configuration is intentionally a stress/reproduction case; the later 15-controller validation used 28 pixels per controller.
xLights_40FPS_800Pixel_Reproduction.zip
xLights-2026.15-OutputTimer-DDP-BugReport-with-EXE.zip