Skip to main content

Documentation

AI Scene Generation

3 min readEdit on GitHub

Lights Pi includes an AI-powered scene generation system that translates natural language descriptions into proper DMX values for your specific fixture rig.

How It Works

  1. You describe a scene in plain English ("soft warm sunset", "moody purple and blue")
  2. The system reads your fixture inventory from the QLC+ workspace
  3. Each fixture's channel layout is resolved from its .qxf definition file (the same files QLC+ uses)
  4. The AI receives your description plus the full channel metadata — names, roles, presets, groups
  5. It generates a QLC+ scene XML with correct channel values per fixture
  6. The scene is applied live via WebSocket — lights change immediately

Fixture-Aware Generation

The AI doesn't guess channel positions. It knows that:

  • A SlimPAR Pro W has Warm White / Cool White / Amber (no RGB) — so "warm light" drives the warm channel, not a non-existent red channel
  • A SlimPAR Pro H has Dimmer / R / G / B / Amber / White / UV — so it can mix full-spectrum color
  • A SlimPAR 56 in 3-Ch mode is pure RGB — simple color mixing
  • Strobe, macro, and auto-program channels are always set to 0 for static scenes

This prevents the common problem of AI-generated scenes accidentally triggering strobe or color-wheel modes.

Using the CLI

bash
1# Generate and preview
2./lightsctl.sh generate-scene "warm sunset ambiance" --preview
3
4# Generate and deploy to the Pi
5./lightsctl.sh generate-scene "party mode" --add-to-workspace
6
7# Generate multiple variations
8./lightsctl.sh generate-scene "dramatic spotlight" --variations 3
9
10# Save to file
11./lightsctl.sh generate-scene "cool morning" --output scenes/morning.xml
12
13# Use a specific style
14./lightsctl.sh generate-scene "concert energy" --style modular

Using the Web UI

  1. Open http://lights.local:5000
  2. Type a description in the AI chat box (e.g. "soft dim warm light")
  3. The scene is generated and applied live
  4. If you like it, click the 💾 save button to persist it permanently
  5. Saved scenes appear in the Scenes tab — no AI call needed to recall them

From an MCP Agent

If you've installed the MCP server, the same generation pipeline is reachable as the generate_scene tool. Tell Claude Desktop (or any MCP client) something like "generate a scene for a warm evening glow, apply it, and save it as 'evening edit'" — it'll call generate_scene followed by snapshot_scene automatically. Agents can also use describe_scene to inspect any saved scene before activating it.

See MCP-Server for the full tool catalog.

Saving Scenes

Every successful AI command in the web UI shows a 💾 save button. Clicking it:

  1. Prompts you for a name (pre-filled with your command text)
  2. Saves the scene XML into the QLC+ workspace under "AI Generated" folder
  3. The scene immediately appears in the Scenes tab
  4. It persists through reboots — it's a first-class QLC+ scene

For non-generation commands (like "make it warmer"), the save button captures a snapshot of the current live channel state as a new scene.

Scene Templates

Pre-defined templates that don't require an AI call:

bash
./lightsctl.sh list-templates
./lightsctl.sh generate-from-template youtube-studio --add-to-workspace

Available: youtube-studio, party, ambient, spotlight, work-light, warm-white, cool-white

Configuration

In your .env file:

bash
1AI_PROVIDER=openai          # openai, anthropic, or ollama
2AI_API_KEY=sk-...           # API key (not needed for ollama)
3AI_MODEL=gpt-4.1            # Model name
4AI_SCENE_STYLE=complete     # Default style: complete, modular, timeline, reactive

Fixture Groups

Target specific fixtures with AI commands:

bash
./lightsctl.sh group-create "front" "0,3,4" "Front wash lights"
./lightsctl.sh group-scene "front" "warm and bright" --add-to-workspace

In the web UI, select groups from the chip row before sending a command — the AI will only affect those fixtures.

Was this page helpful?