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

For local runs, edit the constants at the top of luz-musica.py or export environment variables:

• 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

Ubuntu User Service

Install and start the script as a systemd --user service:

make install-service

The install target:

• creates .venv and installs requirements.txt
• copies music-light.env.example to ~/.config/music-light/env if it does not exist
• writes ~/.config/systemd/user/music-light.service
• enables and starts the service

Edit the service environment file with your Home Assistant settings:

nano ~/.config/music-light/env
make restart-service

Manage the service with:

make status-service
make logs-service
make restart-service
make stop-service
make start-service

Remove the service:

make uninstall-service

This is installed as a user service because playerctl needs access to the desktop user's MPRIS session.

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.
• If the service cannot see the media player, make sure it is running under the same logged-in desktop user.