49 lines
2 KiB
Markdown
49 lines
2 KiB
Markdown
# 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`
|
|
- Service install: `make install-service` creates and starts a `systemd --user` unit on Ubuntu.
|
|
|
|
## 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`
|
|
|
|
## Ubuntu service
|
|
- The service is installed as `~/.config/systemd/user/music-light.service`.
|
|
- The service loads optional environment overrides from `~/.config/music-light/env`.
|
|
- Use `make status-service`, `make logs-service`, `make restart-service`, and `make uninstall-service`.
|
|
- Keep it as a user service because `playerctl` needs access to the logged-in desktop user's MPRIS session.
|
|
|
|
## 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.
|