LumiSync

Control your lights, switches and smart plugs. Sync local lights with your screen or music.

Visit the website: lumisync.minlor.net

Features • Installation • Usage • Development • Roadmap

Features

Supported devices

The dependencies for these transports ship with a single install. Device support depends on its firmware, capabilities, and the account's authorization.

See account setup. LSC and Tuya Smart password login use built-in client configuration; no Android package, installation or developer account is required. Each brand uses its own account namespace: choose the service and country used in your phone app. LumiSync suggests a country from your computer's region; you can change it before signing in. Account routing is automatic, and account lists partially hide email addresses.

Cloud connections provide manual controls. Screen and music sync use supported local connections. Meter readings and history depend on the device schema, firmware and account service; missing measurements are shown as not reported. Voltage and current are live readings; historical energy is measured in kWh.

Screenshots

Screenshots show LumiSync 0.8.2 with example devices, accounts and readings.

Devices

_{Recognize each device type and use the controls it supports.}

Accounts and plug readings

Sign in with your own account and choose its country from a dropdown. Opening a supported plug refreshes its electrical readings every five seconds while visible; monthly energy totals and daily readings load on demand.

Account sign-in and connected accounts

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

Prebuilt Windows and Linux downloads do not require a separate Python install. Installing from PyPI or source requires 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. Connect or discover. Open Devices → Accounts for Wi-Fi account control. Find Devices refreshes linked accounts, local discovery and saved readings together.
2. Select your devices. Use device cards and the inspector. Find Devices also matches imported Tuya devices to their LAN addresses.
3. Control your devices. Power, brightness, color, white-temperature and meter controls appear where the device supports them.
4. Start syncing. Choose local connections in the device inspector, then open Monitor Sync or Music Sync. Cloud connections offer manual controls.

Account setup

Open Devices → Accounts, choose Govee, Tuya or LSC, then enter your email and password. For Tuya and LSC, select the country used for your account. LumiSync suggests your computer's region and handles account routing. Enter an email verification code if the service requests one.

Tuya Smart and LSC accounts are separate. Smart Life uses Tuya → QR sign-in: copy the user code from the phone app's Account and Security settings, request a QR code, scan it and approve. The approval screen names Home Assistant because LumiSync uses that public device-sharing registration; no Home Assistant installation is needed. Govee also offers an API key method.

Remember this account saves its session in the OS credential store. Passwords and verification codes are not saved, and account labels mask emails. Use Find Devices to refresh linked accounts and local devices together.

Tuya and LSC sign-in configuration is included. No Android package, Android installation or developer account is needed.

Interface

• Devices — Discover lights, switches and plugs; connect vendor accounts, choose local/cloud connections, create groups, and view supported electrical readings and energy history.
• 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. The device inspector's Panel Tools opens clock, countdown, scoreboard, and rotation controls.
• Settings — Choose Acrylic, Mica or Solid Dark; tune sync, startup and system-tray behavior. About shows your version, account setup, update checks and the logs folder.

The UI adapts to short/narrow windows: account actions and sync Start/Stop stay visible, Draw tools reflow above the canvas, and Settings uses a section dropdown when space is tight. Daily readings and technical details expand on demand.

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

Troubleshooting

If a connection or command fails, open Settings → About → Open logs folder. Connection logs and native crash diagnostics are kept there. Try Find Devices to refresh linked accounts and local status. Vendor verification challenges may require a code or completing sign-in in the phone app; see account setup.

Development

Project Structure

lumisync/
├── lumisync.py          # Entry point & CLI
├── connection.py        # Govee UDP protocol (port 4001/4002)
├── devices.py           # Device discovery & caching
├── accounts/            # Vendor sign-in, credential vault & energy history
├── drivers/             # LAN, Bluetooth and account device adapters
├── config/options.py    # Runtime configuration
├── sync/                # Monitor & music sync engines
├── gui/                 # PySide6 application
│   ├── controllers/     # Business logic (QObject + Signal)
│   ├── 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

Regenerate the README and website screenshots with isolated example data and no device or account requests:

python tools/capture_example_screenshots.py

The separate tools/capture_readme_screenshots.py utility captures your live application setup; review those images for private details before sharing.

Platform Support

Roadmap

• Multi-device support
• Govee, Tuya Smart and LSC personal accounts
• Device capability controls and supported plug metering
• iDotMatrix drawing and display tools
• 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