LumiSync

Synchronize Govee, iDotMatrix, and LSC/Tuya lights with your screen or music.

Visit the website: lumisync.minlor.net

Features • Installation • Usage • Development • Roadmap

✨ Features

Supported devices

Every device family works out of the box — a single pip install lumisync (or the packaged Windows build) bundles all transports, no extras to remember.

📸 Screenshots

Devices

_{Discover, organize, and directly control LAN and Bluetooth lights.}

Monitor and music sync

Monitor Sync Map display colors across one or more lights.	Music Sync Choose reactions and palettes or let Auto Director decide.

📦 Installation

Requirements: Python 3.11 or higher

From PyPI (Recommended)

pip install lumisync

From GitHub (Latest)

pip install git+https://github.com/Minlor/LumiSync.git

Development Install

git clone https://github.com/Minlor/LumiSync.git
cd LumiSync
pip install -e .

Prebuilt downloads

• Windows — a portable .zip and a single-file .exe are attached to each GitHub release.
• Linux — an x86_64 AppImage is attached to each release; chmod +x it and run. Build it yourself with tools/build_linux.sh (needs Python 3.12+ and the Qt X11 runtime libraries listed in the Linux build workflow). The AppImage requires glibc 2.35 or newer (Ubuntu 22.04+). Linux releases are checked by opening the packaged GUI on X11 in a clean Ubuntu 22.04 runtime. A Flatpak is scaffolded in packaging/flatpak/ but not yet finished.

Platform notes: Windows is fully supported. On Linux, device control, music sync, and manual control work on X11 and Wayland; screen (monitor) sync currently requires an X11/Xorg session — Wayland capture is planned.

🚀 Usage

Launch the App

lumisync

The GUI opens by default. The legacy interactive terminal is still available with lumisync --cli; direct headless modes are available through lumisync --monitor and lumisync --music.

Quick Start

1. Discover devices — Click "Discover Devices" for Govee LAN lights or "Scan Bluetooth" for pixel panels.
2. Select your lights — Choose one or more devices from the Devices page.
3. Control your lights — Set color, brightness and power directly from each device card.
4. Start syncing — Open Monitor Sync or Music Sync, choose the target devices and start the mode.

Interface

• Devices — Discover, add and control LAN or Bluetooth lights; multi-select devices for bulk actions.
• Monitor Sync — Map display colors to selected devices, groups, zones, and custom LED regions.
• Music Sync — Choose reactions, palettes, targets and brightness, or use Auto Director.
• Draw — Paint still images or frame-by-frame animations for compatible iDotMatrix panels.
• Settings — Choose Acrylic, Mica, or Solid Dark; select a display, tune sync behavior, manage groups, startup and system-tray options.

Configuration

• LED Mapping - Customize which screen regions map to which LEDs
• Brightness - Adjust per-mode brightness (10-100%)
• Display Selection - Choose which monitor to capture (multi-monitor support)
• Sync Tuning - Tune smoothing, saturation, frame rate, gamma and music response

🛠️ Development

Project Structure

lumisync/
├── lumisync.py          # Entry point & CLI
├── connection.py        # Govee UDP protocol (port 4001/4002)
├── devices.py           # Device discovery & caching
├── config/options.py    # Runtime configuration
├── sync/                # Monitor & music sync engines
├── gui/                 # PySide6 application
│   ├── controllers/     # Business logic (QObject + pyqtSignal)
│   ├── views/           # UI components
│   └── widgets/         # Reusable widgets
└── utils/               # Logging, colors, file ops

Run Tests

python -m unittest discover -s tests

Brand and documentation assets

The production app icon, transparent mark, tray variants, Windows .ico, and GitHub banner live in assets/brand. Regenerate the complete icon set from its single SVG geometry with:

python tools/generate_brand_assets.py

Fresh README screenshots can be captured from the real PySide application on Windows with:

python tools/capture_readme_screenshots.py --material acrylic

Platform Support

🗺️ Roadmap

• Multi-device support
• Wayland & macOS screen capture
• Basic color control mode
• Custom sync algorithms
• Plugin system for community extensions

🙏 Credits

• Wireshark — Protocol analysis
• See pyproject.toml for all dependencies

📄 License

MIT © Minlor