added support for fseq files

[Andrejchrcek]

This PR adds a usermod for playing FSEQ files from xLights.

• Added an "FSEQ" button to the main menu.
• Implemented a basic file explorer for uploading, deleting, and playing FSEQ files.

The feature is still in development, and further improvements are planned.
Feedback and testing on different ESP32 boards are welcome!

Summary by CodeRabbit

• New Features
  • Added support for FSEQ file playback from SD cards, along with a new web interface that provides controls for file listing, uploading, deletion, and playback management.
  • Enhanced remote synchronization and control for LED animations via network protocols.
• Documentation
  • Introduced comprehensive installation and configuration guides to help users set up and use the new FSEQ and SD file management functionalities.

[coderabbitai[bot]]

Walkthrough

Adds a complete FSEQ subsystem: README, SD manager, FSEQPlayer playback engine, Web UI + REST endpoints, two usermods (UsermodFseq, UsermodFPP) with UDP/FPP sync and upload handling, usermod registration, and a simplified particle velocity change.

Changes

Cohort / File(s)	Summary
FSEQ Documentation usermods/FSEQ/README.md	New README describing installation, PlatformIO flags, web UI integration, HTTP endpoints, features, and default SD SPI pins.
FSEQ Playback Engine usermods/FSEQ/fseq_player.h, usermods/FSEQ/fseq_player.cpp, usermods/FSEQ/fseq_player.cpp.header_add	New FSEQPlayer: header/file parsing, frame processing, timing/sync, seeking, loop/repeat behavior, playback state and static member definitions.
SD Card Management usermods/FSEQ/sd_manager.h, usermods/FSEQ/sd_manager.cpp	New SDManager: SD init for SPI/MMC, shutdown, directory listing and file deletion APIs using SD adapter.
Web UI & REST API usermods/FSEQ/web_ui_manager.h, usermods/FSEQ/web_ui_manager.cpp	New WebUIManager: serves embedded UI at /fsequi and registers REST endpoints for SD listing/upload/delete and FSEQ playback control/status.
Core Usermods usermods/FSEQ/usermod_fseq.h, usermods/FSEQ/usermod_fpp.h	New UsermodFseq: integrates SD, FSEQPlayer, Web UI, configurable SPI pins and reinit. New UsermodFPP: AsyncUDP FPP sync/ping, HTTP upload handling, playback control and system/status endpoints.
Usermod Registration usermods/FSEQ/register_usermod.cpp	Registers UsermodFseq and UsermodFPP conditionally via preprocessor flags.
Particle System wled00/FXparticleSystem.cpp	Simplified particle velocity variation: replaced circular/rejection sampling with uniform random offsets in [-var, var].

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

• Pay extra attention to:
  • FSEQPlayer timing, frame indexing, end-of-stream and loop behavior.
  • UsermodFPP AsyncUDP handlers, multicast/ping logic, and upload buffering/finalization.
  • Web API parameter validation, multipart upload handling, and concurrent SD access.
  • SD SPI reinitialization: pin allocation/deallocation and SPI port reconfiguration.
  • Embedded Web UI client/server interactions (upload/delete/play/stop flows).

Suggested reviewers

• willmmiles
• netmindz
• blazoncek
• DedeHai

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.68% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'added support for fseq files' is a clear, concise statement reflecting the primary change — introducing FSEQ playback functionality as a new usermod.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d172a0eaa7dec8cd65ecdd54f667f6dd40abbf73 and 2e90b5d9947600b211971a100eff1c81bf8b2a0b.

📒 Files selected for processing (1)

• wled00/FXparticleSystem.cpp (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• wled00/FXparticleSystem.cpp

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[netmindz]

Now we have playback of gif files in the main code. Is there any chance this could be extended to support this file type as well or is there too little in common?

[blazoncek]

@netmindz there is an old PR from @fastbytes #2413 and @constant-flow #2292 for FSEQ/TPM2 file playback we never got around to properly migrate/update for WLED. These have nothing in common with GIF playback except perhaps SD card support.

I am really sorry those old PRs were left hanging but one man just couldn't do everything. I hope this fares better or old PRs are revived.

[Andrejchrcek]

xLights can now discover WLED using the network discovery feature. FPP Connect detects the WLED device and allows uploading FSEQ files directly.

[netmindz]

No worries if there isn't anything in common. I had a vague memory I'd seen a comment about GIF just being the first to be done then extend, but maybe that was just aspirational rather than any software architecture/design

[netmindz]

@coderabbitai review

[coderabbitai[bot]]

:white_check_mark: Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[netmindz]

xLights can now discover WLED using the network discovery feature. FPP Connect detects the WLED device and allows uploading FSEQ files directly.

So someone presumable has already written FSEQ support in a fork somewhere if xLights has an upload option?

[blazoncek]

Since I'm already getting tonnes of mail, let's join the fray.

What I'll veto is the change in UI. Please remove Fseq button from UI as this is a usermod. Usermods (can) have their own HTTP handler (as you've shown) and you can get a pointer to it into Info dialog.

[Andrejchrcek]

@coderabbitai review

[coderabbitai[bot]]

:white_check_mark: Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Andrejchrcek]

I have tested the code, and it works fine for me. However, it would be great if someone could test it on different boards to ensure compatibility.

[noman1228]

ESP32-DevkitV4 (wroom32-u) tested working Freenove Wrover wrover-e) confirmed working DoItDevKit1 - Confirmed Working D32 - Confirmed Working ESP32-TETH- Confirmed Working

[PaoloTK]

I'm interested in testing this in production. I have a pretty aggressive use case, so can provide feedback on robustness hopefully. I have 4 Quinled-Dig-Octa Brainboards running around 2k pixels each. I would like to run FSEQ off an SD card on each board and keep the boards synced between each other over WiFi. How feasible is this currently?

[Andrejchrcek]

Hi, thanks for your interest. Syncing FSEQ files over Wi‑Fi using Falcon Player (FPP) should work. I’ve built a custom remote that sends the same data as the FPP server. I can’t confirm 100% without testing, but it ought to work. Let me know if you run into any issues.

[github-actions[bot]]

Hey! This pull request has been open for quite some time without any new comments now. It will be closed automatically in a week if no further activity occurs. Thank you for contributing to WLED! ❤️

[netmindz]

This PR needs to be updated to follow the new usermod setup that does not require changing usermods_list.cpp but does require the library.json

[npike]

Pretty excited to see this PR as someone who has a lot of WLED devices deployed but is lately suffering from congestion on the 2.4ghz wifi. Thank you for your work on this @Andrejchrcek

I tried this on a DigUno ESP32+AE+, configured as:

int8_t configPinSourceSelect = 5;
int8_t configPinSourceClock = 18;
int8_t configPinPoci = 19; 
int8_t configPinPico = 23;

This DigUno has a string of 5v ws2811 pixels on GPIO16.

What works

• Fseq button on main UI, when clicked loads a two tab html interface
• Uploading a fseq file seems to work, although there is no indication of upload progress.
• fseq tab shows all uploaded files - pressing "play" button does something (see what doesn't work below)

What doesn't seem to work

• xlights/fpp connect doesn't seem to discover this device, even when manually adding it via IP address
• fpp doesn't seem to discover this device as a remote player
• Attempting to play an uploaded fseq file just produces random looking colors for about half a second, before returning to the previously selected WLED effect
• Periodically, WLED shows an unexpected live data message for a few seconds: "WLED is receiving live USB Adalight/TPM2 data" (this is curious because nothing is connected to the USB port..). Sometimes this changes to "WLED is receiving live Hyperion data"

[netmindz]

@Andrejchrcek can you either grant maintainers permission to your branch so we can apply that changes for being a 0.16 usermod or make the changes yourself please

[netmindz]

As this is a pretty sizable bit of code, I think this probably should be an out of tree usermod, can you give some details on how to do this and how to then build please @willmmiles

[willmmiles]

As this is a pretty sizable bit of code, I think this probably should be an out of tree usermod, can you give some details on how to do this and how to then build please @willmmiles

I'm not sure I agree, actually -- rather I think it should be broken up in to smaller components. I have not done an in-depth review, but to my cursory lookover, there are a number of features wrapped up here:

• Adding SD card support. With the addition of GIF and video animation support in mainline, the ability to access external storage could be broadly useful. This should be a module on its own, or outright integrated in to the main codebase, and at the very least made available to the gif player.
• Adding a web manager/viewer for animation files on storage. This has substantial overlap with some of the things @DedeHai is working on, both in #4982 and to a lesser extent #4956. The key features here should get integrated with the existing efforts.
• The FSEQ playback engine. The current implementation here treats playback as a realtime data source; I think it might be better implemented as an effect, similar to the gif player, that can operate inside the segment mapping -- particularly given the 0.16 blending framework.
• The FPP UDP protocol handler. Not much to say here, it is what it says on the tin

As a general-purpose integration with another LED control framework, I think this feature is a good candidate for mainline inclusion -- it's not as tied to someone's unique project as some other modules ;) The things that make it bigger than most are IMO good ideas that we probably want for other things too.

[blazoncek]

I fully agree with @willmmiles

[DedeHai]

I concur. With the features in the pipeline (Matrix tool,a little further out the Video player as an (external) part of that) we should think of breaking this up into more paletable junks. Is @Andrejchrcek still around to work on this?

[Danit2]

Hello.

First of all, thank you very much for this great project.

What about support for FSEQ files? Will this be included in version 16?

It would be great if WLED supported FSEQ files from the SD card and also synchronized with the FPP player.

As a cool alternative, it would also be nice if the FSEQ files could be stored directly on the ESP32. With a 16 MB ESP, there should be plenty of space available.

In my case, this would massively reduce the network load. I currently control my WLED controllers via DDP and WiFi, but I always have the problem that the controllers are not 100% synchronized.

Thank you very much for your work.

[Andrejchrcek]

This update introduces enhanced compatibility with the latest WLED version. Additionally, I've identified and fixed several minor bugs to improve overall stability and functionality.

I am currently considering adding a feature for file unzipping.