# music-light (agent notes)

This repo is a single Python script (`luz-musica.py`) that:
- reads the currently playing track via `playerctl` (MPRIS metadata),
- fetches the album art (URL or `file://`),
- extracts a dominant color (filtering dark/low-saturation pixels),
- sends `light.turn_on` to a Home Assistant instance with `rgb_color` + `brightness_pct`.

## How to run (local)
- System dependency: `playerctl` must be installed and your player must expose MPRIS metadata.
- Python deps: `requests`, `Pillow`.
- Run: `python3 luz-musica.py`

## Dependencies

### Ubuntu/Debian/etc: isolated venv (pip)
Install system bits:
- `sudo apt-get update`
- `sudo apt-get install -y python3 python3-venv playerctl`

Create a venv and install Python deps:
- `python3 -m venv .venv`
- `source .venv/bin/activate`
- `python -m pip install -U pip`
- `pip install -r requirements.txt`

Then run:
- `python luz-musica.py`

## Configuration
Edit constants at the top of `luz-musica.py`:
- `HA_URL`, `HA_TOKEN`, `LIGHT_ENTITY`
- tuning: `BRIGHTNESS_PCT`, `SATURATION_BOOST`, `MIN_SATURATION`, `MIN_VALUE`, `REQUEST_TIMEOUT`

## Expected behavior / troubleshooting
- If nothing is playing (or `playerctl` fails), the loop sleeps and retries.
- If `mpris:artUrl` is missing, it logs and waits for the next track change.
- If Home Assistant is unreachable or returns an error, it logs the exception and retries.

## Suggested improvements (optional)
- Read `HA_URL`/`HA_TOKEN` from env vars (keep defaults as fallback) to avoid editing the script.
- Add a `requirements.txt` and a short `README.md` once the project grows.