AmbiSync

Real-time screen color synchronization for Philips Hue and IKEA Dirigera smart lights.

What is AmbiSync?

AmbiSync captures your screen content, analyzes the dominant colors in three zones (left, center, right), and updates your smart lights to match. This creates an immersive ambient lighting effect that extends your screen into your room.

How It Works

1. Screen Capture: Uses mss (or PIL fallback) to capture your screen at configurable FPS (5-30)
2. Color Analysis: Divides screen into 3 zones, downsamples for performance, calculates dominant color per zone
3. Smart Processing:
   • Automatically dims lights for dark content
   • Converts BGRA to RGB on Windows
   • Handles multi-monitor setups
4. Light Control: Updates smart lights with calculated colors

Installation

Pre-built Binaries

Download from Releases:

Windows:

AmbiSync-vX.X.X-Windows.exe

Double-click to run.

macOS:

AmbiSync-vX.X.X-macOS.dmg

Open and drag to Applications.

Linux (all distros):

Option 1: With installer (recommended)

tar -xzf AmbiSync-vX.X.X-Linux-x86_64.tar.gz
cd AmbiSync-vX.X.X
./install.sh
ambisync

Option 2: Standalone binary

chmod +x AmbiSync-vX.X.X-Linux-x86_64
./AmbiSync-vX.X.X-Linux-x86_64

From Source

Prerequisites:

• Python 3.9+
• tkinter

Installation:

git clone https://github.com/Chafficui/AmbiSync.git
cd AmbiSync
pip install -r requirements.txt
python run_ambisync.py

Configuration

First Setup

1. Start AmbiSync
2. Click Settings (⚙)
3. Configure your smart lights:

Philips Hue

• Bridge IP: Find in Hue app → Settings → Bridge
• Username: Click "🔑 Generate" → Press bridge button → Wait for confirmation

IKEA Dirigera

• Hub IP: Find in IKEA Home app → Settings → Hub
• Token: Click "🔑 Generate" → Press action button on hub bottom → Wait for confirmation

Light Mapping

Switch to "Light Mapping" tab - lights are auto-discovered.

Click on lights to assign them to zones:

• Left Zone: Lights for left side of screen
• Center Zone: Lights for center/behind screen
• Right Zone: Lights for right side of screen

Lights can be assigned to multiple zones.

Performance

• FPS: Update frequency (5-30). Lower = less CPU usage. Default: 15
• Brightness: Light brightness (50-254). Default: 200
• Monitor: Select which monitor to capture (auto-detected)

All settings auto-save.

Usage

1. Configure lights (first time only)
2. Click "▶ Start Sync"
3. Lights follow screen colors
4. Click "⏸ Stop Sync" to stop (lights turn off automatically)

Configuration File

Settings are stored in:

• Linux/macOS: ~/.config/ambisync/config.json
• Windows: C:\Users\USERNAME\.config\ambisync\config.json

Example:

{
  "hue_enabled": true,
  "hue_bridge_ip": "192.168.1.100",
  "hue_username": "abc123...",
  "dirigera_enabled": false,
  "fps": 15,
  "brightness": 200,
  "monitor_index": 1,
  "light_mapping": {
    "left": ["hue_1", "hue_2"],
    "center": ["hue_3"],
    "right": ["hue_4"]
  }
}

Project Structure

AmbiSync/
├── src/
│   ├── controllers/           # Light controller implementations
│   │   ├── hue_controller.py
│   │   └── dirigera_controller.py
│   ├── core/                  # Core logic
│   │   ├── color_analyzer.py  # Screen capture & color extraction
│   │   └── sync_engine.py     # Main synchronization loop
│   ├── gui/                   # User interface
│   │   ├── main_window.py
│   │   └── setup_wizard.py
│   └── utils/                 # Utilities
│       ├── config.py
│       └── color_utils.py
├── run_ambisync.py           # Entry point
└── requirements.txt          # Dependencies

Technical Details

Color Analysis Algorithm

1. Capture screen using mss (or PIL on fallback)
2. Convert BGRA → RGB (Windows compatibility)
3. Downsample image by factor of 15 for performance
4. Split into 3 horizontal zones
5. Calculate mean color per zone
6. Apply darkness handling (dim/blue tint for black content)
7. Update lights via API

Performance

• Screen capture: ~5-10ms (mss) or ~50ms (PIL)
• Color analysis: ~2-5ms
• API calls: ~10-50ms per light (async)
• Total latency: ~50-100ms per frame

API Usage

Philips Hue:

• REST API: PUT /api/{username}/lights/{id}/state
• Payload: {"on": true, "bri": 200, "xy": [x, y]}

IKEA Dirigera:

• Python library: dirigera
• WebSocket-based communication

Troubleshooting

Linux: Screen Capture Fails

Wayland Issue:

xhost +local:

Or log in with X11 session instead of Wayland.

Auto-fallback: App automatically switches to PIL if mss fails.

Windows: Wrong Colors

Fixed in v2.0+ (BGRA → RGB conversion).

Lights Not Responding

1. Verify network connectivity (lights and PC on same network)
2. Test connection in Settings
3. Check light IDs in mapping
4. Ensure lights are powered on

High CPU Usage

• Lower FPS (try 10 instead of 15)
• Reduce number of lights
• Check for other screen recording software

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/Chafficui/AmbiSync.git
cd AmbiSync
pip install -r requirements.txt
python run_ambisync.py

Code Style

• Follow PEP 8
• Use type hints where possible
• Add docstrings to functions/classes
• Test on multiple platforms before submitting

Building

Builds are automated via GitHub Actions. To test locally:

pip install pyinstaller
pyinstaller --name=AmbiSync --onefile --windowed run_ambisync.py

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• dirigera - IKEA Dirigera Python client
• mss - Fast screen capture
• Philips Hue API - Smart light control

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for ambient lighting enthusiasts