Add Ubuntu user service support

README.md

@@ -29,7 +29,7 @@ pip install -r requirements.txt
 
 ## Configuration
 
-Edit the constants at the top of `luz-musica.py`:
+For local runs, edit the constants at the top of `luz-musica.py` or export environment variables:
 
 - `HA_URL`
 - `HA_TOKEN`
@@ -56,8 +56,49 @@ Or use the Makefile:
 make run
 ```
 
+## Ubuntu User Service
+
+Install and start the script as a `systemd --user` service:
+
+```bash
+make install-service
+```
+
+The install target:
+
+- creates `.venv` and installs `requirements.txt`
+- copies `music-light.env.example` to `~/.config/music-light/env` if it does not exist
+- writes `~/.config/systemd/user/music-light.service`
+- enables and starts the service
+
+Edit the service environment file with your Home Assistant settings:
+
+```bash
+nano ~/.config/music-light/env
+make restart-service
+```
+
+Manage the service with:
+
+```bash
+make status-service
+make logs-service
+make restart-service
+make stop-service
+make start-service
+```
+
+Remove the service:
+
+```bash
+make uninstall-service
+```
+
+This is installed as a user service because `playerctl` needs access to the desktop user's MPRIS session.
+
 ## Troubleshooting
 
 - If nothing is playing, or `playerctl` cannot read metadata, the loop sleeps and retries.
 - If `mpris:artUrl` is missing, the script logs it and waits for the next track change.
 - If Home Assistant is unreachable or returns an error, the script logs the exception and retries.
+- If the service cannot see the media player, make sure it is running under the same logged-in desktop user.