BackgroundMusic Controller Plugin for FPP

This is the home of the BackgroundMusic FPP Plugin Repo

The purpose of this FPP plugin is to allow the end user to control a background music playlist directly from the FPP UI and have music playing over the top of sequence-only playlists to create background atmosphere, great for pre-show ambiance.

The plugin allows the user to start an audio-only background playlist whilst a normal FSEQ sequence is already running (normally an animation sequence on repeat).

A 'Start Show' button allows the user to trigger a configured show playlist. When triggered, the plugin uses the fpp-brightness plugin to smoothly fade brightness (with MultiSync support for multi-controller setups), while simultaneously fading out the background music (time configurable). Once the fade completes, the background music and FSEQ playlists stop, have a blackout period (time configurable), and then return FPP to its previous brightness setting before starting the configured show playlist.

🆕 PSA System Added!

New in this version:

• PSA (Public Service Announcement) System - 5 configurable buttons to play announcements over background music
• Automatic Volume Ducking - Background music fades during announcements
• PipeWire Audio Mixing - Rock-solid concurrent playback without ALSA hacks
• Enhanced API - New endpoints for PSA control

Upgrading from v1.x? The plugin now provisions a dedicated PipeWire stack (including ffmpeg resampling support). After upgrade, stop/restart background music to pick up the new audio pipeline. See CHANGELOG.md for full details.

Requirements

• FPP Version: 9.0 or higher
• Required Plugin: fpp-brightness - Provides brightness control with MultiSync support

Installing fpp-brightness Plugin

The fpp-brightness plugin must be installed on ALL controllers (master and remotes) for brightness transitions and MultiSync to work properly.

Installation Steps:

1. On each controller, go to Plugin Manager → Install Plugins
2. Search for "brightness"
3. Click "Install" on the fpp-brightness plugin
4. Restart FPPd when prompted
5. Repeat on all controllers in your setup

Alternatively, install manually on each controller:

cd /home/fpp/media/plugins
git clone https://github.com/FalconChristmas/fpp-brightness.git
cd fpp-brightness
make
sudo systemctl restart fppd

Important: The brightness plugin enables MultiSync, meaning brightness changes will automatically synchronize across all controllers when MultiSync is enabled in FPP. Make sure to install on every controller for this to work.

Features

• 🎵 Background Music Player - Independent audio player that runs alongside FPP sequences
• 🔀 Shuffle Mode - Randomize playlist order for variety, reshuffles on each loop
• 🔊 Volume Control - Separate volume settings for background music, show, and post-show
• 📈 Track Progress Display - Real-time track name, progress bar, and time remaining
• 🎭 Smooth Show Transitions - Configurable fade-out with brightness control using fpp-brightness plugin
• 🌐 MultiSync Compatible - Brightness fading synchronizes across all controllers automatically
• 🔄 Auto-Return to Pre-Show - Optionally restart background music after show ends with configurable delay
• 📊 Real-Time Status - View current FPP playlist, plugin state, and playing track
• 🎼 Playlist Details View - See all tracks with durations, highlights currently playing track
• � PSA System - 5 configurable announcement buttons with automatic volume ducking
• �🔌 GPIO Integration - Trigger show start via physical buttons or sensors using FPP commands
• ⚙️ REST API - Full programmatic control via HTTP endpoints

Technical Requirements

Audio Configuration

The installer now deploys a self-contained PipeWire stack for the fpp user so the plugin can manage concurrent audio cleanly without touching system-wide ALSA configs.

During install we:

• Install pipewire, pipewire-alsa, pipewire-pulse, wireplumber, and ffmpeg
• Back up /home/fpp/.asoundrc if present so PipeWire's ALSA shim can take over
• Drop ~/.config/pipewire/pipewire.conf.d/70-backgroundmusic.conf with large audio buffers to eliminate underruns
• Make sure scripts/start_pipewire.sh is executable and run it to (re)launch the PipeWire/WirePlumber processes under the fpp account

What you get:

• ✅ Background music and PSA announcements share the same low-latency PipeWire graph
• ✅ Automatic ffmpeg resampling to 48 kHz stereo WAV for glitch-free PSA playback
• ✅ Smooth ducking because both players run through the same mixer
• ✅ Zero changes to FPP's native playlist audio pipeline—FPP media still plays normally

Operational tips:

• If audio ever drops out, run scripts/start_pipewire.sh via SSH or reinstall the plugin to restart the stack
• When changing the physical audio device in FPP settings, rerun the installer (or start_pipewire.sh) so PipeWire reconnects to the new sink
• Keep ffmpeg installed; the PSA pipeline depends on it for on-the-fly conversions

Automatic Update Notifications

The plugin checks for updates automatically when internet is available:

• 🔍 Checks GitHub repository hourly for new versions
• 📢 Shows notification banner when updates are available
• 🌿 Branch-aware: Automatically checks the correct branch based on your FPP version (defined in pluginInfo.json)
• ⚙️ Uses FPP's native version management (git commits)
• 🌐 Only checks when system has internet connectivity
• ❌ Can be dismissed if you prefer to update later
• 🔄 Update via FPP's Plugin Manager

How it works:

• Reads pluginInfo.json to determine which branch to check based on FPP version
• Compares local git commit with remote repository
• Shows notification with commit count and latest changes
• Provides direct link to Plugin Manager for one-click updates

Quick Start

1. Installation

Plugin automatically installs via FPP plugin manager.

2. Configuration

1. Navigate to Content Setup → Background Music Settings
2. Select Background Music Playlist (audio-only playlist)
3. Select Main Show Playlist (your main show)
4. Configure Volume Settings (background, show, and post-show volumes)
5. Set fade/blackout times and post-show delay
6. Enable Shuffle if desired
7. Enable Return to Pre-Show if you want automatic restart after show
8. Click Save Settings

3. Basic Usage

Start Background Music:

• Go to Status/Control → Background Music Controller
• Click "Start Background Music" button
• Background music plays over scheduler-controlled sequences
• See real-time track progress and playlist details

Start Main Show:

• Click "Start Main Show" button on controller page
• OR configure GPIO input to trigger show (see below)
• Background music fades out → blackout → show starts

4. GPIO Setup (Optional)

The plugin exposes FPP commands that can be triggered via GPIO inputs, allowing physical buttons or sensors to start your show.

Setup Steps:

1. Go to Input/Output Setup → GPIO Inputs
2. Configure a GPIO pin with:
   • Mode: GPIO Input
   • Edge: Rising (for button press) or Falling
3. Under Run Command When Triggered, select:
   • Command: "Plugin Command"
   • Plugin: "fpp-plugin-BackgroundMusic"
   • Command: "Start Main Show"
4. Save configuration and test

Available FPP Commands:

• Start Main Show - Initiates fade transition and starts main show playlist
• Start Background Music - Starts background music playback
• Stop Background Music - Stops background music playback

Use Cases:

• Push button at entrance to start show
• PIR motion sensor to trigger when audience arrives
• Toggle switch for manual show control
• Integration with other automation systems

Controller Features

Real-Time Status Display

• Background music running state
• Currently playing track with progress bar
• Time elapsed/remaining display
• FPP playlist status
• System brightness and volume levels
• Configuration summary

Playlist Details Panel

• View all tracks in background music playlist
• Track numbers, names, and durations
• Total track count and playlist duration
• Highlights currently playing track with play icon
• Auto-updates every 2 seconds

Volume Control

• Real-time volume adjustment slider
• Syncs with FPP's system volume
• Separate volume settings for:
  • Background Music (pre-show)
  • Show Playlist (main show)
  • Post-Show Background (after show returns)

API Endpoints

All endpoints available at: /api/plugin/fpp-plugin-BackgroundMusic/

Status

GET /api/plugin/fpp-plugin-BackgroundMusic/status

Returns current plugin state, FPP playlist, brightness, track progress, and configuration.

Control Background Music

POST /api/plugin/fpp-plugin-BackgroundMusic/start-background
POST /api/plugin/fpp-plugin-BackgroundMusic/stop-background

Trigger Show

POST /api/plugin/fpp-plugin-BackgroundMusic/start-show

Set Volume

POST /api/plugin/fpp-plugin-BackgroundMusic/set-volume
Content-Type: application/json
{"volume": 70}

Playlist Details

GET /api/plugin/fpp-plugin-BackgroundMusic/playlist-details

Returns track list with durations and metadata for the configured background music playlist.

Save Settings

POST /api/plugin/fpp-plugin-BackgroundMusic/save-settings
Content-Type: application/json
{
  "BackgroundMusicPlaylist": "Background music only",
  "ShowPlaylist": "Main Show",
  "BackgroundMusicVolume": 70,
  "ShowPlaylistVolume": 100,
  "PostShowBackgroundVolume": 70,
  "FadeTime": 5,
  "BlackoutTime": 2,
  "ShuffleMusic": 1,
  "ReturnToPreShow": 1,
  "PostShowDelay": 5
}

How It Works

The plugin uses an independent audio player (ffplay) that runs completely separate from FPP's playlist system. This allows:

• ✅ Background music + FPP sequences running simultaneously
• ✅ No playlist conflicts
• ✅ Scheduler controls sequences
• ✅ Plugin adds music layer
• ✅ Clean transitions between pre-show and show
• ✅ FPP commands for GPIO integration

Architecture Highlights

• Independent Player: Uses ffplay process, not FPP playlists
• Volume Management: Integrates with FPP's native volume API
• Process Control: PID-based tracking for reliable start/stop
• Smooth Transitions: Coordinated brightness fading and audio crossfade
• Auto-Recovery: Optional return to pre-show after main show completes

Support & Development

Plugin Developer: Stuart Ledingham of Dynamic Pixels

Resources:

• GitHub Repository
• Bug Reports & Feature Requests

License

This project is licensed under the terms specified in the LICENSE file.