FPP Connect

FPP Connect

FPP Connect is xLights' tool for uploading sequences, media, models, and controller/network configuration to one or more Falcon Player (FPP) instances — and to a handful of "FPP-like" pixel controllers (Falcon F16V4/F48V4/F16V5, Genius, PowerDMX, ESPixelStick).

Opening FPP Connect

• Tools > FPP Connect menu item, or
• The FPP Connect button on the Layout/Setup screen, next to the Discover / Add USB / Add Ethernet / Add Null controller buttons.

Before the dialog opens, xLights recalculates your layout/models and, if the currently open sequence has unsaved changes, prompts you to save it first.

Make sure your computer and the FPP instance(s) are on the same network subnet, or that you've configured an FPP proxy, or upload/discovery may fail.

Dialog Layout

The FPP Upload window is split into two resizable panes.

Top pane — FPP Instance list

One row per discovered (or manually added) device, with these columns:

Column	Purpose
Upload	Check to include this device as an upload target. Disabled and shown as "Unsupported" or "Unavailable" if the device can't be used (see Version Requirements).
HostName / IP Address	Clickable links that open the device's web UI in your browser (routed through an FPP proxy automatically if one is configured).
Description	Device description reported by FPP.
Mode	The FPP mode — player, master, remote, bridge, etc. See Mode.
Version	Full FPP version string.
FSEQ Type	Sequence format to generate for this device — see FSEQ Type.
Media	Upload the paired audio/video file along with the sequence.
Models	None / All / Local — upload model/display-map data for FPP's virtual display feature. See Models.
UDP Out	None / All / Proxied — configure pixel-output UDP forwarding from this instance. See UDP Out.
Add Proxies	Push proxy IP mappings so this FPP relays pixel data for other controllers.
Playlist	Pick (or type) an FPP playlist name to append uploaded sequences to. Only shown for player/master mode instances.
Pixel Hat/Cape	Upload full controller I/O configuration (pixel/panel/virtual-matrix/serial outputs and bridge inputs) for the detected controller hardware.

Right-clicking most column headers opens a context menu:

• Upload header — Select All, Deselect All, Sort by upload state, and Select Subnet (pick a /24 subnet from a list and check only instances in it).
• HostName header — Sort instances alphabetically by hostname.
• IP Address header — Sort instances numerically by IP.
• Media header — Deselect All.
• Pixel Hat/Cape header — Select All / Deselect All.

Bottom pane — Sequences to upload

Control	Purpose
Filter	Recursive Search scans subfolders of the sequence directory (skipping Backup); Only Current Directory scans just the top level.
Folder	Choose a subfolder of the show directory to scan instead of the default sequence folder.
Selected: n/n	Running count of checked vs. total sequences.
Sequence list	A checkbox tree of .fseq/.eseq files found, with Sequence, Modified Date, Media, and Channel Count columns. The currently open sequence is auto-checked, as are sequences you had selected the last time you used FPP Connect.

Right-clicking the sequence list gives you: Select All, Clear Selections, Select Highlighted, Deselect Highlighted, Select Batch Render (re-check whatever you last queued in Batch Render), and Select Failed Uploads (re-check sequences that failed to upload last time).

Bottom button bar

Button	Purpose
Add FPP	Manually add an instance by IP/hostname if it wasn't discovered automatically. It's probed, authenticated, and remembered for next time.
Re-Discover	Re-runs network discovery and merges any newly found instances without disturbing rows you've already configured.
Keep Open	Keep the dialog open after a successful upload instead of closing automatically.
Upload	Starts the upload (see Upload Process below).
Cancel	Closes the dialog without uploading.

FSEQ Type

Choose the compression/format used when generating the .fseq file for a given device:

• FPP targets: V1, V2 zstd, V2 Sparse/zstd, V2 Sparse/Uncompressed (defaults to sparse/zstd, or V2 zstd if the instance is in master mode).
• Falcon V4/V5 and PowerDMX targets: V1, V2 zlib, V2 Sparse/zlib, V2 Sparse/Uncompressed, V2 Uncompressed.
• ESPixelStick / Genius: fixed to V2 Sparse/Uncompressed.

V2 formats require FPP 2.6 or later.

Mode

The Mode column simply reports the role each FPP instance told xLights it is playing (via discovery) — xLights doesn't set it, but it does change its own behavior based on what it sees:

Mode	What it means	In a home multi-Pi show
player (sometimes shown as player w/multisync)	This Pi plays its own playlist/schedule and pushes pixel data to its own controllers.	Typically your single show Pi, or the "conductor" if it's also broadcasting multi-sync packets.
master	Same as player, but explicitly the multi-sync master — it owns the schedule and sends sync packets that other Pis follow.	The "brain" of a multi-Pi show — the unit wired to the show computer/schedule that your other Pis slave off of.
remote	Doesn't run its own playlist — it waits for sync commands from a master/player and plays back what it's told.	A satellite Pi (mailbox display, roofline, detached prop) kept in lockstep with the main show.
bridge	Not running a sequence at all — it just receives E1.31/Artnet/DDP data over the network and pushes it straight to its local pixel outputs.	A Pi (or Falcon/Genius-class device) used purely as a pixel converter, with xLights or another master doing all real playback.

Why this matters — Mode changes FPP Connect's behavior in several concrete ways:

• Playlist picker only appears for player/master rows. Remotes and bridges have no playlist of their own, so that column is blank for them.
• FSEQ Type default is V2 zstd for a master, and V2 Sparse/zstd for everything else — sparse formats are generally smaller/faster for remotes that only need a subset of channels.
• Media checkbox defaults unchecked for remote (it's checked by default for other modes). A satellite Pi shouldn't independently start playing its own copy of the audio — only the master/player driving timing should, to avoid audio drifting out of sync across the property. When uploading to a Falcon-class device in remote mode, xLights forces the media filename blank regardless of the checkbox.
• Bridge-mode Falcon/Genius/Illuminous devices are hidden from FPP Connect entirely — in bridge mode those units are just pixel repeaters with no FPPD-style config to manage through this dialog.
• UDP Out auto-defaults to "All" when xLights detects there is exactly one player-mode instance on the whole network (a "sole player") — see UDP Out below.

Guidance: in a typical multi-Pi setup, set up one Pi as master (or player w/multisync) that owns the schedule, and one or more remote Pis elsewhere on the property that just play back what the master syncs to them. Only enable Media on the master. Bridge mode is mainly relevant to pixel-converter hardware, not full FPP show Pis.

Models

Checking Models uploads a JSON "model memory map" (name, start channel, channel count, string/strand layout, and for custom models the pixel-shape data) to FPP's /api/models endpoint. This is what powers FPP's own Display Testing / virtual display web page — the browser tool on the Pi that lets you click a model and light it up, or overlay a live preview of a running sequence, without xLights open. Choosing All or Local also uploads the 2D virtual layout used to draw that preview canvas.

FPP 7+ builds its own model overlays from the channel data you already upload, so this is largely a legacy/optional feature now — mainly useful for pre-7.0 FPP builds, or when you specifically want named models (rather than raw channel ranges) in the Display Testing page.

• None (default) — nothing is uploaded. This is the right choice for most rows most of the time; re-uploading models on every push forces an unnecessary FPPD restart and uses extra RAM/flash on lower-power Pis.
• All — uploads every model in the entire show, across the whole channel range (all controllers, all universes), plus the full virtual layout. Use this on your master/primary Pi if you want its web UI to let you click-test the entire show, not just what it directly drives.
• Local — only uploads models whose start channel falls within this specific controller's own channel range (only available when the FPP's IP maps to exactly one controller in your show), and skips the virtual layout upload. Use this on a remote/satellite Pi so its web UI only shows the handful of models actually wired to it — much lighter on RAM/CPU than holding the whole show's model list, which matters on a Pi Zero/Pi 3 with a large show.

Both All and Local always force an FPPD restart, since FPP needs to reload to pick up a new model list — don't check this casually on a running show.

UDP Out

UDP Out doesn't affect anything xLights sends — it configures this FPP instance's own outgoing channel/universe config (/api/channel/output/universeOutputs) so FPPD itself re-broadcasts pixel data it receives out to other controllers, effectively turning that Pi into a network bridge/repeater, the same way xLights would if it were plugged directly into your show network.

• None (default) — no change is made; the device doesn't forward pixel data to anyone else.
• All — the FPP instance is configured to output/forward data for every controller in your show marked ACTIVE. Use this when a single Pi is meant to be the hub that relays the whole show's universe data onward to other controllers on its local network segment (e.g., a Pi wired into the same switch as several older Falcon controllers that you'd rather address as one hop instead of individually over a flaky WiFi link).
• Proxied — only controllers whose "FPP Proxy" IP field (set on the controller in the Controllers tab) matches this FPP instance's IP are forwarded. Use this for a specific controller that can't be reached directly from your show computer — e.g., a WiFi-only or otherwise network-isolated controller — by pointing its Proxy IP at a nearby FPP Pi that can reach it, then setting that Pi's UDP Out to Proxied.

xLights automatically defaults UDP Out to All when it detects there is only one player-mode instance across the whole discovered network (a "sole player") — in a single-Pi show, "forward to all active controllers" and "drive the whole show" are effectively the same thing. There's also a related, separate Add Proxies checkbox that uploads the list of proxy IP addresses FPPD itself should be aware of — distinct from, but complementary to, the UDP Out universe configuration above.

Upload Process

Clicking Upload runs through these steps for every checked instance and checked sequence, shown in a progress dialog with a gauge per device:

1. Any previously recorded failed-upload list is cleared.
2. For each checked device: upload the playlist assignment, upload proxy mappings (if Add Proxies is checked), upload UDP-out universe configuration (if UDP Out isn't None), and — if Pixel Hat/Cape is checked — upload the full pixel/panel/serial output and bridge input configuration.
3. If Models is All or Local, model memory maps and the display map are uploaded (this always forces a restart).
4. FPPD is restarted on the device if any configuration change required it.
5. Each checked sequence is prepared (validated, re-encoded to the selected FSEQ type if needed, media file located) and uploaded to every checked device — sequence data is streamed in batches, in parallel, across all target devices at once.
6. Playlists are uploaded/updated again and devices restarted a final time if needed.
7. The dialog reports success, cancellation, or a Problems Uploading message box listing any errors or warnings.

Warning: Checking Pixel Hat/Cape uploads I/O configuration before sequence data and will restart FPPD, which can interrupt a currently running show. Only check it when you intend to push controller config changes.

Credentials and Errors

• If a device returns an authentication error, xLights prompts for a username/password (default username admin), with an option to save the password to your OS's secure credential store for future sessions.
• Devices that can't be reached, or whose FPP version is too old to support FPP Connect, show Unavailable or Unsupported in the FSEQ Type column and can't be checked for upload.

Version Requirements

FPP Connect only allows uploading to an FPP build that is:

• FPP 7.1 or later, or
• FPP 6.3.3 or later with a verified cape/hat identified.

Older FPP builds are excluded entirely. A few other notes:

• FPP 7+ generates its own model overlays from the uploaded channel data, so the Models dropdown is generally unnecessary — it's mainly useful for pre-7.0 FPP builds or specific virtual-display setups.
• FPP 9.0+ doesn't need the legacy restart-flag API call in most cases (model uploads still force it regardless of version).
• File uploads to FPP 7+ use a chunked upload API; older builds use a simpler single-request upload.

Persisted Settings

FPP Connect remembers, per show directory:

• Window size/position and splitter position.
• Sequence list sort order, filter, and folder selection.
• The last set of checked sequences and any that failed to upload.
• Manually added (forced) IP addresses/hostnames.
• Per-device settings (upload checkbox, media, FSEQ type, models, UDP out, pixel outputs, proxy) so your choices carry over between sessions.
• Saved credentials (if you opt to save a password), via your OS credential store.

---

See Also

• Controllers-Tab
• Menus
• Quick-Start-Guide

---

Last updated: 2026-07-06