flake

.gitignore

@@ -0,0 +1,29 @@
+# Python bytecode / caches
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Virtualenvs
+.venv/
+venv/
+ENV/
+
+# direnv / nix
+.direnv/
+.envrc
+result
+result-*
+
+# Env/config files (keep secrets out of git even for local projects)
+.env
+.env.*
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Logs / temp
+*.log
+*.tmp

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.

Makefile

@@ -0,0 +1,15 @@
+PY ?= python3
+VENV ?= .venv
+
+.PHONY: venv deps run
+
+venv:
+	$(PY) -m venv $(VENV)
+	$(VENV)/bin/python -m pip install -U pip
+
+deps: venv
+	$(VENV)/bin/pip install -r requirements.txt
+
+run: deps
+	$(VENV)/bin/python luz-musica.py
+

flake.nix

@@ -0,0 +1,42 @@
+{
+  description = "music-light: dev environment (Python + playerctl) for NixOS/Nix";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = { self, nixpkgs }:
+    let
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+      ];
+
+      forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f system);
+    in
+    {
+      devShells = forAllSystems (system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+
+          # Use a stable Python version with good binary coverage for Pillow.
+          py = pkgs.python312.withPackages (ps: [
+            ps.requests
+            ps.pillow
+          ]);
+        in
+        {
+          default = pkgs.mkShell {
+            packages = [
+              py
+              pkgs.playerctl
+            ];
+
+            shellHook = ''
+              echo "music-light devShell ready: $(python --version)"
+            '';
+          };
+        });
+    };
+}
+

requirements.txt

@@ -0,0 +1,2 @@
+requests>=2.0
+Pillow>=9.0

shell.nix

@@ -0,0 +1,14 @@
+{ pkgs ? import <nixpkgs> { } }:
+let
+  py = pkgs.python312.withPackages (ps: [
+    ps.requests
+    ps.pillow
+  ]);
+in
+pkgs.mkShell {
+  packages = [
+    py
+    pkgs.playerctl
+  ];
+}
+