# 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:

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

## Setup

Create a virtual environment and install dependencies:

```bash
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

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

Or use the Makefile:

```bash
make run
```

## Ubuntu User Service

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

```bash
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:

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

Manage the service with:

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

Remove the service:

```bash
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.