Schedule music-synced light shows on Falcon Player (FPP) / xLights #158

New issue

Open

opened 2026-09-26 05:02:13 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-09-26 05:02:13 +00:00

Collaborator

Idea

The serious end of the holiday-lighting hobby runs music-synced shows. They are sequenced in xLights, played by Falcon Player (FPP) on a Raspberry Pi or BeagleBone, and often broadcast on a low-power FM transmitter so cars can tune in. FPP's own scheduler is a weekly timetable that knows nothing about holidays, sunset or the Christmas season as a whole.

Iris's calendar is exactly what that community lacks. This is the most distinctive of the "beyond WLED" ideas, and also the largest.

Behaviour

Show windows on events: "during Christmas-tagged events, run playlist Christmas 2026 at the top of every hour from 18:00 to 21:00, and let the ambient scheme run between shows". Relative times work too: "30 minutes after sunset, then hourly".
Iris chooses which playlist runs and when; FPP plays it. FPP's REST API (/api/playlist/<name>/start, /api/playlists, /api/fppd/status) covers starting, stopping and checking.
Hand-off with the ambient scheme is the hard part:
- FPP commonly drives WLED controllers over DDP or E1.31, and WLED enters realtime mode while it receives that data. The realtime data overrides Iris's pushed state; when it stops, WLED returns to its previous state after a timeout.
- So while a show runs, Iris must not push or watchdog-correct those controllers. The watchdog (#148) must treat "FPP show active" as expected.
- After the show, Iris restores the ambient scheme explicitly. It shouldn't rely on WLED's realtime timeout.
Quiet hours: shows with audio end by a configurable time. Neighbours matter, and some HOAs and municipalities have rules.
Review: a show window is approved like a scheme. The side panel shows the playlist, its length and the schedule for that night.

Depends on

The device-model design issue (#155), for a sequence capability: a device that plays pre-rendered shows, not states.
#32 (triggers), if shows should also start on demand. For example, a button at the kerb, which is a common feature of FPP displays.

Acceptance

FPP devices are configured and their playlists discovered via the API.
Show windows attach to events or tags with absolute or sunset-relative times, and are previewed on the calendar.
During a show, Iris doesn't push to or correct the WLED controllers FPP is driving. Afterwards it restores the ambient scheme within seconds.
Verified against a real FPP instance, with at least one WLED controller as a DDP target.
Docs: the hand-off model and the realtime-mode caveat.

## Idea The serious end of the holiday-lighting hobby runs **music-synced shows**. They are sequenced in **xLights**, played by **Falcon Player (FPP)** on a Raspberry Pi or BeagleBone, and often broadcast on a low-power FM transmitter so cars can tune in. FPP's own scheduler is a weekly timetable that knows nothing about holidays, sunset or the Christmas season as a whole. Iris's calendar is exactly what that community lacks. This is the most distinctive of the "beyond WLED" ideas, and also the largest. ## Behaviour - **Show windows on events:** "during Christmas-tagged events, run playlist *Christmas 2026* at the top of every hour from 18:00 to 21:00, and let the ambient scheme run between shows". Relative times work too: "30 minutes after sunset, then hourly". - **Iris chooses which playlist runs and when; FPP plays it.** FPP's REST API (`/api/playlist/<name>/start`, `/api/playlists`, `/api/fppd/status`) covers starting, stopping and checking. - **Hand-off with the ambient scheme is the hard part:** - FPP commonly drives WLED controllers over **DDP or E1.31**, and WLED enters *realtime mode* while it receives that data. The realtime data overrides Iris's pushed state; when it stops, WLED returns to its previous state after a timeout. - So while a show runs, Iris must **not** push or watchdog-correct those controllers. The watchdog (#148) must treat "FPP show active" as expected. - After the show, Iris restores the ambient scheme **explicitly**. It shouldn't rely on WLED's realtime timeout. - **Quiet hours:** shows with audio end by a configurable time. Neighbours matter, and some HOAs and municipalities have rules. - **Review:** a show window is approved like a scheme. The side panel shows the playlist, its length and the schedule for that night. ## Depends on - The **device-model design** issue (#155), for a `sequence` capability: a device that plays pre-rendered shows, not states. - #32 (triggers), if shows should also start on demand. For example, a button at the kerb, which is a common feature of FPP displays. ## Acceptance - [ ] FPP devices are configured and their playlists discovered via the API. - [ ] Show windows attach to events or tags with absolute or sunset-relative times, and are previewed on the calendar. - [ ] During a show, Iris doesn't push to or correct the WLED controllers FPP is driving. Afterwards it restores the ambient scheme within seconds. - [ ] Verified against a real FPP instance, with at least one WLED controller as a DDP target. - [ ] Docs: the hand-off model and the realtime-mode caveat.

claude-bot added this to the v2.0.0 milestone

2026-09-26 05:02:40 +00:00

claude-bot added the

labels

2026-09-26 05:02:48 +00:00

claude-bot referenced this issue