Documentation

Complete guide to using and configuring LightGroove.

Quick Start

1. Install LightGroove for your platform
2. Launch the application - the web UI will open at http://localhost:5555
3. Configure your ArtNet nodes in the Config tab
4. Start controlling your lights from the Faders or Colors tabs

User Interface Guide

Globals Tab

Master controls that affect all fixtures:

• Master (0-100%): Scales all DMX output. Use this as a global brightness control without touching individual faders.
• FX BPM (1-480): Controls the speed of color effects in beats per minute.
• FX Fade (0-100%): Smoothness of color transitions as a percentage of the beat interval. 0% = instant, 100% = smooth fade over entire beat.

Faders Tab

Individual fixture control:

• Each fixture is displayed as a card with its name and channels
• Vertical faders control each channel (Dimmer, R, G, B, W, etc.)
• DMX values (0-255) are displayed in real-time below each fader
• Changes are sent immediately to the DMX output

Colors Tab

Static Colors

Click any color button to set all fixtures to that color:

• Red, Green, Blue - Primary colors
• Cyan, Magenta, Yellow - Secondary colors
• White, Orange, Purple - Additional colors
• Black - Turns all color channels off

Colors are defined in config/colors.json and can be edited in the Config tab.

Color FX

Dynamic effects that run on the server:

• Random 1: All fixtures show the same random color, changing at BPM speed
• Random 2: Each fixture gets a different random color every beat
• Random 3: Even/odd fixtures alternate with black (strobe effect)
• Random 4: Chaser - one fixture at a time in sequence

All effects respect the FX BPM and FX Fade settings from the Globals tab.

Config Tab

Web-based configuration editor:

ArtNet Nodes

• Add new nodes with IP address and universe number
• Edit existing nodes
• Delete nodes you no longer need

Universe Mapping

• Map DMX universes to ArtNet nodes and universes
• Example: DMX Universe 1 → Node IP 192.168.1.100, ArtNet Universe 0

Colors

• Edit RGBW values (0.0-1.0) for each color with sliders
• Live preview shows the color as you edit
• Add new colors or remove existing ones

Global Settings

• Default output mode
• Frames per second (FPS)

Note: All changes are saved immediately and the server reloads automatically.

Configuration Files

fixtures.json

Defines fixture types and their channel layouts:

{
  "PAR_RGBW": {
    "channels": {
      "dimmer": 0,
      "red": 1,
      "green": 2,
      "blue": 3,
      "white": 4
    }
  }
}

patch.json

Maps fixtures to DMX universes and addresses:

{
  "1": [
    {
      "fixture": "PAR_RGBW",
      "address": 1,
      "name": "Front Left"
    },
    {
      "fixture": "PAR_RGBW",
      "address": 6,
      "name": "Front Right"
    }
  ]
}

artnet.json

Configures ArtNet output nodes and universe mapping:

{
  "nodes": [
    {
      "ip": "192.168.1.100",
      "universe": 0
    }
  ],
  "universe_mapping": {
    "1": {
      "node_ip": "192.168.1.100",
      "artnet_universe": 0
    }
  }
}

colors.json

Defines RGBW color values (0.0-1.0 range):

{
  "red": {"r": 1.0, "g": 0.0, "b": 0.0, "w": 0.0},
  "green": {"r": 0.0, "g": 1.0, "b": 0.0, "w": 0.0},
  "blue": {"r": 0.0, "g": 0.0, "b": 1.0, "w": 0.0},
  "white": {"r": 0.0, "g": 0.0, "b": 0.0, "w": 1.0}
}

DMX and ArtNet

What is DMX?

DMX512 is the standard lighting control protocol. It sends data to fixtures telling them what to do (brightness, color, etc.). Each DMX universe can control up to 512 channels.

What is ArtNet?

ArtNet is a protocol for sending DMX data over Ethernet networks. It allows you to control DMX fixtures using network equipment instead of traditional DMX cables.

How LightGroove Uses ArtNet

1. LightGroove generates DMX values based on your fader positions and color settings
2. These values are packaged into ArtNet packets
3. Packets are sent over your network to ArtNet nodes
4. ArtNet nodes convert the network data back to DMX signals
5. DMX signals control your lighting fixtures

Hardware Setup

Required Equipment

• Computer running LightGroove (Windows, macOS, or Linux)
• Network (router/switch) to connect computer and ArtNet nodes
• ArtNet Node (e.g., Enttec ODE, DMXking eDMX1, etc.) to convert ArtNet to DMX
• DMX Fixtures (lights) with DMX input
• DMX Cables to connect fixtures (standard 5-pin XLR or 3-pin XLR)

Connection Diagram

Computer (LightGroove)
    |
    | Ethernet
    |
Network Switch/Router
    |
    | Ethernet
    |
ArtNet Node
    |
    | DMX Cable
    |
Lighting Fixtures (daisy-chained)

Network Configuration

1. Connect your computer and ArtNet node to the same network
2. Set the ArtNet node to a static IP or note its DHCP-assigned address
3. Configure the ArtNet node's universe in its settings
4. Add the node's IP address in LightGroove's Config tab

Advanced Usage

Multiple Universes

You can use multiple DMX universes for large setups:

1. Add fixtures to different universes in patch.json
2. Configure universe mapping in the Config tab
3. Each universe can go to a different ArtNet node or different universe on the same node

Custom Fixture Profiles

Create profiles for any fixture type:

1. Determine the fixture's channel layout from its manual
2. Add a new fixture type in fixtures.json
3. Define each channel and its offset from the start address
4. Use the new fixture type in patch.json

HTTP API

LightGroove exposes a REST API for integration:

• GET /api/state - Get current state
• POST /api/master - Set master level
• POST /api/color - Set color
• POST /api/fader - Control individual channels

See the code in src/http_api.py for full API documentation.

Performance Tips

• Use wired Ethernet for ArtNet nodes when possible (more reliable than WiFi)
• Keep ArtNet nodes on the same network segment as the computer
• Adjust FPS in config if you experience network congestion
• Use quality DMX cables and terminators for long cable runs

Development

For development setup, architecture details, and contribution guidelines, see DEVELOPMENT.md on GitHub.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

See the Issues page for ideas or report bugs.

License

LightGroove is released under the MIT License. See LICENSE for details.