FSEQ Usermod: integrate sd_card usermod and add support for compressed xLights sequence uploads#5417
Closed
FSEQ Usermod: integrate sd_card usermod and add support for compressed xLights sequence uploads#5417
Conversation
Introduce a new FSEQ usermod that enables playing .fseq animations from an SD card with a web UI and FPP/UDP synchronization. Adds core components: FSEQ player (fseq_player.cpp/.h), SD manager (sd_manager.*), web/UI & upload/FPP handling (usermod_fpp.h, web_ui_manager.*), registration (register_usermod.cpp), library metadata and auto-build script (library.json, auto_fseq_sd.py) and a README. Also includes helpers for buffered uploads and FPP ping/sync packets. Small updates in existing wled00 files (const.h, json.cpp) are included to integrate the usermod.
Added additional author credit and improved project description.
Multiple cleanups and feature changes across the FSEQ usermod: - fseq_player: Add a bool loop parameter to loadRecording(), use file_header.channel_data_offset when seeking, avoid prematurely closing recordingFile, and open files via WLED_FS.open for FS paths. Set recordingRepeats from the new loop flag instead of using secondsElapsed heuristics. - fseq_player.h: Update loadRecording signature and remove unused REALTIME_MODE_FSEQ define. - sd_manager: Add compile-time check that an SD backend is enabled (SPI or MMC) and remove the listFiles implementation/API; keep deleteFile. Corresponding header prototype removed. - web_ui_manager: Switch FSEQ/SD endpoints to POST with application/x-www-form-urlencoded bodies (start, startloop, stop, delete). Replace manual string-based SD file listing with a JSON response using DynamicJsonDocument. Improve file upload handling by storing a File pointer on the request and cleaning up on completion. Return status/info endpoints as JSON. - usermod_fpp/usermod_fseq: Various robustness and modernizations — null-buffer check in write(), inline constexpr and inline variables for UDP and timing, use snprintf for time formatting, suppress noisy debug hex dump, add override annotations, and rework SD reinit to accept and deallocate old pins before reinitializing. Overall these changes improve robustness of file handling, enforce SD backend presence at compile time, reduce string concatenation overhead by using JSON, and standardize the web API to POST for mutating actions.
…ks & UI Widen FSEQ frame size counters to 32-bit and make frame buffer reads safe (fixed 48-byte buffer and proper length casts). Add stricter UDP packet length checks for sync packets. Replace raw SD file ops with SD_ADAPTER (exists/remove/open) and add upload open-failure handling/cleanup. Refactor web UI SD list to emit proper JSON via ArduinoJson, fix JS loop-state bug, and adjust loadRecording loop parameter. Remove stale backup file.
Update FSEQ usermod and docs to new API routes and add FPP endpoints; adjust usermod IDs and fix minor web UI handling. Changes: - README: revise endpoints (use /api/ prefix, switch some endpoints to POST, rename /sd/ui to /fsequi) and add FPP control endpoints (system info/status and multisync). Merge author line. - const.h: add USERMOD_ID_FSEQ (59) and USERMOD_ID_FPP (60). - usermod_fpp.h: change getId() to return USERMOD_ID_FPP instead of USERMOD_ID_SD_CARD. - web_ui_manager.cpp: store file.name() in a temporary String before use, fix upload handler brace/formatting, and remove an outdated comment about loop mode. Notes: API route and usermod ID changes may require updates elsewhere that reference the old routes or IDs.
Update README to correct and standardize API paths (/api/...), add FPP endpoints and format SPI pin block. In usermod_fpp.h remove unused helpers, parse versionString into major/minor, change typeId to 195, and harden UDP sync handling with length checks and safe filename extraction to avoid buffer overruns (also remove an old commented sendSyncMessage). In web_ui_manager.cpp only update UI buttons after successful server response and add JSON overflow handling when returning file lists. These changes improve correctness, safety, and UX.
Replace unsafe reinterpret_cast of UDP sync packet with explicit parsing of sync action, frame number and seconds elapsed, and pass those parsed values to ProcessSyncPacket. Add a concurrent-upload guard (returns 409) and make UsermodFPP::_name inline. In the web UI manager add UploadContext for safer upload state handling, rework /api/sd/upload to use the context (better error handling, proper cleanup and file close), write chunks only when the file is valid, and return appropriate responses. Also check JSON overflow when serializing file lists and return 507 if the buffer is too small.
Replace the human-readable hostname with a deterministic unique device ID built from "WLED-" + MAC (colons removed) and use this ID consistently across all FPP payloads. This change prevents conflicts in FPP when multiple WLED devices share the same default hostname (e.g. multiple devices left as "WLED"). FPP requires unique host identifiers; duplicate hostnames can cause device collisions, sync issues, or undefined behavior in the player. The new unique ID is now used in: advancedView sys.id FPP ping packet hostname field (truncated to 64 bytes) The human-readable device name is preserved in HostDescription.
…orrection This changes replaces the previous hard frame-based synchronization logic in FSEQPlayer::syncPlayback() with a proportional time-based drift correction mechanism. Instead of immediately jumping to the expected frame when a small deviation is detected, the new implementation performs a smooth time adjustment using a proportional correction model. Hard resynchronization is now only triggered when the drift exceeds a defined safety threshold. This significantly improves visual smoothness during Multisync playback, especially on ESP32-based controllers where clock drift is common.
…d xLights sequence uploads PR Description This PR introduces two improvements to the FSEQ usermod: 1. Use the sd_card usermod The FSEQ usermod now depends on and uses the existing sd_card usermod instead of implementing its own SD handling. This ensures consistent SD card access across usermods and reduces duplicated code. 2. Support compressed xLights sequence uploads (.xlz) Uploading large sequence files can take significant time over the network. To improve upload performance, the web API now supports uploading compressed xLights sequence archives (.xlz). Behavior: .xlz files can be uploaded via the SD upload API. Uploaded archives are not unpacked immediately to avoid blocking the main loop. The archive will be unpacked: 10 seconds after the last upload, or automatically on the next device reboot. This approach allows faster uploads while keeping runtime performance stable. Summary Switch FSEQ usermod to the shared sd_card usermod Add support for compressed .xlz sequence uploads Implement deferred extraction to avoid blocking the ESP main loop Extraction runs 10s after upload or on reboot
Contributor
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (14)
WalkthroughAdds a comprehensive FSEQ (Fast Sequence) playback usermod system including core playback engine, FPP Connect UDP synchronization, web UI with file management, XLZ archive extraction, and integration with WLED's realtime LED control framework. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes Possibly related PRs
Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
FSEQ Usermod: integrate sd_card usermod and add support for compressed xLights sequence uploads
This PR introduces two improvements to the FSEQ usermod.
1. Use the
sd_cardusermodThe FSEQ usermod now uses the existing
sd_cardusermod for SD card access instead of implementing its own SD handling.Benefits:
2. Support compressed xLights sequence uploads (
.xlz)Uploading large sequence files can take significant time over the network.
To improve upload performance, the SD upload API now supports compressed xLights sequence archives (
.xlz).Behavior
.xlzfiles can be uploaded via the SD upload APIUploaded archives are not unpacked immediately to avoid blocking the main loop
The archive will be unpacked:
This allows faster uploads while keeping runtime performance stable.
Summary
sd_cardusermod.xlzsequence uploadsSummary by CodeRabbit
Release Notes