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

Network control settings:

- `CONTROL_HOST`: bind address for the control API, default `0.0.0.0`
- `CONTROL_PORT`: bind port for the control API, default `8765`
- `CONTROL_TOKEN`: optional shared token required for control requests

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

## Home Assistant Control

The running script exposes a small HTTP API that Home Assistant can call over the local network:

- `GET /status`
- `POST /pause`
- `POST /resume`
- `POST /toggle`

When paused, the systemd service stays running but the script stops changing the light. When resumed, it forces an update from the current track.

Example requests from another machine on the same network:

```bash
curl http://ubuntu-host:8765/status
curl -X POST http://ubuntu-host:8765/pause
curl -X POST http://ubuntu-host:8765/resume
curl -X POST http://ubuntu-host:8765/toggle
```

If you set `CONTROL_TOKEN`, include it as a header:

```bash
curl -X POST -H "X-Music-Light-Token: your-token" http://ubuntu-host:8765/toggle
```

Home Assistant `configuration.yaml` example:

```yaml
rest_command:
  music_light_pause:
    url: "http://ubuntu-host:8765/pause"
    method: post
  music_light_resume:
    url: "http://ubuntu-host:8765/resume"
    method: post
  music_light_toggle:
    url: "http://ubuntu-host:8765/toggle"
    method: post
```

With `CONTROL_TOKEN`:

```yaml
rest_command:
  music_light_toggle:
    url: "http://ubuntu-host:8765/toggle"
    method: post
    headers:
      X-Music-Light-Token: "your-token"
```

Create Home Assistant scripts so they can be shown as dashboard buttons:

```yaml
script:
  pause_music_light:
    alias: Pause Music Light
    sequence:
      - service: rest_command.music_light_pause

  resume_music_light:
    alias: Resume Music Light
    sequence:
      - service: rest_command.music_light_resume

  toggle_music_light:
    alias: Toggle Music Light
    sequence:
      - service: rest_command.music_light_toggle
```

Then add `script.pause_music_light`, `script.resume_music_light`, or `script.toggle_music_light` to a Home Assistant dashboard as button cards.

## 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.
- If Home Assistant cannot reach the control API, check the Ubuntu host firewall and confirm `CONTROL_HOST=0.0.0.0`.