Screen Light Sync

A Python application for real-time screen color synchronization with Home Assistant smart lights.

🌟 Features

• Real-time Color Sync: Synchronize screen colors with smart lights in real-time
• Multiple Color Modes:
  • average - Average color from entire screen
  • dominant - Most dominant color on screen
  • center - Color from center of screen (fastest)
• Fast Mode: Quick capture mode for optimal performance
• Rate Limiting: Control update frequency to avoid API spam
• Multi-Monitor Support: Support for multiple monitors
• Home Assistant Integration: Direct integration with Home Assistant

📋 Requirements

• Python 3.7+
• Home Assistant with RGB-capable smart light
• Monitor/screen to sync

🚀 Installation

1. Clone repository:

git clone https://github.com/fadelmvi/screen-light-sync
cd screen-light-sync

2. Install dependencies:

pip install -r requirements.txt

3. Setup configuration: Copy the .env.example file and configure:

cp .env.example .env

Then edit .env with your settings:

• HA_URL: Your Home Assistant URL
• HA_TOKEN: Home Assistant access token
• LIGHT_ENTITY: Your smart light entity ID

⚙️ Configuration

Copy the example environment file and configure your settings:

cp .env.example .env

Edit the .env file with your Home Assistant configuration:

# Home Assistant Configuration
HA_URL=http://your-home-assistant:8123/api/services/light/turn_on
HA_TOKEN=your-home-assistant-token
LIGHT_ENTITY=light.your_smart_light

# Screen Capture Settings
UPDATE_INTERVAL=0.5
COLOR_CHANGE_THRESHOLD=25
BRIGHTNESS=255

Getting Home Assistant Token

1. Login to Home Assistant
2. Go to Profile → Long-Lived Access Tokens
3. Click "Create Token"
4. Copy the token and paste it into the HA_TOKEN field in your .env file

🎮 Usage

Basic Usage

python main.py

Advanced Options

# Use dominant color mode
python main.py --mode dominant

# Fast mode with center color
python main.py --fast

# Custom update interval
python main.py --interval 1.0

# Use second monitor
python main.py --monitor 2

# Test Home Assistant connection
python main.py --test

Command Line Options

Option	Description	Default
--mode	Color extraction mode: average, dominant, center	average
--interval	Update interval in seconds	0.5
--fast	Fast mode - use center capture area	False
--test	Test Home Assistant connection	False
--monitor	Monitor index to capture	1

🏗️ Project Structure

screen-light-sync/
├── main.py                 # Application entry point
├── requirements.txt        # Dependencies
├── README.md              # Documentation
└── src/
    ├── __init__.py        # Package initialization
    ├── config.py          # Configuration
    ├── color_utils.py     # Color extraction utilities
    ├── ha_controller.py   # Home Assistant controller
    └── screen_capture.py  # Screen capture utilities

🔧 Development

Setup Development Environment

# Install development dependencies
pip install -r requirements.txt

# Run tests (if available)
pytest

# Format code
black .

# Lint code
flake8 .

Adding New Color Modes

1. Add new color extraction function in src/color_utils.py
2. Update ColorMode enum in src/screen_capture.py
3. Update extract_color method in ScreenLightSync class

🎯 Performance Tips

1. Use Fast Mode (--fast) for best performance
2. Adjust interval - higher interval = lower CPU usage
3. Use Center Mode for screens with static content on edges
4. Single monitor - disable additional monitors if not needed

🐛 Troubleshooting

Connection Issues

# Test Home Assistant connection
python main.py --test

Performance Issues

• Use --fast mode
• Increase --interval value
• Check CPU usage and adjust accordingly

Common Errors

Error	Solution
Import "numpy" could not be resolved	Install: pip install numpy
Connection failed	Check HA_URL and HA_TOKEN in .env file
Entity not found	Verify LIGHT_ENTITY ID in Home Assistant

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork repository
2. Create feature branch
3. Commit changes
4. Push to branch
5. Create Pull Request

📞 Support

If you encounter issues, please:

1. Check troubleshooting section
2. Create issue on GitHub
3. Contact developer

---

Happy syncing! 🌈💡