List all configured xLights show folders.

Returns the available show folders (e.g., Christmas, Halloween) and indicates which one is currently active.

Add an xLights show folder by path.

Use this to confirm a detected show folder or provide a custom path. The folder must contain an xlights_rgbeffects.xml file.

Args: path: Full filesystem path to the xLights show folder name: Optional display name for the show (derived from folder name if omitted)

Switch the active xLights show folder.

Args: show_name: Name of the show to activate (e.g., "christmas", "halloween")

List all light models in the active xLights show.

Returns model names, types, controller assignments, and channel info.

List all controllers configured in the active xLights show.

Returns controller names, IPs, protocols, and channel counts.

List all sequences (.xsq files) in the active show folder.

Inspect an existing xLights sequence file.

Shows the song info, duration, models used, and effect summary.

Args: sequence_name: Name of the sequence (without .xsq extension)

List all available xLights effects with descriptions.

Returns effect names, descriptions, and which model types they work best on.

Analyze a music file for light show sequencing.

Performs full audio analysis: beat detection, song structure, frequency spectrum, energy profile, and optionally source separation.

Args: mp3_path: Path to the .mp3 file to analyze

Get the verse/chorus/bridge structure of a song.

Args: mp3_path: Path to the .mp3 file

Get beat and downbeat timestamps for a song.

Args: mp3_path: Path to the .mp3 file

Get energy and frequency band analysis for a song.

Returns loudness curve and bass/mid/high energy over time.

Args: mp3_path: Path to the .mp3 file

Create an xLights sequence from a music file.

Analyzes the audio and generates a .xsq file with effects placed on your light models according to the selected generation mode.

Args: mp3_path: Path to the .mp3 file mode: Generation mode — "auto" (AI picks everything), "guided" (interactive), or "template" (apply saved recipes) palette_hint: Optional color hint (e.g., "red and green", "orange and purple") theme: Optional theme hint (e.g., "christmas", "halloween", "energetic") vocal_assignments: Optional mapping of model names to vocal track names. Use {"all": "<track_name>"} to assign one track to all singing models, or map individual models like {"Snowman": "Vocals", "Bulb Blue": "Full Mix Vocals"}. If omitted and singing models are detected, returns available models and tracks so you can prompt the user for assignments. show_name: Which show folder to generate the sequence in (e.g., "christmas", "halloween"). If omitted and multiple shows exist, returns available shows so you can ask the user which one to use.

Preview the sequence generation plan without creating a file.

Shows what effects would be placed on which models, based on the audio analysis and selected mode.

Args: mp3_path: Path to the .mp3 file mode: Generation mode — "auto", "guided", or "template" show_name: Which show folder to preview against. If omitted and multiple shows exist, returns available shows so you can ask the user.

Import a sequence from a different show layout and remap it to your models.

Accepts a .xsq file or .zip package from the xLights community. Automatically matches imported models to your show's models using name similarity, model type, and pixel count. Generates a new .xsq with effects remapped to your layout.

Args: import_path: Path to the .xsq or .zip file to import. overrides: Optional dict mapping imported model names to your model names. These take precedence over automatic matching. pixel_threshold: Similarity threshold for pixel count matching (0.0-1.0). Default 0.70 means models must have at least 70% pixel count similarity. show_name: Which show folder to import into (e.g., "christmas", "halloween"). If omitted and multiple shows exist, returns available shows so you can ask the user which one to use.

Returns: Dict with mapping report, output path, and summary statistics.

Check Falcon Pi Player connection status and current state.

Returns FPP version, current playlist, scheduler state, etc.

Upload a sequence (.fseq) and optional audio to Falcon Pi Player.

Args: fseq_path: Path to the .fseq file to upload audio_path: Optional path to the audio file (.mp3/.ogg)

List all playlists on the Falcon Pi Player.

Start a playlist on the Falcon Pi Player.

Args: playlist_name: Name of the playlist to start repeat: Whether to loop the playlist

Stop current playback on the Falcon Pi Player.