feat: production-ready Linux & macOS support

- Add `linux` (dbus-python, PyGObject, python-xlib) and `macos`
  (pyobjc) extras to pyproject.toml with sys_platform markers; move
  cross-platform screen-brightness-control + monitorcontrol to base deps.
- build-dist-linux.sh: install `.[linux]`, pkg-config pre-flight for
  dbus-1/glib-2.0, emit a systemd unit with DBUS_SESSION_BUS_ADDRESS +
  XDG_RUNTIME_DIR + ReadWritePaths for ~/.config and ~/.cache so MPRIS
  works and audit-log / thumbnail writes aren't blocked by ProtectHome.
- New build-dist-macos.sh + per-user LaunchAgent installer producing
  MediaServer-vX.Y-macos-{arm64,x86_64}.tar.gz.
- Templated media-server.service updated to match the dist layout with
  proper session-bus env vars and a writable state-dir grant.
- install_linux.sh: drop dead requirements.txt path; install via
  `pip install ".[linux]"` and pre-create the writable state dirs.
- Cross-platform album artwork: abstract MediaController.get_album_art()
  with Linux (mpris:artUrl, file:// + http(s)://) and macOS (Spotify URL)
  impls; routes/media artwork endpoint now awaits the controller.
- LinuxMediaController connects to the session bus lazily — failure no
  longer crashes lifespan startup; MPRIS calls return idle until the bus
  is reachable. Logged once at INFO with a hint about
  `loginctl enable-linger`.
- Startup preflight on Linux warns if DBUS_SESSION_BUS_ADDRESS or
  XDG_RUNTIME_DIR is unset and informs the user when Wayland disables
  the foreground probe.
- /api/media/visualizer/status now reports a per-OS unavailable_reason.
- tray._confirm guarded against ctypes.windll on non-Windows.
- config.example.yaml: per-OS commented script examples; on_turn_off
  default is now a no-op echo (used to silently fail off Windows).
- README: replace stale `pip install -r requirements.txt` instructions
  with the new extras; add systemd lingering doc + troubleshooting
  section; add macOS LaunchAgent section.
- CI: new linux-smoke job (installs `.[linux]`, boots the server under
  dbus-run-session, asserts /api/health). Release workflow gains
  apt-deps step for the Linux build and a best-effort macOS build job.

media_server/service/install_linux.sh

@@ -57,25 +57,38 @@ install_service() {
     # Create installation directory
     mkdir -p "$INSTALL_DIR"
 
-    # Copy source files
-    cp -r "$(dirname "$0")/../"* "$INSTALL_DIR/"
+    # Resolve the source-tree root (two levels up from this script:
+    # media_server/service/install_linux.sh → repo root).
+    SOURCE_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+    # Copy the source tree (pyproject.toml + media_server/ package)
+    cp -r "$SOURCE_ROOT/." "$INSTALL_DIR/"
 
     # Create virtual environment
     echo_info "Creating Python virtual environment..."
     python3 -m venv "$INSTALL_DIR/venv"
 
-    # Install Python dependencies
+    # Install Python dependencies from pyproject.toml (with linux extra).
+    # cd into the install dir so pip resolves `.[linux]` against the local
+    # pyproject — passing a path-with-extras (`$INSTALL_DIR[linux]`) trips
+    # the requirement-spec parser on some pip versions.
     echo_info "Installing Python dependencies..."
     "$INSTALL_DIR/venv/bin/pip" install --upgrade pip
-    "$INSTALL_DIR/venv/bin/pip" install -r "$INSTALL_DIR/requirements.txt"
+    (cd "$INSTALL_DIR" && "$INSTALL_DIR/venv/bin/pip" install ".[linux]")
 
-    # Install systemd service file
+    # Install systemd service file (templated unit)
     echo_info "Installing systemd service..."
-    cp "$INSTALL_DIR/service/media-server.service" "$SERVICE_FILE"
+    cp "$INSTALL_DIR/media_server/service/media-server.service" "$SERVICE_FILE"
 
     # Reload systemd
     systemctl daemon-reload
 
+    # Pre-create writable state dirs so the unit's ReadWritePaths grant
+    # actually has something to grant.
+    sudo -u "$SUDO_USER" mkdir -p \
+        "/home/$SUDO_USER/.config/media-server" \
+        "/home/$SUDO_USER/.cache/media-server"
+
     # Generate config if not exists
     if [[ ! -f "/home/$SUDO_USER/.config/media-server/config.yaml" ]]; then
         echo_info "Generating configuration file..."

media_server/service/media-server.service

@@ -3,34 +3,38 @@ Description=Media Server - REST API for controlling system media playback
 After=network.target sound.target
 Wants=sound.target
 
+# Templated unit. Enable as:
+#   sudo systemctl enable --now media-server@$USER
+# %i is the user name supplied after the '@'; %U is the matching numeric UID.
+
 [Service]
 Type=simple
 User=%i
 Group=%i
 
-# Environment variables (optional - can also use config file)
-# Environment=MEDIA_SERVER_HOST=0.0.0.0
-# Environment=MEDIA_SERVER_PORT=8765
-# Environment=MEDIA_SERVER_API_TOKEN=your-secret-token
-
-# Working directory
+# Working directory (override via drop-in if you install elsewhere)
 WorkingDirectory=/opt/media-server
 
-# Start command - adjust path to your Python environment
-ExecStart=/opt/media-server/venv/bin/python -m media_server.main
+# Start command — adjust to match where you installed the venv. --no-tray
+# avoids pulling pystray into a headless service environment.
+ExecStart=/opt/media-server/venv/bin/python -m media_server.main --no-tray
 
-# Restart policy
-Restart=always
+Restart=on-failure
 RestartSec=10
 
-# Security hardening
+# Required for MPRIS (dbus.SessionBus) and PulseAudio/PipeWire loopback.
+Environment=PYTHONUNBUFFERED=1
+Environment=XDG_RUNTIME_DIR=/run/user/%U
+Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/%U/bus
+
+# Light sandboxing. ProtectHome=read-only by itself blocks the app's own
+# audit.log / thumbnail cache writes — ReadWritePaths re-opens just the
+# two state dirs the server owns.
 NoNewPrivileges=true
+PrivateTmp=true
 ProtectSystem=strict
 ProtectHome=read-only
-PrivateTmp=true
-
-# Required for D-Bus access (MPRIS)
-Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/%U/bus
+ReadWritePaths=/home/%i/.config/media-server /home/%i/.cache/media-server
 
 [Install]
 WantedBy=multi-user.target