FPP 10.2

FPP 10.2

FPP 10.2 is a point release on top of 10.1 — 244 commits from 11 contributors in the two and a half weeks since 10.1 shipped. The headline is audio/light sync: songs no longer lose their first second on slower boards, and the lights now wait for the sound. Around that: a much more capable plugin manager, a new Diagnostic Report for bug reports, full playlist validation, LED panel work for BeagleBone capes, and a long list of crash fixes and hardening.

NOTE: The OS level moves from 2026-09 to 2026-10, but an "OS Level" upgrade is not required to run 10.2. The only changes at the OS level are kernel updates and security patches — recommended, but entirely optional. A normal FPP update from 10.1 gets you every feature and fix listed below, including the OS-level changes made since 10.1 (the Pi SPI1 overlay and the BeagleBone Black kernel lockout), which are applied by the update itself.

Enhancements

Audio & Video

• Songs no longer lose their first second on slower boards — audio-only playback keeps one PipeWire output stream open across a scheduled playlist, so a track is audible in about 200 ms instead of 800-900 ms on a BeagleBone with a USB sound card. The sequence now holds its lights until the audio is actually audible, and back-to-back tracks and resumes after Insert Playlist Immediate no longer run the lights ahead of the sound (#3016)
• New "Keep Audio Output Open" setting (Settings → Audio/Video, Advanced) so media triggered without warning — GPIO, commands, the API — also starts with no delay, at the cost of the sound card never idling
• New VBAN audio streaming — a VBAN Config page, with VBAN receive streams selectable as sources on the PipeWire Input Mixing page
• New "Prevent HDMI CEC at Boot" setting (Settings → System) stops the player waking a TV or projector at boot (#2939)
• Quieter logs during playback — one "started playing" line per track at info level instead of about fifteen

Plugins

• Background plugin update checks — the player checks for plugin updates itself, and a puzzle-piece icon in the header on every page shows when an update is waiting (#2929). Check for Updates, Update All, the rows and the Updates tab all use the same answer, with progress, its age, and which plugins could not be checked and why in plain words (needs a GitHub token, repository moved, offline, …)
• Plugin install history — every install, update, uninstall, failed install, Reset Config delete and Copy Settings restore is recorded, together with the system package changes made for the plugin. See Help → Troubleshooting Commands → Plugins
• Updating a plugin now installs any new dependencies its new version declares (and releases ones it dropped) before running its upgrade script, instead of leaving it broken until a reinstall
• Plugins can show their release notes in-app from the plugin card and detail dialog, for plugins that opt in
• Package Manager shows the dependencies each package pulled in, an Installed/Missing status per row, and why Uninstall is disabled when a package is still needed
• A calmer, simpler install dialog: a short one-time notice replaces the red "untrusted code" callouts, privacy chips all read ": " so a green chip can't be mistaken for an undisclosed one, and the wording says plainly what the plugin list does and doesn't check, including "Includes closed-source software" (#2976)
• The plugin detail popup shows when a plugin joined the plugin list

Diagnostics & Troubleshooting

• New Diagnostic Report (F8 on any page, or Help → Diagnostic Report) builds a redacted report — settings, configuration, logs, Troubleshooting page output and the health check — to attach to a bug report, with no crash needed. Reports stay on the player for review and are only sent with explicit consent, and one can be built even when fppd is not running (#2968)
• File Manager → Logs: the Zip button is replaced by the Diagnostic Report, which carries everything the zip did, redacted
• Crash reports carry more context: the main-loop phase, the library load map, the playing playlist, overlay actions — and no longer fill their log history with status polls
• Troubleshooting → Webserver renders Apache server-status and phpinfo as formatted pages in the current theme

Scheduler, Playlists & Commands

• Playlist validation now checks every entry the way fppd will play it — files, sub-playlists (including loops and too-deep nesting), commands and their arguments, branch targets — and the editor marks each problem row. The Schedule, Command Presets, GPIO and Recurring Tasks pages flag invalid FPP commands too (#3011)
• "If" conditions compare times, days of the week and months in order, and "between" handles ranges that wrap (22:00–02:00, Friday–Sunday, November–February)
• New SetPlaylistRepeat command and API to turn a running playlist's repeat on or off
• New Restart FPPD command

Web UI

• Custom keyboard shortcuts — Settings → UI (Advanced) lists the built-in shortcuts and lets you bind keys to run a command preset, run an FPP command, or open an FPP page from anywhere in the UI (#3008)
• The Channel Outputs page opens on the tab that matches the detected cape — Pixel Strings for a string cape, LED Panels for a panel-only cape
• File Manager: Delete asks for confirmation and lists the files; a new "Hide Empty Tabs" setting keeps the tab row from wrapping on small screens; Audio and Video tabs appear immediately instead of waiting for every media duration
• Pixel Strings: "Clone String" steps start channels correctly for RGBW and grouped strings and skips ports on an expansion set to None
• Troubleshooting shows a neutral "nothing to check" badge for a section whose checks all skipped

Pixel Overlays & Effects

• Text effect color modes — Gradient, Per Letter/Word/Line, Random Letter/Word, Sparkle and Chase, with custom colors, rainbow or preset palettes and an animation speed; also available through the overlay model API. Existing presets are unchanged
• Pixel Overlay Models support polar buffer layouts imported from xLights; WLED effects can sweep radially or around the circle on them
• New WLED "Copy Segment" effect
• The overlay font list now includes the TrueType fonts (Liberation, Noto, DejaVu, Lato, FreeFont, …), not just the 35 Type 1 fonts

LED Panels

• BBBMatrix capes now support ABC-addressed (shift-register row driver) panels, and the panel page offers Standard, Direct Row Select and ABC-Addressed on all BeagleBone panel capes
• FM6373, ICND1065L and SM16380SH panels on BBShiftPanel capes can import a PWM register profile, since the right register table depends on the panel's row driver and pitch, not just the chip; the chosen values travel with a backup
• The same panels expose OE pulse and register-upload timing for bringing up a panel that stays dark; left blank, timing is exactly as before (#2955)

MultiSync & Discovery

• Twinkly lights are discovered on the MultiSync page (model, name, firmware) without logging in, so a running Twinkly output's token is never invalidated
• macOS players discover other controllers over mDNS/Bonjour

Capes & Hardware

• Raspberry Pi: SPI1 is available as a device without claiming any header pins, so GPIO19-21 stay free until something actually uses SPI. Existing Pi's get it on update (a reboot is requested)

Performance

• The exim mail daemon no longer runs — on single-core BeagleBones it regenerated a certificate every ~90 minutes and pinned the CPU for 5-10 seconds. Email still works, and deferred mail is retried only when mail is queued
• Optional usage statistics now include the WLED Audio Sync mode, the header current sensor and the audio card type

Bug Fixes (since 10.1)

Fixes already delivered in 10.1.1 and 10.1.2 are included but not repeated here.

Crashes & Stability

• fppd could crash after an OS (fppos) upgrade on the next media play or plugin load — in-use shared libraries are now replaced rather than overwritten in place
• Fixed a use-after-free in the ping/discovery code that newly resolved MultiSync/mDNS hosts could trigger, mostly on single-core boards
• Fixed crashes from: a truncated, corrupt or zero-step-time .fseq file (now played at the 50 ms default); an overlay submodel outside its parent model; a model with no layout position in the Virtual Display; two virtual matrix outputs of different sizes; an HDMI virtual matrix removed on reload next to DPIPixels; a Pi panel layout using more chains than its pinout supports; an unavailable PWM channel; an invalid multiplexed sensor or nRF24L01 speed; an unreadable system UUID; an out-of-memory overlay buffer; and the end of a media file racing the next playlist entry
• An output whose channels run past the end of the channel space is disabled with a warning instead of reading past the sequence buffer every frame
• BeagleBone PRU outputs and BBBMatrix fail cleanly with a warning instead of crashing when the PRU can't be started or mapped
• Unloading a channel-data plugin, or a plugin installed without an fppd restart, could crash fppd or leave some of its API paths unanswered
• Boards with per-port current sensing leaked a file handle per port on every output reload until fppd could not open files
• Crash-report redaction could take minutes to hours inside the crash handler on a log with a very long line

Audio & Video

• Video into a pixel overlay model crashed fppd on the first frame on a Pi 4 with hardware-decoded H.264
• Selecting a hot-plugged USB sound card in Simple audio mode sent audio nowhere; affected players are repaired at the next boot (#3021)
• An audio output group could play silently forever after FPP took over a late-detected sound card (#3030)
• Resuming after "Insert Playlist Immediate" restarted the audio from the beginning, freezing the lights until it caught up
• Audio-reactive WLED effects sat flat when fed from an audio input

Scheduler & Playlists

• Playlists, schedules, presets and GPIO actions still using the "Remote …" commands removed in FPP 10 silently stopped working — they are now converted to the equivalent MultiSync command automatically when fppd starts (#3011)
• Plugins now get correct playlist events — "start" fires when a playlist begins (it never did), the first item gets a "playing" event, and a spurious "playing" right after "stop" no longer turns plugin-controlled hardware back on as the show ends
• A playlist Branch time window crossing midnight or the top of the hour never tested true, and an end-time-only window was ignored; Branch warnings now clear after 60 seconds
• A scheduled playlist containing "Restart FPPD" or "Switch To Player/Remote Mode" restarted fppd in a loop for the rest of the schedule window
• The header playing badge shows sequences started outside a playlist
• A sequence could be reported as running, with no output, if an invalid sequence name arrived while another was being prepared

Pixel Strings & Panels

• A quote or backslash in an output description (e.g. 12" Mini Trees) corrupted the channel output config on save, blacking out every output in that file; malformed saves are now refused
• The Pixel Overlay Models page wiped custom-model layouts uploaded from xLights when saved — affected models need to be re-uploaded from xLights
• BBBMatrix panels stayed dark on roughly one start in twelve
• PocketBeagle 2 panel output could show displaced or blended rows after a few minutes
• BBShiftPanel ABC-addressed panels: a doubled row, a dark row, rows in the wrong band, and a faint ghost on the next row are fixed; the ABC Shift choice now actually applies to FM6373-family panels (#2955)
• Beagle panels: the Panel Interleave "Off" choice, which left the panel dark when interleave is needed, is disabled and no longer the default
• After an fppd restart a changed BeagleBone PRU output setting could silently keep the previous value
• Twinkly output no longer stalls after many hours, survives stop/start cycles and rejected tokens, and no longer crashes when a device drops off mid-show
• Pi: a cape output-enable pin on a UART/I2C/SPI header pin (such as GPIO15) was never driven, leaving that port unpowered (#2979)

MultiSync

• Lights could freeze on a MultiSync remote whose output ran far ahead of the player
• Channel ranges for non-FPP controllers in the systems list were one channel high
• The Reboot button in a row's action log did nothing

Plugins

• Uninstalling a plugin could remove system packages that were already on the player (a plugin declaring fontconfig could take ffmpeg and GStreamer with it); only packages installed for the plugin are ever released
• Update All reported success when a plugin's install script failed
• A plugin pinned to a commit in its pluginInfo.json jumped to the branch tip on update
• Plugin settings stored as unquoted JSON had their quotes stripped
• An uninstall reported failure when the plugin's own uninstall script had already removed its directory
• The cached plugin list now survives a reboot, so an offline player's Available tab is not empty
• The Plugins page no longer recommends plugins not updated for this FPP release
• "Help for This Page" appears on plugin pages that ship their own help

Upgrade & Install

• Plugin installs/updates, Reset Config, Flash to Storage, OS upgrade, Package Manager installs, manual update and Rebuild FPP now run to completion if the browser tab is closed or the connection drops
• BeagleBone Black players first installed from a 10.1 image now get the same stock-kernel lockout new images have, so an apt upgrade can no longer replace FPP's PRU kernel and turn off every PRU-driven cape (#2966)
• After an OS upgrade from FPP 8/9, MP3Gain could fail with "undefined symbol" (#2990); OS upgrades now refresh any rebuilt-package file the copy would otherwise skip
• Replaying user-installed packages after an OS upgrade skips packages the new OS no longer has, so it no longer re-runs on every boot
• A settings file still in the pre-5.0 "master" mode is rewritten as Player with MultiSync at every boot, including after restoring an old backup (#3041)

Web UI

• Config pages could show stale data for up to a year after one unchanged reload, and saving such a page wrote the old config back
• Settings no longer randomly appear lost (bouncing to initial setup) when a page reads them while fppd is writing; deleting a setting no longer corrupts JSON-valued settings
• Channel Outputs → Other: plugin-provided output types were hidden and dropped on Save; they now show on a "Misc" tab
• Uploads larger than 64 MB stalled in Safari (#3013); a retried chunk no longer corrupts the file, and a failed upload is reported
• Once a UI password was set it could not be removed (#2985)
• Kiosk on a Pi Touch Display 2: touch rotation applies on the first boot after enabling Rotate and no longer remaps a USB touch monitor alongside it
• File Manager: Images tab columns, dark-mode tab colors, and the Videos tab's Add To Playlist button (#3032)
• A GPIO pin claimed by another peripheral no longer reads as a held-down button (#2965); an OLED with buttons on an I2C expander shows its Network menu again (#2947)
• The tethering hotspot uses the DHCP pool set on the Network page
• Setting the log level to "excess" now enables it; the logging banner stays in sync
• Initial setup no longer asks for a reboot when nothing needs one, and honours the chosen jurisdiction on players with no cape
• A missing media directory is reported as such instead of a false "disk nearly full"
• F1 on Settings shows help for the current tab
• MultiSync tooltips show the playing sequence on players that also play media

Backups

• Restoring scripts from a backup now runs their install actions, and file names inside a backup can no longer write outside their target directory (#2997)

Privacy & Security

• Names, versions and warnings reported by other systems on the MultiSync page are escaped so they can't inject markup
• Crash and Diagnostic Report redaction catches more secret formats (URL credentials, GitHub/GitLab tokens, Authorization headers, JWTs, escaped JSON)
• A plugin with a privacy disclosure can no longer be installed via the API or as a dependency without the disclosure being accepted
• Release notes on the About page and in the plugin manager are rendered through a safe markdown renderer
• Hardening across plugin install/uninstall, version checkout, OS upgrade, backup copy, cape EEPROM signing and firmware download, network interface names, sequence filenames, File Manager actions, plugin history URLs, Troubleshooting output and pip arguments

Deprecations & Behavior Changes

• GET /api/files/zip is deprecated and will be removed in FPP 11 — use a Diagnostic Report instead
• Stored "Remote …" commands are rewritten in place to MultiSync commands when fppd starts
• Plugins with no privacy disclosure are now shown with red lights and "Install anyway"
• Plugin config files are read with FPP's own INI reader: unquoted yes/no/true/false values reach plugins verbatim instead of as "1"/""
• POST /api/gpio/{pin} returns 409 when the pin can't be acquired, instead of reporting success

Installation Instructions

No fppos / "Upgrade OS" step is required to run 10.2. The OS level does move from 2026-09 to 2026-10, but the only changes there are kernel updates and security patches. The OS-level changes made since 10.1 — the Raspberry Pi SPI1 overlay and the BeagleBone Black stock-kernel lockout — are applied by the normal update. Applying the 2026-10 fppos (or re-imaging) is recommended if you have the opportunity, but it is optional.

Upgrading from 10.0 or 10.1.x

Go to the FPP About page (about.php) and click "Manual Update" first — on 10.0 and 10.1 this also brings in the fix for the Upgrade button, which otherwise reports "Upgrade complete" without changing anything. Then a green "Upgrade" bar will appear on the main status page — click it to start. It typically takes 5-10 minutes. Reboot when it finishes to complete the upgrade.

To take the optional OS update as well: About → Upgrade OS → pick the 10.2_2026-10 image for your board.

Coming from 10.0, 10.2 includes every 10.1 change, so read the 10.1 release notes too.

Upgrading from 9.x or older

Due to incompatibilities with the underlying libraries, an OS Level upgrade is required, and moving from 32-bit to 64-bit requires re-imaging.

• Fresh install — back up your config, flash the 10.2 image for your board, restore your config.
• In-place upgrade (same architecture only) — make sure you are fully updated on 9.x first, then About → Upgrade OS → pick the 10.2_2026-10 image for your board. FPP downloads the fppos and installs it. This takes a LONG time. When it reboots into 10.2, delete the fppos file from File Manager → Uploads.

NOTE: In SOME cases the reboot will fail due to library replacement. A power cycle may be needed to get it back up and running.

Which image do I need?

Board	Image
64-bit capable Pi (3/4/5, Zero 2 W, CM4/CM5)	FPP-v10.2-Pi64.img.zip
Older/32-bit-only Pi	FPP-v10.2-Pi.img.zip
BeagleBone Black/Green/PocketBeagle/Green Gateway	FPP-v10.2-BBB.img.zip
PocketBeagle 2 / PocketBeagle 2 Industrial	FPP-v10.2-BB64.img.zip

---

Thanks

Code contributions in the 10.1 → 10.2 cycle came from:

Daniel Kulp, Daryl C, Jessica Ryan, Stuart Ledingham, Pat Delaney, Patrick Gianotto, Nick Scilingo, Matthew Shorts, Jeremy (getjboards), Harris Christiansen and Paul (MrPaulAR).

Thanks also to everyone who reported, reproduced and tested issues on GitHub and the forums since 10.1 shipped — a lot of what is in this release came straight from those reports.

Full changelog: 10.1...10.2