music-light/AGENTS.md

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.