music-light/README.md

music-light

luz-musica.py changes a Home Assistant light to match the active media artwork.

Requirements

• python3
• python3-venv
• playerctl
• Python packages from requirements.txt

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y python3 python3-venv playerctl

Setup

Create a virtual environment and install dependencies:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt

Configuration

Edit the constants at the top of luz-musica.py:

• HA_URL
• HA_TOKEN
• LIGHT_ENTITY

You can also tune:

• BRIGHTNESS_PCT
• SATURATION_BOOST
• MIN_SATURATION
• MIN_VALUE
• REQUEST_TIMEOUT

Run

source .venv/bin/activate
python luz-musica.py

Or use the Makefile:

make run

Troubleshooting

• If nothing is playing, or playerctl cannot read metadata, the loop sleeps and retries.
• If mpris:artUrl is missing, the script logs it and waits for the next track change.
• If Home Assistant is unreachable or returns an error, the script logs the exception and retries.