Installation Guide

LightGroove is easy to install on Windows, macOS, and Linux. Choose the method that best suits your needs.

Windows (Recommended)

Using the Installer

The easiest way to get started on Windows:

  1. Download the latest LightGrooveSetup.exe from the Releases page
  2. Run the installer and follow the prompts
  3. Launch LightGroove from the Start Menu or Desktop shortcut
  4. The web UI will automatically open at http://localhost:5555

Note: The installer is automatically built and published whenever changes are pushed to the main branch, so you always get the latest version.

macOS

Using Homebrew

The recommended installation method for macOS:

# Add the LightGroove tap
brew tap oliverbyte/lightgroove https://github.com/oliverbyte/lightgroove.git

# Install LightGroove
brew install --HEAD oliverbyte/lightgroove/lightgroove

# Run LightGroove
lightgroove

After running lightgroove, open your browser to http://localhost:5555.

Linux

From Source

The recommended method for Linux users:

# Clone the repository
git clone https://github.com/oliverbyte/lightgroove.git
cd lightgroove

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run LightGroove
python main.py

Then open http://localhost:5555 in your browser.

From Source (All Platforms)

Requirements

Installation Steps

# Clone the repository
git clone https://github.com/oliverbyte/lightgroove.git
cd lightgroove

# Create and activate virtual environment
python -m venv .venv

# On Windows:
.venv\Scripts\activate

# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run LightGroove
python main.py

Dependencies

LightGroove requires the following Python packages (automatically installed via requirements.txt):

First Run

After installation, LightGroove will:

  1. Start the web server on port 5555
  2. Load configuration files from the config/ directory
  3. Begin sending ArtNet data to configured nodes
  4. Open the web UI in your default browser (or manually navigate to http://localhost:5555)

Configuration

Before using LightGroove with your lighting setup, you'll need to configure:

1. Fixtures

Define your fixture profiles in config/fixtures.json or use the provided examples. Each fixture needs:

2. Patch

Configure which fixtures are patched to which universes and DMX addresses in config/patch.json.

3. ArtNet Nodes

Set up your ArtNet output nodes using the Config tab in the web UI:

4. Colors (Optional)

Customize color definitions in the Config tab or edit config/colors.json directly. Define RGBW values (0.0-1.0 range) for each color.

Network Setup

For ArtNet Output

Ensure your computer and ArtNet nodes are on the same network:

  1. Connect your computer and ArtNet interface to the same network switch or router
  2. Configure your ArtNet node's IP address (check the device documentation)
  3. Add the ArtNet node in LightGroove's Config tab with the correct IP address
  4. Verify connectivity by checking DMX output on your fixtures

Firewall Configuration

If you encounter issues:

Updating

Windows Installer

Download and run the latest installer from the Releases page. It will update your installation automatically.

Homebrew (macOS)

brew upgrade lightgroove

From Source

cd lightgroove
git pull
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt --upgrade

Troubleshooting

Port Already in Use

If port 5555 is already in use, you can modify the port in main.py or stop the other application using the port.

No DMX Output

Check the following:

Web UI Not Loading

Try the following:

Getting Help

If you encounter issues: