flake

AGENTS.md

@@ -0,0 +1,51 @@
+# 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 (recommended setups)
+
+### Option A (NixOS / Nix): reproducible dev shell (no pip)
+If you have Nix with flakes enabled:
+- Enter shell: `nix develop`
+- Run: `python3 luz-musica.py`
+
+Without flakes:
+- Enter shell: `nix-shell`
+- Run: `python3 luz-musica.py`
+
+### Option B (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.