Play FSEQ shows from any mount, flash or SD alike

[TouchMyLight]

FseqPlayerEffect plays pre-rendered FSEQ animations (the xLights/Falcon Player format) from anywhere the file manager reaches, as a playlist with shuffle/loop modes and a full transport (play/pause/stop/previous/next). Zlib-compressed files decode on ESP32 only; zstd isn't decoded by any target yet.

KPI: 256lights | Desktop:3093KB | tick:5/6/471/8/5/13/5/4/18/5us(FPS:200000/166666/2123/125000/200000/76923/200000/250000/55555/200000) | src:332(84020) | test:245(56823) | functions-over:350
Commit: src +979/-32 lines | test +874/-27 lines | duplicated lines 3586 -> 3586 (+0)

Core

• platform::zlibInflateAll: ESP32 decodes via the ROM's tinfl_decompress at zero flash cost; desktop and Teensy stub it to false, since neither links a decoder.
• module_types.cpp registers FseqPlayerEffect.

Light domain

• src/light/util/FseqFile.h: a pure, platform-agnostic FSEQ v1/v2 header and sparse-range-table parser, no I/O of its own.
• src/light/effects/FseqPlayerEffect.h: the player. Scans the generic filesystem root with no special case for /sd or any other mount, so a flash file plays exactly like an SD one. Decodes off the render tick (tick20ms, the same split HttpServerModule::driveSdTransfers uses for SD reads); tick() only blits the already-decoded frame. The playlist is ListSource/EditableListSource-backed, with shuffle, loop modes, and a file-authored or manual fps rate, capped at tick20ms()'s own 50 Hz.

Tests

• unit_FseqFile.cpp: the parser against hand-built and real xLights-exported bytes, including crafted headers pinning every validated bound (a non-advancing or past-frameCount block entry, a channelDataOffset inside the header's own tables, an overflow-adjacent block size).
• unit_FseqPlayerEffect.cpp: scan/playlist/decode/transport against real .fseq bytes on a test filesystem root, mounted-card and plain-flash-root alike.

Docs/CI

• test/CMakeLists.txt registers unit_FseqFile.cpp.
• docs/assets/light/effects/FseqPlayerEffect.{gif,png} refreshed to the current card.
• Generated metrics (repo-health.json/.md, docgen.md) deliberately left uncommitted per review item 4 below.

Reviews (🐇 CodeRabbit / 🧑 ewowi, from PR #145)

1. Two PRs, player first → done: this commit is the player alone; the zstd compression commit stays on its own branch for its own PR.
2. Teensy build needs zlibInflateAll/zstdInflateAll stubs → done for zlibInflateAll (the only one this commit's code calls); zstdInflateAll belongs to the zstd commit.
3. A corrupt file must not write past a buffer → done: validateBlockRange refuses a non-advancing or past-frameCount block entry and guards the channelCount multiply against overflow before any buffer is sized; channelDataOffset is refused when it lands inside the header's own tables; frameBuf_'s allocation is checked for success rather than bounded, a deliberate degrade-not-crash choice documented in the header.
4. Leave out generated files → done: repo-health.json/.md, code.md, docgen.md and scenario observation blocks excluded from this commit.
5. Small (prose, fileIndexOf) → done: "currently" reworded, fileIndexOf returns -1 on no match with the UI showing no selection rather than the first file.
6. SD-only flash-read restriction (originally added after a hardware crash matching upstream Guru Meditation Error: Core 0 panic'ed (Cache disabled but cached memory region accessed) (IDFGH-4053) espressif/esp-idf#5924) → removed: real-hardware reproduction (11,200+ continuous flash reads, then five real playback sessions over the network via the device's own web-UI API, including a full 180s/35fps real show) found no repeat of the crash. Flash and SD now play identically; the underlying ESP-IDF cache-disable-during-flash-read behavior remains a known architectural fact of this chip family, not something this effect special-cases around.

Pre-commit checks:
PASS check_specs
PASS check_prose (1 real finding fixed in added lines; the repo-wide prose.md ROSE is a stale-baseline artifact from vale only just being available this session, not a regression — prose.md left reverted) PASS check_code --module FseqPlayerEffect (1 accepted finding: raw heap allocation in scanDir, a deliberate heap-per-level recursion documented in the header's own @technical section, matching FilesystemModule::removeTree's precedent) PASS build_desktop (0 errors; 19 pre-existing GCC-16.2.1/Clang-23 warnings already accepted on misc_fix, none in these files) PASS build_desktop --tests + test_desktop (2637/2637 cases, 146698/146698 assertions) PASS check_docgen (1 pre-existing environmental error: help.json/libclang version mismatch, unrelated; both new test files fully clean; the two new headers carry only the "unreferenced appendix section" warning, a pattern already unfixed on several unrelated existing files, left as-is rather than forcing artificial @Xref links) PASS check_esp32_built (recompiled and reflashed after this message's own docgen edits; confirmed fresh) SKIP build_docs --strict, test_host --python/--js, check_devices, check_firmwares, improv_smoke_test (no .md, src/ui, moondeck/moonlive, or provisioning files touched) Real-hardware verification: ESP32-P4-ETH (esp32p4rev1-eth), flashed and monitored clean (no panic) after every rebuild in this cycle; functional playback confirmed live over the network via the device's own web-UI API, both from internal flash and from a real SD-mounted xLights show.

[TouchMyLight]

Here the first FSEQ player commit, with just the player without zstd support.
I could not reproduce the cache issue for the internal flash, so this commit can read files from any source.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: MoonModules/MoonLight/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 9bef7bb4-4fdf-4667-b844-abc7b2d1873a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[ewowi]

Hi @TouchMyLight, thanks for the second round! Splitting out zstd made this one much easier to review. The parser is careful and well pinned (every truncation offset, the block-table advance, the overflow guard), and the playlist on EditableListSource with the full transport reads cleanly. Playing from any mount, flash or SD alike, is exactly the right shape.

Three things to fix before we merge, in order of importance:

1. Keep the frame in wiring order. An FSEQ frame is the byte stream a controller sends, so it is already in wiring order. On main the player writes it through ChannelDataSink (sink_.prepare(true), sink_.tick(), deliversWiringOrder/copyWiringFrame), as Network Receive does, and the output takes it unmapped. This PR copies the frame into the layer's buffer instead, so the layout maps it a second time: a serpentine panel, a projection or a multi-panel wall shows every other row reversed. The tests use a plain 4×4 grid, where the double mapping changes nothing. Please bring the sink back: decode into sink_.write(0, frame, n), and blitFrameBuf, the stopped memset and the second copy can go. A test on a serpentine layout pins it.

2. The zlib decoder's stack. tinfl_decompress_mem_to_mem keeps its tinfl_decompressor (about 11 KB) on the caller's stack, and the decode runs on the 12 KB main task. A compressed show is very likely to overflow it. Please use tinfl_init + tinfl_decompress with the decompressor allocated once on the heap (platform::alloc, PSRAM is fine). Could you also check the main task's stack high-water mark while a zlib track plays on the P4? That number tells us the margin.

3. Files that are unusual rather than broken:

   • A file with 0 channels or 0 frames: please refuse it in the parser. Today it reports "out of memory", and a looping playlist then reopens it 50 times a second.
   • Long names: a file name over 39 characters disappears from the picker without a word, and a path over 95 characters is cut short. One budget of 192 for the name, the path and Track::file, as removeTree uses, with a status line when something is skipped.
   • A compressed file on desktop or Teensy currently says "file read failed mid-file". A hasZlibInflate flag in platform_config.h, checked in loadTrack, gives the clean "zlib plays on ESP32 only" status the header promises. One desktop test pins it.

Worth doing, here or in a follow-up PR, your choice:

• A whole compressed block is read and decoded in one tick20ms, which runs between frames, so each block boundary stalls the render. Reading it in slices per tick, as driveTransfers does, and decoding one block ahead would remove the hitch.
• Every track change calls rebuildControls(), which pushes a full control resync to every browser. And any file upload rescans the whole tree; a filter on .fseq keeps that to shows.

We'll finish these ourselves, nothing needed from you:

• the decoder moves out of the SD-card file into platform_esp32.cpp, so a board without SD also plays a compressed show from flash
• the duplicate unit_FseqPlayerEffect.cpp line in test/CMakeLists.txt
• help lines for the transport and playlist controls, and @attribution FPP back on the class
• the block-table read moves into FseqFile.h
• the full check_code and check_docgen runs (neither ran fully on your machine, and the libclang mismatch meant the controls weren't checked)
• the generated metrics at merge

On size: it's over our 400-line guideline, but it's one topic and already the second round, so no need to split it.

Thanks again, this is a big step toward playing xLights shows on MoonLight!

[ewowi]

Either way works for us: if you'd rather we take any of the three, say which and we'll do it on your branch, and if you want to do our list too, go ahead.

[TouchMyLight]

Thanks for the feedback. I'll try to tackle all recommendations today/tomorrow and will let you know. I'll do them in separate commits on this branch for easier identification.

[TouchMyLight]

Here all changes except "We'll finish these ourselves".
Let me know if you see other improvement I can take care of.
Once merged, I'll work on adding the zstd compression support in the next PR.
Don't hold back on commit changes to main (for example the ones from the "ourselves"), I'll make sure to rebase on main.