chore: release v0.4.0

- Replace generic Spotify-green circle with a refined "Beacon" design:
  squircle + deep-teal diagonal gradient (#0B3D3B → #1A6B5E) + warm
  parchment play triangle (#F5F1E8) with drop shadow, top sheen, and
  ghosted echo-chevrons hinting at broadcast/stream
- Grow icon.ico from a single 16×16 frame (208 B) to a 10-frame
  multi-resolution ICO (16/20/24/32/40/48/64/96/128/256, ~37 KB) so
  Windows no longer upscales 16×16 into mush for the installer chrome,
  Start Menu, desktop shortcuts, Alt+Tab, and File Explorer tiles
- Add scripts/generate-icon.py: SVG is the source of truth; resvg-py
  rasterizes every ICO size; Pillow packs the multi-resolution ICO
- Update tray.py to pick a 64×64 frame from the new ICO and update its
  procedural fallback to the same Beacon palette so a missing ICO no
  longer regresses the tray to the old Spotify-green circle
- Add resvg-py to [dev] deps (build-time only)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.gitattributes

@@ -0,0 +1,16 @@
+# Normalise text files to LF in the repo so Windows checkouts stop
+# nagging "LF will be replaced by CRLF" on every git status.
+* text=auto eol=lf
+
+# Binary assets — never touch.
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.ico  binary
+*.svg  text
+*.woff  binary
+*.woff2 binary
+*.exe  binary
+*.dll  binary
+*.zip  binary

.gitea/workflows/build.yml

@@ -0,0 +1,72 @@
+name: Build Artifacts
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version label (e.g. dev, 0.3.0-test)'
+        required: false
+        default: 'dev'
+
+jobs:
+  build-windows:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build frontend
+        run: npm ci && npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends nsis zip
+
+      - name: Build Windows distribution
+        run: |
+          chmod +x build-dist-windows.sh
+          ./build-dist-windows.sh "v${{ inputs.version }}"
+
+      - name: Build NSIS installer
+        run: makensis -DVERSION="${{ inputs.version }}" installer.nsi
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: MediaServer-${{ inputs.version }}-win-x64
+          path: |
+            build/MediaServer-*.zip
+            build/MediaServer-*-setup.exe
+          retention-days: 90
+
+  build-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build frontend
+        run: npm ci && npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Build Linux distribution
+        run: |
+          chmod +x build-dist-linux.sh
+          ./build-dist-linux.sh "v${{ inputs.version }}"
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: MediaServer-${{ inputs.version }}-linux-x64
+          path: build/MediaServer-*-linux-x64.tar.gz
+          retention-days: 90

.gitea/workflows/release.yml

@@ -0,0 +1,296 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  # --- Create Gitea release ---
+  create-release:
+    runs-on: ubuntu-latest
+    outputs:
+      release_id: ${{ steps.create.outputs.release_id }}
+      version: ${{ steps.create.outputs.version }}
+    steps:
+      - name: Fetch RELEASE_NOTES.md only
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: RELEASE_NOTES.md
+          sparse-checkout-cone-mode: false
+
+      - name: Create Gitea release
+        id: create
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          TAG="${{ gitea.ref_name }}"
+          VERSION="${TAG#v}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          IS_PRE="false"
+          if echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
+            IS_PRE="true"
+          fi
+
+          if [ -f RELEASE_NOTES.md ]; then
+            export RELEASE_NOTES=$(cat RELEASE_NOTES.md)
+            echo "Found RELEASE_NOTES.md"
+          else
+            export RELEASE_NOTES=""
+            echo "No RELEASE_NOTES.md found"
+          fi
+
+          BODY_JSON=$(python3 -c "
+          import json, os, textwrap
+
+          tag = '$TAG'
+          release_notes = os.environ.get('RELEASE_NOTES', '')
+
+          sections = []
+
+          if release_notes.strip():
+              sections.append(release_notes.strip())
+
+          sections.append(textwrap.dedent(f'''
+          ## Downloads
+
+          | Platform | File |
+          |----------|------|
+          | Windows (installer) | \`MediaServer-{tag}-setup.exe\` |
+          | Windows (portable) | \`MediaServer-{tag}-win-x64.zip\` |
+          | Linux | \`MediaServer-{tag}-linux-x64.tar.gz\` |
+          | macOS (Apple Silicon) | \`MediaServer-{tag}-macos-arm64.tar.gz\` |
+          | macOS (Intel) | \`MediaServer-{tag}-macos-x86_64.tar.gz\` |
+          ''').strip())
+
+          print(json.dumps('\n\n'.join(sections)))
+          ")
+
+          RELEASE=$(curl -s -X POST "$BASE_URL/releases" \
+            -H "Authorization: token $DEPLOY_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "{
+              \"tag_name\": \"$TAG\",
+              \"name\": \"Media Server $TAG\",
+              \"body\": $BODY_JSON,
+              \"draft\": false,
+              \"prerelease\": $IS_PRE
+            }")
+
+          # Extract release ID; if creation failed (already exists), fetch existing
+          RELEASE_ID=$(echo "$RELEASE" | python3 -c "
+          import sys, json
+          data = json.load(sys.stdin)
+          if 'id' in data:
+              print(data['id'])
+          else:
+              print('FAILED', file=sys.stderr)
+              print(json.dumps(data, indent=2), file=sys.stderr)
+              sys.exit(1)
+          " 2>&1) || {
+            echo "::warning::Release already exists for tag $TAG — reusing existing release"
+            RELEASE=$(curl -s "$BASE_URL/releases/tags/$TAG" \
+              -H "Authorization: token $DEPLOY_TOKEN")
+            RELEASE_ID=$(echo "$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+          }
+          echo "release_id=$RELEASE_ID" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+  # --- Build Windows installer + portable ZIP ---
+  build-windows:
+    needs: create-release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build frontend
+        run: npm ci && npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends nsis zip
+
+      - name: Build Windows distribution
+        run: |
+          chmod +x build-dist-windows.sh
+          ./build-dist-windows.sh "${{ gitea.ref_name }}"
+
+      - name: Build NSIS installer
+        run: |
+          VERSION="${{ needs.create-release.outputs.version }}"
+          makensis -DVERSION="${VERSION}" installer.nsi
+
+      - name: Upload assets to release
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          RELEASE_ID="${{ needs.create-release.outputs.release_id }}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          upload_asset() {
+            local file="$1"
+            local name
+            name=$(basename "$file")
+
+            # Delete existing asset with the same name (idempotent re-runs)
+            EXISTING=$(curl -s "$BASE_URL/releases/$RELEASE_ID/assets" \
+              -H "Authorization: token $DEPLOY_TOKEN")
+            ASSET_ID=$(echo "$EXISTING" | python3 -c "
+          import sys, json
+          assets = json.load(sys.stdin)
+          for a in assets:
+              if a['name'] == '$name':
+                  print(a['id'])
+                  break
+          " 2>/dev/null || true)
+
+            if [ -n "$ASSET_ID" ]; then
+              echo "Replacing existing asset: $name (id=$ASSET_ID)"
+              curl -s -X DELETE "$BASE_URL/releases/$RELEASE_ID/assets/$ASSET_ID" \
+                -H "Authorization: token $DEPLOY_TOKEN"
+            fi
+
+            echo "Uploading $name..."
+            curl -s -X POST \
+              "$BASE_URL/releases/$RELEASE_ID/assets?name=$name" \
+              -H "Authorization: token $DEPLOY_TOKEN" \
+              -H "Content-Type: application/octet-stream" \
+              --data-binary "@$file"
+          }
+
+          for FILE in build/MediaServer-*.zip build/MediaServer-*-setup.exe; do
+            [ -f "$FILE" ] || continue
+            upload_asset "$FILE"
+          done
+
+  # --- Build Linux tarball ---
+  build-linux:
+    needs: create-release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build frontend
+        run: npm ci && npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install native deps for dbus-python + PyGObject
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libdbus-1-dev libglib2.0-dev pkg-config \
+            libcairo2-dev libgirepository1.0-dev
+
+      - name: Build Linux distribution
+        run: |
+          chmod +x build-dist-linux.sh
+          ./build-dist-linux.sh "${{ gitea.ref_name }}"
+
+      - name: Upload assets to release
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          RELEASE_ID="${{ needs.create-release.outputs.release_id }}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          FILE=$(ls build/MediaServer-*-linux-x64.tar.gz | head -1)
+          NAME=$(basename "$FILE")
+
+          # Delete existing asset with the same name (idempotent re-runs)
+          EXISTING=$(curl -s "$BASE_URL/releases/$RELEASE_ID/assets" \
+            -H "Authorization: token $DEPLOY_TOKEN")
+          ASSET_ID=$(echo "$EXISTING" | python3 -c "
+          import sys, json
+          assets = json.load(sys.stdin)
+          for a in assets:
+              if a['name'] == '$NAME':
+                  print(a['id'])
+                  break
+          " 2>/dev/null || true)
+
+          if [ -n "$ASSET_ID" ]; then
+            echo "Replacing existing asset: $NAME (id=$ASSET_ID)"
+            curl -s -X DELETE "$BASE_URL/releases/$RELEASE_ID/assets/$ASSET_ID" \
+              -H "Authorization: token $DEPLOY_TOKEN"
+          fi
+
+          echo "Uploading $NAME..."
+          curl -s -X POST \
+            "$BASE_URL/releases/$RELEASE_ID/assets?name=$NAME" \
+            -H "Authorization: token $DEPLOY_TOKEN" \
+            -H "Content-Type: application/octet-stream" \
+            --data-binary "@$FILE"
+
+  # --- Build macOS tarball (best-effort; requires a macos runner) ---
+  # PyObjC wheels are macOS-only, so this job must run on a real Mac.
+  # If your Gitea instance has no macos runners, the job is skipped at
+  # scheduling time and the rest of the release still ships.
+  build-macos:
+    needs: create-release
+    runs-on: macos-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build frontend
+        run: npm ci && npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Build macOS distribution
+        run: |
+          chmod +x build-dist-macos.sh
+          ./build-dist-macos.sh "${{ gitea.ref_name }}"
+
+      - name: Upload assets to release
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          RELEASE_ID="${{ needs.create-release.outputs.release_id }}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          FILE=$(ls build/MediaServer-*-macos-*.tar.gz | head -1)
+          NAME=$(basename "$FILE")
+
+          EXISTING=$(curl -s "$BASE_URL/releases/$RELEASE_ID/assets" \
+            -H "Authorization: token $DEPLOY_TOKEN")
+          ASSET_ID=$(echo "$EXISTING" | python3 -c "
+          import sys, json
+          assets = json.load(sys.stdin)
+          for a in assets:
+              if a['name'] == '$NAME':
+                  print(a['id'])
+                  break
+          " 2>/dev/null || true)
+
+          if [ -n "$ASSET_ID" ]; then
+            curl -s -X DELETE "$BASE_URL/releases/$RELEASE_ID/assets/$ASSET_ID" \
+              -H "Authorization: token $DEPLOY_TOKEN"
+          fi
+
+          curl -s -X POST \
+            "$BASE_URL/releases/$RELEASE_ID/assets?name=$NAME" \
+            -H "Authorization: token $DEPLOY_TOKEN" \
+            -H "Content-Type: application/octet-stream" \
+            --data-binary "@$FILE"

.gitea/workflows/test.yml

@@ -0,0 +1,97 @@
+name: Lint & Test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    if: "!startsWith(github.event.head_commit.message, 'chore: release')"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build frontend
+        run: npm ci && npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check media_server/
+
+      - name: Test
+        run: pytest --tb=short -q || test $? -eq 5
+
+  # Linux smoke test: install the linux extra in the same way build-dist-linux.sh
+  # does, then boot the server and hit /api/health. Catches dependency-resolution
+  # and import-time regressions for the Linux distribution path.
+  linux-smoke:
+    if: "!startsWith(github.event.head_commit.message, 'chore: release')"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build frontend
+        run: npm ci && npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Linux system deps for dbus-python + PyGObject
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libdbus-1-dev libglib2.0-dev pkg-config \
+            libcairo2-dev libgirepository1.0-dev
+
+      - name: Install with linux extra
+        run: |
+          pip install --upgrade pip
+          pip install ".[linux]"
+
+      - name: Smoke — server boots and /api/health responds
+        run: |
+          # Headless Linux runners have no PulseAudio and no display
+          # server, so we disable the visualizer + update checker, and we
+          # use `dbus-run-session` to give LinuxMediaController a real
+          # session bus to talk to (otherwise dbus.SessionBus() would
+          # raise during startup). This isn't a full MPRIS integration
+          # test — it only proves the dispatcher selects the Linux
+          # controller, all imports resolve, and /api/health returns 200.
+          sudo apt-get install -y --no-install-recommends dbus-x11
+          export MEDIA_SERVER_VISUALIZER_ENABLED=false
+          export MEDIA_SERVER_UPDATE_CHECK_ENABLED=false
+          dbus-run-session -- bash -c '
+            python -m media_server.main --no-tray --port 18765 &
+            SERVER_PID=$!
+            for i in $(seq 1 30); do
+              if curl -sf "http://127.0.0.1:18765/api/health" >/dev/null; then
+                echo "Health check passed"
+                kill $SERVER_PID
+                wait $SERVER_PID 2>/dev/null || true
+                exit 0
+              fi
+              sleep 0.5
+            done
+            echo "Server did not respond within 15s"
+            kill $SERVER_PID 2>/dev/null || true
+            exit 1
+          '

.gitignore

@@ -46,3 +46,12 @@ logs/
 # OS
 .DS_Store
 Thumbs.db
+
+# Thumbnail cache
+.cache/
+
+# Node.js / esbuild
+node_modules/
+media_server/static/dist/
+# Added by code-review-graph
+.code-review-graph/

.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "code-review-graph": {
+      "command": "uvx",
+      "args": [
+        "code-review-graph",
+        "serve"
+      ],
+      "type": "stdio"
+    }
+  }
+}

CLAUDE.md

@@ -26,6 +26,67 @@ To remove the scheduled task:
 Unregister-ScheduledTask -TaskName "MediaServer" -Confirm:$false
 ```
 
+## Development Workflow
+
+### Server Restart After Code Changes
+
+**CRITICAL:** When making changes to backend code (Python files, API routes, service logic), the media server MUST be restarted for changes to take effect.
+
+**When to restart:**
+
+- Changes to any Python files (`*.py`) in the media_server directory
+- Changes to API endpoints, routes, or request/response models
+- Changes to service logic, callbacks, or script execution
+- Changes to configuration handling or startup logic
+
+**When restart is NOT needed:**
+
+- Static file changes (`*.html`, `*.css`, `*.json`) - browser refresh is enough
+- README or documentation updates
+- Changes to install/service scripts (only affects new installations)
+
+### Frontend Rebuild After JS Changes
+
+**CRITICAL:** The frontend is bundled via esbuild into `static/dist/app.bundle.js`. After modifying ANY JavaScript file in `media_server/static/js/`, you **MUST** run:
+
+```bash
+npm run build
+```
+
+Raw JS file edits have **NO effect** until the bundle is rebuilt. After rebuilding, a browser hard-refresh (Ctrl+Shift+R) is sufficient — no server restart needed.
+
+**How to restart during development:**
+
+1. Find the running server process:
+
+   ```bash
+   # Windows
+   netstat -ano | findstr :8765
+
+   # Linux/macOS
+   lsof -i :8765
+   ```
+
+2. Stop the server:
+
+   ```bash
+   # Windows
+   taskkill //F //PID <process_id>
+
+   # Linux/macOS
+   kill <process_id>
+   ```
+
+3. Start the server again:
+
+   ```bash
+   python -m media_server.main
+   ```
+
+**Best Practice:** Always restart the server immediately after committing backend changes to verify they work correctly before pushing.
+
+**CRITICAL** Always check acccessibility of WebUI after server restart to ensure that server has started without issues
+
 ## Configuration
 
 Copy `config.example.yaml` to `config.yaml` and customize.
@@ -34,18 +95,143 @@ The API token is generated on first run and displayed in the console output.
 
 Default port: `8765`
 
+## Internationalization (i18n)
+
+The Web UI supports multiple languages with translations stored in separate JSON files.
+
+### Locale Files
+
+Translation files are located in:
+- `media_server/static/locales/en.json` - English (default)
+- `media_server/static/locales/ru.json` - Russian
+
+### Maintaining Translations
+
+**IMPORTANT:** When adding or modifying user-facing text in the Web UI:
+
+1. **Update all locale files** - Add or update the translation key in **both** `en.json` and `ru.json`
+2. **Use consistent keys** - Follow the existing key naming pattern (e.g., `section.element`, `scripts.button.save`)
+3. **Test both locales** - Verify translations appear correctly by switching between EN/RU
+
+### Adding New Text
+
+When adding new UI elements:
+
+1. Add the English text to `static/locales/en.json`
+2. Add the Russian translation to `static/locales/ru.json`
+3. In HTML: use `data-i18n="key.name"` for text content
+4. In HTML: use `data-i18n-placeholder="key.name"` for input placeholders
+5. In HTML: use `data-i18n-title="key.name"` for title attributes
+6. In JavaScript: use `t('key.name')` or `t('key.name', {param: value})` for dynamic text
+
+### Adding New Locales
+
+To add support for a new language:
+
+1. Create `media_server/static/locales/{lang_code}.json` (copy from `en.json`)
+2. Translate all strings to the new language
+3. Add the language code to `supportedLocales` array in `index.html`
+
 ## Versioning
 
-Version is tracked in two files that must be kept in sync:
+**`pyproject.toml`** is the single source of truth for the version string.
 
-- `pyproject.toml` - `[project].version`
-- `media_server/__init__.py` - `__version__`
+At runtime, `media_server/__init__.py` reads the version via `importlib.metadata.version()` — no manual syncing needed.
 
-When releasing a new version, update both files with the same version string.
+Version flow:
+1. `git tag v0.3.0` → CI reads the tag
+2. Build scripts stamp `pyproject.toml` with the clean version via `sed`
+3. `pip install` bakes the version into package metadata
+4. `importlib.metadata.version("media-server")` reads it at runtime
+
+When bumping the version for a new release, only `pyproject.toml` needs to be updated.
 
 **Important:** After making any changes, always ask the user if the version needs to be incremented.
 
+## CI/CD
+
+Gitea Actions workflow at `.gitea/workflows/test.yml` runs on every push/PR to `master`:
+
+1. **Lint** — `ruff check media_server/` (rules: E, F, I, W)
+2. **Test** — `pytest --tb=short -q`
+
+Release workflow at `.gitea/workflows/release.yml` triggers on `v*` tags:
+
+1. **Create release** — Gitea release via REST API (detects pre-release from tag)
+2. **Build Windows** — cross-builds on Linux using embedded Python + NSIS installer
+3. **Upload assets** — portable ZIP + installer `.exe` attached to the release
+
+### Releasing
+
+```bash
+# Stable release
+git tag v1.0.0 && git push origin v1.0.0
+
+# Pre-release
+git tag v1.1.0-alpha.1 && git push origin v1.1.0-alpha.1
+```
+
+### Installer
+
+The NSIS installer (`installer.nsi`) installs to `%LOCALAPPDATA%\Media Server` (no admin required) with optional:
+- **Desktop shortcut**
+- **Start with Windows** (Startup folder shortcut, runs hidden via VBS)
+
+Uninstall preserves `config.yaml` (user data).
+
+Reference: [gitea-python-ci-cd.md](https://git.dolgolyov-family.by/alexei.dolgolyov/claude-code-facts/src/branch/main/gitea-python-ci-cd.md)
+
+**IMPORTANT:** When modifying CI/CD workflows, `installer.nsi`, or build scripts (`build-dist-*.sh`), always fetch and consult the guide above first to ensure changes stay in sync with established patterns.
+
+### Before Pushing
+
+Ensure CI will pass locally:
+
+```bash
+ruff check media_server/
+pytest --tb=short -q
+```
+
 ## Git Rules
 
 - **ALWAYS ask for user approval before committing and pushing changes.**
 - When pushing, always push to all remotes: `git push origin master && git push github master`
+
+<!-- code-review-graph MCP tools -->
+## MCP Tools: code-review-graph
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
+the codebase.** The graph is faster, cheaper (fewer tokens), and gives
+you structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### When to use graph tools FIRST
+
+- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
+- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
+- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
+- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
+- **Architecture questions**: `get_architecture_overview` + `list_communities`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+
+### Key Tools
+
+| Tool | Use when |
+|------|----------|
+| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
+| `get_review_context` | Need source snippets for review — token-efficient |
+| `get_impact_radius` | Understanding blast radius of a change |
+| `get_affected_flows` | Finding which execution paths are impacted |
+| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
+| `semantic_search_nodes` | Finding functions/classes by name or keyword |
+| `get_architecture_overview` | Understanding high-level codebase structure |
+| `refactor_tool` | Planning renames, finding dead code |
+
+### Workflow
+
+1. The graph auto-updates on file changes (via hooks).
+2. Use `detect_changes` for code review.
+3. Use `get_affected_flows` to understand impact.
+4. Use `query_graph` pattern="tests_for" to check coverage.

README.md

@@ -5,40 +5,64 @@ A REST API server for controlling system media playback on Windows, Linux, macOS
 ## Features
 
 - **Built-in Web UI** for real-time media control and monitoring
+- **Installable PWA** - Add to home screen on mobile for a native app experience
+- **Audio Visualizer** - Real-time spectrum analyzer with beat-reactive album art effects
+- **Dynamic WebGL Background** - Audio-reactive animated background with album art color extraction
+- **Media Browser** - Browse and play media files from configured folders
+- **Display Control** - Monitor brightness and power management
+- **Quick Actions & Scripts** - Execute custom scripts with one click
+- **Callbacks** - Trigger commands on media events (play, pause, volume, etc.)
+- **Header Links** - Configurable quick-access links in the UI header
 - Control any media player via system-wide media transport controls
 - Play/Pause/Stop/Next/Previous track
 - Volume control and mute
 - Seek within tracks
 - Get current track info (title, artist, album, artwork)
 - WebSocket support for real-time updates
-- Token-based authentication
-- Cross-platform support
+- Token-based authentication with multi-token support
+- Dark/light theme with customizable accent colors
+- Multi-language support (English, Russian)
+- Cross-platform support (Windows, Linux, macOS, Android)
 
 ## Web UI
 
 The media server includes a built-in web interface for controlling and monitoring media playback.
 
-### Features
+![Web UI](docs/web-ui.PNG)
+
+### Web UI Highlights
 
 - **Real-time status updates** via WebSocket connection
-- **Album artwork display** with automatic updates
+- **Album artwork display** with glow effect and automatic updates
+- **Vinyl record mode** - Album art displayed as a spinning vinyl disc with grooves and center spindle
 - **Playback controls** - Play, pause, next, previous
 - **Volume control** with mute toggle
 - **Seekable progress bar** - Click to jump to any position
+- **Mini player** - Sticky compact player that appears when scrolling away from the main player
 - **Connection status indicator** - Know when you're connected
 - **Token authentication** - Saved in browser localStorage
-- **Responsive design** - Works on desktop and mobile
-- **Dark theme** - Easy on the eyes
+- **Audio spectrum visualizer** - Real-time frequency bars with beat-reactive album art scaling and glow (on-demand WASAPI loopback capture)
+- **Dynamic WebGL background** - Fragment shader-based animated background that reacts to audio beats and extracts colors from album art (toggle on/off in header)
+- **Display control** - Monitor brightness adjustment and power on/off
+- **Header quick links** - Configurable external URLs with icons shown in the header bar
+- **Installable PWA** - Add to home screen on mobile/desktop for standalone app experience with safe area support for notched phones
+- **Responsive design** - Works on desktop, tablet, and mobile
+- **Dark and light themes** - Toggle between dark and light modes with dynamic status bar theming
+- **Accent color picker** - Choose from 9 preset accent colors or pick a custom color
+- **Tab-based navigation** - Player, Display, Browser, Quick Actions, and Settings tabs
+- **Multi-language support** - English and Russian locales with automatic detection
 
 ### Accessing the Web UI
 
 1. Start the media server:
+
    ```bash
    python -m media_server.main
    ```
 
 2. Open your browser and navigate to:
-   ```
+
+   ```text
    http://localhost:8765/
    ```
 
@@ -46,6 +70,32 @@ The media server includes a built-in web interface for controlling and monitorin
 
 4. Start playing media in any supported player and watch the UI update in real-time!
 
+### Installing as a PWA
+
+The Web UI can be installed as a Progressive Web App for a native app-like experience:
+
+1. Open the Web UI in Chrome/Edge on your phone or desktop
+2. Tap the **Install** icon in the address bar (or "Add to Home Screen" on mobile)
+3. The app launches in standalone mode — no browser chrome, with proper safe area handling for notched phones
+
+### Audio Visualizer
+
+The Web UI includes a real-time audio spectrum visualizer that captures system audio output:
+
+- **On-demand capture** - Audio capture starts only when a client enables the visualizer, and stops when the last client disconnects
+- **Beat-reactive effects** - Album art pulses and glows in response to bass frequencies
+- **Dynamic WebGL background** - Animated shader background that reacts to bass frequencies and adapts colors from current album art
+- **Configurable device** - Select which audio output device to capture in Settings
+
+Requires `soundcard` and `numpy` Python packages. Enable in `config.yaml`:
+
+```yaml
+visualizer_enabled: true
+visualizer_fps: 30          # Frame rate (10-60)
+visualizer_bins: 32          # Frequency bins (8-128)
+# visualizer_device: "Speakers"  # optional: specific device name
+```
+
 ### Remote Access
 
 To access the Web UI from other devices on your network:
@@ -56,6 +106,178 @@ To access the Web UI from other devices on your network:
 
 **Security Note:** For remote access over the internet, use a reverse proxy with HTTPS (nginx, Caddy) to encrypt traffic.
 
+### Localization
+
+The Web UI supports multiple languages with automatic browser locale detection:
+
+**Available Languages:**
+
+- **English (en)** - Default
+- **Русский (ru)** - Russian
+
+The interface automatically detects your browser language on first visit. You can manually switch languages using the dropdown in the top-right corner of the Web UI.
+
+**Contributing New Locales:**
+
+We welcome translations for additional languages! To contribute a new locale:
+
+1. Copy `media_server/static/locales/en.json` to a new file named with your language code (e.g., `de.json` for German)
+2. Translate all strings to your language, keeping the same JSON structure
+3. Add your language to the `supportedLocales` object in `media_server/static/index.html`:
+
+   ```javascript
+   const supportedLocales = {
+       'en': 'English',
+       'ru': 'Русский',
+       'de': 'Deutsch'  // Add your language here
+   };
+   ```
+
+4. Test the translation by switching to your language in the Web UI
+5. Submit a pull request with your changes
+
+See [CLAUDE.md](CLAUDE.md#internationalization-i18n) for detailed translation guidelines.
+
+## Media Browser
+
+The Media Browser feature allows you to browse and play media files from configured folders directly through the Web UI.
+
+![Media Browser](docs/media-browser.PNG)
+
+### Browser Highlights
+
+- **Folder Configuration** - Mount multiple media folders (music/video directories)
+- **Recursive Navigation** - Browse through folder hierarchies with breadcrumb navigation
+- **Multiple View Modes** - Grid, compact grid, and list views with toggle buttons
+- **Thumbnail Display** - Automatically generated thumbnails from album art (lazy-loaded)
+- **Metadata Extraction** - View title, artist, album, duration, bitrate, file size, and more
+- **Remote Playback** - Play files on the PC running the media server (not in the browser)
+- **Play All** - Play all media files in the current folder (generates M3U playlist)
+- **File Download** - Download individual media files directly from the browser
+- **Search & Filter** - Real-time search across files in the current folder
+- **Pagination** - Navigate large folders with configurable page sizes (25, 50, 100, 200, 500)
+- **Last Path Memory** - Automatically returns to your last browsed location
+- **Folder Management** - Create, edit, and delete media folders from the UI
+
+### Browser Setup
+
+Add media folders in your `config.yaml`:
+
+```yaml
+# Media folders for browser
+media_folders:
+  music:
+    path: "C:\\Users\\YourUsername\\Music"
+    label: "My Music"
+    enabled: true
+  videos:
+    path: "C:\\Users\\YourUsername\\Videos"
+    label: "My Videos"
+    enabled: true
+
+# Thumbnail size: "small" (150x150), "medium" (300x300), or "both"
+thumbnail_size: "medium"
+```
+
+### How Playback Works
+
+When you play a file from the Media Browser:
+
+1. The file is opened using the **default system media player** on the PC running the media server
+2. This is designed for **remote control scenarios** where you browse media from one device (e.g., Home Assistant dashboard, phone) but want audio to play on the PC
+3. The media player must support the **Windows Media Session API** for playback tracking
+
+### Media Player Compatibility
+
+**Important Limitation:** Not all media players expose their playback information to the Windows Media Session API. This means some players will open and play the file, but the Media Server UI won't show playback status, track information, or allow remote control.
+
+**Compatible Players** (work with playback tracking):
+
+- **VLC Media Player** - Full support
+- **Groove Music** (Windows 10/11 built-in) - Full support
+- **Spotify** - Full support (if already running)
+- **Chrome/Edge/Firefox** - Full support for web players
+- **foobar2000** - Full support (with proper configuration/plugins)
+
+**Limited/No Support:**
+
+- **Windows Media Player Classic** - Opens files but doesn't expose session info
+- **Windows Media Player** (classic version) - Limited session support
+
+**Recommendation:** Set **VLC Media Player** or **Groove Music** as your default audio player for the best experience with the Media Browser.
+
+#### Changing Your Default Media Player (on Windows)
+
+1. Open Windows Settings > Apps > Default apps
+2. Search for "Music player" or "Video player"
+3. Select VLC Media Player or Groove Music
+4. Files opened from Media Browser will now use the selected player
+
+## Display Control
+
+The Display Control feature allows you to manage monitor brightness and power state from the Web UI or via API.
+
+- **Brightness adjustment** - Set brightness (0-100%) for each monitor
+- **Power management** - Turn monitors on or off
+- **Multi-monitor support** - See all connected monitors with model, manufacturer, and resolution info
+- **Technology**: DDC-CI on Windows, XRandR/ACPI on Linux, IOKit on macOS
+
+### Display API
+
+| Endpoint                                 | Method   | Body                      | Description                                      |
+|------------------------------------------|----------|---------------------------|--------------------------------------------------|
+| `/api/display/monitors`                  | GET      | -                         | List monitors (use `?refresh=true` to refresh)   |
+| `/api/display/brightness/{monitor_id}`   | POST     | `{"brightness": 0-100}`   | Set monitor brightness                           |
+| `/api/display/power/{monitor_id}`        | POST     | `{"on": true\             | false}`                                          |
+
+**Monitor response:**
+
+```json
+{
+  "id": 0,
+  "name": "Monitor Name",
+  "brightness": 100,
+  "power_supported": true,
+  "power_on": true,
+  "model": "Model Number",
+  "manufacturer": "Manufacturer",
+  "resolution": "1920x1080",
+  "is_primary": true
+}
+```
+
+## Header Links
+
+Configure quick-access links that appear in the Web UI header bar with custom icons.
+
+### Links Setup
+
+Add links in your `config.yaml`:
+
+```yaml
+links:
+  spotify:
+    url: "https://open.spotify.com"
+    icon: "mdi:spotify"
+    label: "Spotify"
+  settings:
+    url: "https://your-server.com/settings"
+    icon: "mdi:cog"
+    label: "Settings"
+    description: "System settings"
+```
+
+### Links API
+
+| Endpoint                          | Method   | Body                                | Description      |
+|-----------------------------------|----------|-------------------------------------|------------------|
+| `/api/links/list`                 | GET      | -                                   | List all links   |
+| `/api/links/create/{link_name}`   | POST     | `{url, icon, label, description}`   | Create link      |
+| `/api/links/update/{link_name}`   | PUT      | `{url, icon, label, description}`   | Update link      |
+| `/api/links/delete/{link_name}`   | DELETE   | -                                   | Delete link      |
+
+All connected WebSocket clients receive a `links_changed` notification when links are modified.
+
 ## Requirements
 
 - Python 3.10+
@@ -63,37 +285,44 @@ To access the Web UI from other devices on your network:
 
 ## Installation
 
-### Windows
+Dependencies are declared in `pyproject.toml`. Pick the extra that matches
+your OS — the Python deps differ enough between Windows / Linux / macOS
+that there's no single `pip install` line.
+
+### Installing on Windows
 
 ```bash
-pip install -r requirements.txt
+pip install ".[windows]"
 ```
 
-Required packages: `winsdk`, `pywin32`, `pycaw`, `comtypes`
+Pulls in `winsdk`, `pywin32`, `pycaw`, `comtypes`, `pystray`, etc.
 
-### Linux
+### Installing on Linux
 
 ```bash
-# Install system dependencies
-sudo apt-get install python3-dbus python3-gi libdbus-1-dev libglib2.0-dev
+# System packages required to build dbus-python + PyGObject from sdist.
+sudo apt-get install -y python3-pip python3-venv \
+    libdbus-1-dev libglib2.0-dev pkg-config
 
-pip install -r requirements.txt
+pip install ".[linux]"
 ```
 
-### macOS
+### Installing on macOS
 
 ```bash
-pip install -r requirements.txt
+pip install ".[macos]"
 ```
 
-No additional dependencies - uses built-in `osascript`.
+Pulls in `pyobjc-framework-Cocoa` + `pyobjc-framework-Quartz` for the
+foreground-window probe; AppleScript-based media control uses the
+built-in `osascript`.
 
-### Android (Termux)
+### Installing on Android (Termux)
 
 ```bash
 # In Termux
 pkg install python termux-api
-pip install -r requirements.txt
+pip install "."
 ```
 
 Requires Termux and Termux:API apps from F-Droid.
@@ -101,26 +330,31 @@ Requires Termux and Termux:API apps from F-Droid.
 ## Quick Start
 
 1. Generate configuration with API token:
+
    ```bash
    python -m media_server.main --generate-config
    ```
 
 2. View your API token:
+
    ```bash
    python -m media_server.main --show-token
    ```
 
 3. Start the server:
+
    ```bash
    python -m media_server.main
    ```
 
 4. **Open the Web UI** (recommended):
+
    - Navigate to `http://localhost:8765/` in your browser
    - Enter your API token from step 2
    - Start playing media and control it from the web interface!
 
 5. Or test via API:
+
    ```bash
    # Health check (no auth required)
    curl http://localhost:8765/api/health
@@ -129,20 +363,102 @@ Requires Termux and Termux:API apps from F-Droid.
    curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8765/api/media/status
    ```
 
-## Configuration
+## Configuration Reference
 
 Configuration file locations:
+
 - Windows: `%APPDATA%\media-server\config.yaml`
 - Linux/macOS: `~/.config/media-server/config.yaml`
 
-### config.yaml
+### Full config.yaml Example
 
 ```yaml
 host: 0.0.0.0
 port: 8765
-api_token: your-secret-token-here
+
+# API Tokens - Multiple tokens with labels for client identification
+api_tokens:
+  home_assistant: "your-home-assistant-token-here"
+  mobile: "your-mobile-app-token-here"
+  web_ui: "your-web-ui-token-here"
+
 poll_interval: 1.0
 log_level: INFO
+
+# Audio device for system volume control (null = default device)
+audio_device: null
+
+# Audio visualizer (requires soundcard + numpy)
+visualizer_enabled: true
+visualizer_fps: 30
+visualizer_bins: 32
+visualizer_device: null   # null = auto-detect loopback
+
+# Media folders for browser
+media_folders:
+  music:
+    path: "C:\\Users\\YourUsername\\Music"
+    label: "My Music"
+    enabled: true
+
+# Thumbnail size: "small" (150x150), "medium" (300x300), or "both"
+thumbnail_size: "medium"
+
+# Custom scripts (execute via API/UI)
+scripts:
+  lock_screen:
+    command: "rundll32.exe user32.dll,LockWorkStation"
+    label: "Lock Screen"
+    description: "Lock the workstation"
+    icon: "mdi:lock"
+    timeout: 5
+    shell: true
+
+# Callbacks (execute after media actions)
+callbacks:
+  on_turn_off:
+    command: "rundll32.exe user32.dll,LockWorkStation"
+    timeout: 5
+    shell: true
+
+# Header quick links
+links:
+  spotify:
+    url: "https://open.spotify.com"
+    icon: "mdi:spotify"
+    label: "Spotify"
+```
+
+### Authentication
+
+The media server supports multiple API tokens with friendly labels. This allows you to:
+
+- Issue different tokens for different clients (Home Assistant, mobile apps, web UI, etc.)
+- Identify which client is making requests in the server logs
+- Revoke individual tokens without affecting other clients
+
+**Token labels** appear in all server logs, making it easy to track and debug client connections:
+
+```text
+2026-02-06 03:36:20,806 - media_server.services.websocket_manager - [home_assistant] - INFO - WebSocket client connected
+2026-02-06 03:28:24,258 - media_server.routes.scripts - [mobile] - INFO - Executing script: lock_screen
+```
+
+**Viewing your tokens:**
+
+```bash
+python -m media_server.main --show-token
+```
+
+Output:
+
+```text
+Config directory: C:\Users\...\AppData\Roaming\media-server
+
+API Tokens:
+  home_assistant       B04zhGDjnxH6LIwxL3VOT0F4qORwaipD7LoDyeAG4EU
+  mobile               xyz123...
+  web_ui               abc456...
 ```
 
 ### Environment Variables
@@ -152,21 +468,23 @@ All settings can be overridden with environment variables (prefix: `MEDIA_SERVER
 ```bash
 export MEDIA_SERVER_HOST=0.0.0.0
 export MEDIA_SERVER_PORT=8765
-export MEDIA_SERVER_API_TOKEN=your-token
 export MEDIA_SERVER_LOG_LEVEL=DEBUG
 ```
 
+**Note:** For multi-token configuration, use the config.yaml file. Environment variables only support single-token mode.
+
 ## API Reference
 
 ### Health Check
 
-```
+```text
 GET /api/health
 ```
 
 No authentication required. Returns server status and platform info.
 
 **Response:**
+
 ```json
 {
   "status": "healthy",
@@ -177,12 +495,13 @@ No authentication required. Returns server status and platform info.
 
 ### Get Media Status
 
-```
+```text
 GET /api/media/status
 Authorization: Bearer <token>
 ```
 
 **Response:**
+
 ```json
 {
   "state": "playing",
@@ -198,58 +517,66 @@ Authorization: Bearer <token>
 }
 ```
 
+### Album Artwork
+
+```text
+GET /api/media/artwork
+Authorization: Bearer <token>
+```
+
+Returns current album artwork as PNG/JPEG/WebP binary. Also accepts token as a query parameter.
+
 ### Media Controls
 
 All control endpoints require authentication and return `{"success": true}` on success.
 
-| Endpoint | Method | Body | Description |
-|----------|--------|------|-------------|
-| `/api/media/play` | POST | - | Resume playback |
-| `/api/media/pause` | POST | - | Pause playback |
-| `/api/media/stop` | POST | - | Stop playback |
-| `/api/media/next` | POST | - | Next track |
-| `/api/media/previous` | POST | - | Previous track |
-| `/api/media/volume` | POST | `{"volume": 75}` | Set volume (0-100) |
-| `/api/media/mute` | POST | - | Toggle mute |
-| `/api/media/seek` | POST | `{"position": 60.0}` | Seek to position (seconds) |
-| `/api/media/turn_on` | POST | - | Execute on_turn_on callback |
-| `/api/media/turn_off` | POST | - | Execute on_turn_off callback |
-| `/api/media/toggle` | POST | - | Execute on_toggle callback |
+| Endpoint                | Method   | Body                   | Description                    |
+|-------------------------|----------|------------------------|--------------------------------|
+| `/api/media/play`       | POST     | -                      | Resume playback                |
+| `/api/media/pause`      | POST     | -                      | Pause playback                 |
+| `/api/media/stop`       | POST     | -                      | Stop playback                  |
+| `/api/media/next`       | POST     | -                      | Next track                     |
+| `/api/media/previous`   | POST     | -                      | Previous track                 |
+| `/api/media/volume`     | POST     | `{"volume": 75}`       | Set volume (0-100)             |
+| `/api/media/mute`       | POST     | -                      | Toggle mute                    |
+| `/api/media/seek`       | POST     | `{"position": 60.0}`   | Seek to position (seconds)     |
+| `/api/media/turn_on`    | POST     | -                      | Execute on_turn_on callback    |
+| `/api/media/turn_off`   | POST     | -                      | Execute on_turn_off callback   |
+| `/api/media/toggle`     | POST     | -                      | Execute on_toggle callback     |
 
-### Script Execution
+### Visualizer API
 
-The server supports executing pre-defined scripts via API.
+| Endpoint                          | Method   | Body                                    | Description                            |
+|-----------------------------------|----------|-----------------------------------------|----------------------------------------|
+| `/api/media/visualizer/status`    | GET      | -                                       | Check availability and running state   |
+| `/api/media/visualizer/devices`   | GET      | -                                       | List loopback audio devices            |
+| `/api/media/visualizer/device`    | POST     | `{"device_name": "..." \                | null}`                                 |
 
-#### List Scripts
+### Audio Devices
 
-```
-GET /api/scripts/list
+```text
+GET /api/audio/devices
 Authorization: Bearer <token>
 ```
 
-**Response:**
-```json
-[
-  {
-    "name": "lock_screen",
-    "label": "Lock Screen",
-    "description": "Lock the workstation",
-    "timeout": 5
-  }
-]
-```
+Returns a list of available audio output devices.
 
-#### Execute Script
+### Script Management
 
-```
-POST /api/scripts/execute/{script_name}
-Authorization: Bearer <token>
-Content-Type: application/json
+Scripts can be managed via API or directly from the Web UI (Quick Actions tab).
 
-{"args": []}
-```
+![Script and Callback Management](docs/scripts-management.PNG)
+
+| Endpoint                               | Method   | Body                                                    | Description        |
+|----------------------------------------|----------|---------------------------------------------------------|--------------------|
+| `/api/scripts/list`                    | GET      | -                                                       | List all scripts   |
+| `/api/scripts/execute/{script_name}`   | POST     | `{"args": []}`                                          | Execute a script   |
+| `/api/scripts/create/{script_name}`    | POST     | `{command, label, description, icon, timeout, shell}`   | Create a script    |
+| `/api/scripts/update/{script_name}`    | PUT      | `{command, label, description, icon, timeout, shell}`   | Update a script    |
+| `/api/scripts/delete/{script_name}`    | DELETE   | -                                                       | Delete a script    |
+
+**Execute response:**
 
-**Response:**
 ```json
 {
   "success": true,
@@ -260,7 +587,7 @@ Content-Type: application/json
 }
 ```
 
-### Configuring Scripts
+### Script Config Options
 
 Add scripts in your `config.yaml`:
 
@@ -302,21 +629,33 @@ scripts:
     shell: true
 ```
 
-Script configuration options:
+Script fields:
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `command` | Yes | Command to execute |
-| `label` | No | User-friendly display name (defaults to script name) |
-| `description` | No | Description of what the script does |
-| `icon` | No | Custom MDI icon (e.g., `mdi:power`) |
-| `timeout` | No | Execution timeout in seconds (default: 30, max: 300) |
-| `working_dir` | No | Working directory for the command |
-| `shell` | No | Run in shell (default: true) |
+| Field           | Required   | Description                                            |
+|-----------------|------------|--------------------------------------------------------|
+| `command`       | Yes        | Command to execute                                     |
+| `label`         | No         | User-friendly display name (defaults to script name)   |
+| `description`   | No         | Description of what the script does                    |
+| `icon`          | No         | Custom MDI icon (e.g., `mdi:power`)                    |
+| `timeout`       | No         | Execution timeout in seconds (default: 30, max: 300)   |
+| `working_dir`   | No         | Working directory for the command                      |
+| `shell`         | No         | Run in shell (default: true)                           |
 
-### Configuring Callbacks
+### Callback Management
 
-Callbacks are optional commands executed after media actions. Add them in your `config.yaml`:
+Callbacks are commands executed after media actions. They can be managed via API or the Web UI (Quick Actions tab).
+
+| Endpoint                                  | Method   | Body                                       | Description              |
+|-------------------------------------------|----------|--------------------------------------------|--------------------------|
+| `/api/callbacks/list`                     | GET      | -                                          | List all callbacks       |
+| `/api/callbacks/execute/{callback_name}`  | POST     | -                                          | Execute (for debugging)  |
+| `/api/callbacks/create/{callback_name}`   | POST     | `{command, timeout, working_dir, shell}`   | Create a callback        |
+| `/api/callbacks/update/{callback_name}`   | PUT      | `{command, timeout, working_dir, shell}`   | Update a callback        |
+| `/api/callbacks/delete/{callback_name}`   | DELETE   | -                                          | Delete a callback        |
+
+### Callback Config Options
+
+Add callbacks in your `config.yaml`:
 
 ```yaml
 callbacks:
@@ -380,28 +719,83 @@ callbacks:
 
 Available callbacks:
 
-| Callback | Triggered by | Description |
-|----------|--------------|-------------|
-| `on_play` | `/api/media/play` | After play succeeds |
-| `on_pause` | `/api/media/pause` | After pause succeeds |
-| `on_stop` | `/api/media/stop` | After stop succeeds |
-| `on_next` | `/api/media/next` | After next track succeeds |
-| `on_previous` | `/api/media/previous` | After previous track succeeds |
-| `on_volume` | `/api/media/volume` | After volume change succeeds |
-| `on_mute` | `/api/media/mute` | After mute toggle |
-| `on_seek` | `/api/media/seek` | After seek succeeds |
-| `on_turn_on` | `/api/media/turn_on` | Callback-only action |
-| `on_turn_off` | `/api/media/turn_off` | Callback-only action |
-| `on_toggle` | `/api/media/toggle` | Callback-only action |
+| Callback        | Triggered by            | Description                     |
+|-----------------|-------------------------|---------------------------------|
+| `on_play`       | `/api/media/play`       | After play succeeds             |
+| `on_pause`      | `/api/media/pause`      | After pause succeeds            |
+| `on_stop`       | `/api/media/stop`       | After stop succeeds             |
+| `on_next`       | `/api/media/next`       | After next track succeeds       |
+| `on_previous`   | `/api/media/previous`   | After previous track succeeds   |
+| `on_volume`     | `/api/media/volume`     | After volume change succeeds    |
+| `on_mute`       | `/api/media/mute`       | After mute toggle               |
+| `on_seek`       | `/api/media/seek`       | After seek succeeds             |
+| `on_turn_on`    | `/api/media/turn_on`    | Callback-only action            |
+| `on_turn_off`   | `/api/media/turn_off`   | Callback-only action            |
+| `on_toggle`     | `/api/media/toggle`     | Callback-only action            |
 
-Callback configuration options:
+Callback fields:
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `command` | Yes | Command to execute |
-| `timeout` | No | Execution timeout in seconds (default: 30, max: 300) |
-| `working_dir` | No | Working directory for the command |
-| `shell` | No | Run in shell (default: true) |
+| Field           | Required   | Description                                            |
+|-----------------|------------|--------------------------------------------------------|
+| `command`       | Yes        | Command to execute                                     |
+| `timeout`       | No         | Execution timeout in seconds (default: 30, max: 300)   |
+| `working_dir`   | No         | Working directory for the command                      |
+| `shell`         | No         | Run in shell (default: true)                           |
+
+### Browser API
+
+| Endpoint                                    | Method   | Body                                   | Description                                |
+|---------------------------------------------|----------|----------------------------------------|--------------------------------------------|
+| `/api/browser/folders`                      | GET      | -                                      | List configured media folders              |
+| `/api/browser/browse`                       | GET      | -                                      | Browse directory (query: folder_id, path)  |
+| `/api/browser/metadata`                     | GET      | -                                      | Get file metadata (query: file_path)       |
+| `/api/browser/thumbnail`                    | GET      | -                                      | Get thumbnail image (query: file_path)     |
+| `/api/browser/download`                     | GET      | -                                      | Download file (query: folder_id, path)     |
+| `/api/browser/play`                         | POST     | `{"file_path": "..."}`                 | Open file with default player              |
+| `/api/browser/play-folder`                  | POST     | `{"folder_id": "...", "path": ""}`     | Play all files in folder (M3U)             |
+| `/api/browser/folders/create`               | POST     | `{folder_id, label, path, enabled}`    | Create folder config                       |
+| `/api/browser/folders/update/{folder_id}`   | PUT      | `{label, path, enabled}`               | Update folder config                       |
+| `/api/browser/folders/delete/{folder_id}`   | DELETE   | -                                      | Delete folder config                       |
+
+All endpoints require bearer token authentication.
+
+### Security Notes
+
+- **Path Traversal Protection** - All paths are validated to prevent directory traversal attacks
+- **Folder Restrictions** - Only configured folders are accessible
+- **Authentication Required** - All endpoints require a valid API token
+- **Output Limits** - Script stdout/stderr capped at 10KB
+
+### WebSocket
+
+```text
+WebSocket /api/media/ws
+Authorization: Bearer <token>
+```
+
+The WebSocket connection provides real-time updates and low-latency control.
+
+**Messages from server:**
+
+| Type                | Data                   | Description                            |
+|---------------------|------------------------|----------------------------------------|
+| `status`            | Media status object    | Initial status on connection           |
+| `status_update`     | Media status object    | Status changes during playback         |
+| `audio_data`        | `[0.1, 0.2, ...]`      | Visualizer frequency data (30 fps)     |
+| `scripts_changed`   | `{}`                   | Scripts were created/updated/deleted   |
+| `links_changed`     | `{}`                   | Links were created/updated/deleted     |
+| `pong`              | -                      | Response to client ping                |
+| `error`             | `{"message": "..."}`   | Error messages                         |
+
+**Messages from client:**
+
+| Type                  | Data                   | Description                                                |
+|-----------------------|------------------------|------------------------------------------------------------|
+| `ping`                | -                      | Keepalive ping                                             |
+| `get_status`          | -                      | Request current status                                     |
+| `volume`              | `{"volume": 0-100}`    | Low-latency volume control via WebSocket                   |
+| `enable_visualizer`   | -                      | Subscribe to audio data (starts capture)                   |
+| `disable_visualizer`  | -                      | Unsubscribe from audio data (stops capture on last client) |
 
 ## Running as a Service
 
@@ -419,20 +813,23 @@ To remove the scheduled task:
 Unregister-ScheduledTask -TaskName "MediaServer" -Confirm:$false
 ```
 
-### Windows Service
+### Windows Service (Alternative)
 
 Install:
+
 ```bash
 python -m media_server.service.install_windows install
 ```
 
 Start/Stop:
+
 ```bash
 python -m media_server.service.install_windows start
 python -m media_server.service.install_windows stop
 ```
 
 Remove:
+
 ```bash
 python -m media_server.service.install_windows remove
 ```
@@ -440,24 +837,68 @@ python -m media_server.service.install_windows remove
 ### Linux (systemd)
 
 Install:
+
 ```bash
 sudo ./service/install_linux.sh install
 ```
 
-Enable and start for your user:
+**Enable user lingering** — required so `/run/user/$UID/bus` (the D-Bus
+session socket needed for MPRIS) exists even when no graphical session
+is active. Without this the server boots but every `/api/media/*` call
+silently returns idle.
+
 ```bash
-sudo systemctl enable media-server@$USER
-sudo systemctl start media-server@$USER
+sudo loginctl enable-linger $USER
+```
+
+Enable and start the templated unit for your user:
+
+```bash
+sudo systemctl enable --now media-server@$USER
 ```
 
 View logs:
+
 ```bash
 journalctl -u media-server@$USER -f
 ```
 
+**Troubleshooting:**
+
+- *"`/api/media/status` always returns `idle`"* — check the service log for
+  `D-Bus session bus not available`. Most commonly: lingering isn't
+  enabled, or the unit is using the wrong `XDG_RUNTIME_DIR` (`%U` must
+  expand to the user's numeric UID).
+- *"Visualizer permanently unavailable"* — PulseAudio/PipeWire must
+  expose monitor sources. `pactl list sources short | grep monitor`
+  should list at least one entry; if not, install `pipewire-pulse` and
+  restart your session.
+- *"Volume control silently fails"* — `pactl` must be on `PATH` and the
+  user's PulseAudio/PipeWire server must be reachable
+  (`PULSE_RUNTIME_PATH=/run/user/$UID/pulse`).
+- *"Foreground window is always `null`"* — expected under Wayland; the
+  compositor hides window info from unprivileged clients. X11 sessions
+  work normally.
+
+### macOS (LaunchAgent)
+
+The distribution tarball ships an installer:
+
+```bash
+./install-launchagent.sh
+```
+
+This drops `~/Library/LaunchAgents/com.dolgolyov.media-server.plist`,
+starts the service immediately, and re-launches it at every login. Logs
+go to `~/Library/Logs/media-server/{stdout,stderr}.log`. To stop:
+
+```bash
+./uninstall-launchagent.sh
+```
+
 ## Command Line Options
 
-```
+```text
 python -m media_server.main [OPTIONS]
 
 Options:
@@ -476,15 +917,19 @@ Options:
 
 ## Supported Media Players
 
-### Windows
+### Players on Windows
+
 - Spotify
 - Windows Media Player
 - VLC
 - Groove Music
-- Web browsers (Chrome, Edge, Firefox)
+- foobar2000
+- AIMP
+- Web browsers (Chrome, Edge, Firefox, Opera, Brave)
 - Any app using Windows Media Transport Controls
 
-### Linux
+### Players on Linux
+
 - Any MPRIS-compliant player:
   - Spotify
   - VLC
@@ -493,28 +938,33 @@ Options:
   - Web browsers
   - MPD (with MPRIS bridge)
 
-### macOS
+### Players on macOS
+
 - Spotify
 - Apple Music
 - VLC (partial)
 - QuickTime Player
 
-### Android (via Termux)
+### Players on Android (via Termux)
+
 - System media controls
 - Limited seek support
 
 ## Troubleshooting
 
 ### "No active media session"
+
 - Ensure a media player is running and has played content
 - On Windows, check that the app supports media transport controls
 - On Linux, verify MPRIS with: `dbus-send --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames | grep mpris`
 
 ### Permission errors on Linux
+
 - Ensure your user has access to the D-Bus session bus
 - For systemd service, the `DBUS_SESSION_BUS_ADDRESS` must be set correctly
 
 ### Volume control not working
+
 - Windows: Run as administrator if needed
 - Linux: Ensure PulseAudio/PipeWire is running
 

RELEASE_NOTES.md

@@ -0,0 +1,51 @@
+## v0.4.0 (2026-05-28)
+
+Two headline changes since v0.3.1: **Media Server now ships first-class Linux and macOS builds** (no more Windows-only), and the **Windows app icon was redesigned** with a proper multi-resolution ICO so the installer, Start Menu, desktop shortcut, Alt+Tab, and system tray all render sharp.
+
+### Features
+
+- **Linux support, production-ready.** New `linux` extra (`dbus-python`, `PyGObject`, `python-xlib`) plus a `build-dist-linux.sh` that emits a portable tarball and a systemd user unit. The unit sets `DBUS_SESSION_BUS_ADDRESS`, `XDG_RUNTIME_DIR`, and `ReadWritePaths` for `~/.config` / `~/.cache` so MPRIS works and audit-log / thumbnail writes aren't blocked by `ProtectHome`. The Linux MPRIS controller now connects to the session bus lazily — a missing or late bus no longer crashes lifespan startup, and the user is logged a one-line hint about `loginctl enable-linger`. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+- **macOS support.** New `macos` extra (`pyobjc-framework-Cocoa`, `pyobjc-framework-Quartz`), a `build-dist-macos.sh` script, and a per-user LaunchAgent installer producing `MediaServer-vX.Y-macos-{arm64,x86_64}.tar.gz` artifacts. Spotify URL artwork is wired through `MediaController.get_album_art()`. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+- **Cross-platform album artwork.** `MediaController.get_album_art()` is now abstract with Linux (`mpris:artUrl`, `file://` + `http(s)://`) and macOS (Spotify URL) implementations; the `/api/media/artwork` endpoint awaits the controller. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+- **Per-OS unavailable reasons on `/api/media/visualizer/status`** so the Web UI can explain *why* the visualizer is off on Linux / macOS instead of just hiding it. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+- **Startup preflight on Linux** warns when `DBUS_SESSION_BUS_ADDRESS` or `XDG_RUNTIME_DIR` is unset and informs the user when running under Wayland disables the foreground-window probe — so silent loss of features is now diagnosable from the log. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+- **Redesigned app icon ("Beacon").** Replaces the generic Spotify-green circle with a refined squircle + deep-teal diagonal gradient (`#0B3D3B → #1A6B5E`) + warm parchment play triangle (`#F5F1E8`) with a drop shadow, top sheen, and ghosted echo-chevrons that hint at broadcast/stream. ([d798fed](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/d798fed))
+- **Multi-resolution Windows ICO.** `icon.ico` grew from a single 16×16 frame (208 B) to a 10-frame ICO (16/20/24/32/40/48/64/96/128/256 — ~37 KB) so Windows no longer upscales 16×16 into mush for the installer chrome, Start Menu, desktop shortcuts, Alt+Tab, and File Explorer tiles. ([d798fed](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/d798fed))
+- **System tray uses the new icon.** `tray.py` now picks a 64×64 frame from the multi-res ICO; the procedural fallback was reskinned to the same Beacon palette so a missing ICO no longer regresses the tray back to the old Spotify-green circle. ([d798fed](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/d798fed))
+
+### Bug Fixes
+
+- **`tray._confirm` guarded against `ctypes.windll` on non-Windows** so the new Linux / macOS builds don't crash when the tray prompts for confirmation. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+- **`config.example.yaml` defaults are now cross-platform.** Per-OS commented examples for the on/off scripts, and `on_turn_off` defaults to a harmless `echo` (the previous default silently failed everywhere but Windows). ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+
+---
+
+### Development / Internal
+
+#### Build & Packaging
+
+- **`scripts/generate-icon.py`** — SVG is the canonical source; `resvg-py` rasterizes every ICO size; Pillow packs the multi-resolution `icon.ico`. Re-run any time the SVG changes. ([d798fed](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/d798fed))
+- **Dependency reorganization in `pyproject.toml`** — `screen-brightness-control` and `monitorcontrol` are cross-platform and moved to base deps; new `linux` and `macos` optional-deps groups with `sys_platform` markers. `resvg-py` added to `[dev]` for the icon-generation script. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c), [d798fed](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/d798fed))
+- **`install_linux.sh`** — dropped the dead `requirements.txt` path; now installs via `pip install ".[linux]"` and pre-creates the writable state dirs. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+- **Templated `media-server.service`** updated to match the new dist layout, with proper session-bus env vars and a writable state-dir grant. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+
+#### CI
+
+- **New `linux-smoke` job** in `.gitea/workflows/test.yml` — installs `.[linux]`, boots the server under `dbus-run-session`, and asserts `/api/health`. Catches dependency-resolution and import-time regressions for the Linux dist path. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+- **Release workflow gains apt-deps step** for the Linux build and a best-effort macOS build job that produces the per-arch macOS tarballs. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+
+#### Documentation
+
+- **README rewritten for the new extras** — replaces the stale `pip install -r requirements.txt` instructions, adds a systemd-lingering note + troubleshooting section, and a macOS LaunchAgent section. ([ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c))
+
+---
+
+<details>
+<summary>All Commits</summary>
+
+| Hash | Message | Author |
+|------|---------|--------|
+| [d798fed](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/d798fed) | feat(icon): redesign app icon as "Beacon" and ship multi-resolution ICO | alexei.dolgolyov |
+| [ddf4a6c](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server/commit/ddf4a6c) | feat: production-ready Linux & macOS support | alexei.dolgolyov |
+
+</details>

build-common.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# build-common.sh — shared functions for platform build scripts
+# Source this file, do not execute directly.
+
+# --- Version detection ---
+# Fallback chain: CLI arg → git tag → CI env var → pyproject.toml
+detect_version() {
+    local arg="${1:-}"
+    VERSION="${arg}"
+
+    if [ -z "$VERSION" ]; then
+        VERSION=$(git describe --tags --exact-match 2>/dev/null || true)
+    fi
+
+    if [ -z "$VERSION" ]; then
+        VERSION="${GITEA_REF_NAME:-${GITHUB_REF_NAME:-}}"
+    fi
+
+    if [ -z "$VERSION" ]; then
+        VERSION=$(grep -oP '^version\s*=\s*"\K[^"]+' \
+          pyproject.toml 2>/dev/null || echo "0.0.0")
+    fi
+
+    VERSION_CLEAN="${VERSION#v}"
+
+    # Normalize non-PEP440 labels (e.g. "dev", "nightly", "snapshot") to a
+    # valid PEP440 dev release. Without this, pip/setuptools rejects
+    # pyproject.toml with: `project.version` must be pep440.
+    #
+    # Valid forms:   1.2.3, 1.2.3a1, 1.2.3rc2, 1.2.3.dev0, 1.2.3.post1, +local
+    # Invalid forms: dev, vdev, nightly, snapshot-2024
+    if ! [[ "$VERSION_CLEAN" =~ ^[0-9]+(\.[0-9]+)*((a|b|rc|\.dev|\.post)[0-9]+)*(\+[a-zA-Z0-9.]+)?$ ]]; then
+        echo "  Warning: '$VERSION_CLEAN' is not PEP440-compliant, using 0.0.0.dev0"
+        VERSION_CLEAN="0.0.0.dev0"
+    fi
+
+    # Stamp version into pyproject.toml (single source of truth)
+    sed -i "s/^version = .*/version = \"${VERSION_CLEAN}\"/" pyproject.toml
+}
+
+# --- Clean dist/build directories ---
+clean_dist() {
+    rm -rf dist build
+    mkdir -p "$@"
+}
+
+# --- Verify frontend bundle exists ---
+verify_frontend() {
+    if [ ! -f "media_server/static/dist/app.bundle.js" ]; then
+        echo "ERROR: Frontend bundle not found. Run 'npm ci && npm run build' first."
+        exit 1
+    fi
+}
+
+# --- Copy application files into dist ---
+# Args: $1 = DIST_DIR
+copy_app_files() {
+    local dist_dir="$1"
+
+    echo "Copying application files..."
+    mkdir -p "${dist_dir}/app"
+    cp -r media_server "${dist_dir}/app/"
+
+    # Remove source JS (bundle is in dist/)
+    rm -rf "${dist_dir}/app/media_server/static/js"
+    # Remove source maps from release
+    rm -f "${dist_dir}/app/media_server/static/dist/"*.map
+
+    # Copy config example
+    cp config.example.yaml "${dist_dir}/"
+
+    # Write version file
+    echo "$VERSION_CLEAN" > "${dist_dir}/VERSION"
+}
+
+# --- Clean up site-packages for smaller distribution ---
+# Args: $1 = site-packages path, $2 = ext suffix (pyd|so), $3 = lib suffix (dll|so)
+# Windows: cleanup_site_packages "$SP" "pyd" "dll"
+# Linux:   cleanup_site_packages "$SP" "so"  "so"
+cleanup_site_packages() {
+    local sp_dir="$1"
+    local ext_suffix="${2:-so}"
+    local lib_suffix="${3:-so}"
+
+    echo "Optimizing size..."
+
+    # Generic cleanup
+    find "$sp_dir" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+    find "$sp_dir" -type d -name tests -exec rm -rf {} + 2>/dev/null || true
+    find "$sp_dir" -type d -name "*.dist-info" -exec rm -rf {} + 2>/dev/null || true
+    find "$sp_dir" -name "*.pyi" -delete 2>/dev/null || true
+    rm -rf "$sp_dir"/{pip,setuptools,pkg_resources,_distutils_hack}* 2>/dev/null || true
+
+    # Trim numpy if present.
+    # Keep only modules that numpy/__init__.py does NOT import unconditionally —
+    # lib, linalg, ma, polynomial, fft, ctypeslib, matrixlib are all required for
+    # `import numpy` to succeed, so they MUST stay.
+    for mod in distutils f2py typing _pyinstaller; do
+        rm -rf "$sp_dir/numpy/$mod" 2>/dev/null || true
+    done
+
+    # Trim OpenCV if present
+    rm -f "$sp_dir"/cv2/opencv_videoio_ffmpeg*."$lib_suffix" 2>/dev/null || true
+    rm -rf "$sp_dir"/cv2/{data,gapi,misc,utils,typing_stubs,typing} 2>/dev/null || true
+
+    # Trim Pillow unused plugins if present
+    rm -rf "$sp_dir"/PIL/{FpxImagePlugin,MicImagePlugin,McIdasImagePlugin}* 2>/dev/null || true
+
+    # Trim zeroconf service DB if present
+    rm -rf "$sp_dir"/zeroconf/_services 2>/dev/null || true
+
+    # Strip debug symbols from native extensions
+    find "$sp_dir" -name "*.$ext_suffix" -exec strip --strip-debug {} \; 2>/dev/null || true
+
+    # NOTE: do NOT strip .py source files. A previous version of this function
+    # ran `find ... -name "*.py" ! -name "__init__.py" -delete` with a comment
+    # claiming "keep .pyc only" — but no compileall step exists, so the dist
+    # shipped with __init__.py + .pyd only, missing every submodule (Image.py,
+    # ImageDraw.py, _version.py, ...). Fresh installs would fail with
+    # ModuleNotFoundError; in-place upgrades over an older install produced a
+    # half-old/half-new site-packages where PIL/__init__.py was new but
+    # PIL/_version.py was stale, yielding the runtime "_imaging extension was
+    # built for another version of Pillow" import error.
+}

build-dist-linux.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build Linux distribution (self-contained venv + tarball)
+# Usage: ./build-dist-linux.sh [VERSION]
+
+source "$(dirname "$0")/build-common.sh"
+
+detect_version "${1:-}"
+echo "Building Media Server v${VERSION_CLEAN} for Linux"
+
+# --- Configuration ---
+DIST_DIR="dist/media-server"
+BUILD_OUTPUT="build/MediaServer-v${VERSION_CLEAN}-linux-x64"
+
+clean_dist "${DIST_DIR}" build
+verify_frontend
+
+# --- Sanity check: native deps required for dbus-python + PyGObject ---
+# These compile from sdist on Linux. We don't try to install them via the
+# distro package manager here (the CI image must already have them); fail
+# with a clear message instead of cryptic gcc/pkg-config errors deep
+# inside pip.
+need_pkg() {
+    local pkg="$1"
+    if ! command -v pkg-config >/dev/null 2>&1; then
+        echo "ERROR: pkg-config is required (apt: pkg-config / dnf: pkgconf-pkg-config)" >&2
+        exit 1
+    fi
+    if ! pkg-config --exists "$pkg" 2>/dev/null; then
+        echo "ERROR: $pkg headers missing — install libdbus-1-dev libglib2.0-dev (apt)" >&2
+        echo "       or dbus-devel glib2-devel (dnf) before running this script." >&2
+        exit 1
+    fi
+}
+need_pkg dbus-1
+need_pkg glib-2.0
+
+# --- Create self-contained virtualenv ---
+echo "Creating virtualenv..."
+python3 -m venv "${DIST_DIR}/venv"
+source "${DIST_DIR}/venv/bin/activate"
+pip install --quiet --upgrade pip
+# Install with the linux extra so dbus-python / PyGObject / python-xlib land
+# in the venv. Falls back to base deps if the extra is unsupported (shouldn't
+# happen post-0.3.2 but keep the fallback for older tags re-built here).
+if ! pip install --quiet ".[linux]"; then
+    echo "WARN: '.[linux]' extra unavailable; installing base deps only" >&2
+    pip install --quiet "."
+fi
+
+# Remove the installed package (app source is on PYTHONPATH via launcher)
+rm -rf "${DIST_DIR}"/venv/lib/python*/site-packages/media_server*
+rm -rf "${DIST_DIR}"/venv/lib/python*/site-packages/media_server*.dist-info
+
+deactivate
+
+# Trim venv site-packages
+LINUX_SP=$(echo "${DIST_DIR}"/venv/lib/python*/site-packages)
+cleanup_site_packages "$LINUX_SP" "so" "so"
+
+copy_app_files "$DIST_DIR"
+
+# --- Create launcher ---
+cat > "${DIST_DIR}/media-server.sh" << 'LAUNCHER'
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+export PYTHONPATH="$SCRIPT_DIR/app"
+source "$SCRIPT_DIR/venv/bin/activate"
+exec python -m media_server.main "$@"
+LAUNCHER
+chmod +x "${DIST_DIR}/media-server.sh"
+
+# --- Create systemd service installer ---
+# Emits a non-templated unit that runs as the invoking user with the env
+# bits MPRIS / PulseAudio need: DBUS_SESSION_BUS_ADDRESS and XDG_RUNTIME_DIR
+# must be set or DBus.SessionBus() either fails or talks to the wrong bus.
+# We also relax ProtectHome to read-write for ~/.config/media-server +
+# ~/.cache/media-server so audit.log and thumbnail cache writes succeed.
+cat > "${DIST_DIR}/install-service.sh" << 'SERVICE'
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SERVICE_NAME="media-server"
+SERVICE_FILE="/etc/systemd/system/${SERVICE_NAME}.service"
+
+if [ "$EUID" -ne 0 ]; then
+    echo "Please run with sudo: sudo ./install-service.sh"
+    exit 1
+fi
+
+REAL_USER="${SUDO_USER:-$USER}"
+USER_UID="$(id -u "$REAL_USER")"
+USER_HOME="$(getent passwd "$REAL_USER" | cut -d: -f6)"
+RUNTIME_DIR="/run/user/${USER_UID}"
+
+cat > "$SERVICE_FILE" << EOF
+[Unit]
+Description=Media Server
+After=network.target sound.target
+
+[Service]
+Type=simple
+User=${REAL_USER}
+WorkingDirectory=${SCRIPT_DIR}
+ExecStart=${SCRIPT_DIR}/media-server.sh
+Restart=on-failure
+RestartSec=5
+
+# Required by MPRIS (dbus.SessionBus) and PulseAudio/PipeWire loopback.
+Environment=PYTHONUNBUFFERED=1
+Environment=HOME=${USER_HOME}
+Environment=XDG_RUNTIME_DIR=${RUNTIME_DIR}
+Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=${RUNTIME_DIR}/bus
+
+# Light sandboxing — keep ~/.config/media-server + ~/.cache/media-server
+# writable so audit.log / thumbnails / config CRUD continue to work.
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=${USER_HOME}/.config/media-server ${USER_HOME}/.cache/media-server
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Pre-create state dirs so ReadWritePaths actually has something to grant.
+sudo -u "$REAL_USER" mkdir -p \
+    "${USER_HOME}/.config/media-server" \
+    "${USER_HOME}/.cache/media-server"
+
+systemctl daemon-reload
+systemctl enable "${SERVICE_NAME}"
+systemctl start "${SERVICE_NAME}"
+echo "Service '${SERVICE_NAME}' installed and started."
+echo "Check status: systemctl status ${SERVICE_NAME}"
+echo "Tail logs:    journalctl -u ${SERVICE_NAME} -f"
+SERVICE
+chmod +x "${DIST_DIR}/install-service.sh"
+
+# --- Package ---
+echo "Creating archive..."
+cp -r "${DIST_DIR}" "${BUILD_OUTPUT}"
+tar -czf "${BUILD_OUTPUT}.tar.gz" -C build "MediaServer-v${VERSION_CLEAN}-linux-x64"
+
+echo "Build complete: ${BUILD_OUTPUT}.tar.gz"

build-dist-macos.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build macOS distribution (self-contained venv + tarball)
+# Usage: ./build-dist-macos.sh [VERSION]
+#
+# Must be run on macOS (PyObjC wheels are platform-specific). For CI use
+# the github-hosted macos-latest runner.
+
+source "$(dirname "$0")/build-common.sh"
+
+if [ "$(uname -s)" != "Darwin" ]; then
+    echo "ERROR: build-dist-macos.sh must run on macOS (uname=$(uname -s))" >&2
+    exit 1
+fi
+
+detect_version "${1:-}"
+echo "Building Media Server v${VERSION_CLEAN} for macOS"
+
+# Detect host architecture for archive naming (arm64 = Apple Silicon, x86_64 = Intel).
+ARCH="$(uname -m)"
+DIST_DIR="dist/media-server"
+BUILD_OUTPUT="build/MediaServer-v${VERSION_CLEAN}-macos-${ARCH}"
+
+clean_dist "${DIST_DIR}" build
+verify_frontend
+
+# --- Create self-contained virtualenv ---
+echo "Creating virtualenv..."
+python3 -m venv "${DIST_DIR}/venv"
+# shellcheck disable=SC1091
+source "${DIST_DIR}/venv/bin/activate"
+pip install --quiet --upgrade pip
+if ! pip install --quiet ".[macos]"; then
+    echo "WARN: '.[macos]' extra unavailable; installing base deps only" >&2
+    pip install --quiet "."
+fi
+
+# Remove the installed package (app source is on PYTHONPATH via launcher)
+rm -rf "${DIST_DIR}"/venv/lib/python*/site-packages/media_server*
+rm -rf "${DIST_DIR}"/venv/lib/python*/site-packages/media_server*.dist-info
+
+deactivate
+
+# Trim venv site-packages — macOS native ext is .so, dylibs are .dylib
+MAC_SP=$(echo "${DIST_DIR}"/venv/lib/python*/site-packages)
+cleanup_site_packages "$MAC_SP" "so" "dylib"
+
+copy_app_files "$DIST_DIR"
+
+# --- Launcher ---
+cat > "${DIST_DIR}/media-server.sh" << 'LAUNCHER'
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+export PYTHONPATH="$SCRIPT_DIR/app"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/venv/bin/activate"
+exec python -m media_server.main "$@"
+LAUNCHER
+chmod +x "${DIST_DIR}/media-server.sh"
+
+# --- LaunchAgent installer ---
+# LaunchAgents run as the user, with the user's GUI session — exactly what
+# we want for AppleScript / Music.app / Spotify control. KeepAlive auto-
+# restarts on crash; RunAtLoad starts at login.
+cat > "${DIST_DIR}/install-launchagent.sh" << 'LAUNCHAGENT'
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LABEL="com.dolgolyov.media-server"
+PLIST_DIR="${HOME}/Library/LaunchAgents"
+PLIST="${PLIST_DIR}/${LABEL}.plist"
+LOG_DIR="${HOME}/Library/Logs/media-server"
+
+mkdir -p "$PLIST_DIR" "$LOG_DIR"
+
+cat > "$PLIST" << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${SCRIPT_DIR}/media-server.sh</string>
+        <string>--no-tray</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${SCRIPT_DIR}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>${LOG_DIR}/stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>${LOG_DIR}/stderr.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PYTHONUNBUFFERED</key>
+        <string>1</string>
+    </dict>
+</dict>
+</plist>
+EOF
+
+# Reload if already loaded, then load fresh.
+launchctl unload "$PLIST" 2>/dev/null || true
+launchctl load -w "$PLIST"
+
+echo "LaunchAgent '${LABEL}' installed and started."
+echo "Plist:  $PLIST"
+echo "Logs:   $LOG_DIR/{stdout,stderr}.log"
+echo "Stop:   launchctl unload \"$PLIST\""
+echo "Start:  launchctl load -w \"$PLIST\""
+LAUNCHAGENT
+chmod +x "${DIST_DIR}/install-launchagent.sh"
+
+# Convenience uninstaller.
+cat > "${DIST_DIR}/uninstall-launchagent.sh" << 'UNINSTALL'
+#!/usr/bin/env bash
+set -euo pipefail
+LABEL="com.dolgolyov.media-server"
+PLIST="${HOME}/Library/LaunchAgents/${LABEL}.plist"
+launchctl unload "$PLIST" 2>/dev/null || true
+rm -f "$PLIST"
+echo "LaunchAgent '${LABEL}' removed (config preserved under ~/.config/media-server)."
+UNINSTALL
+chmod +x "${DIST_DIR}/uninstall-launchagent.sh"
+
+# --- Package ---
+echo "Creating archive..."
+cp -r "${DIST_DIR}" "${BUILD_OUTPUT}"
+tar -czf "${BUILD_OUTPUT}.tar.gz" -C build "MediaServer-v${VERSION_CLEAN}-macos-${ARCH}"
+
+echo "Build complete: ${BUILD_OUTPUT}.tar.gz"

build-dist-windows.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Cross-build Windows distribution on Linux
+# Usage: ./build-dist-windows.sh [VERSION]
+
+source "$(dirname "$0")/build-common.sh"
+
+detect_version "${1:-}"
+echo "Building Media Server v${VERSION_CLEAN} for Windows"
+
+# --- Configuration ---
+PYTHON_VERSION="3.11.9"
+PYTHON_SHORT="311"
+DIST_DIR="dist/media-server"
+WHEEL_DIR="build/win-wheels"
+SITE_PACKAGES="${DIST_DIR}/python/Lib/site-packages"
+BUILD_OUTPUT="build/MediaServer-v${VERSION_CLEAN}-win-x64"
+
+clean_dist "${DIST_DIR}" "${WHEEL_DIR}" "${SITE_PACKAGES}"
+
+# --- Download embedded Python (cache-friendly) ---
+mkdir -p build
+if [ ! -f build/python-embed.zip ]; then
+    echo "Downloading embedded Python ${PYTHON_VERSION}..."
+    curl -sL "https://www.python.org/ftp/python/${PYTHON_VERSION}/python-${PYTHON_VERSION}-embed-amd64.zip" \
+        -o build/python-embed.zip
+else
+    echo "Using cached embedded Python ${PYTHON_VERSION}"
+fi
+unzip -qo build/python-embed.zip -d "${DIST_DIR}/python"
+
+# Patch ._pth to enable site-packages and app source
+PTH_FILE=$(ls "${DIST_DIR}"/python/python*._pth | head -1)
+sed -i 's/^#\s*import site/import site/' "$PTH_FILE"
+echo 'Lib\site-packages' >> "$PTH_FILE"
+echo '..\app' >> "$PTH_FILE"
+
+# --- Download Windows wheels ---
+echo "Downloading Windows wheels..."
+
+# Core dependencies
+# NOTE: uvicorn[standard] pulls in uvloop via `sys_platform != 'win32'` marker.
+# pip evaluates env markers against the HOST (Linux in CI), so uvloop is
+# requested, but `--platform win_amd64 --only-binary :all:` cannot find a
+# Windows wheel for uvloop (none exist). Result: pip backtracks across every
+# uvicorn[standard] version and ResolutionImpossible. Fix: use plain uvicorn
+# and list only the Windows-compatible standard extras we actually need.
+CORE_DEPS=(
+    "fastapi>=0.109.0"
+    "uvicorn>=0.27.0"
+    "httptools>=0.5.0"
+    "websockets>=10.4"
+    "python-dotenv>=0.13"
+    "pydantic>=2.0"
+    "pydantic-settings>=2.0"
+    "pyyaml>=6.0"
+    "mutagen>=1.47.0"
+    "pillow>=10.0.0"
+)
+
+# Windows-specific dependencies
+# NOTE: wmi is a transitive dep of screen-brightness-control gated on
+# `platform_system == "Windows"`. pip evaluates env markers against the HOST
+# (Linux in CI), so it gets skipped during cross-build. Listed explicitly here
+# so the wheel actually lands in the Windows bundle. Same gotcha as the
+# uvicorn[standard]/uvloop case documented above.
+WIN_DEPS=(
+    "winsdk>=1.0.0b10"
+    "pywin32>=306"
+    "comtypes>=1.2.0"
+    "pycaw>=20230407"
+    "screen-brightness-control>=0.20.0"
+    "wmi>=1.5.1"
+    "monitorcontrol>=3.0.0"
+)
+
+# Visualizer dependencies
+VIS_DEPS=(
+    "soundcard>=0.4.0"
+    "numpy>=1.24.0,<2.0"
+    # pystray lives here (not WIN_DEPS) so its transitive Pillow resolves in the
+    # same pass as CORE_DEPS. Keeping it in the per-dep WIN_DEPS loop downloaded
+    # a second Pillow version that clobbered the core one on unzip, producing
+    # "_imaging extension was built for another version of Pillow" at runtime.
+    "pystray>=0.19.0"
+)
+
+# Resolve core + visualizer deps in a SINGLE call so pip picks compatible
+# transitive versions (notably pydantic/pydantic-core must match).
+# Per-dep loops resolve each dep independently and can leave mismatched
+# transitive versions that overwrite each other in the site-packages unzip.
+CROSS_DEPS=("${CORE_DEPS[@]}" "${VIS_DEPS[@]}")
+pip download --quiet --no-cache-dir --dest "$WHEEL_DIR" \
+    --platform win_amd64 --python-version "${PYTHON_SHORT}" \
+    --implementation cp --only-binary :all: \
+    "${CROSS_DEPS[@]}"
+
+# Windows-only deps in a loop with --pre: winsdk only ships beta wheels
+# (1.0.0bNN) and each dep needs its own platform/non-platform fallback.
+for dep in "${WIN_DEPS[@]}"; do
+    pip download --pre --quiet --no-cache-dir --dest "$WHEEL_DIR" \
+        --platform win_amd64 --python-version "${PYTHON_SHORT}" \
+        --implementation cp --only-binary :all: \
+        "$dep" 2>/dev/null || \
+    pip download --pre --quiet --no-cache-dir --dest "$WHEEL_DIR" \
+        --only-binary :all: \
+        "$dep"
+done
+
+# Remove numpy 2.x wheels pulled as transitive deps (soundcard requires <2.0)
+for f in "$WHEEL_DIR"/numpy-2*; do
+    [ -f "$f" ] && echo "Removing incompatible: $(basename "$f")" && rm "$f"
+done
+
+# Install wheels into site-packages
+echo "Installing wheels..."
+for whl in "$WHEEL_DIR"/*.whl; do
+    unzip -qo "$whl" -d "$SITE_PACKAGES"
+done
+
+# numpy wheels from PyPI don't include _distributor_init_local.py unless
+# patched by delvewheel. In embedded Python, os.add_dll_directory() is never
+# called, so libopenblas can't be found and numpy fails to import.
+# Generate the missing loader here instead.
+if [ -d "${SITE_PACKAGES}/numpy" ]; then
+    cat > "${SITE_PACKAGES}/numpy/_distributor_init_local.py" << 'EOF'
+import os
+import sys
+if sys.platform == 'win32':
+    _libs = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'numpy.libs'))
+    if os.path.isdir(_libs):
+        os.add_dll_directory(_libs)
+EOF
+    echo "Generated numpy/_distributor_init_local.py"
+fi
+
+cleanup_site_packages "$SITE_PACKAGES" "pyd" "dll"
+verify_frontend
+copy_app_files "$DIST_DIR"
+
+# Copy scripts needed for auto-start
+mkdir -p "${DIST_DIR}/scripts"
+cp scripts/start-hidden.vbs "${DIST_DIR}/scripts/"
+
+# --- Create launcher ---
+cat > "${DIST_DIR}/media-server.bat" << 'LAUNCHER'
+@echo off
+setlocal
+set "ROOT=%~dp0"
+"%ROOT%python\python.exe" -m media_server.main %*
+LAUNCHER
+
+# --- Package ---
+echo "Creating archives..."
+mkdir -p build
+
+# Portable ZIP
+cp -r "${DIST_DIR}" "${BUILD_OUTPUT}"
+cd build
+zip -qr "MediaServer-v${VERSION_CLEAN}-win-x64.zip" "MediaServer-v${VERSION_CLEAN}-win-x64"
+cd ..
+
+echo "Build complete: build/MediaServer-v${VERSION_CLEAN}-win-x64.zip"
+echo "Dist directory ready for NSIS: ${DIST_DIR}"

config.example.yaml

@@ -1,107 +1,160 @@
 # Media Server Configuration
 # Copy this file to config.yaml and customize as needed.
-# A secure token will be auto-generated on first run if not specified.
+#
+# Secure-by-default: the server binds to loopback (127.0.0.1) only and refuses
+# to bind a non-loopback address with no tokens configured.
+#
+# To expose on the LAN you must do ONE of:
+#   1. Configure api_tokens below AND change host to "0.0.0.0", OR
+#   2. Set `allow_lan_without_auth: true` (LAN-open, no auth — insecure on
+#      hostile networks, only acceptable on a trusted home LAN).
 
-# API Token (generate a secure random token)
-api_token: "your-secure-token-here"
+# API Tokens - Multiple tokens with friendly labels
+# This allows you to identify which client is making requests in the logs
+# api_tokens:
+#   home_assistant: "your-home-assistant-token-here"
+#   mobile: "your-mobile-app-token-here"
+#   web_ui: "your-web-ui-token-here"
 
 # Server settings
-host: "0.0.0.0"
+host: "127.0.0.1"
 port: 8765
+# allow_lan_without_auth: true   # uncomment + change host to 0.0.0.0 for LAN-open mode
+
+# ─── Custom scripts ─────────────────────────────────────────────────────
+#
+# Examples below are platform-specific. Uncomment the block that matches
+# your OS — YAML keys must be unique, so don't ship multiple
+# `lock_screen:` entries.
 
-# Custom scripts
 scripts:
-  lock_screen:
-    command: "rundll32.exe user32.dll,LockWorkStation"
-    label: "Lock Screen"
-    description: "Lock the workstation"
-    timeout: 5
-    shell: true
+  # ── Windows ─────────────────────────────────────────────────────────
+  # lock_screen:
+  #   command: "rundll32.exe user32.dll,LockWorkStation"
+  #   label: "Lock Screen"
+  #   description: "Lock the workstation"
+  #   icon: "mdi:lock"
+  #   timeout: 5
+  #   shell: true
+  # sleep:
+  #   command: "rundll32.exe powrprof.dll,SetSuspendState 0,1,0"
+  #   label: "Sleep"
+  #   icon: "mdi:sleep"
+  #   timeout: 10
+  #   shell: true
+  # shutdown:
+  #   command: "shutdown /s /t 0"
+  #   label: "Shutdown"
+  #   icon: "mdi:power"
+  #   timeout: 10
+  #   shell: true
 
-  hibernate:
-    command: "shutdown /h"
-    label: "Hibernate"
-    description: "Hibernate the PC"
+  # ── Linux (systemd / xdg) ───────────────────────────────────────────
+  # lock_screen:
+  #   command: "loginctl lock-session"   # or: xdg-screensaver lock
+  #   label: "Lock Screen"
+  #   icon: "mdi:lock"
+  #   timeout: 5
+  #   shell: true
+  # sleep:
+  #   command: "systemctl suspend"
+  #   label: "Sleep"
+  #   icon: "mdi:sleep"
+  #   timeout: 10
+  #   shell: true
+  # shutdown:
+  #   command: "systemctl poweroff"
+  #   label: "Shutdown"
+  #   icon: "mdi:power"
+  #   timeout: 10
+  #   shell: true
+
+  # ── macOS ───────────────────────────────────────────────────────────
+  # lock_screen:
+  #   command: "pmset displaysleepnow"
+  #   label: "Lock Screen"
+  #   icon: "mdi:lock"
+  #   timeout: 5
+  #   shell: true
+  # sleep:
+  #   command: "pmset sleepnow"
+  #   label: "Sleep"
+  #   icon: "mdi:sleep"
+  #   timeout: 5
+  #   shell: true
+  # shutdown:
+  #   command: "osascript -e 'tell application \"System Events\" to shut down'"
+  #   label: "Shutdown"
+  #   icon: "mdi:power"
+  #   timeout: 10
+  #   shell: true
+
+  # Cross-platform smoke test (always defined so first-run users see the UI populate).
+  example_script:
+    command: "echo Hello from Media Server!"
+    description: "Example script - echoes a message"
     timeout: 10
     shell: true
 
-  sleep:
-    command: "rundll32.exe powrprof.dll,SetSuspendState 0,1,0"
-    label: "Sleep"
-    description: "Put PC to sleep"
-    timeout: 10
-    shell: true
+# Media folder management from Web UI (default: false)
+# When enabled, media folders can be added, edited, and deleted from the Settings tab.
+# media_folders_management: true
 
-  shutdown:
-    command: "shutdown /s /t 0"
-    label: "Shutdown"
-    description: "Shutdown the PC immediately"
-    timeout: 10
-    shell: true
+# ─── Callback scripts (executed by integration events) ──────────────────
+#
+# Callbacks are OS-agnostic — if you want side effects, fill in commands
+# below. The defaults are no-op echos so first-run logs don't error out.
 
-  restart:
-    command: "shutdown /r /t 0"
-    label: "Restart"
-    description: "Restart the PC immediately"
-    timeout: 10
-    shell: true
-
-# Callback scripts (executed after media actions)
-# All callbacks are optional - if not defined, the action runs without callback
 callbacks:
-  # Media control callbacks (run after successful action)
   on_play:
     command: "echo Play triggered"
     timeout: 10
     shell: true
-
   on_pause:
     command: "echo Pause triggered"
     timeout: 10
     shell: true
-
   on_stop:
     command: "echo Stop triggered"
     timeout: 10
     shell: true
-
   on_next:
     command: "echo Next track"
     timeout: 10
     shell: true
-
   on_previous:
     command: "echo Previous track"
     timeout: 10
     shell: true
-
   on_volume:
     command: "echo Volume changed"
     timeout: 10
     shell: true
-
   on_mute:
     command: "echo Mute toggled"
     timeout: 10
     shell: true
-
   on_seek:
     command: "echo Seek triggered"
     timeout: 10
     shell: true
 
-  # Turn on/off/toggle (callback-only actions, no default behavior)
+  # Turn on/off/toggle (callback-only actions, no default behavior).
+  # The Windows-only example used to ship as the default for `on_turn_off`,
+  # which silently failed on Linux/macOS. Defaults are now no-ops — pick a
+  # platform-appropriate command below.
   on_turn_on:
     command: "echo Turn on callback"
     timeout: 10
     shell: true
-
   on_turn_off:
-    command: "rundll32.exe user32.dll,LockWorkStation"
+    # Windows: "rundll32.exe user32.dll,LockWorkStation"
+    # Linux:   "loginctl lock-session"
+    # macOS:   "pmset displaysleepnow"
+    command: "echo Turn off callback"
     timeout: 5
     shell: true
-
   on_toggle:
     command: "echo Toggle callback"
     timeout: 10
-    shell: true
+    shell: true

esbuild.mjs

@@ -0,0 +1,26 @@
+import * as esbuild from 'esbuild';
+
+const srcDir = 'media_server/static';
+const outDir = `${srcDir}/dist`;
+
+const watch = process.argv.includes('--watch');
+
+/** @type {esbuild.BuildOptions} */
+const jsOpts = {
+    entryPoints: [`${srcDir}/js/app.js`],
+    bundle: true,
+    format: 'iife',
+    outfile: `${outDir}/app.bundle.js`,
+    minify: true,
+    sourcemap: true,
+    target: ['es2020'],
+    logLevel: 'info',
+};
+
+if (watch) {
+    const jsCtx = await esbuild.context(jsOpts);
+    await jsCtx.watch();
+    console.log('Watching for changes...');
+} else {
+    await esbuild.build(jsOpts);
+}

installer.nsi

@@ -0,0 +1,180 @@
+; Media Server NSIS Installer
+; Cross-compilable: apt install nsis && makensis -DVERSION="1.0.0" installer.nsi
+
+!include "MUI2.nsh"
+!include "FileFunc.nsh"
+
+; --- Configuration ---
+!define APPNAME "Media Server"
+!define EXENAME "media-server.bat"
+!define VBSNAME "start-hidden.vbs"
+!ifndef VERSION
+    !define VERSION "0.0.0"
+!endif
+
+Name "${APPNAME} ${VERSION}"
+OutFile "build\MediaServer-v${VERSION}-setup.exe"
+InstallDir "$LOCALAPPDATA\${APPNAME}"
+RequestExecutionLevel user
+
+; --- UI ---
+!define MUI_ICON "media_server\static\icons\icon.ico"
+!define MUI_UNICON "media_server\static\icons\icon.ico"
+!define MUI_ABORTWARNING
+!define MUI_FINISHPAGE_RUN ""
+!define MUI_FINISHPAGE_RUN_TEXT "Launch ${APPNAME}"
+!define MUI_FINISHPAGE_RUN_FUNCTION LaunchApp
+
+!insertmacro MUI_PAGE_WELCOME
+!insertmacro MUI_PAGE_DIRECTORY
+!insertmacro MUI_PAGE_COMPONENTS
+!insertmacro MUI_PAGE_INSTFILES
+!insertmacro MUI_PAGE_FINISH
+
+!insertmacro MUI_UNPAGE_CONFIRM
+!insertmacro MUI_UNPAGE_INSTFILES
+
+!insertmacro MUI_LANGUAGE "English"
+
+; --- Functions ---
+Function LaunchApp
+    ExecShell "open" "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"'
+    ; Give the server a moment to start, then open the UI in the default browser
+    Sleep 2000
+    ExecShell "open" "http://localhost:8765/"
+FunctionEnd
+
+Function .onInit
+    ; Check if server is running by trying to open its Python executable exclusively
+    IfFileExists "$INSTDIR\python\python.exe" 0 done
+    ClearErrors
+    FileOpen $0 "$INSTDIR\python\python.exe" a
+    IfErrors locked
+    ; File opened fine — server is not running
+    FileClose $0
+    Goto done
+    locked:
+        MessageBox MB_YESNOCANCEL|MB_ICONEXCLAMATION \
+            "${APPNAME} is currently running.$\n$\nYes = Stop the server and continue$\nNo = Continue without stopping (may cause errors)$\nCancel = Abort installation" \
+            IDYES kill IDNO done
+        Abort
+        kill:
+            nsExec::ExecToLog 'wmic process where "ExecutablePath like $\'%Media Server%python%$\'" call terminate'
+            Sleep 2000
+    done:
+FunctionEnd
+
+; --- Sections ---
+Section "!Core (required)" SecCore
+    SectionIn RO
+
+    SetOutPath "$INSTDIR"
+
+    ; Wipe previous payload before extracting so stale files from an older
+    ; version cannot survive an upgrade. Without this, in-place upgrades
+    ; produce a half-old/half-new site-packages — e.g. an old PIL/_version.py
+    ; alongside a new PIL/_imaging.pyd, which raises "_imaging extension was
+    ; built for another version of Pillow" at runtime. config.yaml lives at
+    ; $INSTDIR root and is preserved.
+    RMDir /r "$INSTDIR\python"
+    RMDir /r "$INSTDIR\app"
+    RMDir /r "$INSTDIR\scripts"
+    Delete "$INSTDIR\${EXENAME}"
+    Delete "$INSTDIR\VERSION"
+    Delete "$INSTDIR\config.example.yaml"
+
+    ; Copy entire distribution
+    File /r "dist\media-server\*.*"
+
+    ; Create config.yaml from example if it doesn't already exist (preserve user config on upgrade)
+    IfFileExists "$INSTDIR\config.yaml" +2
+    CopyFiles /SILENT "$INSTDIR\config.example.yaml" "$INSTDIR\config.yaml"
+
+    ; Create uninstaller
+    WriteUninstaller "$INSTDIR\uninstall.exe"
+
+    ; Start Menu shortcuts
+    CreateDirectory "$SMPROGRAMS\${APPNAME}"
+    CreateShortcut "$SMPROGRAMS\${APPNAME}\${APPNAME}.lnk" \
+        "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"' \
+        "$INSTDIR\app\media_server\static\icons\icon.ico" 0
+    CreateShortcut "$SMPROGRAMS\${APPNAME}\${APPNAME} (Console).lnk" \
+        "$INSTDIR\${EXENAME}" "" \
+        "$INSTDIR\app\media_server\static\icons\icon.ico" 0
+    CreateShortcut "$SMPROGRAMS\${APPNAME}\Uninstall.lnk" \
+        "$INSTDIR\uninstall.exe"
+
+    ; Registry for Add/Remove Programs
+    WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+        "DisplayName" "${APPNAME}"
+    WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+        "DisplayVersion" "${VERSION}"
+    WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+        "UninstallString" "$\"$INSTDIR\uninstall.exe$\""
+    WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+        "InstallLocation" "$INSTDIR"
+    WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+        "Publisher" "Alexei Dolgolyov"
+    WriteRegDWORD HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+        "NoModify" 1
+    WriteRegDWORD HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+        "NoRepair" 1
+
+    ; Calculate installed size
+    ${GetSize} "$INSTDIR" "/S=0K" $0 $1 $2
+    IntFmt $0 "0x%08X" $0
+    WriteRegDWORD HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+        "EstimatedSize" "$0"
+SectionEnd
+
+Section "Desktop shortcut" SecDesktop
+    CreateShortcut "$DESKTOP\${APPNAME}.lnk" \
+        "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"' \
+        "$INSTDIR\app\media_server\static\icons\icon.ico" 0
+SectionEnd
+
+Section "Start with Windows" SecAutostart
+    ; Create Startup folder shortcut (runs hidden via VBS)
+    CreateShortcut "$SMSTARTUP\${APPNAME}.lnk" \
+        "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"' \
+        "$INSTDIR\app\media_server\static\icons\icon.ico" 0
+SectionEnd
+
+; --- Section descriptions ---
+!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
+    !insertmacro MUI_DESCRIPTION_TEXT ${SecCore} \
+        "Core application files, embedded Python, and Start Menu shortcuts."
+    !insertmacro MUI_DESCRIPTION_TEXT ${SecDesktop} \
+        "Create a desktop shortcut to launch ${APPNAME}."
+    !insertmacro MUI_DESCRIPTION_TEXT ${SecAutostart} \
+        "Automatically start ${APPNAME} when you log in to Windows."
+!insertmacro MUI_FUNCTION_DESCRIPTION_END
+
+; --- Uninstaller ---
+Section "Uninstall"
+    ; Stop running instance
+    nsExec::ExecToLog 'wmic process where "ExecutablePath like $\'%Media Server%python%$\'" call terminate'
+    nsExec::ExecToLog 'taskkill /F /IM media-server.exe'
+
+    ; Remove application files
+    RMDir /r "$INSTDIR\python"
+    RMDir /r "$INSTDIR\app"
+    RMDir /r "$INSTDIR\scripts"
+    Delete "$INSTDIR\${EXENAME}"
+    Delete "$INSTDIR\VERSION"
+    Delete "$INSTDIR\uninstall.exe"
+
+    ; Preserve config.yaml (user data) — only remove the example
+    Delete "$INSTDIR\config.example.yaml"
+
+    ; Remove shortcuts
+    Delete "$DESKTOP\${APPNAME}.lnk"
+    Delete "$SMSTARTUP\${APPNAME}.lnk"
+    RMDir /r "$SMPROGRAMS\${APPNAME}"
+
+    ; Remove registry
+    DeleteRegKey HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}"
+
+    ; Remove install dir only if empty (config.yaml may remain)
+    RMDir "$INSTDIR"
+SectionEnd

media_server/__init__.py

@@ -1,3 +1,37 @@
 """Media Server - REST API for controlling system media playback."""
 
-__version__ = "1.0.0"
+import re
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+_VERSION_RE = re.compile(r'^version\s*=\s*"([^"]+)"', re.MULTILINE)
+
+
+def _detect_version() -> str:
+    # 1. Live pyproject.toml — only present in dev checkouts. Prefer this
+    # over installed package metadata so `pip install -e .` users don't
+    # see stale versions after editing pyproject.toml without reinstalling.
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    if pyproject.is_file():
+        try:
+            match = _VERSION_RE.search(pyproject.read_text(encoding="utf-8"))
+            if match:
+                return match.group(1)
+        except OSError:
+            pass
+
+    # 2. Package metadata (works for any pip-installed copy).
+    try:
+        return version("media-server")
+    except PackageNotFoundError:
+        pass
+
+    # 3. VERSION file written by build scripts (production builds).
+    version_file = Path(__file__).resolve().parent.parent.parent / "VERSION"
+    if version_file.is_file():
+        return version_file.read_text().strip()
+
+    return "0.0.0-dev"
+
+
+__version__ = _detect_version()

media_server/auth.py

@@ -1,5 +1,7 @@
 """Authentication middleware and utilities."""
 
+import secrets
+from contextvars import ContextVar
 from typing import Optional
 
 from fastapi import Depends, HTTPException, Query, Request, status
@@ -9,6 +11,61 @@ from .config import settings
 
 security = HTTPBearer(auto_error=False)
 
+# Context variable to store current request's token label
+token_label_var: ContextVar[str] = ContextVar("token_label", default="unknown")
+# Per-request correlation ID — generated in middleware if upstream didn't send one.
+request_id_var: ContextVar[str] = ContextVar("request_id", default="-")
+
+
+def auth_enabled() -> bool:
+    """Check if authentication is enabled (i.e. at least one token is configured)."""
+    return bool(settings.api_tokens)
+
+
+def get_token_label(token: str) -> Optional[str]:
+    """Get the label for a token. Returns None if token is invalid.
+
+    Args:
+        token: The token to look up
+
+    Returns:
+        The label for the token, or None if invalid
+    """
+    for label, spec in settings.api_tokens.items():
+        if secrets.compare_digest(spec.token, token):
+            return label
+    return None
+
+
+def token_has_scope(label: str, required: str) -> bool:
+    """Whether the token identified by `label` grants `required` scope."""
+    spec = settings.api_tokens.get(label)
+    if spec is None:
+        # Unknown label = no auth or anonymous; treat as full access only
+        # when auth is disabled entirely (matches existing behaviour).
+        return not auth_enabled()
+    return spec.grants(required)
+
+
+def require_scope(scope: str):
+    """Build a FastAPI dependency that enforces the given scope.
+
+    Use as ``Depends(require_scope("admin"))`` on management endpoints. When
+    auth is disabled the dependency is a no-op (anonymous access).
+    """
+
+    async def _checker(label: str = Depends(verify_token)) -> str:
+        if not auth_enabled():
+            return label
+        if not token_has_scope(label, scope):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Token '{label}' lacks required scope: {scope}",
+            )
+        return label
+
+    return _checker
+
 
 async def verify_token(
     request: Request,
@@ -16,16 +73,24 @@ async def verify_token(
 ) -> str:
     """Verify the API token from the Authorization header.
 
-    Args:
-        request: The incoming request
-        credentials: The bearer token credentials
+    When no tokens are configured, authentication is skipped entirely.
+    Reuses the label from middleware context when already validated.
 
     Returns:
-        The validated token
+        The token label (or "anonymous" when auth is disabled)
 
     Raises:
-        HTTPException: If the token is missing or invalid
+        HTTPException: If the token is missing or invalid (only when auth enabled)
     """
+    if not auth_enabled():
+        token_label_var.set("anonymous")
+        return "anonymous"
+
+    # Reuse label already set by middleware to avoid redundant O(n) scan
+    existing = token_label_var.get("unknown")
+    if existing != "unknown":
+        return existing
+
     if credentials is None:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
@@ -33,14 +98,16 @@ async def verify_token(
             headers={"WWW-Authenticate": "Bearer"},
         )
 
-    if credentials.credentials != settings.api_token:
+    label = get_token_label(credentials.credentials)
+    if label is None:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Invalid authentication token",
             headers={"WWW-Authenticate": "Bearer"},
         )
 
-    return credentials.credentials
+    token_label_var.set(label)
+    return label
 
 
 class TokenAuth:
@@ -54,7 +121,11 @@ class TokenAuth:
         request: Request,
         credentials: HTTPAuthorizationCredentials = Depends(security),
     ) -> str | None:
-        """Verify the token and return it or raise an exception."""
+        """Verify the token and return the label or raise an exception."""
+        if not auth_enabled():
+            token_label_var.set("anonymous")
+            return "anonymous"
+
         if credentials is None:
             if self.auto_error:
                 raise HTTPException(
@@ -64,7 +135,8 @@ class TokenAuth:
                 )
             return None
 
-        if credentials.credentials != settings.api_token:
+        label = get_token_label(credentials.credentials)
+        if label is None:
             if self.auto_error:
                 raise HTTPException(
                     status_code=status.HTTP_401_UNAUTHORIZED,
@@ -73,7 +145,9 @@ class TokenAuth:
                 )
             return None
 
-        return credentials.credentials
+        # Set label in context for logging
+        token_label_var.set(label)
+        return label
 
 
 async def verify_token_or_query(
@@ -89,23 +163,36 @@ async def verify_token_or_query(
         token: Token from query parameter
 
     Returns:
-        The validated token
+        The token label
 
     Raises:
         HTTPException: If the token is missing or invalid
     """
+    if not auth_enabled():
+        token_label_var.set("anonymous")
+        return "anonymous"
+
+    # Reuse label already set by middleware
+    existing = token_label_var.get("unknown")
+    if existing != "unknown":
+        return existing
+
+    label = None
+
     # Try header first
     if credentials is not None:
-        if credentials.credentials == settings.api_token:
-            return credentials.credentials
+        label = get_token_label(credentials.credentials)
 
     # Try query parameter
-    if token is not None:
-        if token == settings.api_token:
-            return token
+    if label is None and token is not None:
+        label = get_token_label(token)
 
-    raise HTTPException(
-        status_code=status.HTTP_401_UNAUTHORIZED,
-        detail="Missing or invalid authentication token",
-        headers={"WWW-Authenticate": "Bearer"},
-    )
+    if label is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing or invalid authentication token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    token_label_var.set(label)
+    return label

media_server/config.py

@@ -1,14 +1,62 @@
 """Configuration management for the media server."""
 
+import logging
 import os
 import secrets
 from pathlib import Path
 from typing import Optional
 
 import yaml
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+logger = logging.getLogger(__name__)
+
+
+# Token scopes form a strict hierarchy: admin > control > read. Helper utility
+# used by both auth.py and the validator below.
+SCOPE_HIERARCHY: dict[str, frozenset[str]] = {
+    "read": frozenset({"read"}),
+    "control": frozenset({"read", "control"}),
+    "admin": frozenset({"read", "control", "admin"}),
+}
+ALL_SCOPES: frozenset[str] = frozenset(SCOPE_HIERARCHY.keys())
+
+
+class TokenSpec(BaseModel):
+    """Per-token authentication entry with explicit scopes."""
+
+    token: str = Field(..., min_length=8, description="Secret token value")
+    scopes: list[str] = Field(
+        default_factory=lambda: ["admin"],
+        description="Granted scopes (subset of read|control|admin).",
+    )
+
+    @field_validator("scopes")
+    @classmethod
+    def _validate_scopes(cls, v: list[str]) -> list[str]:
+        if not v:
+            raise ValueError("scopes must list at least one of read|control|admin")
+        unknown = set(v) - ALL_SCOPES
+        if unknown:
+            raise ValueError(f"unknown scopes: {sorted(unknown)}; valid={sorted(ALL_SCOPES)}")
+        return v
+
+    def grants(self, required: str) -> bool:
+        """Whether this token grants the requested scope (with hierarchy expansion)."""
+        granted: set[str] = set()
+        for s in self.scopes:
+            granted |= SCOPE_HIERARCHY.get(s, frozenset({s}))
+        return required in granted
+
+
+class MediaFolderConfig(BaseModel):
+    """Configuration for a media folder."""
+
+    path: str = Field(..., description="Absolute path to media folder")
+    label: str = Field(..., description="Human-readable display label")
+    enabled: bool = Field(default=True, description="Whether this folder is active")
+
 
 class CallbackConfig(BaseModel):
     """Configuration for a callback script (no label/description needed)."""
@@ -19,6 +67,33 @@ class CallbackConfig(BaseModel):
     shell: bool = Field(default=True, description="Run command in shell")
 
 
+class ScriptParameterConfig(BaseModel):
+    """Configuration for a script parameter."""
+
+    type: str = Field(
+        ...,
+        description="Parameter type: string, integer, float, boolean, select",
+        pattern=r"^(string|integer|float|boolean|select)$",
+    )
+    description: str = Field(default="", description="Parameter description")
+    required: bool = Field(default=False, description="Whether the parameter is required")
+    default: Optional[str | int | float | bool] = Field(
+        default=None, description="Default value if not provided"
+    )
+    min: Optional[float] = Field(default=None, description="Minimum value (numeric types only)")
+    max: Optional[float] = Field(default=None, description="Maximum value (numeric types only)")
+    options: Optional[list[str]] = Field(
+        default=None, description="Allowed values (select type only)"
+    )
+    pattern: Optional[str] = Field(
+        default=None,
+        description=(
+            "Optional regex (Python flavour) that string-typed values must match."
+            " Use to harden parameters that flow into shell=true scripts."
+        ),
+    )
+
+
 class ScriptConfig(BaseModel):
     """Configuration for a custom script."""
 
@@ -29,6 +104,18 @@ class ScriptConfig(BaseModel):
     timeout: int = Field(default=30, description="Execution timeout in seconds", ge=1, le=300)
     working_dir: Optional[str] = Field(default=None, description="Working directory")
     shell: bool = Field(default=True, description="Run command in shell")
+    parameters: dict[str, ScriptParameterConfig] = Field(
+        default_factory=dict, description="Named parameters with type and validation rules"
+    )
+
+
+class LinkConfig(BaseModel):
+    """Configuration for a header quick link."""
+
+    url: str = Field(..., description="URL to open")
+    icon: str = Field(default="mdi:link", description="MDI icon name (e.g., 'mdi:led-strip-variant')")
+    label: str = Field(default="", description="Tooltip text")
+    description: str = Field(default="", description="Optional description")
 
 
 class Settings(BaseSettings):
@@ -42,14 +129,106 @@ class Settings(BaseSettings):
     )
 
     # Server settings
-    host: str = Field(default="0.0.0.0", description="Server bind address")
-    port: int = Field(default=8765, description="Server port")
-
-    # Authentication
-    api_token: str = Field(
-        default_factory=lambda: secrets.token_urlsafe(32),
-        description="API authentication token",
+    host: str = Field(
+        default="127.0.0.1",
+        description=(
+            "Server bind address. Use 127.0.0.1 for loopback-only (default, safest),"
+            " or 0.0.0.0 to expose on the LAN (requires api_tokens to be set)."
+        ),
     )
+    port: int = Field(default=8765, description="Server port")
+    allow_lan_without_auth: bool = Field(
+        default=False,
+        description=(
+            "Allow binding to a non-loopback address with no api_tokens configured."
+            " Off by default to prevent unauthenticated LAN exposure."
+        ),
+    )
+    cors_origins: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Allowed CORS origins. Empty (default) means only same-origin requests"
+            " from http://localhost:<port> and http://127.0.0.1:<port>."
+        ),
+    )
+
+    # Reverse-proxy deployment: when serving the API behind nginx/Caddy/Traefik,
+    # uvicorn must trust the X-Forwarded-* headers from the proxy so that the
+    # `Origin` allow-list, request URLs, and logs reflect the public-facing
+    # values. Off by default — only enable when there's a real proxy in front
+    # (otherwise clients can spoof their own IP).
+    proxy_headers: bool = Field(
+        default=False,
+        description="Honor X-Forwarded-For / X-Forwarded-Proto from upstream proxy.",
+    )
+    forwarded_allow_ips: str = Field(
+        default="127.0.0.1",
+        description=(
+            "Comma-separated IPs / CIDRs that uvicorn should trust X-Forwarded-* from."
+            " Use '*' to trust all (only safe when bound to a private interface)."
+        ),
+    )
+
+    # HTTPS / TLS. Both must be set together to enable TLS; if only one is set
+    # the server refuses to start. Use `mkcert` or letsencrypt to generate the
+    # pair; the server reads them at startup.
+    ssl_certfile: Optional[str] = Field(
+        default=None,
+        description="Path to TLS certificate (PEM). Pair with ssl_keyfile.",
+    )
+    ssl_keyfile: Optional[str] = Field(
+        default=None,
+        description="Path to TLS private key (PEM). Pair with ssl_certfile.",
+    )
+    ssl_keyfile_password: Optional[str] = Field(
+        default=None,
+        description="Optional password for the private key if encrypted.",
+    )
+
+    # Admin-grade operations (script / callback / link / folder create/update/delete).
+    # When True the same token used for read/play can also persist arbitrary shell
+    # commands. Default False so a single leaked token cannot escalate to RCE; opt
+    # in explicitly to manage scripts/callbacks/links via the Web UI.
+    scripts_management: bool = Field(default=False, description="Allow scripts CRUD via API")
+    callbacks_management: bool = Field(default=False, description="Allow callbacks CRUD via API")
+    links_management: bool = Field(default=False, description="Allow links CRUD via API")
+
+    # Authentication (empty = auth disabled, anyone can access the API).
+    #
+    # Each entry can be either:
+    #   • a bare string (legacy form, treated as scopes = ["admin"] for back-compat), OR
+    #   • a mapping with explicit scopes, e.g.
+    #         "ha":     {token: "<token>", scopes: ["read", "control"]}
+    #         "kiosk":  {token: "<token>", scopes: ["read"]}
+    #         "ops":    {token: "<token>", scopes: ["admin"]}
+    #
+    # Available scopes:
+    #   read    — GET /api/* (status, list, browse) but no state-changing calls.
+    #   control — read + media transport, display/audio, script EXECUTE, callback EXECUTE.
+    #   admin   — control + CRUD on scripts/callbacks/links/folders.
+    #
+    # Validation normalises both forms to TokenSpec at load time.
+    api_tokens: dict[str, TokenSpec] = Field(
+        default_factory=dict,
+        description=(
+            "Named API tokens. Value can be a bare token string (= admin scope) or"
+            " a {token, scopes} mapping. See TokenSpec for scope definitions."
+        ),
+    )
+
+    @field_validator("api_tokens", mode="before")
+    @classmethod
+    def _normalise_tokens(cls, v):
+        """Accept legacy `label: <bare-token>` form and promote to TokenSpec."""
+        if not isinstance(v, dict):
+            return v
+        out: dict[str, dict | TokenSpec] = {}
+        for label, entry in v.items():
+            if isinstance(entry, str):
+                out[label] = {"token": entry, "scopes": ["admin"]}
+            else:
+                out[label] = entry
+        return out
 
     # Media controller settings
     poll_interval: float = Field(
@@ -59,7 +238,10 @@ class Settings(BaseSettings):
     # Audio device settings
     audio_device: Optional[str] = Field(
         default=None,
-        description="Audio device name to control (None = default device). Use /api/audio/devices to list available devices.",
+        description=(
+            "Audio device name to control (None = default device)."
+            " Use /api/audio/devices to list available devices."
+        ),
     )
 
     # Logging
@@ -77,6 +259,61 @@ class Settings(BaseSettings):
         description="Callback scripts executed by integration events (on_turn_on, on_turn_off, on_toggle)",
     )
 
+    # Media folders for browsing
+    media_folders: dict[str, MediaFolderConfig] = Field(
+        default_factory=dict,
+        description="Media folders available for browsing in the media browser",
+    )
+    media_folders_management: bool = Field(
+        default=False,
+        description="Allow adding, editing, and deleting media folders from the Web UI",
+    )
+
+    # Thumbnail settings
+    thumbnail_size: str = Field(
+        default="medium",
+        description='Thumbnail size: "small" (150x150), "medium" (300x300), or "both"',
+    )
+
+    # Header quick links
+    links: dict[str, LinkConfig] = Field(
+        default_factory=dict,
+        description="Quick links displayed as icons in the header",
+    )
+
+    # Audio visualizer
+    visualizer_enabled: bool = Field(
+        default=True,
+        description="Enable audio spectrum visualizer (requires soundcard + numpy)",
+    )
+    visualizer_fps: int = Field(
+        default=30,
+        description="Visualizer update rate in frames per second",
+        ge=10,
+        le=60,
+    )
+    visualizer_bins: int = Field(
+        default=32,
+        description="Number of frequency bins for the visualizer",
+        ge=8,
+        le=128,
+    )
+    visualizer_device: Optional[str] = Field(
+        default=None,
+        description="Loopback audio device name for visualizer (None = auto-detect)",
+    )
+
+    # Update checker
+    update_check_enabled: bool = Field(
+        default=True,
+        description="Check for new versions on startup and periodically",
+    )
+    update_check_interval: int = Field(
+        default=21600,
+        description="Update check interval in seconds (default: 6 hours)",
+        ge=600,
+    )
+
     @classmethod
     def load_from_yaml(cls, path: Optional[Path] = None) -> "Settings":
         """Load settings from a YAML configuration file."""
@@ -121,19 +358,28 @@ def get_config_dir() -> Path:
 
 
 def generate_default_config(path: Optional[Path] = None) -> Path:
-    """Generate a default configuration file with a new API token."""
+    """Generate a default configuration file with a freshly generated API token.
+
+    The token is written into ``api_tokens.default`` and printed to the logger
+    so first-run users can copy it. Subsequent runs preserve whatever the user
+    has set.
+    """
     if path is None:
         path = get_config_dir() / "config.yaml"
 
+    default_token = secrets.token_urlsafe(32)
+
     config = {
-        "host": "0.0.0.0",
+        "host": "127.0.0.1",
         "port": 8765,
-        "api_token": secrets.token_urlsafe(32),
+        # Default token grants "admin" scope (full access). To create a
+        # read-only or control-only token, add a second entry:
+        #   ha_readonly: {token: "<token>", scopes: ["read"]}
+        "api_tokens": {
+            "default": {"token": default_token, "scopes": ["admin"]},
+        },
         "poll_interval": 1.0,
         "log_level": "INFO",
-        # Audio device to control (use GET /api/audio/devices to list available devices)
-        # Set to null or remove to use default device
-        # "audio_device": "Speakers (Realtek",
         "scripts": {
             "example_script": {
                 "command": "echo Hello from Media Server!",
@@ -141,26 +387,72 @@ def generate_default_config(path: Optional[Path] = None) -> Path:
                 "timeout": 10,
                 "shell": True,
             },
-            # Add your custom scripts here:
-            # "shutdown": {
-            #     "command": "shutdown /s /t 60",
-            #     "description": "Shutdown computer in 60 seconds",
-            #     "timeout": 5,
-            # },
-            # "lock_screen": {
-            #     "command": "rundll32.exe user32.dll,LockWorkStation",
-            #     "description": "Lock the workstation",
-            #     "timeout": 5,
-            # },
         },
     }
 
     path.parent.mkdir(parents=True, exist_ok=True)
-    with open(path, "w", encoding="utf-8") as f:
-        yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+    _write_yaml_atomic(path, config)
+    _restrict_config_perms(path)
+
+    logger.info("Generated default config at %s", path)
+    logger.info("API token (label=default): %s", default_token)
 
     return path
 
 
+def _write_yaml_atomic(path: Path, data: dict) -> None:
+    """Write YAML to disk atomically via tmp file + rename, with restricted perms."""
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+    _restrict_config_perms(tmp)
+    os.replace(tmp, path)
+
+
+def _restrict_config_perms(path: Path) -> None:
+    """Ensure config file is readable only by its owner.
+
+    POSIX → ``chmod 0600``. On Windows the default NTFS ACL leaves the file
+    readable by every interactive user on the machine (Users group has Read),
+    which is bad given the file stores plaintext API tokens. Use ``icacls`` to
+    grant exclusive access to the current user + SYSTEM + Administrators and
+    strip inheritance.
+    """
+    if os.name == "nt":
+        _restrict_config_perms_windows(path)
+        return
+    try:
+        os.chmod(path, 0o600)
+        os.chmod(path.parent, 0o700)
+    except OSError:
+        logger.debug("Could not chmod %s", path, exc_info=True)
+
+
+def _restrict_config_perms_windows(path: Path) -> None:
+    """Apply restrictive NTFS ACL to a config file (Windows only)."""
+    import subprocess
+
+    try:
+        username = os.environ.get("USERNAME") or os.environ.get("USER")
+        if not username:
+            logger.debug("Cannot detect current user; skipping icacls hardening")
+            return
+        # Disable inheritance and remove every existing ACE, then grant access
+        # only to current user, SYSTEM, and Administrators. /Q suppresses
+        # progress output; /C lets per-file errors not abort the batch.
+        subprocess.run(
+            ["icacls", str(path), "/inheritance:r"],
+            check=False, capture_output=True, timeout=5,
+        )
+        for principal in (username, "SYSTEM", "Administrators"):
+            subprocess.run(
+                ["icacls", str(path), "/grant:r", f"{principal}:(R,W)"],
+                check=False, capture_output=True, timeout=5,
+            )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        # `icacls` missing or sandboxed — leave the default ACL in place.
+        logger.debug("icacls hardening failed for %s", path, exc_info=True)
+
+
 # Global settings instance
 settings = Settings.load_from_yaml()

media_server/config_manager.py

@@ -0,0 +1,229 @@
+"""Thread-safe configuration file manager for runtime updates."""
+
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+from .config import (
+    CallbackConfig,
+    LinkConfig,
+    MediaFolderConfig,
+    ScriptConfig,
+    _restrict_config_perms,
+    _write_yaml_atomic,
+    settings,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigManager:
+    """Thread-safe configuration file manager.
+
+    All writes go through ``_save()`` which writes to ``config.yaml.tmp`` and
+    then ``os.replace()``s it into place so a crash mid-write cannot corrupt
+    the only persistent user data. On POSIX the file is also chmodded to 0600
+    so co-tenant users cannot read the API token.
+    """
+
+    def __init__(self, config_path: Optional[Path] = None):
+        self._lock = threading.Lock()
+        self._config_path = config_path or self._find_config_path()
+        logger.info(f"ConfigManager initialized with path: {self._config_path}")
+
+    @staticmethod
+    def _find_config_path() -> Path:
+        """Find the active config file path (or the default if none exists yet)."""
+        search_paths = [Path("config.yaml"), Path("config.yml")]
+
+        if os.name == "nt":
+            appdata = os.environ.get("APPDATA", "")
+            if appdata:
+                search_paths.append(Path(appdata) / "media-server" / "config.yaml")
+        else:
+            search_paths.append(Path.home() / ".config" / "media-server" / "config.yaml")
+            search_paths.append(Path("/etc/media-server/config.yaml"))
+
+        for search_path in search_paths:
+            if search_path.exists():
+                return search_path
+
+        if os.name == "nt":
+            default_path = Path(os.environ.get("APPDATA", "")) / "media-server" / "config.yaml"
+        else:
+            default_path = Path.home() / ".config" / "media-server" / "config.yaml"
+
+        logger.warning(f"No config file found, using default path: {default_path}")
+        return default_path
+
+    def _load(self) -> dict[str, Any]:
+        """Read the config YAML, returning an empty dict if the file is missing."""
+        if not self._config_path.exists():
+            return {}
+        with open(self._config_path, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+
+    def _save(self, data: dict[str, Any]) -> None:
+        """Atomically write the config YAML and lock down its permissions."""
+        self._config_path.parent.mkdir(parents=True, exist_ok=True)
+        _write_yaml_atomic(self._config_path, data)
+        _restrict_config_perms(self._config_path)
+
+    # --- Generic per-section CRUD --------------------------------------
+
+    def _upsert(
+        self,
+        section: str,
+        key: str,
+        value: Any,
+        *,
+        require_absent: bool = False,
+        require_present: bool = False,
+        in_memory_target: dict[str, Any] | None = None,
+        verb: str = "set",
+    ) -> None:
+        with self._lock:
+            data = self._load()
+            existing = data.get(section, {})
+            if require_absent and key in existing:
+                raise ValueError(f"{section[:-1].title()} '{key}' already exists")
+            if require_present and (not isinstance(existing, dict) or key not in existing):
+                raise ValueError(f"{section[:-1].title()} '{key}' does not exist")
+
+            if not isinstance(existing, dict):
+                existing = {}
+            existing[key] = value.model_dump(exclude_none=True)
+            data[section] = existing
+
+            self._save(data)
+
+            if in_memory_target is not None:
+                in_memory_target[key] = value
+            logger.info(f"{section[:-1].title()} '{key}' {verb} in config")
+
+    def _delete(
+        self,
+        section: str,
+        key: str,
+        *,
+        in_memory_target: dict[str, Any] | None = None,
+    ) -> None:
+        with self._lock:
+            data = self._load()
+            existing = data.get(section, {})
+            if not isinstance(existing, dict) or key not in existing:
+                raise ValueError(f"{section[:-1].title()} '{key}' does not exist")
+            del existing[key]
+            data[section] = existing
+
+            self._save(data)
+
+            if in_memory_target is not None and key in in_memory_target:
+                del in_memory_target[key]
+            logger.info(f"{section[:-1].title()} '{key}' deleted from config")
+
+    # --- Scripts -------------------------------------------------------
+
+    def add_script(self, name: str, config: ScriptConfig) -> None:
+        self._upsert(
+            "scripts", name, config,
+            require_absent=True,
+            in_memory_target=settings.scripts,
+            verb="added",
+        )
+
+    def update_script(self, name: str, config: ScriptConfig) -> None:
+        self._upsert(
+            "scripts", name, config,
+            require_present=True,
+            in_memory_target=settings.scripts,
+            verb="updated",
+        )
+
+    def delete_script(self, name: str) -> None:
+        self._delete("scripts", name, in_memory_target=settings.scripts)
+
+    # --- Callbacks -----------------------------------------------------
+
+    def add_callback(self, name: str, config: CallbackConfig) -> None:
+        self._upsert(
+            "callbacks", name, config,
+            require_absent=True,
+            in_memory_target=settings.callbacks,
+            verb="added",
+        )
+
+    def update_callback(self, name: str, config: CallbackConfig) -> None:
+        self._upsert(
+            "callbacks", name, config,
+            require_present=True,
+            in_memory_target=settings.callbacks,
+            verb="updated",
+        )
+
+    def delete_callback(self, name: str) -> None:
+        self._delete("callbacks", name, in_memory_target=settings.callbacks)
+
+    # --- Media folders -------------------------------------------------
+
+    def add_media_folder(self, folder_id: str, config: MediaFolderConfig) -> None:
+        self._upsert(
+            "media_folders", folder_id, config,
+            require_absent=True,
+            in_memory_target=settings.media_folders,
+            verb="added",
+        )
+
+    def update_media_folder(self, folder_id: str, config: MediaFolderConfig) -> None:
+        self._upsert(
+            "media_folders", folder_id, config,
+            require_present=True,
+            in_memory_target=settings.media_folders,
+            verb="updated",
+        )
+
+    def delete_media_folder(self, folder_id: str) -> None:
+        self._delete("media_folders", folder_id, in_memory_target=settings.media_folders)
+
+    # --- Links ---------------------------------------------------------
+
+    def add_link(self, name: str, config: LinkConfig) -> None:
+        self._upsert(
+            "links", name, config,
+            require_absent=True,
+            in_memory_target=settings.links,
+            verb="added",
+        )
+
+    def update_link(self, name: str, config: LinkConfig) -> None:
+        self._upsert(
+            "links", name, config,
+            require_present=True,
+            in_memory_target=settings.links,
+            verb="updated",
+        )
+
+    def delete_link(self, name: str) -> None:
+        self._delete("links", name, in_memory_target=settings.links)
+
+    # --- Top-level settings --------------------------------------------
+
+    def set_setting(self, key: str, value: Any) -> None:
+        """Set a top-level config setting and persist to YAML."""
+        with self._lock:
+            data = self._load()
+            if value is None:
+                data.pop(key, None)
+            else:
+                data[key] = value
+            self._save(data)
+            if hasattr(settings, key):
+                setattr(settings, key, value)
+            logger.info("Setting '%s' updated to: %s", key, value)
+
+
+config_manager = ConfigManager()

media_server/main.py

@@ -2,50 +2,259 @@
 
 import argparse
 import logging
+import socket
 import sys
 from contextlib import asynccontextmanager
 from pathlib import Path
 
 import uvicorn
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
 from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 
 from . import __version__
-from .config import settings, generate_default_config, get_config_dir
-from .routes import audio_router, health_router, media_router, scripts_router
+from .auth import get_token_label, request_id_var, token_label_var
+from .config import generate_default_config, get_config_dir, settings
+from .routes import (
+    audio_router,
+    browser_router,
+    callbacks_router,
+    display_router,
+    foreground_router,
+    health_router,
+    links_router,
+    media_router,
+    scripts_router,
+)
 from .services import get_media_controller
 from .services.websocket_manager import ws_manager
 
 
+class TokenLabelFilter(logging.Filter):
+    """Add token label + request_id to log records."""
+
+    def filter(self, record):
+        record.token_label = token_label_var.get("unknown")
+        record.request_id = request_id_var.get("-")
+        return True
+
+
+class _StripTokenQueryFilter(logging.Filter):
+    """Strip `token=...` from query strings before they hit the access log.
+
+    uvicorn's default access log format includes the full request line, so
+    `/api/media/artwork?token=SECRET` would otherwise be persisted verbatim
+    in stdout/journald/file sinks.
+    """
+
+    import re as _re
+
+    _TOKEN_RE = _re.compile(r"([?&])token=[^&\s\"']+")
+
+    def filter(self, record):  # type: ignore[override]
+        if isinstance(record.args, tuple):
+            record.args = tuple(
+                self._TOKEN_RE.sub(r"\1token=REDACTED", a) if isinstance(a, str) else a
+                for a in record.args
+            )
+        if isinstance(record.msg, str) and "token=" in record.msg:
+            record.msg = self._TOKEN_RE.sub(r"\1token=REDACTED", record.msg)
+        return True
+
+
 def setup_logging():
-    """Configure application logging."""
+    """Configure application logging with token labels."""
+    # Create filter and handler
+    token_filter = TokenLabelFilter()
+    handler = logging.StreamHandler(sys.stdout)
+    handler.addFilter(token_filter)
+
     logging.basicConfig(
         level=getattr(logging, settings.log_level.upper()),
-        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-        handlers=[logging.StreamHandler(sys.stdout)],
+        format=(
+            "%(asctime)s - %(name)s - [%(token_label)s] [%(request_id)s]"
+            " - %(levelname)s - %(message)s"
+        ),
+        handlers=[handler],
     )
 
+    # Suppress noisy third-party loggers
+    logging.getLogger("screen_brightness_control").setLevel(logging.ERROR)
+
+    # Make sure the uvicorn access log never persists tokens leaked into the
+    # query string (the artwork + WS endpoints accept `?token=` for browser
+    # compatibility — see verify_token_or_query).
+    strip_filter = _StripTokenQueryFilter()
+    for name in ("uvicorn.access", "uvicorn"):
+        logging.getLogger(name).addFilter(strip_filter)
+
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    """Application lifespan handler."""
+    """Application lifespan handler.
+
+    All long-lived resources started during startup are kept in local refs and
+    torn down in a `finally:` so a partial-startup failure cannot orphan tasks
+    or thread pools.
+    """
+    import asyncio
+
     setup_logging()
     logger = logging.getLogger(__name__)
     logger.info(f"Media Server starting on {settings.host}:{settings.port}")
-    logger.info(f"API Token: {settings.api_token[:8]}...")
 
-    # Start WebSocket status monitor
-    controller = get_media_controller()
-    await ws_manager.start_status_monitor(controller.get_status)
-    logger.info("WebSocket status monitor started")
+    # Log authentication status — never log full or partial token material.
+    if settings.api_tokens:
+        labels = ", ".join(settings.api_tokens.keys())
+        logger.info(f"Authentication enabled. Tokens configured: [{labels}]")
+    else:
+        logger.warning("No API tokens configured — authentication is DISABLED")
 
-    yield
+    # Linux preflight: most MPRIS / PulseAudio failures are environmental
+    # (no DBUS_SESSION_BUS_ADDRESS, missing XDG_RUNTIME_DIR, systemd service
+    # started before logind). Surface that early so the failure mode is a
+    # warning at boot instead of silent "/api/media/status returns idle".
+    import os
+    import platform as _platform
+    if _platform.system() == "Linux":
+        missing = [
+            v for v in ("DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR")
+            if not os.environ.get(v)
+        ]
+        if missing:
+            logger.warning(
+                "Linux preflight: %s not set — MPRIS / PulseAudio may be unavailable."
+                " Under systemd, run `loginctl enable-linger <user>` and ensure the"
+                " service unit sets DBUS_SESSION_BUS_ADDRESS + XDG_RUNTIME_DIR.",
+                ", ".join(missing),
+            )
+        if os.environ.get("WAYLAND_DISPLAY"):
+            logger.info(
+                "Wayland session detected — foreground-window probe is intentionally"
+                " disabled (Wayland hides window info from unprivileged clients)."
+            )
 
-    # Stop WebSocket status monitor
-    await ws_manager.stop_status_monitor()
-    logger.info("Media Server shutting down")
+    update_checker = None
+    cleanup_task: asyncio.Task | None = None
+    analyzer = None
+    status_monitor_started = False
+
+    try:
+        # Start WebSocket status monitor
+        controller = get_media_controller()
+        await ws_manager.start_status_monitor(controller.get_status)
+        status_monitor_started = True
+        logger.info("WebSocket status monitor started")
+
+        # Start update checker
+        if settings.update_check_enabled:
+            from .services.gitea_release_provider import GiteaReleaseProvider
+            from .services.update_checker import UpdateChecker
+
+            provider = GiteaReleaseProvider()
+            update_checker = UpdateChecker(provider, __version__)
+            await update_checker.start(settings.update_check_interval)
+            # Store globally so health endpoint can access cached result
+            app.state.update_checker = update_checker
+
+        # Schedule periodic thumbnail cache cleanup so the 500 MB cap is actually
+        # enforced. Runs once at startup and then hourly until shutdown.
+        from .services.thumbnail_service import ThumbnailService
+
+        async def _thumbnail_cleanup_loop() -> None:
+            while True:
+                try:
+                    await asyncio.to_thread(ThumbnailService.cleanup_cache)
+                except Exception as e:
+                    logger.warning("Thumbnail cache cleanup failed: %s", e)
+                try:
+                    await asyncio.sleep(3600)
+                except asyncio.CancelledError:
+                    break
+
+        cleanup_task = asyncio.create_task(_thumbnail_cleanup_loop())
+
+        # Register audio visualizer (capture starts on-demand when clients subscribe)
+        if settings.visualizer_enabled:
+            from .services.audio_analyzer import get_audio_analyzer
+
+            analyzer = get_audio_analyzer(
+                num_bins=settings.visualizer_bins,
+                target_fps=settings.visualizer_fps,
+                device_name=settings.visualizer_device,
+            )
+            if analyzer.available:
+                await ws_manager.start_audio_monitor(analyzer)
+                logger.info("Audio visualizer available (capture on-demand)")
+            else:
+                logger.info("Audio visualizer unavailable (install soundcard + numpy)")
+
+        yield
+    finally:
+        # Stop update checker
+        if update_checker is not None:
+            try:
+                await update_checker.stop()
+            except Exception:
+                logger.exception("Error stopping update checker")
+
+        # Cancel periodic thumbnail cleanup
+        if cleanup_task is not None:
+            cleanup_task.cancel()
+            try:
+                await cleanup_task
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                logger.exception("Error awaiting thumbnail cleanup task")
+
+        # Stop audio visualizer
+        try:
+            await ws_manager.stop_audio_monitor()
+        except Exception:
+            logger.exception("Error stopping audio monitor")
+        if analyzer and analyzer.running:
+            try:
+                analyzer.stop()
+            except Exception:
+                logger.exception("Error stopping audio analyzer")
+
+        # Stop WebSocket status monitor
+        if status_monitor_started:
+            try:
+                await ws_manager.stop_status_monitor()
+            except Exception:
+                logger.exception("Error stopping status monitor")
+
+        # Shut down dedicated thread pools so pending scripts don't leak threads
+        try:
+            from .routes.callbacks import shutdown_callback_executor
+            from .routes.scripts import shutdown_script_executor
+
+            shutdown_script_executor()
+            shutdown_callback_executor()
+        except Exception:
+            logger.exception("Error shutting down script/callback executors")
+
+        # Flush audit log writer
+        try:
+            from .services.audit_log import shutdown_audit_log
+            shutdown_audit_log()
+        except Exception:
+            logger.exception("Error flushing audit log")
+
+        # Clean up platform-specific resources
+        import platform as _platform
+        if _platform.system() == "Windows":
+            try:
+                from .services.windows_media import shutdown_executor
+                shutdown_executor()
+            except Exception:
+                logger.exception("Error shutting down windows_media executor")
+
+        logger.info("Media Server shutting down")
 
 
 def create_app() -> FastAPI:
@@ -57,30 +266,168 @@ def create_app() -> FastAPI:
         lifespan=lifespan,
     )
 
-    # Add CORS middleware for cross-origin requests
+    # Compress responses > 1KB
+    app.add_middleware(GZipMiddleware, minimum_size=1000)
+
+    # CORS — restrict to same-origin by default; users that integrate the API
+    # from another origin (e.g. Home Assistant on a different host) can set
+    # cors_origins in config.yaml. Refuse "*" outright: combined with the
+    # admin endpoints this would let any origin in the universe run
+    # arbitrary shell. If users genuinely need every origin, they can list
+    # them explicitly.
+    if any(o.strip() == "*" for o in settings.cors_origins):
+        raise RuntimeError(
+            "cors_origins must not contain '*' — list exact origins instead. "
+            "This protects the script-execution endpoints from any-origin abuse."
+        )
+    cors_origins = settings.cors_origins or [
+        f"http://localhost:{settings.port}",
+        f"http://127.0.0.1:{settings.port}",
+    ]
     app.add_middleware(
         CORSMiddleware,
-        allow_origins=["*"],
-        allow_credentials=True,
-        allow_methods=["*"],
-        allow_headers=["*"],
+        allow_origins=cors_origins,
+        allow_credentials=False,
+        allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+        allow_headers=["Authorization", "Content-Type"],
     )
 
+    # Request correlation ID — accept upstream X-Request-ID if it's a sane
+    # ASCII id, otherwise mint a fresh UUID4. Emitted on the response so
+    # clients can quote it back in bug reports.
+    import re
+    import uuid as _uuid
+
+    _REQ_ID_RE = re.compile(r"^[A-Za-z0-9._\-]{1,128}$")
+
+    @app.middleware("http")
+    async def request_id_middleware(request: Request, call_next):
+        incoming = request.headers.get("x-request-id", "")
+        req_id = incoming if _REQ_ID_RE.match(incoming) else _uuid.uuid4().hex[:16]
+        request_id_var.set(req_id)
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = req_id
+        return response
+
+    # Security headers — strict CSP for the bundled UI, disallow framing, hide referrer.
+    @app.middleware("http")
+    async def security_headers_middleware(request: Request, call_next):
+        response = await call_next(request)
+        response.headers.setdefault(
+            "Content-Security-Policy",
+            (
+                "default-src 'self'; "
+                "img-src 'self' data: blob: https://api.iconify.design; "
+                "connect-src 'self' https://api.iconify.design ws: wss:; "
+                "script-src 'self'; "
+                "style-src 'self' 'unsafe-inline'; "
+                "font-src 'self' data:; "
+                "frame-ancestors 'none'; "
+                "form-action 'self'; "
+                "worker-src 'self'; "
+                "manifest-src 'self'; "
+                "base-uri 'self'"
+            ),
+        )
+        response.headers.setdefault("X-Frame-Options", "DENY")
+        response.headers.setdefault("X-Content-Type-Options", "nosniff")
+        response.headers.setdefault("Referrer-Policy", "no-referrer")
+        return response
+
+    # Add token logging middleware + auth-failure rate limit
+    from fastapi.responses import JSONResponse
+
+    from .services.rate_limit import check as ratelimit_check
+    from .services.rate_limit import get_peer
+
+    @app.middleware("http")
+    async def token_logging_middleware(request: Request, call_next):
+        """Extract token label, set in context, and rate-limit failed auths."""
+        if not settings.api_tokens:
+            token_label_var.set("anonymous")
+        else:
+            token_label = "unknown"
+            token_present = False
+            token_valid = False
+
+            # Try Authorization header
+            auth_header = request.headers.get("authorization", "")
+            if auth_header.startswith("Bearer "):
+                token_present = True
+                token = auth_header[7:]
+                label = get_token_label(token)
+                if label:
+                    token_label = label
+                    token_valid = True
+
+            # Try query parameter (for artwork endpoint)
+            elif "token" in request.query_params:
+                token_present = True
+                token = request.query_params["token"]
+                label = get_token_label(token)
+                if label:
+                    token_label = label
+                    token_valid = True
+
+            token_label_var.set(token_label)
+
+            # Brute-force gate: a peer that produces a wrong/missing token gets
+            # 5 failures per minute before being throttled. Static-asset
+            # requests (GET /static/*, /, /sw.js) and the docs endpoint are
+            # exempt — they're served unauthenticated by design.
+            if token_present and not token_valid:
+                path = request.url.path
+                if not (
+                    path == "/" or path == "/sw.js"
+                    or path.startswith("/static/")
+                    or path.startswith("/docs") or path.startswith("/openapi")
+                    or path.startswith("/redoc")
+                ):
+                    allowed, retry_after = ratelimit_check("auth", get_peer(request))
+                    if not allowed:
+                        return JSONResponse(
+                            status_code=429,
+                            content={"detail": "Too many authentication failures"},
+                            headers={"Retry-After": str(int(retry_after or 60))},
+                        )
+
+        response = await call_next(request)
+        return response
+
     # Register routers
     app.include_router(audio_router)
+    app.include_router(browser_router)
+    app.include_router(callbacks_router)
+    app.include_router(display_router)
+    app.include_router(foreground_router)
     app.include_router(health_router)
+    app.include_router(links_router)
     app.include_router(media_router)
     app.include_router(scripts_router)
 
     # Mount static files and serve UI at root
     static_dir = Path(__file__).parent / "static"
     if static_dir.exists():
+        @app.get("/sw.js", include_in_schema=False)
+        async def serve_service_worker():
+            """Serve service worker from root scope for PWA installability."""
+            return FileResponse(
+                static_dir / "sw.js",
+                media_type="application/javascript",
+                headers={"Cache-Control": "no-cache"},
+            )
+
         app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
 
         @app.get("/", include_in_schema=False)
         async def serve_ui():
             """Serve the Web UI."""
             return FileResponse(static_dir / "index.html")
+    else:
+        logging.getLogger(__name__).warning(
+            "static_dir not found at %s — Web UI disabled (API only)",
+            static_dir,
+        )
 
     return app
 
@@ -112,26 +459,153 @@ def main():
         action="store_true",
         help="Show the current API token and exit",
     )
+    parser.add_argument(
+        "--no-tray",
+        action="store_true",
+        help="Disable system tray icon (for headless/service mode)",
+    )
 
     args = parser.parse_args()
 
     if args.generate_config:
         config_path = generate_default_config()
         print(f"Configuration file generated at: {config_path}")
-        print(f"API Token has been saved to the config file.")
+        print("A random API token was generated under api_tokens.default.")
+        print("Run `python -m media_server.main --show-token` to view it.")
         return
 
     if args.show_token:
-        print(f"API Token: {settings.api_token}")
         print(f"Config directory: {get_config_dir()}")
+        if settings.api_tokens:
+            print("\nAPI Tokens:")
+            for label, spec in settings.api_tokens.items():
+                scope_str = ",".join(spec.scopes)
+                print(f"  {label:20} {spec.token}  [scopes: {scope_str}]")
+        else:
+            print("\nAuthentication is DISABLED (no tokens configured)")
         return
 
-    uvicorn.run(
-        "media_server.main:app",
-        host=args.host,
-        port=args.port,
-        reload=False,
-    )
+    # Stderr is invisible when launched via wscript / pythonw (Start Menu shortcut,
+    # autostart). Mirror pre-uvicorn failures to a file in the config dir so the
+    # next silent boot failure is diagnosable.
+    def _fatal(msg: str, exit_code: int = 1) -> None:
+        print(msg, file=sys.stderr)
+        try:
+            log_path = get_config_dir() / "startup-errors.log"
+            from datetime import datetime
+            with open(log_path, "a", encoding="utf-8") as f:
+                f.write(f"[{datetime.now().isoformat(timespec='seconds')}] {msg}\n")
+        except OSError:
+            pass
+        sys.exit(exit_code)
+
+    # First-run bootstrap: if no config has ever been written, generate one
+    # with a random token instead of starting in the insecure "no-auth" mode.
+    config_path = get_config_dir() / "config.yaml"
+    if not config_path.exists() and not settings.api_tokens:
+        try:
+            generate_default_config(config_path)
+            _fatal(
+                f"\nFirst run: generated default config at {config_path}.\n"
+                "Run --show-token to retrieve the API token, then restart.",
+                exit_code=0,
+            )
+        except OSError as e:
+            print(f"WARNING: could not bootstrap config: {e}", file=sys.stderr)
+
+    # Refuse to bind a non-loopback address with no tokens, unless explicitly opted in.
+    non_loopback = args.host not in ("127.0.0.1", "localhost", "::1")
+    if non_loopback and not settings.api_tokens and not settings.allow_lan_without_auth:
+        _fatal(
+            "ERROR: refusing to bind a non-loopback address with no api_tokens configured.\n"
+            "Either set api_tokens in config.yaml, bind to 127.0.0.1,"
+            " or set allow_lan_without_auth: true in config.yaml to override."
+        )
+
+    # Check if port is available before starting
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        try:
+            sock.bind((args.host if args.host != "0.0.0.0" else "127.0.0.1", args.port))
+        except OSError:
+            _fatal(
+                f"ERROR: Port {args.port} is already in use. "
+                f"Another instance of Media Server may be running.\n"
+                f"Stop the other process or use --port to pick a different port."
+            )
+
+    from .tray import PYSTRAY_AVAILABLE, TrayManager
+
+    use_tray = PYSTRAY_AVAILABLE and not args.no_tray
+
+    # Validate TLS pair consistency before either path so we don't fail late.
+    if bool(settings.ssl_certfile) ^ bool(settings.ssl_keyfile):
+        _fatal(
+            "ERROR: ssl_certfile and ssl_keyfile must both be set, or both unset."
+        )
+
+    def _uvicorn_kwargs() -> dict:
+        kw: dict = {
+            "host": args.host,
+            "port": args.port,
+            "log_level": settings.log_level.lower(),
+            "proxy_headers": settings.proxy_headers,
+            "forwarded_allow_ips": settings.forwarded_allow_ips,
+        }
+        if settings.ssl_certfile and settings.ssl_keyfile:
+            kw["ssl_certfile"] = settings.ssl_certfile
+            kw["ssl_keyfile"] = settings.ssl_keyfile
+            if settings.ssl_keyfile_password:
+                kw["ssl_keyfile_password"] = settings.ssl_keyfile_password
+        return kw
+
+    if use_tray:
+        import asyncio
+        import threading
+
+        # Run uvicorn in a background thread so tray owns the main thread message loop
+        uv_config = uvicorn.Config(
+            "media_server.main:app",
+            **_uvicorn_kwargs(),
+        )
+        server = uvicorn.Server(uv_config)
+
+        def run_server():
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            loop.run_until_complete(server.serve())
+
+        server_thread = threading.Thread(target=run_server, daemon=True)
+        server_thread.start()
+
+        # Tray on main thread (blocking)
+        tray = TrayManager(
+            port=args.port,
+            on_exit=lambda: setattr(server, "should_exit", True),
+        )
+        tray.run()
+
+        # Tray exited — wait for server to finish graceful shutdown
+        server_thread.join(timeout=10)
+
+        if tray.restart_requested:
+            import subprocess
+
+            # Always restart via `python -m media_server.main` — this works
+            # regardless of how we were originally started (console_script,
+            # python -m, or direct script invocation).
+            cmd = [sys.executable, "-m", "media_server.main"]
+
+            subprocess.Popen(
+                cmd,
+                cwd=Path.cwd(),
+                start_new_session=True,
+            )
+    else:
+        uvicorn.run(
+            "media_server.main:app",
+            reload=False,
+            **_uvicorn_kwargs(),
+        )
 
 
 if __name__ == "__main__":

media_server/models/__init__.py

@@ -1,11 +1,11 @@
 """Pydantic models for the media server API."""
 
 from .media import (
+    MediaInfo,
     MediaState,
     MediaStatus,
-    VolumeRequest,
     SeekRequest,
-    MediaInfo,
+    VolumeRequest,
 )
 
 __all__ = [

media_server/routes/__init__.py

@@ -1,8 +1,23 @@
 """API route modules."""
 
 from .audio import router as audio_router
+from .browser import router as browser_router
+from .callbacks import router as callbacks_router
+from .display import router as display_router
+from .foreground import router as foreground_router
 from .health import router as health_router
+from .links import router as links_router
 from .media import router as media_router
 from .scripts import router as scripts_router
 
-__all__ = ["audio_router", "health_router", "media_router", "scripts_router"]
+__all__ = [
+    "audio_router",
+    "browser_router",
+    "callbacks_router",
+    "display_router",
+    "foreground_router",
+    "health_router",
+    "links_router",
+    "media_router",
+    "scripts_router",
+]

media_server/routes/audio.py

@@ -0,0 +1,28 @@
+"""Audio device API endpoints."""
+
+import logging
+
+from fastapi import APIRouter, Depends
+
+from ..auth import verify_token
+from ..services import get_audio_devices
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/audio", tags=["audio"])
+
+
+@router.get("/devices")
+async def list_audio_devices(_: str = Depends(verify_token)) -> list[dict[str, str]]:
+    """List available audio output devices.
+
+    Returns a list of audio devices with their IDs and friendly names.
+    Use the device name in the `audio_device` config option to control
+    a specific device instead of the default one.
+
+    Returns:
+        List of audio devices with id and name
+    """
+    devices = get_audio_devices()
+    logger.debug("Found %d audio devices", len(devices))
+    return devices

media_server/routes/browser.py

@@ -0,0 +1,611 @@
+"""Browser API routes for media file browsing."""
+
+import asyncio
+import logging
+import tempfile
+from pathlib import Path
+from urllib.parse import unquote
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, Field
+
+from ..auth import verify_token, verify_token_or_query
+from ..config import MediaFolderConfig, settings
+from ..config_manager import config_manager
+from ..services import get_media_controller
+from ..services.browser_service import BrowserService
+from ..services.metadata_service import MetadataService
+from ..services.thumbnail_service import ThumbnailService
+from ..services.websocket_manager import ws_manager
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/browser", tags=["browser"])
+
+# Strong refs to background tasks so they don't get garbage-collected mid-flight.
+_background_tasks: set[asyncio.Task] = set()
+
+
+def _spawn_background(coro) -> asyncio.Task:
+    """Schedule a background coroutine and keep a strong ref to its Task."""
+    task = asyncio.create_task(coro)
+    _background_tasks.add(task)
+    task.add_done_callback(_background_tasks.discard)
+    return task
+
+
+def _require_folder_management() -> None:
+    """Raise 403 if media folder management is disabled OR caller lacks admin scope."""
+    if not settings.media_folders_management:
+        raise HTTPException(
+            status_code=403,
+            detail="Media folder management is disabled. Set media_folders_management: true in config.yaml to enable.",
+        )
+    from ..auth import auth_enabled, token_has_scope, token_label_var
+    if auth_enabled():
+        label = token_label_var.get("unknown")
+        if not token_has_scope(label, "admin"):
+            raise HTTPException(
+                status_code=403,
+                detail=f"Token '{label}' lacks required scope: admin",
+            )
+
+
+async def _broadcast_after_open(controller, label: str, max_wait: float = 2.0) -> None:
+    """Poll until media session registers, then broadcast status update.
+
+    Fires as a background task so the HTTP response returns immediately.
+    """
+    status = None
+    try:
+        interval = 0.3
+        elapsed = 0.0
+        while elapsed < max_wait:
+            await asyncio.sleep(interval)
+            elapsed += interval
+            try:
+                status = await controller.get_status()
+            except Exception as poll_err:  # noqa: BLE001 — broadcast is best-effort
+                logger.debug("get_status during broadcast poll failed: %s", poll_err)
+                continue
+            if status.state in ("playing", "paused"):
+                break
+
+        if status is None:
+            return
+        status_dict = status.model_dump()
+        await ws_manager.broadcast({"type": "status", "data": status_dict})
+        logger.info(f"Broadcasted status update after opening: {label}")
+    except Exception as e:
+        logger.warning(f"Failed to broadcast status after opening {label}: {e}")
+
+
+# Request/Response Models
+class FolderCreateRequest(BaseModel):
+    """Request model for creating a media folder."""
+
+    folder_id: str = Field(..., description="Unique folder ID")
+    label: str = Field(..., description="Display label")
+    path: str = Field(..., description="Absolute path to media folder")
+    enabled: bool = Field(default=True, description="Whether folder is enabled")
+
+
+class FolderUpdateRequest(BaseModel):
+    """Request model for updating a media folder."""
+
+    label: str = Field(..., description="Display label")
+    path: str = Field(..., description="Absolute path to media folder")
+    enabled: bool = Field(default=True, description="Whether folder is enabled")
+
+
+class PlayRequest(BaseModel):
+    """Request model for playing a media file.
+
+    Both ``folder_id`` and ``path`` are required so the server can validate
+    the file lives inside a configured media folder.
+    """
+
+    folder_id: str = Field(..., description="Media folder ID")
+    path: str = Field(..., description="Path relative to folder root")
+
+
+class PlayFolderRequest(BaseModel):
+    """Request model for playing all media files in a folder."""
+
+    folder_id: str = Field(..., description="Media folder ID")
+    path: str = Field(default="", description="Path relative to folder root")
+
+
+# Folder Management Endpoints
+@router.get("/folders")
+async def list_folders(_: str = Depends(verify_token)):
+    """List all configured media folders.
+
+    Returns:
+        Dictionary with folder configurations and management flag.
+    """
+    folders = {}
+    for folder_id, config in settings.media_folders.items():
+        folder_path = Path(config.path)
+        folders[folder_id] = {
+            "id": folder_id,
+            "label": config.label,
+            "path": config.path,
+            "enabled": config.enabled,
+            "available": folder_path.is_dir(),
+        }
+    return {
+        "folders": folders,
+        "management_enabled": settings.media_folders_management,
+    }
+
+
+@router.post("/folders/create")
+async def create_folder(
+    request: FolderCreateRequest,
+    _: str = Depends(verify_token),
+):
+    """Create a new media folder configuration.
+
+    Args:
+        request: Folder creation request.
+
+    Returns:
+        Success message.
+
+    Raises:
+        HTTPException: If folder already exists or validation fails.
+    """
+    _require_folder_management()
+    try:
+        # Validate folder_id format (alphanumeric and underscore only).
+        # Same constraint is enforced when validating paths so traversal can't
+        # be smuggled through the ID itself.
+        if not request.folder_id or not request.folder_id.replace("_", "").isalnum():
+            raise HTTPException(
+                status_code=400,
+                detail="Folder ID must contain only alphanumeric characters and underscores",
+            )
+
+        # Validate path exists
+        path = Path(request.path)
+        if not path.exists():
+            raise HTTPException(status_code=400, detail=f"Path does not exist: {request.path}")
+        if not path.is_dir():
+            raise HTTPException(status_code=400, detail=f"Path is not a directory: {request.path}")
+
+        # Create config
+        config = MediaFolderConfig(
+            path=request.path,
+            label=request.label,
+            enabled=request.enabled,
+        )
+
+        # Add to config manager
+        config_manager.add_media_folder(request.folder_id, config)
+
+        return {
+            "success": True,
+            "message": f"Media folder '{request.folder_id}' created successfully",
+        }
+
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error creating media folder: {e}")
+        raise HTTPException(status_code=500, detail="Failed to create media folder")
+
+
+@router.put("/folders/update/{folder_id}")
+async def update_folder(
+    folder_id: str,
+    request: FolderUpdateRequest,
+    _: str = Depends(verify_token),
+):
+    """Update an existing media folder configuration.
+
+    Args:
+        folder_id: ID of the folder to update.
+        request: Folder update request.
+
+    Returns:
+        Success message.
+
+    Raises:
+        HTTPException: If folder doesn't exist or validation fails.
+    """
+    _require_folder_management()
+    try:
+        # Validate path exists
+        path = Path(request.path)
+        if not path.exists():
+            raise HTTPException(status_code=400, detail=f"Path does not exist: {request.path}")
+        if not path.is_dir():
+            raise HTTPException(status_code=400, detail=f"Path is not a directory: {request.path}")
+
+        # Create config
+        config = MediaFolderConfig(
+            path=request.path,
+            label=request.label,
+            enabled=request.enabled,
+        )
+
+        # Update config manager
+        config_manager.update_media_folder(folder_id, config)
+
+        return {
+            "success": True,
+            "message": f"Media folder '{folder_id}' updated successfully",
+        }
+
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error updating media folder: {e}")
+        raise HTTPException(status_code=500, detail="Failed to update media folder")
+
+
+@router.delete("/folders/delete/{folder_id}")
+async def delete_folder(
+    folder_id: str,
+    _: str = Depends(verify_token),
+):
+    """Delete a media folder configuration.
+
+    Args:
+        folder_id: ID of the folder to delete.
+
+    Returns:
+        Success message.
+
+    Raises:
+        HTTPException: If folder doesn't exist.
+    """
+    _require_folder_management()
+    try:
+        config_manager.delete_media_folder(folder_id)
+
+        return {
+            "success": True,
+            "message": f"Media folder '{folder_id}' deleted successfully",
+        }
+
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error deleting media folder: {e}")
+        raise HTTPException(status_code=500, detail="Failed to delete media folder")
+
+
+# Browse Endpoints
+@router.get("/browse")
+async def browse(
+    folder_id: str = Query(..., description="Media folder ID"),
+    path: str = Query(default="", description="Path relative to folder root"),
+    offset: int = Query(default=0, ge=0, description="Pagination offset"),
+    limit: int = Query(default=100, ge=1, le=1000, description="Pagination limit"),
+    nocache: bool = Query(default=False, description="Bypass directory cache"),
+    _: str = Depends(verify_token),
+):
+    """Browse a directory and list files/folders.
+
+    Args:
+        folder_id: ID of the media folder.
+        path: Path to browse (URL-encoded, relative to folder root).
+        offset: Pagination offset.
+        limit: Maximum items to return.
+
+    Returns:
+        Directory listing with items and metadata.
+
+    Raises:
+        HTTPException: If path validation fails or directory not accessible.
+    """
+    try:
+        # URL decode the path
+        decoded_path = unquote(path)
+
+        # Browse directory in a thread — iterdir() + stat() can block on
+        # network shares for many seconds; never run on the event loop.
+        result = await asyncio.to_thread(
+            BrowserService.browse_directory,
+            folder_id,
+            decoded_path,
+            offset,
+            limit,
+            nocache,
+        )
+
+        return result
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except (OSError, PermissionError) as e:
+        # Network share unavailable or access denied
+        logger.warning(f"Folder temporarily unavailable: {e}")
+        raise HTTPException(
+            status_code=503,
+            detail="Folder is temporarily unavailable. It may be a network share that is not accessible at the moment."
+        )
+    except Exception as e:
+        logger.error(f"Error browsing directory (type: {type(e).__name__}): {e}")
+        raise HTTPException(status_code=500, detail="Failed to browse directory")
+
+
+# Metadata Endpoint
+@router.get("/metadata")
+async def get_metadata(
+    folder_id: str = Query(..., description="Media folder ID"),
+    path: str = Query(..., description="Path relative to folder root (URL-encoded)"),
+    _: str = Depends(verify_token),
+):
+    """Get metadata for a media file inside a configured media folder.
+
+    Args:
+        folder_id: ID of the media folder.
+        path: Path relative to folder root (URL-encoded).
+
+    Returns:
+        Media file metadata.
+    """
+    try:
+        decoded_path = unquote(path)
+        file_path = BrowserService.validate_path(folder_id, decoded_path)
+
+        if not file_path.is_file():
+            raise HTTPException(status_code=400, detail="Path is not a file")
+        if not BrowserService.is_media_file(file_path):
+            raise HTTPException(status_code=400, detail="File is not a media file")
+
+        loop = asyncio.get_running_loop()
+        metadata = await loop.run_in_executor(
+            None,
+            MetadataService.extract_metadata,
+            file_path,
+        )
+        return metadata
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error extracting metadata: {e}")
+        raise HTTPException(status_code=500, detail="Failed to extract metadata")
+
+
+# Thumbnail Endpoint
+@router.get("/thumbnail")
+async def get_thumbnail(
+    folder_id: str = Query(..., description="Media folder ID"),
+    path: str = Query(..., description="Path relative to folder root (URL-encoded)"),
+    size: str = Query(default="medium", description='Thumbnail size: "small" or "medium"'),
+    _: str = Depends(verify_token),
+):
+    """Get thumbnail for a media file inside a configured media folder."""
+    try:
+        decoded_path = unquote(path)
+        file_path = BrowserService.validate_path(folder_id, decoded_path)
+
+        if not file_path.is_file():
+            raise HTTPException(status_code=400, detail="Path is not a file")
+        if not BrowserService.is_media_file(file_path):
+            raise HTTPException(status_code=400, detail="File is not a media file")
+
+        if size not in ("small", "medium"):
+            size = "medium"
+
+        thumbnail_data = await ThumbnailService.get_thumbnail(file_path, size)
+
+        if thumbnail_data is None:
+            return Response(status_code=204)
+
+        import hashlib
+        stat = file_path.stat()
+        etag_data = f"{file_path}:{stat.st_mtime}:{size}".encode()
+        etag = hashlib.md5(etag_data).hexdigest()
+
+        return Response(
+            content=thumbnail_data,
+            media_type="image/jpeg",
+            headers={
+                "ETag": f'"{etag}"',
+                "Cache-Control": "public, max-age=86400",
+            },
+        )
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error generating thumbnail: {e}")
+        raise HTTPException(status_code=500, detail="Failed to generate thumbnail")
+
+
+# Playback Endpoint
+@router.post("/play")
+async def play_file(
+    request: PlayRequest,
+    _: str = Depends(verify_token),
+):
+    """Open a media file with the default system player.
+
+    Requires both ``folder_id`` and a folder-relative ``path``; the resolved
+    file must live inside the configured media folder and be a recognized
+    media file. This prevents arbitrary OS-handler invocation (e.g.,
+    ``os.startfile`` on Windows ``.lnk``/UNC paths).
+    """
+    try:
+        decoded_path = unquote(request.path)
+        file_path = BrowserService.validate_path(request.folder_id, decoded_path)
+
+        if not file_path.is_file():
+            raise HTTPException(status_code=400, detail="Path is not a file")
+        if not BrowserService.is_media_file(file_path):
+            raise HTTPException(status_code=400, detail="File is not a media file")
+
+        controller = get_media_controller()
+        success = await controller.open_file(str(file_path))
+
+        if not success:
+            raise HTTPException(status_code=500, detail="Failed to open file")
+
+        _spawn_background(_broadcast_after_open(controller, file_path.name))
+
+        return {
+            "success": True,
+            "message": f"Playing {file_path.name}",
+        }
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error playing file: {e}")
+        raise HTTPException(status_code=500, detail="Failed to play file")
+
+
+# Play Folder Endpoint (M3U playlist)
+@router.post("/play-folder")
+async def play_folder(
+    request: PlayFolderRequest,
+    _: str = Depends(verify_token),
+):
+    """Play all media files in a folder by generating an M3U playlist.
+
+    Args:
+        request: Play folder request with folder_id and path.
+
+    Returns:
+        Success message with file count.
+
+    Raises:
+        HTTPException: If folder not found or playback fails.
+    """
+    try:
+        decoded_path = unquote(request.path)
+        full_path = BrowserService.validate_path(request.folder_id, decoded_path)
+
+        if not full_path.is_dir():
+            raise HTTPException(status_code=400, detail="Path is not a directory")
+
+        def _scan(directory: Path) -> list[Path]:
+            return sorted(
+                (
+                    f for f in directory.iterdir()
+                    if f.is_file() and BrowserService.is_media_file(f)
+                ),
+                key=lambda f: f.name.lower(),
+            )
+
+        media_files = await asyncio.to_thread(_scan, full_path)
+
+        if not media_files:
+            raise HTTPException(status_code=404, detail="No media files found in this folder")
+
+        # Generate M3U playlist with absolute paths and EXTINF entries.
+        # Use NamedTemporaryFile to get a fresh per-call path — prevents
+        # symlink-clobber races between concurrent /play-folder requests
+        # and any local user pre-creating a fixed temp filename.
+        lines = ["#EXTM3U"]
+        for f in media_files:
+            lines.append(f"#EXTINF:-1,{f.stem}")
+            lines.append(str(f))
+        m3u_content = ("\r\n".join(lines) + "\r\n").encode("utf-8-sig")
+
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            prefix=".media_server_playlist_",
+            suffix=".m3u",
+            delete=False,
+        ) as f:
+            f.write(m3u_content)
+            playlist_path = Path(f.name)
+
+        # Open playlist with default player
+        controller = get_media_controller()
+        success = await controller.open_file(playlist_path)
+
+        if not success:
+            raise HTTPException(status_code=500, detail="Failed to open playlist")
+
+        _spawn_background(
+            _broadcast_after_open(controller, f"playlist ({len(media_files)} files)")
+        )
+
+        return {
+            "success": True,
+            "message": f"Playing {len(media_files)} files",
+            "count": len(media_files),
+        }
+
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error playing folder: {e}")
+        raise HTTPException(status_code=500, detail="Failed to play folder")
+
+
+# Download Endpoint
+@router.get("/download")
+async def download_file(
+    folder_id: str = Query(..., description="Media folder ID"),
+    path: str = Query(..., description="File path relative to folder root (URL-encoded)"),
+    _: str = Depends(verify_token_or_query),
+):
+    """Download a media file.
+
+    Args:
+        folder_id: ID of the media folder.
+        path: Path to the file (URL-encoded, relative to folder root).
+
+    Returns:
+        File download response.
+
+    Raises:
+        HTTPException: If file not found or not a media file.
+    """
+    try:
+        decoded_path = unquote(path)
+        file_path = BrowserService.validate_path(folder_id, decoded_path)
+
+        if not file_path.is_file():
+            raise HTTPException(status_code=400, detail="Path is not a file")
+
+        if not BrowserService.is_media_file(file_path):
+            raise HTTPException(status_code=400, detail="File is not a media file")
+
+        return FileResponse(
+            path=file_path,
+            filename=file_path.name,
+            media_type="application/octet-stream",
+        )
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error downloading file: {e}")
+        raise HTTPException(status_code=500, detail="Failed to download file")

media_server/routes/callbacks.py

@@ -0,0 +1,411 @@
+"""Callback management API endpoints."""
+
+import asyncio
+import logging
+import subprocess
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from pydantic import BaseModel, Field
+
+from ..auth import verify_token
+from ..config import CallbackConfig, settings
+from ..config_manager import config_manager
+from ..services.rate_limit import check as ratelimit_check
+from ..services.rate_limit import get_peer
+
+router = APIRouter(prefix="/api/callbacks", tags=["callbacks"])
+logger = logging.getLogger(__name__)
+
+# Dedicated executor for callback/subprocess execution
+_callback_executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="callback")
+
+
+def shutdown_callback_executor() -> None:
+    """Shut down the callback executor cleanly on application teardown."""
+    _callback_executor.shutdown(wait=False, cancel_futures=True)
+
+
+def _require_callbacks_management() -> None:
+    """Authorise a callbacks-CRUD operation. Operator flag + per-token admin scope."""
+    if not settings.callbacks_management:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=(
+                "Callbacks management is disabled. Set callbacks_management: true"
+                " in config.yaml to enable."
+            ),
+        )
+    from ..auth import auth_enabled, token_has_scope, token_label_var
+    if auth_enabled():
+        label = token_label_var.get("unknown")
+        if not token_has_scope(label, "admin"):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Token '{label}' lacks required scope: admin",
+            )
+
+
+class CallbackInfo(BaseModel):
+    """Information about a configured callback."""
+
+    name: str
+    command: str
+    timeout: int
+    working_dir: str | None = None
+    shell: bool
+
+
+class CallbackCreateRequest(BaseModel):
+    """Request model for creating or updating a callback."""
+
+    command: str = Field(..., description="Command to execute", min_length=1)
+    timeout: int = Field(default=30, description="Execution timeout in seconds", ge=1, le=300)
+    working_dir: str | None = Field(default=None, description="Working directory")
+    shell: bool = Field(default=True, description="Run command in shell")
+
+
+class CallbackExecuteResponse(BaseModel):
+    """Response model for callback execution."""
+
+    success: bool
+    callback: str
+    exit_code: int | None = None
+    stdout: str = ""
+    stderr: str = ""
+    error: str | None = None
+    execution_time: float | None = None
+
+
+def _validate_callback_name(name: str) -> None:
+    """Validate callback name.
+
+    Args:
+        name: Callback name to validate.
+
+    Raises:
+        HTTPException: If name is invalid.
+    """
+    # All available callback events
+    valid_names = {
+        "on_play",
+        "on_pause",
+        "on_stop",
+        "on_next",
+        "on_previous",
+        "on_volume",
+        "on_mute",
+        "on_seek",
+        "on_turn_on",
+        "on_turn_off",
+        "on_toggle",
+    }
+
+    if name not in valid_names:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Callback name must be one of: {', '.join(sorted(valid_names))}",
+        )
+
+
+@router.get("/list")
+async def list_callbacks(_: str = Depends(verify_token)) -> list[CallbackInfo]:
+    """List all configured callbacks.
+
+    Returns:
+        List of configured callbacks.
+    """
+    return [
+        CallbackInfo(
+            name=name,
+            command=config.command,
+            timeout=config.timeout,
+            working_dir=config.working_dir,
+            shell=config.shell,
+        )
+        for name, config in settings.callbacks.items()
+    ]
+
+
+@router.post("/execute/{callback_name}")
+async def execute_callback(
+    callback_name: str,
+    http_request: Request,
+    _: str = Depends(verify_token),
+) -> CallbackExecuteResponse:
+    """Execute a callback for debugging purposes.
+
+    Args:
+        callback_name: Name of the callback to execute
+
+    Returns:
+        Execution result including stdout, stderr, and exit code
+    """
+    # Rate-limit callback execution per peer (10/min) — callbacks also run
+    # subprocesses and need the same protection as scripts.
+    allowed, retry_after = ratelimit_check("execute", get_peer(http_request))
+    if not allowed:
+        raise HTTPException(
+            status_code=429,
+            detail="Too many callback executions, slow down",
+            headers={"Retry-After": str(int(retry_after or 60))},
+        )
+
+    # Validate callback name
+    _validate_callback_name(callback_name)
+
+    # Check if callback exists
+    if callback_name not in settings.callbacks:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Callback '{callback_name}' not found. Use /api/callbacks/list to see configured callbacks.",
+        )
+
+    callback_config = settings.callbacks[callback_name]
+
+    logger.info(f"Executing callback for debugging: {callback_name}")
+
+    from ..services.audit_log import record_script_execution
+
+    try:
+        # Execute in dedicated thread pool to not block the default executor
+        loop = asyncio.get_running_loop()
+        result = await loop.run_in_executor(
+            _callback_executor,
+            lambda: _run_callback(
+                command=callback_config.command,
+                timeout=callback_config.timeout,
+                shell=callback_config.shell,
+                working_dir=callback_config.working_dir,
+            ),
+        )
+
+        record_script_execution(
+            kind="callback",
+            name=callback_name,
+            exit_code=result["exit_code"],
+            duration=result.get("execution_time"),
+            stdout=result.get("stdout"),
+            stderr=result.get("stderr"),
+        )
+
+        return CallbackExecuteResponse(
+            success=result["exit_code"] == 0,
+            callback=callback_name,
+            exit_code=result["exit_code"],
+            stdout=result["stdout"],
+            stderr=result["stderr"],
+            execution_time=result.get("execution_time"),
+        )
+
+    except Exception as e:
+        logger.error(f"Callback execution error: {e}")
+        record_script_execution(
+            kind="callback",
+            name=callback_name,
+            exit_code=None,
+            duration=None,
+            error=str(e),
+        )
+        return CallbackExecuteResponse(
+            success=False,
+            callback=callback_name,
+            error=str(e),
+        )
+
+
+def _run_callback(
+    command: str,
+    timeout: int,
+    shell: bool,
+    working_dir: str | None,
+) -> dict[str, Any]:
+    """Run a callback synchronously.
+
+    Args:
+        command: Command to execute
+        timeout: Timeout in seconds
+        shell: Whether to run in shell
+        working_dir: Working directory
+
+    Returns:
+        Dict with exit_code, stdout, stderr, execution_time
+    """
+    start_time = time.time()
+    popen_kwargs: dict[str, Any] = {}
+    if sys.platform == "win32":
+        popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        popen_kwargs["start_new_session"] = True
+    try:
+        result = subprocess.run(
+            command,
+            shell=shell,
+            cwd=working_dir,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            **popen_kwargs,
+        )
+        execution_time = time.time() - start_time
+        return {
+            "exit_code": result.returncode,
+            "stdout": result.stdout[:10000],  # Limit output size
+            "stderr": result.stderr[:10000],
+            "execution_time": execution_time,
+        }
+    except subprocess.TimeoutExpired:
+        execution_time = time.time() - start_time
+        return {
+            "exit_code": -1,
+            "stdout": "",
+            "stderr": f"Callback timed out after {timeout} seconds",
+            "execution_time": execution_time,
+        }
+    except Exception as e:
+        execution_time = time.time() - start_time
+        return {
+            "exit_code": -1,
+            "stdout": "",
+            "stderr": str(e),
+            "execution_time": execution_time,
+        }
+
+
+@router.post("/create/{callback_name}")
+async def create_callback(
+    callback_name: str,
+    request: CallbackCreateRequest,
+    _: str = Depends(verify_token),
+) -> dict[str, Any]:
+    """Create a new callback.
+
+    Args:
+        callback_name: Callback event name (on_turn_on, on_turn_off, on_toggle).
+        request: Callback configuration.
+
+    Returns:
+        Success response with callback name.
+
+    Raises:
+        HTTPException: If callback already exists or name is invalid.
+    """
+    _require_callbacks_management()
+    _validate_callback_name(callback_name)
+
+    # Check if callback already exists
+    if callback_name in settings.callbacks:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=(
+                f"Callback '{callback_name}' already exists."
+                f" Use PUT /api/callbacks/update/{callback_name} to update it."
+            ),
+        )
+
+    # Create callback config
+    callback_config = CallbackConfig(**request.model_dump())
+
+    # Add to config file and in-memory
+    try:
+        config_manager.add_callback(callback_name, callback_config)
+    except Exception as e:
+        logger.error(f"Failed to add callback '{callback_name}': {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to add callback: {str(e)}",
+        )
+
+    logger.info(f"Callback '{callback_name}' created successfully")
+    return {"success": True, "callback": callback_name}
+
+
+@router.put("/update/{callback_name}")
+async def update_callback(
+    callback_name: str,
+    request: CallbackCreateRequest,
+    _: str = Depends(verify_token),
+) -> dict[str, Any]:
+    """Update an existing callback.
+
+    Args:
+        callback_name: Callback event name.
+        request: Updated callback configuration.
+
+    Returns:
+        Success response with callback name.
+
+    Raises:
+        HTTPException: If callback does not exist.
+    """
+    _require_callbacks_management()
+    _validate_callback_name(callback_name)
+
+    # Check if callback exists
+    if callback_name not in settings.callbacks:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=(
+                f"Callback '{callback_name}' not found."
+                f" Use POST /api/callbacks/create/{callback_name} to create it."
+            ),
+        )
+
+    # Create updated callback config
+    callback_config = CallbackConfig(**request.model_dump())
+
+    # Update config file and in-memory
+    try:
+        config_manager.update_callback(callback_name, callback_config)
+    except Exception as e:
+        logger.error(f"Failed to update callback '{callback_name}': {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to update callback: {str(e)}",
+        )
+
+    logger.info(f"Callback '{callback_name}' updated successfully")
+    return {"success": True, "callback": callback_name}
+
+
+@router.delete("/delete/{callback_name}")
+async def delete_callback(
+    callback_name: str,
+    _: str = Depends(verify_token),
+) -> dict[str, Any]:
+    """Delete a callback.
+
+    Args:
+        callback_name: Callback event name.
+
+    Returns:
+        Success response with callback name.
+
+    Raises:
+        HTTPException: If callback does not exist.
+    """
+    _require_callbacks_management()
+    _validate_callback_name(callback_name)
+
+    # Check if callback exists
+    if callback_name not in settings.callbacks:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Callback '{callback_name}' not found",
+        )
+
+    # Delete from config file and in-memory
+    try:
+        config_manager.delete_callback(callback_name)
+    except Exception as e:
+        logger.error(f"Failed to delete callback '{callback_name}': {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to delete callback: {str(e)}",
+        )
+
+    logger.info(f"Callback '{callback_name}' deleted successfully")
+    return {"success": True, "callback": callback_name}

media_server/routes/display.py

@@ -0,0 +1,132 @@
+"""Display brightness, power, contrast, input-source, color-preset and picture-mode API."""
+
+import asyncio
+import logging
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel, Field
+
+from ..auth import verify_token
+from ..services.display_service import (
+    list_monitors,
+    set_brightness,
+    set_color_preset,
+    set_contrast,
+    set_input_source,
+    set_picture_mode,
+    set_power,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/display", tags=["display"])
+
+
+class BrightnessRequest(BaseModel):
+    brightness: int = Field(ge=0, le=100)
+
+
+class PowerRequest(BaseModel):
+    on: bool
+
+
+class ContrastRequest(BaseModel):
+    contrast: int = Field(ge=0, le=100)
+
+
+class InputSourceRequest(BaseModel):
+    source: str
+
+
+class ColorPresetRequest(BaseModel):
+    preset: str
+
+
+class PictureModeRequest(BaseModel):
+    code: int = Field(ge=0, le=255)
+
+
+# DDC/CI hardware writes open a per-monitor handle and can take seconds —
+# every public endpoint dispatches into a worker thread so the event loop
+# stays responsive.
+
+
+@router.get("/monitors")
+async def get_monitors(
+    refresh: bool = False,
+    rediscover: bool = False,
+    _: str = Depends(verify_token),
+) -> list[dict]:
+    """List all connected monitors with their reported DDC/CI capabilities."""
+    monitors = await asyncio.to_thread(
+        list_monitors, force_refresh=refresh, rediscover=rediscover
+    )
+    logger.debug("Found %d monitors", len(monitors))
+    return [m.to_dict() for m in monitors]
+
+
+@router.post("/brightness/{monitor_id}")
+async def set_monitor_brightness(
+    monitor_id: int, request: BrightnessRequest, _: str = Depends(verify_token)
+) -> dict:
+    """Set brightness for a specific monitor."""
+    success = await asyncio.to_thread(set_brightness, monitor_id, request.brightness)
+    if success:
+        logger.info("Set monitor %d brightness to %d", monitor_id, request.brightness)
+    return {"success": success}
+
+
+@router.post("/power/{monitor_id}")
+async def set_monitor_power(
+    monitor_id: int, request: PowerRequest, _: str = Depends(verify_token)
+) -> dict:
+    """Turn a monitor on or off."""
+    action = "on" if request.on else "off"
+    success = await asyncio.to_thread(set_power, monitor_id, request.on)
+    if success:
+        logger.info("Set monitor %d power %s", monitor_id, action)
+    return {"success": success}
+
+
+@router.post("/contrast/{monitor_id}")
+async def set_monitor_contrast(
+    monitor_id: int, request: ContrastRequest, _: str = Depends(verify_token)
+) -> dict:
+    """Set DDC/CI contrast for a specific monitor."""
+    success = await asyncio.to_thread(set_contrast, monitor_id, request.contrast)
+    if success:
+        logger.info("Set monitor %d contrast to %d", monitor_id, request.contrast)
+    return {"success": success}
+
+
+@router.post("/input_source/{monitor_id}")
+async def set_monitor_input_source(
+    monitor_id: int, request: InputSourceRequest, _: str = Depends(verify_token)
+) -> dict:
+    """Switch a monitor's DDC/CI input source (e.g. HDMI1, DP1)."""
+    success = await asyncio.to_thread(set_input_source, monitor_id, request.source)
+    if success:
+        logger.info("Set monitor %d input source to %s", monitor_id, request.source)
+    return {"success": success}
+
+
+@router.post("/color_preset/{monitor_id}")
+async def set_monitor_color_preset(
+    monitor_id: int, request: ColorPresetRequest, _: str = Depends(verify_token)
+) -> dict:
+    """Apply a DDC/CI color preset (color temperature) to the monitor."""
+    success = await asyncio.to_thread(set_color_preset, monitor_id, request.preset)
+    if success:
+        logger.info("Set monitor %d color preset to %s", monitor_id, request.preset)
+    return {"success": success}
+
+
+@router.post("/picture_mode/{monitor_id}")
+async def set_monitor_picture_mode(
+    monitor_id: int, request: PictureModeRequest, _: str = Depends(verify_token)
+) -> dict:
+    """Apply a DDC/CI picture/scene mode (VCP 0xDC) by raw code."""
+    success = await asyncio.to_thread(set_picture_mode, monitor_id, request.code)
+    if success:
+        logger.info("Set monitor %d picture mode to code %d", monitor_id, request.code)
+    return {"success": success}

media_server/routes/foreground.py

@@ -0,0 +1,26 @@
+"""Foreground (topmost) window/process API."""
+
+import asyncio
+import logging
+
+from fastapi import APIRouter, Depends
+
+from ..auth import verify_token
+from ..services.foreground_service import get_foreground_info
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/foreground", tags=["foreground"])
+
+
+@router.get("")
+async def get_foreground(
+    refresh: bool = False, _: str = Depends(verify_token)
+) -> dict:
+    """Return metadata about the foreground window and owning process.
+
+    The probe is cached for ~500ms server-side; pass ``?refresh=1`` to bypass
+    the cache for one-shot queries.
+    """
+    info = await asyncio.to_thread(get_foreground_info, refresh)
+    return info.to_dict()

media_server/routes/health.py

@@ -3,20 +3,33 @@
 import platform
 from typing import Any
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Request
+
+from .. import __version__
+from ..auth import auth_enabled
+from ..config import settings
 
 router = APIRouter(prefix="/api", tags=["health"])
 
 
 @router.get("/health")
-async def health_check() -> dict[str, Any]:
+async def health_check(request: Request) -> dict[str, Any]:
     """Health check endpoint - no authentication required.
 
     Returns:
         Health status and server information
     """
-    return {
+    result: dict[str, Any] = {
         "status": "healthy",
         "platform": platform.system(),
-        "version": "1.0.0",
+        "version": __version__,
+        "auth_required": auth_enabled(),
+        "media_folders_management": settings.media_folders_management,
     }
+
+    # Include cached update info if available
+    checker = getattr(request.app.state, "update_checker", None)
+    if checker is not None and checker.cached_update is not None:
+        result["update_available"] = checker.cached_update
+
+    return result

media_server/routes/links.py

@@ -0,0 +1,233 @@
+"""Header quick links management API endpoints."""
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urlparse
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field, field_validator
+
+from ..auth import verify_token
+from ..config import LinkConfig, settings
+from ..config_manager import config_manager
+from ..services.websocket_manager import ws_manager
+
+router = APIRouter(prefix="/api/links", tags=["links"])
+logger = logging.getLogger(__name__)
+
+# Only allow MDI iconify slugs and safe `http(s)`-ish URLs through the API.
+_MDI_ICON_RE = re.compile(r"^mdi:[a-z0-9][a-z0-9-]{0,63}$")
+_ALLOWED_URL_SCHEMES = {"http", "https"}
+
+
+def _validate_url(url: str) -> str:
+    """Ensure the URL is well-formed http(s) — no ``javascript:`` etc."""
+    parsed = urlparse(url)
+    if parsed.scheme.lower() not in _ALLOWED_URL_SCHEMES:
+        raise ValueError("URL must start with http:// or https://")
+    if not parsed.netloc:
+        raise ValueError("URL must include a host")
+    return url
+
+
+def _validate_icon(icon: str) -> str:
+    """Restrict icon names to safe Material Design Icons slugs."""
+    if not _MDI_ICON_RE.match(icon):
+        raise ValueError("Icon must be of the form 'mdi:<lowercase-slug>'")
+    return icon
+
+
+def _require_links_management() -> None:
+    """Authorise a links-CRUD operation. Operator flag + per-token admin scope."""
+    if not settings.links_management:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Links management is disabled. Set links_management: true in config.yaml to enable.",
+        )
+    from ..auth import auth_enabled, token_has_scope, token_label_var
+    if auth_enabled():
+        label = token_label_var.get("unknown")
+        if not token_has_scope(label, "admin"):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Token '{label}' lacks required scope: admin",
+            )
+
+
+class LinkInfo(BaseModel):
+    """Information about a configured link."""
+
+    name: str
+    url: str
+    icon: str
+    label: str
+    description: str
+
+
+class LinkCreateRequest(BaseModel):
+    """Request model for creating or updating a link."""
+
+    url: str = Field(..., description="URL to open", min_length=1, max_length=2048)
+    icon: str = Field(default="mdi:link", description="MDI icon name (e.g., 'mdi:led-strip-variant')")
+    label: str = Field(default="", description="Tooltip text", max_length=128)
+    description: str = Field(default="", description="Optional description", max_length=512)
+
+    @field_validator("url")
+    @classmethod
+    def _check_url(cls, v: str) -> str:
+        return _validate_url(v)
+
+    @field_validator("icon")
+    @classmethod
+    def _check_icon(cls, v: str) -> str:
+        return _validate_icon(v)
+
+
+def _validate_link_name(name: str) -> None:
+    """Validate link name."""
+    if not re.match(r"^[a-zA-Z0-9_]+$", name):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Link name must contain only letters, numbers, and underscores",
+        )
+    if len(name) > 64:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Link name must be 64 characters or less",
+        )
+
+
+@router.get("/list")
+async def list_links(_: str = Depends(verify_token)) -> list[LinkInfo]:
+    """List all configured links.
+
+    Returns:
+        List of configured links.
+    """
+    return [
+        LinkInfo(
+            name=name,
+            url=config.url,
+            icon=config.icon,
+            label=config.label,
+            description=config.description,
+        )
+        for name, config in settings.links.items()
+    ]
+
+
+@router.post("/create/{link_name}")
+async def create_link(
+    link_name: str,
+    request: LinkCreateRequest,
+    _: str = Depends(verify_token),
+) -> dict[str, Any]:
+    """Create a new link.
+
+    Args:
+        link_name: Link name (alphanumeric and underscores only).
+        request: Link configuration.
+
+    Returns:
+        Success response with link name.
+    """
+    _require_links_management()
+    _validate_link_name(link_name)
+
+    if link_name in settings.links:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Link '{link_name}' already exists. Use PUT /api/links/update/{link_name} to update it.",
+        )
+
+    link_config = LinkConfig(**request.model_dump())
+
+    try:
+        config_manager.add_link(link_name, link_config)
+    except Exception as e:
+        logger.error(f"Failed to add link '{link_name}': {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to add link: {str(e)}",
+        )
+
+    await ws_manager.broadcast_links_changed()
+    logger.info(f"Link '{link_name}' created successfully")
+    return {"success": True, "link": link_name}
+
+
+@router.put("/update/{link_name}")
+async def update_link(
+    link_name: str,
+    request: LinkCreateRequest,
+    _: str = Depends(verify_token),
+) -> dict[str, Any]:
+    """Update an existing link.
+
+    Args:
+        link_name: Link name.
+        request: Updated link configuration.
+
+    Returns:
+        Success response with link name.
+    """
+    _require_links_management()
+    _validate_link_name(link_name)
+
+    if link_name not in settings.links:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Link '{link_name}' not found. Use POST /api/links/create/{link_name} to create it.",
+        )
+
+    link_config = LinkConfig(**request.model_dump())
+
+    try:
+        config_manager.update_link(link_name, link_config)
+    except Exception as e:
+        logger.error(f"Failed to update link '{link_name}': {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to update link: {str(e)}",
+        )
+
+    await ws_manager.broadcast_links_changed()
+    logger.info(f"Link '{link_name}' updated successfully")
+    return {"success": True, "link": link_name}
+
+
+@router.delete("/delete/{link_name}")
+async def delete_link(
+    link_name: str,
+    _: str = Depends(verify_token),
+) -> dict[str, Any]:
+    """Delete a link.
+
+    Args:
+        link_name: Link name.
+
+    Returns:
+        Success response with link name.
+    """
+    _require_links_management()
+    _validate_link_name(link_name)
+
+    if link_name not in settings.links:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Link '{link_name}' not found",
+        )
+
+    try:
+        config_manager.delete_link(link_name)
+    except Exception as e:
+        logger.error(f"Failed to delete link '{link_name}': {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to delete link: {str(e)}",
+        )
+
+    await ws_manager.broadcast_links_changed()
+    logger.info(f"Link '{link_name}' deleted successfully")
+    return {"success": True, "link": link_name}

media_server/routes/media.py

@@ -3,14 +3,22 @@
 import asyncio
 import logging
 
-from fastapi import APIRouter, Depends, HTTPException, Query, WebSocket, WebSocketDisconnect
-from fastapi import status
+from fastapi import (
+    APIRouter,
+    Depends,
+    HTTPException,
+    Query,
+    Request,
+    WebSocket,
+    WebSocketDisconnect,
+    status,
+)
 from fastapi.responses import Response
 
 from ..auth import verify_token, verify_token_or_query
 from ..config import settings
-from ..models import MediaStatus, VolumeRequest, SeekRequest
-from ..services import get_media_controller, get_current_album_art
+from ..models import MediaStatus, SeekRequest, VolumeRequest
+from ..services import get_current_album_art_async, get_media_controller
 from ..services.websocket_manager import ws_manager
 
 logger = logging.getLogger(__name__)
@@ -18,31 +26,64 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/media", tags=["media"])
 
 
-async def _run_callback(callback_name: str) -> None:
-    """Run a callback if configured. Failures are logged but don't raise."""
+# Strong refs to background tasks so the asyncio GC can't drop them before
+# they run. Mirrors the pattern used in routes/browser.py.
+_background_callback_tasks: set[asyncio.Task] = set()
+
+
+def _run_callback(callback_name: str) -> None:
+    """Fire-and-forget a callback if configured. Failures are logged but don't block."""
     if not settings.callbacks or callback_name not in settings.callbacks:
         return
 
-    from .scripts import _run_script
+    async def _execute():
+        # Use the dedicated callback executor (not the default loop pool) so a
+        # misbehaving callback can't starve the rest of the app's sync tasks.
+        from ..services.audit_log import record_script_execution
+        from .callbacks import _callback_executor
+        from .scripts import _run_script
 
-    callback = settings.callbacks[callback_name]
-    loop = asyncio.get_event_loop()
-    result = await loop.run_in_executor(
-        None,
-        lambda: _run_script(
-            command=callback.command,
-            timeout=callback.timeout,
-            shell=callback.shell,
-            working_dir=callback.working_dir,
-        ),
-    )
-    if result["exit_code"] != 0:
-        logger.warning(
-            "Callback %s failed with exit code %s: %s",
-            callback_name,
-            result["exit_code"],
-            result["stderr"],
-        )
+        try:
+            callback = settings.callbacks[callback_name]
+            loop = asyncio.get_running_loop()
+            result = await loop.run_in_executor(
+                _callback_executor,
+                lambda: _run_script(
+                    command=callback.command,
+                    timeout=callback.timeout,
+                    shell=callback.shell,
+                    working_dir=callback.working_dir,
+                ),
+            )
+            record_script_execution(
+                kind="event-callback",
+                name=callback_name,
+                exit_code=result["exit_code"],
+                duration=result.get("execution_time"),
+                stdout=result.get("stdout"),
+                stderr=result.get("stderr"),
+            )
+            if result["exit_code"] != 0:
+                logger.warning(
+                    "Callback %s failed with exit code %s: %s",
+                    callback_name,
+                    result["exit_code"],
+                    result["stderr"],
+                )
+        except Exception as e:
+            logger.error("Callback %s error: %s", callback_name, e)
+            from ..services.audit_log import record_script_execution as _rec
+            _rec(
+                kind="event-callback",
+                name=callback_name,
+                exit_code=None,
+                duration=None,
+                error=str(e),
+            )
+
+    task = asyncio.create_task(_execute())
+    _background_callback_tasks.add(task)
+    task.add_done_callback(_background_callback_tasks.discard)
 
 
 @router.get("/status", response_model=MediaStatus)
@@ -70,7 +111,7 @@ async def play(_: str = Depends(verify_token)) -> dict:
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
             detail="Failed to start playback - no active media session",
         )
-    await _run_callback("on_play")
+    _run_callback("on_play")
     return {"success": True}
 
 
@@ -88,7 +129,7 @@ async def pause(_: str = Depends(verify_token)) -> dict:
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
             detail="Failed to pause - no active media session",
         )
-    await _run_callback("on_pause")
+    _run_callback("on_pause")
     return {"success": True}
 
 
@@ -106,7 +147,7 @@ async def stop(_: str = Depends(verify_token)) -> dict:
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
             detail="Failed to stop - no active media session",
         )
-    await _run_callback("on_stop")
+    _run_callback("on_stop")
     return {"success": True}
 
 
@@ -124,7 +165,7 @@ async def next_track(_: str = Depends(verify_token)) -> dict:
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
             detail="Failed to skip - no active media session",
         )
-    await _run_callback("on_next")
+    _run_callback("on_next")
     return {"success": True}
 
 
@@ -142,7 +183,7 @@ async def previous_track(_: str = Depends(verify_token)) -> dict:
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
             detail="Failed to go back - no active media session",
         )
-    await _run_callback("on_previous")
+    _run_callback("on_previous")
     return {"success": True}
 
 
@@ -165,7 +206,7 @@ async def set_volume(
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
             detail="Failed to set volume",
         )
-    await _run_callback("on_volume")
+    _run_callback("on_volume")
     return {"success": True, "volume": request.volume}
 
 
@@ -178,7 +219,7 @@ async def toggle_mute(_: str = Depends(verify_token)) -> dict:
     """
     controller = get_media_controller()
     muted = await controller.toggle_mute()
-    await _run_callback("on_mute")
+    _run_callback("on_mute")
     return {"success": True, "muted": muted}
 
 
@@ -199,7 +240,7 @@ async def seek(request: SeekRequest, _: str = Depends(verify_token)) -> dict:
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
             detail="Failed to seek - no active media session or seek not supported",
         )
-    await _run_callback("on_seek")
+    _run_callback("on_seek")
     return {"success": True, "position": request.position}
 
 
@@ -210,7 +251,7 @@ async def turn_on(_: str = Depends(verify_token)) -> dict:
     Returns:
         Success status
     """
-    await _run_callback("on_turn_on")
+    _run_callback("on_turn_on")
     return {"success": True}
 
 
@@ -221,7 +262,7 @@ async def turn_off(_: str = Depends(verify_token)) -> dict:
     Returns:
         Success status
     """
-    await _run_callback("on_turn_off")
+    _run_callback("on_turn_off")
     return {"success": True}
 
 
@@ -232,45 +273,153 @@ async def toggle(_: str = Depends(verify_token)) -> dict:
     Returns:
         Success status
     """
-    await _run_callback("on_toggle")
+    _run_callback("on_toggle")
     return {"success": True}
 
 
 @router.get("/artwork")
-async def get_artwork(_: str = Depends(verify_token_or_query)) -> Response:
+async def get_artwork(
+    request: Request,
+    _: str = Depends(verify_token_or_query),
+) -> Response:
     """Get the current album artwork.
 
-    Returns:
-        The album art image as PNG/JPEG
+    Returns the bytes with a content-derived ETag so the browser can serve a
+    304 when the same track is re-requested.
     """
-    art_bytes = get_current_album_art()
+    art_bytes = await get_current_album_art_async()
     if art_bytes is None:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail="No album artwork available",
         )
 
-    # Try to detect image type from magic bytes
-    content_type = "image/png"  # Default
+    # Detect image type from magic bytes
     if art_bytes[:3] == b"\xff\xd8\xff":
         content_type = "image/jpeg"
     elif art_bytes[:8] == b"\x89PNG\r\n\x1a\n":
         content_type = "image/png"
-    elif art_bytes[:4] == b"RIFF" and art_bytes[8:12] == b"WEBP":
+    elif art_bytes[:4] == b"RIFF" and len(art_bytes) > 12 and art_bytes[8:12] == b"WEBP":
         content_type = "image/webp"
+    elif art_bytes[:2] == b"BM":
+        content_type = "image/bmp"
+    else:
+        content_type = "application/octet-stream"
 
-    return Response(content=art_bytes, media_type=content_type)
+    # Content-derived ETag (blake2b-128 — non-crypto cache key, ruff S324-safe)
+    import hashlib
+
+    etag = '"' + hashlib.blake2b(art_bytes, digest_size=16).hexdigest() + '"'
+
+    if request.headers.get("if-none-match") == etag:
+        return Response(status_code=status.HTTP_304_NOT_MODIFIED, headers={"ETag": etag})
+
+    return Response(
+        content=art_bytes,
+        media_type=content_type,
+        headers={
+            "ETag": etag,
+            "Cache-Control": "private, max-age=0, must-revalidate",
+        },
+    )
+
+
+@router.get("/visualizer/status")
+async def visualizer_status(_: str = Depends(verify_token)) -> dict:
+    """Check if audio visualizer is available and running.
+
+    ``available`` is True only when both numpy + soundcard import.
+    ``unavailable_reason`` carries a short human-readable hint when False
+    or when a usable loopback device was not found — useful on Linux where
+    PulseAudio/PipeWire may not expose monitor sources to a headless
+    systemd-as-user service.
+    """
+    import platform as _platform
+
+    from ..services.audio_analyzer import get_audio_analyzer
+
+    analyzer = get_audio_analyzer()
+    reason: str | None = None
+    if not analyzer.available:
+        reason = "soundcard or numpy is not installed"
+    elif getattr(analyzer, "_unavailable", False):
+        if _platform.system() == "Linux":
+            reason = (
+                "No loopback audio device found. On Linux this requires a "
+                "running PulseAudio/PipeWire session with monitor sources "
+                "(systemd user service: ensure DBUS_SESSION_BUS_ADDRESS + "
+                "XDG_RUNTIME_DIR are set)."
+            )
+        elif _platform.system() == "Darwin":
+            reason = (
+                "No loopback audio device found. macOS does not expose system "
+                "loopback by default — install BlackHole or Soundflower."
+            )
+        else:
+            reason = "No loopback audio device found"
+
+    return {
+        "available": analyzer.available,
+        "running": analyzer.running,
+        "current_device": analyzer.current_device,
+        "unavailable_reason": reason,
+    }
+
+
+@router.get("/visualizer/devices")
+async def visualizer_devices(_: str = Depends(verify_token)) -> list[dict[str, str]]:
+    """List available loopback audio devices for the visualizer."""
+    from ..services.audio_analyzer import AudioAnalyzer
+
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, AudioAnalyzer.list_loopback_devices)
+
+
+@router.post("/visualizer/device")
+async def set_visualizer_device(
+    request: dict,
+    _: str = Depends(verify_token),
+) -> dict:
+    """Set the loopback audio device for the visualizer.
+
+    Body: {"device_name": "Device Name" | null}
+    Passing null resets to auto-detect.
+    """
+    from ..services.audio_analyzer import get_audio_analyzer
+
+    device_name = request.get("device_name")
+    analyzer = get_audio_analyzer()
+
+    # set_device() handles stop/start internally if capture was running
+    success = analyzer.set_device(device_name)
+
+    # Persist selection to config.yaml so it survives server restarts
+    if success:
+        from ..config_manager import config_manager
+
+        config_manager.set_setting("visualizer_device", device_name)
+
+    return {
+        "success": success,
+        "current_device": analyzer.current_device,
+        "running": analyzer.running,
+    }
 
 
 @router.websocket("/ws")
 async def websocket_endpoint(
     websocket: WebSocket,
-    token: str = Query(..., description="API authentication token"),
+    token: str | None = Query(None, description="API authentication token (legacy)"),
 ) -> None:
     """WebSocket endpoint for real-time media status updates.
 
-    Authentication is done via query parameter since WebSocket
-    doesn't support custom headers in the browser.
+    Authentication is accepted from two sources, in priority order:
+      1. ``Sec-WebSocket-Protocol`` subprotocol of the form
+         ``media-server.token.<TOKEN>``. This is the preferred path because
+         the token never lands in the URL, request logs, or browser history.
+         The browser WebSocket API supports custom subprotocols natively.
+      2. ``?token=<TOKEN>`` query parameter (legacy, kept for back-compat
+         with older clients and the HA integration).
 
     Messages sent to client:
     - {"type": "status", "data": {...}} - Initial status on connect
@@ -281,21 +430,80 @@ async def websocket_endpoint(
     - {"type": "ping"} - Keepalive, server responds with {"type": "pong"}
     - {"type": "get_status"} - Request current status
     """
-    # Verify token
-    if token != settings.api_token:
-        await websocket.close(code=4001, reason="Invalid authentication token")
-        return
+    # Pull token from subprotocol if present. WebSocket spec lets either side
+    # negotiate exactly one subprotocol back; we accept the token one and
+    # answer with the same string so browsers consider the negotiation
+    # successful.
+    subprotocol_token: str | None = None
+    accept_subprotocol: str | None = None
+    raw_protocols = websocket.headers.get("sec-websocket-protocol", "")
+    for proto in (p.strip() for p in raw_protocols.split(",") if p.strip()):
+        if proto.startswith("media-server.token."):
+            subprotocol_token = proto[len("media-server.token."):]
+            accept_subprotocol = proto
+            break
+    effective_token = subprotocol_token or token
+    # Origin check — block CSWSH from third-party LAN pages. Accept the same
+    # set of origins as CORS plus the default localhost loopback, AND any
+    # same-origin connection (where Origin matches the request's Host header).
+    # Same-origin is inherently safe from CSWSH because CSWSH is a *cross*-
+    # origin attack — without this, binding to 0.0.0.0 and accessing the UI
+    # via a LAN IP would have its WebSocket rejected by the browser-sent
+    # Origin, which the static allowlist can't anticipate.
+    allowed_origins = set(
+        settings.cors_origins
+        or [
+            f"http://localhost:{settings.port}",
+            f"http://127.0.0.1:{settings.port}",
+        ]
+    )
+    origin = websocket.headers.get("origin")
+    # Same-origin connections from native apps may omit Origin entirely; only
+    # reject when an Origin is present AND not in the allow-list.
+    if origin is not None and origin not in allowed_origins:
+        host_header = websocket.headers.get("host", "")
+        # Origin uses http/https; match against both scheme variants of Host
+        # so HTTPS deployments without an explicit cors_origins still work.
+        same_origin_candidates = (
+            {f"http://{host_header}", f"https://{host_header}"}
+            if host_header
+            else set()
+        )
+        if origin not in same_origin_candidates:
+            await websocket.close(code=4003, reason="Origin not allowed")
+            return
 
-    await ws_manager.connect(websocket)
+    # Verify token
+    from ..auth import auth_enabled, get_token_label, token_label_var
+
+    if auth_enabled():
+        label = get_token_label(effective_token) if effective_token else None
+        if label is None:
+            await websocket.close(code=4001, reason="Invalid authentication token")
+            return
+        token_label_var.set(label)
+    else:
+        token_label_var.set("anonymous")
+
+    # Accept with the negotiated subprotocol if one was used. Starlette's
+    # connect() calls accept() with no subprotocol — we need to accept first
+    # explicitly to echo the subprotocol back, then hand off to the manager.
+    if accept_subprotocol is not None:
+        await websocket.accept(subprotocol=accept_subprotocol)
+        await ws_manager.connect(websocket, already_accepted=True)
+    else:
+        await ws_manager.connect(websocket)
 
     try:
         while True:
             # Wait for messages from client (for keepalive/ping)
             data = await websocket.receive_json()
 
-            if data.get("type") == "ping":
+            msg_type = data.get("type") if isinstance(data, dict) else None
+
+            if msg_type == "ping":
                 await websocket.send_json({"type": "pong"})
-            elif data.get("type") == "get_status":
+            elif msg_type == "get_status":
                 # Allow manual status request
                 controller = get_media_controller()
                 status_data = await controller.get_status()
@@ -303,6 +511,21 @@ async def websocket_endpoint(
                     "type": "status",
                     "data": status_data.model_dump(),
                 })
+            elif msg_type == "volume":
+                # Low-latency volume control via WebSocket. Coerce, clamp, and
+                # never drop the socket on a single bad message — that would
+                # turn the WS into a one-shot DoS for any holder of a token.
+                try:
+                    volume = int(data.get("volume"))
+                except (TypeError, ValueError):
+                    continue
+                volume = max(0, min(100, volume))
+                controller = get_media_controller()
+                await controller.set_volume(volume)
+            elif msg_type == "enable_visualizer":
+                await ws_manager.subscribe_visualizer(websocket)
+            elif msg_type == "disable_visualizer":
+                await ws_manager.unsubscribe_visualizer(websocket)
 
     except WebSocketDisconnect:
         await ws_manager.disconnect(websocket)

media_server/routes/scripts.py

@@ -2,23 +2,67 @@
 
 import asyncio
 import logging
+import os
+import re
 import subprocess
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor
 from typing import Any
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Request, status
 from pydantic import BaseModel, Field
 
 from ..auth import verify_token
-from ..config import settings
+from ..config import ScriptConfig, ScriptParameterConfig, settings
+from ..config_manager import config_manager
+from ..services.rate_limit import check as ratelimit_check
+from ..services.rate_limit import get_peer
+from ..services.websocket_manager import ws_manager
 
 router = APIRouter(prefix="/api/scripts", tags=["scripts"])
+
+# Dedicated executor for script/subprocess execution (avoids blocking the default pool)
+_script_executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="script")
 logger = logging.getLogger(__name__)
 
 
-class ScriptExecuteRequest(BaseModel):
-    """Request model for script execution with optional arguments."""
+def shutdown_script_executor() -> None:
+    """Shut down the dedicated executor cleanly on application teardown."""
+    _script_executor.shutdown(wait=False, cancel_futures=True)
 
-    args: list[str] = Field(default_factory=list, description="Additional arguments")
+
+def _require_scripts_management() -> None:
+    """Authorise a scripts-CRUD operation.
+
+    Two gates: the operator-level `scripts_management` flag in config.yaml,
+    AND the per-token `admin` scope check (read from request-context). Either
+    failure → 403.
+    """
+    if not settings.scripts_management:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=(
+                "Scripts management is disabled. Set scripts_management: true"
+                " in config.yaml to enable."
+            ),
+        )
+    from ..auth import auth_enabled, token_has_scope, token_label_var
+    if auth_enabled():
+        label = token_label_var.get("unknown")
+        if not token_has_scope(label, "admin"):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Token '{label}' lacks required scope: admin",
+            )
+
+
+class ScriptExecuteRequest(BaseModel):
+    """Request model for script execution with optional parameters."""
+
+    params: dict[str, str | int | float | bool] = Field(
+        default_factory=dict, description="Named parameters (validated against script schema)"
+    )
 
 
 class ScriptExecuteResponse(BaseModel):
@@ -30,6 +74,19 @@ class ScriptExecuteResponse(BaseModel):
     stdout: str = ""
     stderr: str = ""
     error: str | None = None
+    execution_time: float | None = None
+
+
+class ScriptParameterInfo(BaseModel):
+    """Information about a script parameter."""
+
+    type: str
+    description: str = ""
+    required: bool = False
+    default: str | int | float | bool | None = None
+    min: float | None = None
+    max: float | None = None
+    options: list[str] | None = None
 
 
 class ScriptInfo(BaseModel):
@@ -37,9 +94,11 @@ class ScriptInfo(BaseModel):
 
     name: str
     label: str
+    command: str
     description: str
     icon: str | None = None
     timeout: int
+    parameters: dict[str, ScriptParameterInfo] = Field(default_factory=dict)
 
 
 @router.get("/list")
@@ -53,17 +112,156 @@ async def list_scripts(_: str = Depends(verify_token)) -> list[ScriptInfo]:
         ScriptInfo(
             name=name,
             label=config.label or name.replace("_", " ").title(),
+            command=config.command,
             description=config.description,
             icon=config.icon,
             timeout=config.timeout,
+            parameters={
+                pname: ScriptParameterInfo(**pconfig.model_dump())
+                for pname, pconfig in config.parameters.items()
+            },
         )
         for name, config in settings.scripts.items()
     ]
 
 
+def _validate_params(
+    params: dict[str, str | int | float | bool],
+    param_defs: dict[str, ScriptParameterConfig],
+) -> dict[str, str]:
+    """Validate parameters against script schema and return env vars.
+
+    Args:
+        params: User-supplied parameter values.
+        param_defs: Parameter definitions from script config.
+
+    Returns:
+        Dict of environment variables (SCRIPT_PARAM_<NAME> -> str value).
+
+    Raises:
+        HTTPException: On validation failure.
+    """
+    # Reject unknown parameters
+    unknown = set(params.keys()) - set(param_defs.keys())
+    if unknown:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Unknown parameters: {', '.join(sorted(unknown))}",
+        )
+
+    env_vars: dict[str, str] = {}
+
+    for pname, pdef in param_defs.items():
+        value = params.get(pname)
+
+        # Apply default if missing
+        if value is None and pdef.default is not None:
+            value = pdef.default
+
+        # Check required
+        if value is None:
+            if pdef.required:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Required parameter '{pname}' is missing",
+                )
+            continue
+
+        # Type validation and coercion
+        if pdef.type == "integer":
+            try:
+                value = int(value)
+            except (TypeError, ValueError):
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}' must be an integer, got: {value!r}",
+                )
+            if pdef.min is not None and value < pdef.min:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}' must be >= {pdef.min}, got: {value}",
+                )
+            if pdef.max is not None and value > pdef.max:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}' must be <= {pdef.max}, got: {value}",
+                )
+        elif pdef.type == "float":
+            try:
+                value = float(value)
+            except (TypeError, ValueError):
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}' must be a number, got: {value!r}",
+                )
+            if pdef.min is not None and value < pdef.min:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}' must be >= {pdef.min}, got: {value}",
+                )
+            if pdef.max is not None and value > pdef.max:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}' must be <= {pdef.max}, got: {value}",
+                )
+        elif pdef.type == "boolean":
+            if isinstance(value, str):
+                if value.lower() in ("true", "1", "yes"):
+                    value = True
+                elif value.lower() in ("false", "0", "no"):
+                    value = False
+                else:
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=f"Parameter '{pname}' must be a boolean, got: {value!r}",
+                    )
+            elif not isinstance(value, bool):
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}' must be a boolean, got: {value!r}",
+                )
+        elif pdef.type == "select":
+            value = str(value)
+            if pdef.options and value not in pdef.options:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}' must be one of {pdef.options}, got: {value!r}",
+                )
+        else:
+            # string — just convert to str
+            value = str(value)
+
+        # Optional regex constraint, validated against the *string form* of the
+        # value. This is the only practical defence for string parameters that
+        # flow into shell=true scripts via env vars (Windows cmd.exe expands
+        # `%VAR%` after argument parsing, so embedded `&`/`|`/`%` would inject
+        # commands). Authors of shell scripts should ALWAYS define a pattern.
+        if pdef.pattern:
+            try:
+                if not re.fullmatch(pdef.pattern, str(value)):
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=(
+                            f"Parameter '{pname}' value {value!r} does not match"
+                            f" required pattern: {pdef.pattern}"
+                        ),
+                    )
+            except re.error as e:
+                # Bad pattern in config — fail closed.
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail=f"Parameter '{pname}' has invalid pattern: {e}",
+                ) from e
+
+        env_vars[f"SCRIPT_PARAM_{pname.upper()}"] = str(value)
+
+    return env_vars
+
+
 @router.post("/execute/{script_name}")
 async def execute_script(
     script_name: str,
+    http_request: Request,
     request: ScriptExecuteRequest | None = None,
     _: str = Depends(verify_token),
 ) -> ScriptExecuteResponse:
@@ -71,11 +269,21 @@ async def execute_script(
 
     Args:
         script_name: Name of the script to execute (must be defined in config)
-        request: Optional arguments to pass to the script
+        request: Optional parameters to pass to the script
 
     Returns:
         Execution result including stdout, stderr, and exit code
     """
+    # Rate-limit script execution per peer so a leaked token can't be used to
+    # spam the shell-exec endpoint.
+    allowed, retry_after = ratelimit_check("execute", get_peer(http_request))
+    if not allowed:
+        raise HTTPException(
+            status_code=429,
+            detail="Too many script executions, slow down",
+            headers={"Retry-After": str(int(retry_after or 60))},
+        )
+
     # Check if script exists
     if script_name not in settings.scripts:
         raise HTTPException(
@@ -83,39 +291,56 @@ async def execute_script(
             detail=f"Script '{script_name}' not found. Use /api/scripts/list to see available scripts.",
         )
     script_config = settings.scripts[script_name]
-    args = request.args if request else []
+    params = request.params if request else {}
+
+    # Validate parameters and build env vars
+    extra_env = _validate_params(params, script_config.parameters)
 
     logger.info(f"Executing script: {script_name}")
 
-    try:
-        # Build command
-        command = script_config.command
-        if args:
-            # Append arguments to command
-            command = f"{command} {' '.join(args)}"
+    from ..services.audit_log import record_script_execution
 
-        # Execute in thread pool to not block
-        loop = asyncio.get_event_loop()
+    try:
+        # Execute in dedicated thread pool to not block the default executor
+        loop = asyncio.get_running_loop()
         result = await loop.run_in_executor(
-            None,
+            _script_executor,
             lambda: _run_script(
-                command=command,
+                command=script_config.command,
                 timeout=script_config.timeout,
                 shell=script_config.shell,
                 working_dir=script_config.working_dir,
+                extra_env=extra_env,
             ),
         )
 
+        record_script_execution(
+            kind="script",
+            name=script_name,
+            exit_code=result["exit_code"],
+            duration=result.get("execution_time"),
+            stdout=result.get("stdout"),
+            stderr=result.get("stderr"),
+        )
+
         return ScriptExecuteResponse(
             success=result["exit_code"] == 0,
             script=script_name,
             exit_code=result["exit_code"],
             stdout=result["stdout"],
             stderr=result["stderr"],
+            execution_time=result.get("execution_time"),
         )
 
     except Exception as e:
         logger.error(f"Script execution error: {e}")
+        record_script_execution(
+            kind="script",
+            name=script_name,
+            exit_code=None,
+            duration=None,
+            error=str(e),
+        )
         return ScriptExecuteResponse(
             success=False,
             script=script_name,
@@ -128,6 +353,7 @@ def _run_script(
     timeout: int,
     shell: bool,
     working_dir: str | None,
+    extra_env: dict[str, str] | None = None,
 ) -> dict[str, Any]:
     """Run a script synchronously.
 
@@ -136,33 +362,337 @@ def _run_script(
         timeout: Timeout in seconds
         shell: Whether to run in shell
         working_dir: Working directory
+        extra_env: Additional environment variables (e.g. SCRIPT_PARAM_*)
 
     Returns:
-        Dict with exit_code, stdout, stderr
+        Dict with exit_code, stdout, stderr, execution_time
     """
+    start_time = time.time()
+    env = None
+    if extra_env:
+        env = {**os.environ, **extra_env}
+
+    # Spawn the script in its own process group / job so a timeout kills the
+    # whole tree, not just the shell (POSIX) and not just the parent (Windows).
+    popen_kwargs: dict[str, Any] = {}
+    if sys.platform == "win32":
+        popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        popen_kwargs["start_new_session"] = True
+
+    # When shell=False, the user-provided command string is split via shlex
+    # (POSIX rules — also works for Windows args without backslashes). This
+    # disables shell metacharacter expansion entirely, so SCRIPT_PARAM_* env
+    # vars referenced as $FOO / %FOO% will be treated as literal text by the
+    # process, not interpreted by a shell. Use shell=false for any script
+    # whose params come from external input.
+    if shell:
+        run_command: str | list[str] = command
+    else:
+        import shlex
+        run_command = shlex.split(command, posix=(sys.platform != "win32"))
+
     try:
         result = subprocess.run(
-            command,
+            run_command,
             shell=shell,
             cwd=working_dir,
             capture_output=True,
             text=True,
             timeout=timeout,
+            env=env,
+            **popen_kwargs,
         )
+        execution_time = time.time() - start_time
         return {
             "exit_code": result.returncode,
             "stdout": result.stdout[:10000],  # Limit output size
             "stderr": result.stderr[:10000],
+            "execution_time": execution_time,
         }
     except subprocess.TimeoutExpired:
+        execution_time = time.time() - start_time
         return {
             "exit_code": -1,
             "stdout": "",
             "stderr": f"Script timed out after {timeout} seconds",
+            "execution_time": execution_time,
         }
     except Exception as e:
+        execution_time = time.time() - start_time
         return {
             "exit_code": -1,
             "stdout": "",
             "stderr": str(e),
+            "execution_time": execution_time,
         }
+
+
+# Script management endpoints
+
+
+class ScriptParameterCreateRequest(BaseModel):
+    """Request model for a script parameter definition."""
+
+    type: str = Field(
+        ..., description="Parameter type: string, integer, float, boolean, select"
+    )
+    description: str = Field(default="", description="Parameter description")
+    required: bool = Field(default=False, description="Whether the parameter is required")
+    default: str | int | float | bool | None = Field(
+        default=None, description="Default value if not provided"
+    )
+    min: float | None = Field(default=None, description="Minimum value (numeric types only)")
+    max: float | None = Field(default=None, description="Maximum value (numeric types only)")
+    options: list[str] | None = Field(
+        default=None, description="Allowed values (select type only)"
+    )
+
+
+class ScriptCreateRequest(BaseModel):
+    """Request model for creating or updating a script."""
+
+    command: str = Field(..., description="Command to execute", min_length=1)
+    label: str | None = Field(default=None, description="User-friendly label")
+    description: str = Field(default="", description="Script description")
+    icon: str | None = Field(default=None, description="Custom MDI icon (e.g., 'mdi:power')")
+    timeout: int = Field(default=30, description="Execution timeout in seconds", ge=1, le=300)
+    working_dir: str | None = Field(default=None, description="Working directory")
+    shell: bool = Field(default=True, description="Run command in shell")
+    parameters: dict[str, ScriptParameterCreateRequest] = Field(
+        default_factory=dict, description="Named parameters with type and validation rules"
+    )
+
+
+def _validate_parameter_definitions(
+    parameters: dict[str, ScriptParameterCreateRequest],
+) -> None:
+    """Validate parameter definitions are well-formed.
+
+    Args:
+        parameters: Parameter definitions to validate.
+
+    Raises:
+        HTTPException: If any definition is invalid.
+    """
+    valid_types = {"string", "integer", "float", "boolean", "select"}
+
+    for pname, pdef in parameters.items():
+        if not re.match(r"^[a-zA-Z][a-zA-Z0-9_]*$", pname):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=(
+                    f"Parameter name '{pname}' must start with a letter"
+                    " and contain only alphanumeric characters and underscores"
+                ),
+            )
+
+        if pdef.type not in valid_types:
+            allowed = ", ".join(sorted(valid_types))
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Parameter '{pname}' has invalid type '{pdef.type}'. Must be one of: {allowed}",
+            )
+
+        if pdef.type == "select":
+            if not pdef.options or len(pdef.options) == 0:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}' of type 'select' must have a non-empty 'options' list",
+                )
+
+        if pdef.type not in ("integer", "float"):
+            if pdef.min is not None or pdef.max is not None:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Parameter '{pname}': 'min'/'max' are only valid for integer/float types",
+                )
+
+        if pdef.min is not None and pdef.max is not None and pdef.min > pdef.max:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Parameter '{pname}': 'min' ({pdef.min}) must be <= 'max' ({pdef.max})",
+            )
+
+
+def _validate_script_name(name: str) -> None:
+    """Validate script name.
+
+    Args:
+        name: Script name to validate.
+
+    Raises:
+        HTTPException: If name is invalid.
+    """
+    if not name:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Script name cannot be empty",
+        )
+
+    if not re.match(r"^[a-zA-Z0-9_]+$", name):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Script name must contain only alphanumeric characters and underscores",
+        )
+
+    if len(name) > 64:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Script name must be 64 characters or less",
+        )
+
+
+@router.post("/create/{script_name}")
+async def create_script(
+    script_name: str,
+    request: ScriptCreateRequest,
+    _: str = Depends(verify_token),
+) -> dict[str, Any]:
+    """Create a new script.
+
+    Args:
+        script_name: Name for the new script (alphanumeric + underscore only).
+        request: Script configuration.
+
+    Returns:
+        Success response with script name.
+
+    Raises:
+        HTTPException: If script already exists or name is invalid.
+    """
+    _require_scripts_management()
+    _validate_script_name(script_name)
+
+    # Check if script already exists
+    if script_name in settings.scripts:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Script '{script_name}' already exists. Use PUT /api/scripts/update/{script_name} to update it.",
+        )
+
+    # Validate parameter definitions
+    _validate_parameter_definitions(request.parameters)
+
+    # Build ScriptConfig with ScriptParameterConfig instances
+    data = request.model_dump()
+    data["parameters"] = {
+        pname: ScriptParameterConfig(**pdef)
+        for pname, pdef in data.get("parameters", {}).items()
+    }
+    script_config = ScriptConfig(**data)
+
+    # Add to config file and in-memory
+    try:
+        config_manager.add_script(script_name, script_config)
+    except Exception as e:
+        logger.error(f"Failed to add script '{script_name}': {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to add script: {str(e)}",
+        )
+
+    # Notify WebSocket clients
+    await ws_manager.broadcast_scripts_changed()
+
+    logger.info(f"Script '{script_name}' created successfully")
+    return {"success": True, "script": script_name}
+
+
+@router.put("/update/{script_name}")
+async def update_script(
+    script_name: str,
+    request: ScriptCreateRequest,
+    _: str = Depends(verify_token),
+) -> dict[str, Any]:
+    """Update an existing script.
+
+    Args:
+        script_name: Name of the script to update.
+        request: Updated script configuration.
+
+    Returns:
+        Success response with script name.
+
+    Raises:
+        HTTPException: If script does not exist.
+    """
+    _require_scripts_management()
+    _validate_script_name(script_name)
+
+    # Check if script exists
+    if script_name not in settings.scripts:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Script '{script_name}' not found. Use POST /api/scripts/create/{script_name} to create it.",
+        )
+
+    # Validate parameter definitions
+    _validate_parameter_definitions(request.parameters)
+
+    # Build ScriptConfig with ScriptParameterConfig instances
+    data = request.model_dump()
+    data["parameters"] = {
+        pname: ScriptParameterConfig(**pdef)
+        for pname, pdef in data.get("parameters", {}).items()
+    }
+    script_config = ScriptConfig(**data)
+
+    # Update config file and in-memory
+    try:
+        config_manager.update_script(script_name, script_config)
+    except Exception as e:
+        logger.error(f"Failed to update script '{script_name}': {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to update script: {str(e)}",
+        )
+
+    # Notify WebSocket clients
+    await ws_manager.broadcast_scripts_changed()
+
+    logger.info(f"Script '{script_name}' updated successfully")
+    return {"success": True, "script": script_name}
+
+
+@router.delete("/delete/{script_name}")
+async def delete_script(
+    script_name: str,
+    _: str = Depends(verify_token),
+) -> dict[str, Any]:
+    """Delete a script.
+
+    Args:
+        script_name: Name of the script to delete.
+
+    Returns:
+        Success response with script name.
+
+    Raises:
+        HTTPException: If script does not exist.
+    """
+    _require_scripts_management()
+    _validate_script_name(script_name)
+
+    # Check if script exists
+    if script_name not in settings.scripts:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Script '{script_name}' not found",
+        )
+
+    # Delete from config file and in-memory
+    try:
+        config_manager.delete_script(script_name)
+    except Exception as e:
+        logger.error(f"Failed to delete script '{script_name}': {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to delete script: {str(e)}",
+        )
+
+    # Notify WebSocket clients
+    await ws_manager.broadcast_scripts_changed()
+
+    logger.info(f"Script '{script_name}' deleted successfully")
+    return {"success": True, "script": script_name}

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/install_task_windows.ps1

@@ -1,10 +0,0 @@
-# Get the project root directory (two levels up from this script)
-$projectRoot = (Get-Item $PSScriptRoot).Parent.Parent.FullName
-
-$action = New-ScheduledTaskAction -Execute "python" -Argument "-m media_server.main" -WorkingDirectory $projectRoot
-$trigger = New-ScheduledTaskTrigger -AtStartup
-$principal = New-ScheduledTaskPrincipal -UserId "$env:USERNAME" -LogonType S4U -RunLevel Highest
-$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable
-Register-ScheduledTask -TaskName "MediaServer" -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Description "Media Server for Home Assistant"
-
-Write-Host "Scheduled task 'MediaServer' created with working directory: $projectRoot"

media_server/service/install_windows.py

@@ -13,15 +13,12 @@ Usage:
 
 import os
 import sys
-import socket
-import logging
 
 try:
-    import win32serviceutil
-    import win32service
-    import win32event
     import servicemanager
-    import win32api
+    import win32event
+    import win32service
+    import win32serviceutil
 
     WIN32_AVAILABLE = True
 except ImportError:
@@ -64,8 +61,9 @@ class MediaServerService:
     def main(self):
         """Main service loop."""
         import uvicorn
-        from media_server.main import app
+
         from media_server.config import settings
+        from media_server.main import app
 
         config = uvicorn.Config(
             app,
@@ -95,10 +93,9 @@ def install_service():
 
     try:
         # Get the path to the Python executable
-        python_exe = sys.executable
 
         # Get the path to this module
-        module_path = os.path.abspath(__file__)
+        os.path.abspath(__file__)
 
         win32serviceutil.InstallService(
             MediaServerService._svc_name_,

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

media_server/services/__init__.py

@@ -40,9 +40,10 @@ def get_media_controller() -> "MediaController":
     system = platform.system()
 
     if system == "Windows":
+        from ..config import settings
         from .windows_media import WindowsMediaController
 
-        _controller_instance = WindowsMediaController()
+        _controller_instance = WindowsMediaController(audio_device=settings.audio_device)
     elif system == "Linux":
         # Check if running on Android
         if _is_android():
@@ -64,7 +65,12 @@ def get_media_controller() -> "MediaController":
 
 
 def get_current_album_art() -> bytes | None:
-    """Get the current album art bytes (Windows only for now)."""
+    """Get the current album art bytes (synchronous, Windows-cached path).
+
+    Windows pre-populates a module-level cache via the WinRT polling thread,
+    so this stays sync. For Linux/macOS the controller fetches on demand —
+    use ``get_current_album_art_async()`` from FastAPI handlers instead.
+    """
     system = platform.system()
     if system == "Windows":
         from .windows_media import get_current_album_art as _get_art
@@ -72,4 +78,34 @@ def get_current_album_art() -> bytes | None:
     return None
 
 
-__all__ = ["get_media_controller", "get_current_album_art"]
+async def get_current_album_art_async() -> bytes | None:
+    """Cross-platform album art fetch. Awaits the controller's impl.
+
+    Falls back to the sync Windows cache when running on Windows so we don't
+    pay an extra coroutine hop for the existing path.
+    """
+    system = platform.system()
+    if system == "Windows":
+        return get_current_album_art()
+    controller = get_media_controller()
+    try:
+        return await controller.get_album_art()
+    except Exception:  # noqa: BLE001 — art is best-effort; never break the route
+        return None
+
+
+def get_audio_devices() -> list[dict[str, str]]:
+    """Get list of available audio output devices (Windows only for now)."""
+    system = platform.system()
+    if system == "Windows":
+        from .windows_media import WindowsMediaController
+        return WindowsMediaController.get_audio_devices()
+    return []
+
+
+__all__ = [
+    "get_media_controller",
+    "get_current_album_art",
+    "get_current_album_art_async",
+    "get_audio_devices",
+]

media_server/services/android_media.py

@@ -10,11 +10,10 @@ Installation:
 4. Grant necessary permissions to Termux:API
 """
 
-import asyncio
 import json
 import logging
 import subprocess
-from typing import Optional, Any
+from typing import Any, Optional
 
 from ..models import MediaState, MediaStatus
 from .media_controller import MediaController

media_server/services/audio_analyzer.py

@@ -0,0 +1,425 @@
+"""Audio spectrum analyzer service using system loopback capture."""
+
+import logging
+import math
+import platform
+import threading
+import time
+
+logger = logging.getLogger(__name__)
+
+_np = None
+_sc = None
+
+
+def _load_numpy():
+    global _np
+    if _np is None:
+        try:
+            import os
+            import sys
+            if sys.platform == 'win32':
+                # Embedded Python doesn't auto-load DLLs from numpy.libs;
+                # add the directory explicitly so libopenblas can be found.
+                try:
+                    import importlib.util
+                    spec = importlib.util.find_spec('numpy')
+                    if spec and spec.submodule_search_locations:
+                        numpy_dir = list(spec.submodule_search_locations)[0]
+                        libs_dir = os.path.join(os.path.dirname(numpy_dir), 'numpy.libs')
+                        if os.path.isdir(libs_dir):
+                            os.add_dll_directory(libs_dir)
+                except Exception:
+                    pass
+            import numpy as np
+            _np = np
+        except Exception as e:
+            logger.warning("numpy unavailable - audio visualizer disabled: %s", e)
+    return _np
+
+
+def _load_soundcard():
+    global _sc
+    if _sc is None:
+        try:
+            import soundcard as sc
+            _sc = sc
+        except Exception as e:
+            logger.warning("soundcard unavailable - audio visualizer disabled: %s", e)
+    return _sc
+
+
+class AudioAnalyzer:
+    """Captures system audio loopback and performs real-time FFT analysis."""
+
+    def __init__(
+        self,
+        num_bins: int = 32,
+        sample_rate: int = 44100,
+        chunk_size: int = 1024,
+        target_fps: int = 30,
+        device_name: str | None = None,
+    ):
+        self.num_bins = num_bins
+        self.sample_rate = sample_rate
+        self.chunk_size = chunk_size
+        self.target_fps = target_fps
+        self.device_name = device_name
+
+        self._running = False
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+        self._lifecycle_lock = threading.Lock()
+        self._data: dict | None = None
+        self._current_device_name: str | None = None
+        # Sticky "no usable device" flag — flipped to True if a capture
+        # attempt fails because no loopback device exists. Prevents the
+        # WebSocket manager from looping on start()/stop()/start() forever
+        # when there's nothing to capture. Cleared by set_device().
+        self._unavailable = False
+        # Generation counter — bumped each time _data is refreshed.
+        # Lets the broadcast loop dedupe without comparing dict identity
+        # (which is fragile because we always allocate a new dict).
+        self._data_seq = 0
+        # Threading.Event signaled when new frame data is available.
+        # The broadcast loop awaits this instead of polling on a timer,
+        # so it wakes up exactly once per produced frame.
+        self._data_event = threading.Event()
+        # Slow AGC envelope so the spectrum reflects real dynamics
+        # instead of being renormalized to peak=1.0 every frame.
+        # A loud transient (e.g. notification beep) lifts the reference
+        # for a few seconds afterwards; this is the price of real loudness.
+        self._spectrum_ref = 0.01
+
+        # Pre-compute logarithmic bin edges
+        self._bin_edges = self._compute_bin_edges()
+
+    def _compute_bin_edges(self) -> list[int]:
+        """Compute logarithmic frequency bin boundaries for perceptual grouping."""
+        np = _load_numpy()
+        if np is None:
+            return []
+
+        fft_size = self.chunk_size // 2 + 1
+        min_freq = 20.0
+        max_freq = min(16000.0, self.sample_rate / 2)
+
+        edges = []
+        for i in range(self.num_bins + 1):
+            freq = min_freq * (max_freq / min_freq) ** (i / self.num_bins)
+            bin_idx = int(freq * self.chunk_size / self.sample_rate)
+            edges.append(min(bin_idx, fft_size - 1))
+        return edges
+
+    @property
+    def available(self) -> bool:
+        """Whether audio capture dependencies are available."""
+        return _load_numpy() is not None and _load_soundcard() is not None
+
+    @property
+    def running(self) -> bool:
+        """Whether capture is currently active."""
+        return self._running
+
+    def start(self) -> bool:
+        """Start audio capture in a background thread. Returns False if unavailable."""
+        with self._lifecycle_lock:
+            if self._running:
+                return True
+            if not self.available:
+                return False
+            if self._unavailable:
+                # We already tried and failed to acquire a device. Don't
+                # spin a new capture thread for each new subscriber.
+                return False
+
+            # Reset AGC envelope so a long silent gap between sessions
+            # doesn't make the first new transients clip at the ceiling.
+            self._spectrum_ref = 0.01
+
+            self._running = True
+            self._thread = threading.Thread(target=self._capture_loop, daemon=True)
+            self._thread.start()
+            return True
+
+    def stop(self) -> None:
+        """Stop audio capture and cleanup."""
+        with self._lifecycle_lock:
+            self._running = False
+            # Wake any waiter so it can observe _running and exit cleanly.
+            self._data_event.set()
+            if self._thread:
+                self._thread.join(timeout=3.0)
+                self._thread = None
+            with self._lock:
+                self._data = None
+            self._data_event.clear()
+
+    def get_frequency_data(self) -> dict | None:
+        """Return latest frequency data (thread-safe). None if not running."""
+        with self._lock:
+            return self._data
+
+    def get_frequency_data_versioned(self) -> tuple[dict | None, int]:
+        """Return (data, seq) so callers can dedupe without identity tricks."""
+        with self._lock:
+            return self._data, self._data_seq
+
+    @property
+    def data_event(self) -> threading.Event:
+        """Event signaled when a fresh frame is ready. Caller must clear()."""
+        return self._data_event
+
+    @staticmethod
+    def list_loopback_devices() -> list[dict[str, str]]:
+        """List all available loopback audio devices."""
+        sc = _load_soundcard()
+        if sc is None:
+            return []
+
+        devices = []
+        try:
+            # COM may be needed on Windows for WASAPI
+            if platform.system() == "Windows":
+                try:
+                    import comtypes
+                    comtypes.CoInitializeEx(comtypes.COINIT_MULTITHREADED)
+                except Exception:
+                    pass
+
+            loopback_mics = sc.all_microphones(include_loopback=True)
+            for mic in loopback_mics:
+                if mic.isloopback:
+                    devices.append({"id": mic.id, "name": mic.name})
+        except Exception as e:
+            logger.warning("Failed to list loopback devices: %s", e)
+
+        return devices
+
+    def _find_loopback_device(self):
+        """Find a loopback device for system audio capture."""
+        sc = _load_soundcard()
+        if sc is None:
+            return None
+
+        try:
+            loopback_mics = sc.all_microphones(include_loopback=True)
+
+            # If a specific device is requested, find it by name (partial match)
+            if self.device_name:
+                target = self.device_name.lower()
+                for mic in loopback_mics:
+                    if mic.isloopback and target in mic.name.lower():
+                        logger.info("Found requested loopback device: %s", mic.name)
+                        self._current_device_name = mic.name
+                        return mic
+                logger.warning("Requested device '%s' not found, falling back to default", self.device_name)
+
+            # Default: first loopback device
+            for mic in loopback_mics:
+                if mic.isloopback:
+                    logger.info("Found loopback device: %s", mic.name)
+                    self._current_device_name = mic.name
+                    return mic
+
+            # Fallback: try to get default speaker's loopback
+            default_speaker = sc.default_speaker()
+            if default_speaker:
+                for mic in loopback_mics:
+                    if default_speaker.name in mic.name:
+                        logger.info("Found speaker loopback: %s", mic.name)
+                        self._current_device_name = mic.name
+                        return mic
+
+        except Exception as e:
+            logger.warning("Failed to find loopback device: %s", e)
+
+        return None
+
+    def set_device(self, device_name: str | None) -> bool:
+        """Change the loopback device. Restarts capture if running. Returns True on success."""
+        was_running = self._running
+        if was_running:
+            self.stop()
+
+        self.device_name = device_name
+        self._current_device_name = None
+        # Clear the "no device" sticky flag — the user is asking for a
+        # different device so it's worth attempting capture again.
+        self._unavailable = False
+
+        if was_running:
+            return self.start()
+        return True
+
+    @property
+    def current_device(self) -> str | None:
+        """Return the name of the currently active loopback device."""
+        return self._current_device_name
+
+    def _capture_loop(self) -> None:
+        """Background thread: capture audio and compute FFT continuously."""
+        # Initialize COM on Windows (required for WASAPI/SoundCard)
+        if platform.system() == "Windows":
+            try:
+                import comtypes
+                comtypes.CoInitializeEx(comtypes.COINIT_MULTITHREADED)
+            except Exception:
+                try:
+                    import ctypes
+                    ctypes.windll.ole32.CoInitializeEx(0, 0)
+                except Exception as e:
+                    logger.warning("Failed to initialize COM: %s", e)
+
+        np = _load_numpy()
+        sc = _load_soundcard()
+        if np is None or sc is None:
+            self._running = False
+            return
+
+        device = self._find_loopback_device()
+        if device is None:
+            logger.warning("No loopback audio device found - visualizer disabled")
+            self._running = False
+            self._unavailable = True
+            return
+
+        interval = 1.0 / self.target_fps
+        # Float32 window — matches soundcard's typical buffer dtype and
+        # halves FFT memory traffic vs. the default float64.
+        window = np.hanning(self.chunk_size).astype(np.float32)
+
+        # Pre-compute bin edge pairs for vectorized grouping
+        edges = self._bin_edges
+        bin_starts = np.array([edges[i] for i in range(self.num_bins)], dtype=np.intp)
+        bin_ends = np.array([max(edges[i + 1], edges[i] + 1) for i in range(self.num_bins)], dtype=np.intp)
+        # Counts are constant — compute once.
+        bin_counts = (bin_ends - bin_starts).astype(np.float32)
+
+        # Pre-allocate working buffers so the per-frame allocator churn
+        # on the capture thread (which runs at target_fps Hz, hours on
+        # end) drops to zero copies for these arrays.
+        fft_size = self.chunk_size // 2 + 1
+        windowed = np.empty(self.chunk_size, dtype=np.float32)
+        cumsum = np.empty(fft_size + 1, dtype=np.float32)
+        cumsum[0] = 0.0
+
+        try:
+            with device.recorder(
+                samplerate=self.sample_rate,
+                channels=1,
+                blocksize=self.chunk_size,
+            ) as recorder:
+                logger.info("Audio capture started on: %s", device.name)
+                while self._running:
+                    t0 = time.monotonic()
+
+                    try:
+                        data = recorder.record(numframes=self.chunk_size)
+                    except Exception as e:
+                        logger.debug("Audio capture read error: %s", e)
+                        time.sleep(interval)
+                        continue
+
+                    # Mono mix if needed
+                    if data.ndim > 1:
+                        mono = data.mean(axis=1)
+                    else:
+                        mono = data.ravel()
+
+                    if len(mono) < self.chunk_size:
+                        time.sleep(interval)
+                        continue
+
+                    # Apply window in-place into the pre-allocated buffer.
+                    np.multiply(mono[:self.chunk_size], window, out=windowed)
+                    fft_mag = np.abs(np.fft.rfft(windowed))
+
+                    # Group into logarithmic bins (vectorized via cumsum).
+                    # Write into the pre-allocated [1:] slice so cumsum[0]
+                    # stays 0.0 and we never allocate a new array.
+                    np.cumsum(fft_mag, out=cumsum[1:])
+                    bins = (cumsum[bin_ends] - cumsum[bin_starts]) / bin_counts
+
+                    # True loudness from time-domain RMS via single BLAS
+                    # dot — avoids astype() and ** allocations.
+                    mono32 = mono if mono.dtype == np.float32 else mono.astype(np.float32, copy=False)
+                    energy = float(np.dot(mono32, mono32))
+                    if energy > 1e-12:
+                        rms = (energy / mono32.size) ** 0.5
+                        db = 20.0 * math.log10(rms)
+                        # Map -60 dB..-6 dB to 0..1 (typical music range)
+                        level = max(0.0, min(1.0, (db + 60.0) / 54.0))
+                    else:
+                        level = 0.0
+
+                    # Slow auto-gain: envelope follower with fast attack,
+                    # slow release. Quiet music yields small bars; loud
+                    # passages reach the top; the reference adapts over
+                    # seconds instead of resetting every frame.
+                    current_peak = float(bins.max())
+                    if current_peak > self._spectrum_ref:
+                        self._spectrum_ref += (current_peak - self._spectrum_ref) * 0.05
+                    else:
+                        self._spectrum_ref += (current_peak - self._spectrum_ref) * 0.005
+                    ref = max(self._spectrum_ref, 1e-4)
+                    np.divide(bins, ref, out=bins)
+                    np.clip(bins, 0.0, 1.5, out=bins)
+
+                    # Bass energy: average of first 4 bins (~20-200Hz)
+                    bass = float(bins[:4].mean()) if self.num_bins >= 4 else 0.0
+
+                    # Quantize to 0..1000 ints — same wire fidelity as
+                    # 3-decimal floats but smaller GC churn on both ends
+                    # (frontend smooths anyway, so quantization is
+                    # invisible). JSON encodes ints faster than floats.
+                    frequencies = (bins * 1000.0).astype(np.int16).tolist()
+                    bass_i = int(bass * 1000.0)
+                    level_i = int(level * 1000.0)
+
+                    new_data = {
+                        "frequencies": frequencies,
+                        "bass": bass_i,
+                        "level": level_i,
+                        # Wire-format flag: clients that see this know
+                        # values are 0..1000 ints, not 0..1 floats.
+                        "scale": 1000,
+                    }
+                    with self._lock:
+                        self._data = new_data
+                        self._data_seq += 1
+                    # Wake any broadcast loop waiting on fresh data.
+                    self._data_event.set()
+
+                    # Throttle to target FPS
+                    elapsed = time.monotonic() - t0
+                    if elapsed < interval:
+                        time.sleep(interval - elapsed)
+
+        except Exception as e:
+            logger.error("Audio capture loop error: %s", e)
+        finally:
+            self._running = False
+            logger.info("Audio capture stopped")
+
+
+# Global singleton
+_analyzer: AudioAnalyzer | None = None
+
+
+def get_audio_analyzer(
+    num_bins: int = 32,
+    sample_rate: int = 44100,
+    target_fps: int = 25,
+    device_name: str | None = None,
+) -> AudioAnalyzer:
+    """Get or create the global AudioAnalyzer instance."""
+    global _analyzer
+    if _analyzer is None:
+        _analyzer = AudioAnalyzer(
+            num_bins=num_bins,
+            sample_rate=sample_rate,
+            target_fps=target_fps,
+            device_name=device_name,
+        )
+    return _analyzer

media_server/services/audit_log.py

@@ -0,0 +1,120 @@
+"""Append-only audit log for sensitive actions (script + callback execution).
+
+Writes a single JSONL line per event to ``<config_dir>/audit.log``. The log is
+write-only from the app's perspective — it never reads back, and rotation is
+left to the operator (the file size is dominated by stdout/stderr truncation,
+which is already capped at 10 KB per stream in `_run_script`).
+
+Designed to be cheap: the write goes through a small background thread so the
+hot path never blocks on disk I/O, and a failure to write is logged at WARNING
+but never raised to callers.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import queue
+import threading
+import time
+from typing import Any
+
+from ..auth import token_label_var
+from ..config import get_config_dir
+
+logger = logging.getLogger(__name__)
+
+# Cap on stdout/stderr inside the audit record so a chatty script doesn't
+# explode the log. Mirrors the 10k cap used by _run_script.
+_OUTPUT_CAP = 2000
+
+_audit_queue: "queue.Queue[dict[str, Any] | None]" = queue.Queue(maxsize=1000)
+_audit_thread: threading.Thread | None = None
+_audit_lock = threading.Lock()
+
+
+def _ensure_writer_started() -> None:
+    global _audit_thread
+    with _audit_lock:
+        if _audit_thread is not None and _audit_thread.is_alive():
+            return
+        _audit_thread = threading.Thread(
+            target=_audit_writer_loop,
+            name="audit-log",
+            daemon=True,
+        )
+        _audit_thread.start()
+
+
+def _audit_writer_loop() -> None:
+    log_path = get_config_dir() / "audit.log"
+    while True:
+        try:
+            record = _audit_queue.get()
+        except Exception:
+            return
+        if record is None:
+            return
+        try:
+            line = json.dumps(record, ensure_ascii=False, default=str)
+            with open(log_path, "a", encoding="utf-8") as f:
+                f.write(line + "\n")
+        except OSError as e:
+            logger.warning("Failed to write audit record: %s", e)
+
+
+def _truncate(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if len(value) <= _OUTPUT_CAP:
+        return value
+    return value[:_OUTPUT_CAP] + f"\n…[truncated, {len(value) - _OUTPUT_CAP} chars]"
+
+
+def record_script_execution(
+    *,
+    kind: str,
+    name: str,
+    exit_code: int | None,
+    duration: float | None,
+    stdout: str | None = None,
+    stderr: str | None = None,
+    error: str | None = None,
+) -> None:
+    """Append a single audit record. Never raises."""
+    _ensure_writer_started()
+    try:
+        record = {
+            "ts": time.time(),
+            "iso": time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime()),
+            "token_label": token_label_var.get("unknown"),
+            "kind": kind,
+            "name": name,
+            "exit_code": exit_code,
+            "duration_s": round(duration, 4) if duration is not None else None,
+            "success": exit_code == 0 if exit_code is not None else False,
+            "stdout": _truncate(stdout),
+            "stderr": _truncate(stderr),
+            "error": error,
+        }
+        _audit_queue.put_nowait(record)
+    except queue.Full:
+        # Backpressure: drop oldest record to make room. We'd rather lose an
+        # old entry than block the script that just ran.
+        try:
+            _audit_queue.get_nowait()
+            _audit_queue.put_nowait(record)
+        except queue.Empty:
+            pass
+    except Exception as e:
+        logger.warning("Failed to enqueue audit record: %s", e)
+
+
+def shutdown_audit_log() -> None:
+    """Flush the audit queue on app shutdown."""
+    try:
+        _audit_queue.put_nowait(None)
+    except queue.Full:
+        pass
+    if _audit_thread is not None:
+        _audit_thread.join(timeout=2)

media_server/services/browser_service.py

@@ -0,0 +1,341 @@
+"""Browser service for media file browsing and path validation."""
+
+import logging
+import stat as stat_module
+import time
+from datetime import datetime
+from pathlib import Path
+
+from ..config import settings
+
+# Directory listing cache: {resolved_path_str: (timestamp, all_items)}
+_dir_cache: dict[str, tuple[float, list[dict]]] = {}
+DIR_CACHE_TTL = 300  # 5 minutes
+
+# Media info cache: {(file_path_str, mtime): {duration, bitrate, title}}
+_media_info_cache: dict[tuple[str, float], dict] = {}
+_MEDIA_INFO_CACHE_MAX = 5000
+
+try:
+    from mutagen import File as MutagenFile
+    HAS_MUTAGEN = True
+except ImportError:
+    HAS_MUTAGEN = False
+
+logger = logging.getLogger(__name__)
+
+# Media file extensions
+AUDIO_EXTENSIONS = {".mp3", ".m4a", ".flac", ".wav", ".ogg", ".aac", ".wma", ".opus"}
+VIDEO_EXTENSIONS = {".mp4", ".mkv", ".avi", ".mov", ".wmv", ".webm", ".flv"}
+MEDIA_EXTENSIONS = AUDIO_EXTENSIONS | VIDEO_EXTENSIONS
+
+
+class BrowserService:
+    """Service for browsing media files with path validation."""
+
+    @staticmethod
+    def validate_path(folder_id: str, requested_path: str) -> Path:
+        """Validate and resolve a path within an allowed folder.
+
+        Args:
+            folder_id: ID of the configured media folder.
+            requested_path: Path to validate (relative to folder root or absolute).
+
+        Returns:
+            Resolved absolute Path object.
+
+        Raises:
+            ValueError: If folder_id invalid or path traversal attempted.
+            FileNotFoundError: If path does not exist.
+        """
+        # Get folder config
+        if folder_id not in settings.media_folders:
+            raise ValueError(f"Media folder '{folder_id}' not configured")
+
+        folder_config = settings.media_folders[folder_id]
+        if not folder_config.enabled:
+            raise ValueError(f"Media folder '{folder_id}' is disabled")
+
+        # Get base path
+        base_path = Path(folder_config.path).resolve()
+        if not base_path.exists():
+            raise FileNotFoundError(f"Media folder path does not exist: {base_path}")
+        if not base_path.is_dir():
+            raise ValueError(f"Media folder path is not a directory: {base_path}")
+
+        # Reject absolute paths, drive letters, UNC paths, and NUL bytes outright.
+        # Only true folder-relative paths are accepted.
+        if "\x00" in requested_path:
+            raise ValueError("Path contains NUL byte")
+
+        # Strip a single leading "/" or "\\" (legacy callers send "/sub/dir") but
+        # then refuse anything that still looks absolute.
+        cleaned = requested_path.lstrip("/\\")
+        # Detect Windows drive letter like "C:/..." after stripping.
+        if len(cleaned) >= 2 and cleaned[1] == ":":
+            raise ValueError("Absolute paths are not allowed")
+        # Detect raw UNC ("\\\\server\\share") — the lstrip above strips at most
+        # one leading slash, so a UNC original starts with another "\\" or "/".
+        if cleaned.startswith("\\") or cleaned.startswith("/"):
+            raise ValueError("Absolute paths are not allowed")
+        candidate = Path(cleaned) if cleaned else None
+        if candidate is not None and candidate.is_absolute():
+            raise ValueError("Absolute paths are not allowed")
+
+        # Build and resolve full path
+        if cleaned:
+            full_path = (base_path / cleaned).resolve()
+        else:
+            full_path = base_path
+
+        # Security check: Ensure resolved path is within base path
+        try:
+            full_path.relative_to(base_path)
+        except ValueError:
+            logger.warning(
+                f"Path traversal attempt detected: {requested_path} "
+                f"(resolved to {full_path}, base: {base_path})"
+            )
+            raise ValueError("Path traversal not allowed")
+
+        # Check if path exists
+        if not full_path.exists():
+            raise FileNotFoundError(f"Path does not exist: {requested_path}")
+
+        return full_path
+
+    @staticmethod
+    def is_media_file(path: Path) -> bool:
+        """Check if a file is a media file based on extension.
+
+        Args:
+            path: Path to check.
+
+        Returns:
+            True if file is a media file, False otherwise.
+        """
+        return path.suffix.lower() in MEDIA_EXTENSIONS
+
+    @staticmethod
+    def get_file_type(path: Path) -> str:
+        """Get the file type (folder, audio, video, other).
+
+        Args:
+            path: Path to check.
+
+        Returns:
+            File type string: "folder", "audio", "video", or "other".
+        """
+        if path.is_dir():
+            return "folder"
+
+        suffix = path.suffix.lower()
+        if suffix in AUDIO_EXTENSIONS:
+            return "audio"
+        elif suffix in VIDEO_EXTENSIONS:
+            return "video"
+        else:
+            return "other"
+
+    @staticmethod
+    def get_media_info(file_path: Path, mtime: float | None = None) -> dict:
+        """Get duration, bitrate, and title of a media file (header-only read).
+
+        Results are cached by (path, mtime) to avoid re-reading unchanged files.
+
+        Args:
+            file_path: Path to the media file.
+            mtime: File modification time (avoids an extra stat call).
+
+        Returns:
+            Dict with 'duration' (float or None), 'bitrate' (int or None),
+            and 'title' (str or None).
+        """
+        result = {"duration": None, "bitrate": None, "title": None}
+        if not HAS_MUTAGEN:
+            return result
+
+        # Use mtime-based cache to skip mutagen reads for unchanged files
+        if mtime is None:
+            try:
+                mtime = file_path.stat().st_mtime
+            except (OSError, PermissionError):
+                pass
+
+        if mtime is not None:
+            cache_key = (str(file_path), mtime)
+            cached = _media_info_cache.get(cache_key)
+            if cached is not None:
+                return cached
+
+        try:
+            audio = MutagenFile(str(file_path), easy=True)
+            if audio is not None and hasattr(audio, "info"):
+                if hasattr(audio.info, "length"):
+                    result["duration"] = round(audio.info.length, 2)
+                if hasattr(audio.info, "bitrate") and audio.info.bitrate:
+                    result["bitrate"] = audio.info.bitrate
+            if audio is not None and hasattr(audio, "tags") and audio.tags:
+                tags = audio.tags
+                title = None
+                artist = None
+                if "title" in tags:
+                    title = tags["title"][0] if isinstance(tags["title"], list) else tags["title"]
+                if "artist" in tags:
+                    artist = tags["artist"][0] if isinstance(tags["artist"], list) else tags["artist"]
+                if artist and title:
+                    result["title"] = f"{artist} \u2013 {title}"
+                elif title:
+                    result["title"] = title
+        except Exception:
+            pass
+
+        # Cache result (evict oldest entries if cache is full)
+        if mtime is not None:
+            if len(_media_info_cache) >= _MEDIA_INFO_CACHE_MAX:
+                # Remove oldest ~20% of entries
+                to_remove = list(_media_info_cache.keys())[:_MEDIA_INFO_CACHE_MAX // 5]
+                for k in to_remove:
+                    del _media_info_cache[k]
+            _media_info_cache[(str(file_path), mtime)] = result
+
+        return result
+
+    @staticmethod
+    def browse_directory(
+        folder_id: str,
+        path: str = "",
+        offset: int = 0,
+        limit: int = 100,
+        nocache: bool = False,
+    ) -> dict:
+        """Browse a directory and return items with metadata.
+
+        Args:
+            folder_id: ID of the configured media folder.
+            path: Path to browse (relative to folder root).
+            offset: Pagination offset (default: 0).
+            limit: Maximum items to return (default: 100).
+
+        Returns:
+            Dictionary with:
+                - current_path: Current path (relative to folder root)
+                - parent_path: Parent path (None if at root)
+                - items: List of file/folder items
+                - total: Total number of items
+                - offset: Current offset
+                - limit: Current limit
+                - folder_id: Folder ID
+
+        Raises:
+            ValueError: If path validation fails.
+            FileNotFoundError: If path does not exist.
+        """
+        # Validate path
+        full_path = BrowserService.validate_path(folder_id, path)
+
+        # Get base path for relative path calculation
+        folder_config = settings.media_folders[folder_id]
+        base_path = Path(folder_config.path).resolve()
+
+        # Check if it's a directory
+        if not full_path.is_dir():
+            raise ValueError(f"Path is not a directory: {path}")
+
+        # Calculate relative path
+        try:
+            relative_path = full_path.relative_to(base_path)
+            current_path = "/" + str(relative_path).replace("\\", "/") if str(relative_path) != "." else "/"
+        except ValueError:
+            current_path = "/"
+
+        # Calculate parent path
+        if full_path == base_path:
+            parent_path = None
+        else:
+            parent_relative = full_path.parent.relative_to(base_path)
+            parent_path = "/" + str(parent_relative).replace("\\", "/") if str(parent_relative) != "." else "/"
+
+        # List directory contents (with caching)
+        try:
+            cache_key = str(full_path)
+            now = time.monotonic()
+
+            # Check cache
+            if not nocache and cache_key in _dir_cache:
+                cached_time, cached_items = _dir_cache[cache_key]
+                if now - cached_time < DIR_CACHE_TTL:
+                    all_items = cached_items
+                else:
+                    del _dir_cache[cache_key]
+                    all_items = None
+            else:
+                all_items = None
+
+            # Enumerate directory if not cached
+            if all_items is None:
+                all_items = []
+                for item in full_path.iterdir():
+                    if item.name.startswith("."):
+                        continue
+
+                    # Single stat() call per item — reuse for type check and metadata
+                    try:
+                        st = item.stat()
+                    except (OSError, PermissionError):
+                        continue
+
+                    if stat_module.S_ISDIR(st.st_mode):
+                        file_type = "folder"
+                    else:
+                        suffix = item.suffix.lower()
+                        if suffix in AUDIO_EXTENSIONS:
+                            file_type = "audio"
+                        elif suffix in VIDEO_EXTENSIONS:
+                            file_type = "video"
+                        else:
+                            continue
+
+                    all_items.append({
+                        "name": item.name,
+                        "type": file_type,
+                        "is_media": file_type in ("audio", "video"),
+                        "_size": st.st_size,
+                        "_mtime": st.st_mtime,
+                    })
+
+                all_items.sort(key=lambda x: (x["type"] != "folder", x["name"].lower()))
+                _dir_cache[cache_key] = (now, all_items)
+
+            # Apply pagination
+            total = len(all_items)
+            items = all_items[offset:offset + limit]
+
+            # Enrich items on the current page with metadata
+            for item in items:
+                item["size"] = item["_size"] if item["type"] != "folder" else None
+                item["modified"] = datetime.fromtimestamp(item["_mtime"]).isoformat()
+
+                if item["is_media"]:
+                    item_path = full_path / item["name"]
+                    info = BrowserService.get_media_info(item_path, item["_mtime"])
+                    item["duration"] = info["duration"]
+                    item["bitrate"] = info["bitrate"]
+                    item["title"] = info["title"]
+                else:
+                    item["duration"] = None
+                    item["bitrate"] = None
+                    item["title"] = None
+
+            return {
+                "folder_id": folder_id,
+                "current_path": current_path,
+                "parent_path": parent_path,
+                "items": items,
+                "total": total,
+                "offset": offset,
+                "limit": limit,
+            }
+
+        except PermissionError:
+            raise ValueError(f"Permission denied accessing path: {path}")

media_server/services/browser_url_service.py

@@ -0,0 +1,296 @@
+"""Extract page-level metadata from a focused desktop web browser.
+
+The browser's window title is the reliable signal — every major browser
+formats it as ``"<page title> - <Browser Name>"``, so stripping the suffix
+gives us the page title for free.
+
+URL extraction was attempted via UI Automation (UIA), but Chromium-based
+browsers (Chrome/Edge/Brave/Vivaldi) keep their accessibility tree dormant
+unless a screen reader is active or ``--force-renderer-accessibility`` is
+set — neither is something we want to require from end users. The UIA
+machinery is still here behind a feature flag in case a future caller
+opts into the accessibility-flag path; by default we just return the
+page title and leave ``url=None``.
+
+Other platforms (macOS via AppleScript, Linux via AT-SPI) are out of scope
+for this iteration.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import threading
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+# UIA URL extraction is opt-in because Chromium browsers keep their
+# accessibility tree dormant unless the user starts the browser with
+# ``--force-renderer-accessibility`` (or a screen reader is running).
+# Without that, `FindAll` throws and we'd burn 5s per probe retrying.
+# Set MEDIA_SERVER_BROWSER_UIA=1 to enable; default off.
+_UIA_ENABLED = os.environ.get("MEDIA_SERVER_BROWSER_UIA", "").lower() in (
+    "1", "true", "yes", "on"
+)
+
+
+# Known browser executables (lowercase, .exe-stripped). Used to decide
+# whether to spend the UIA query budget on this foreground process.
+BROWSER_PROCESS_HINTS: frozenset[str] = frozenset({
+    "chrome",
+    "msedge",
+    "firefox",
+    "brave",
+    "opera",
+    "vivaldi",
+    "yandex",
+    "browser",  # Yandex Browser sometimes reports as browser.exe
+    "arc",
+    "thorium",
+})
+
+
+@dataclass(frozen=True)
+class BrowserPageInfo:
+    url: str | None = None
+    page_title: str | None = None
+
+
+_EMPTY = BrowserPageInfo()
+
+
+def is_browser_process(process_name: str | None) -> bool:
+    """Return True when ``process_name`` looks like a supported browser."""
+    if not process_name:
+        return False
+    base = process_name.lower()
+    if base.endswith(".exe"):
+        base = base[:-4]
+    return base in BROWSER_PROCESS_HINTS
+
+
+def _strip_browser_suffix(title: str | None, process_name: str | None) -> str | None:
+    """Pull the page title out of the browser's window title.
+
+    Most browsers format their window title as ``"<page> - <Browser Name>"``.
+    We strip the trailing suffix so consumers get the page title alone. If
+    the suffix can't be matched, return the raw title unchanged.
+    """
+    if not title:
+        return None
+    suffixes = (
+        " - Google Chrome",
+        " — Google Chrome",
+        " - Microsoft Edge",
+        " - Microsoft Edge",
+        " — Mozilla Firefox",
+        " - Mozilla Firefox",
+        " - Brave",
+        " - Opera",
+        " - Vivaldi",
+        " - Yandex",
+    )
+    for s in suffixes:
+        if title.endswith(s):
+            return title[: -len(s)].strip() or None
+    return title
+
+
+# ─── UIA lookup (Windows) ───────────────────────────────────────────
+
+# UIA control type / property constants we need. Avoiding the full
+# UIAutomationClient typelib generation — those constants are stable.
+_UIA_EditControlTypeId = 50004
+_UIA_ControlTypePropertyId = 30003
+_UIA_ValueValuePropertyId = 30045
+_UIA_NamePropertyId = 30005
+_UIA_ValuePatternId = 10002
+_TreeScope_Descendants = 4
+_PropertyConditionFlags_IgnoreCase = 1
+
+
+# Lazy import + per-thread COM init.
+_uia_lock = threading.Lock()
+_uia_singleton = None
+_uia_load_error: str | None = None
+_uia_thread_local = threading.local()
+
+
+def _ensure_com() -> None:
+    """Initialise COM on the current thread (idempotent per thread)."""
+    if getattr(_uia_thread_local, "initialised", False):
+        return
+    try:
+        import comtypes  # type: ignore
+
+        # COINIT_APARTMENTTHREADED is required by UIA; comtypes' default
+        # CoInitializeEx already passes that flag.
+        comtypes.CoInitialize()
+        _uia_thread_local.initialised = True
+    except Exception as e:
+        logger.debug("CoInitialize failed: %s", e)
+
+
+def _get_uia():
+    """Return the IUIAutomation singleton, or None if unavailable."""
+    global _uia_singleton, _uia_load_error
+    if _uia_singleton is not None:
+        return _uia_singleton
+    if _uia_load_error is not None:
+        return None
+    with _uia_lock:
+        if _uia_singleton is not None:
+            return _uia_singleton
+        try:
+            import comtypes.client  # type: ignore
+
+            # CLSID for CUIAutomation. Using GetActiveObject would fail,
+            # so we cocreate. comtypes.client.CreateObject keeps the COM
+            # plumbing tidy.
+            _uia_singleton = comtypes.client.CreateObject(
+                "{ff48dba4-60ef-4201-aa87-54103eef594e}",
+                interface=comtypes.client.GetModule(
+                    "UIAutomationCore.dll"
+                ).IUIAutomation,
+            )
+            return _uia_singleton
+        except Exception as e:
+            _uia_load_error = str(e)
+            logger.info("UIA unavailable; browser URL extraction disabled: %s", e)
+            return None
+
+
+def _find_address_bar_value(hwnd: int) -> str | None:
+    """Walk the UIA tree under ``hwnd`` looking for the URL Edit control.
+
+    Strategy: find every descendant Edit control, then pick the first one
+    whose Name contains an address-bar hint, or — failing that — the first
+    one whose value parses as a URL-ish string. Browsers expose extra Edit
+    controls (search bars, find-in-page) so name matching is the reliable
+    signal; the URL-ish fallback covers locale variants we haven't seen.
+    """
+    _ensure_com()
+    uia = _get_uia()
+    if uia is None:
+        return None
+
+    try:
+        element = uia.ElementFromHandle(hwnd)
+        if not element:
+            return None
+
+        # Build a condition matching ControlType=Edit, then enumerate.
+        edit_condition = uia.CreatePropertyCondition(
+            _UIA_ControlTypePropertyId, _UIA_EditControlTypeId
+        )
+        edits = element.FindAll(_TreeScope_Descendants, edit_condition)
+        count = edits.Length if edits else 0
+        if count == 0:
+            return None
+
+        # Hints (lowercase) used to identify the address bar by its Name
+        # property. Covers en-US plus a few common locales / browsers.
+        name_hints = (
+            "address",          # Chrome/Edge: "Address and search bar"
+            "адрес",            # Chrome ru: "Адресная строка и строка поиска"
+            "адресная",
+            "search with",      # Firefox: "Search with Google or enter address"
+            "поиск или ввод",   # Firefox ru
+            "url",
+            "location",
+        )
+
+        # First pass: name-based match (high confidence).
+        candidates: list[tuple[int, str]] = []
+        for i in range(count):
+            edit = edits.GetElement(i)
+            try:
+                name = (edit.CurrentName or "").lower()
+            except Exception:
+                name = ""
+            try:
+                value = edit.GetCurrentPropertyValue(_UIA_ValueValuePropertyId)
+            except Exception:
+                value = None
+            if value is None:
+                continue
+            value_str = str(value)
+            for h in name_hints:
+                if h in name:
+                    return value_str
+            candidates.append((i, value_str))
+
+        # Second pass: URL-ish fallback. Pick the first candidate that
+        # looks like a URL; this catches browser/locale combos we haven't
+        # listed above.
+        for _i, v in candidates:
+            lv = v.lower()
+            if (
+                lv.startswith("http://")
+                or lv.startswith("https://")
+                or lv.startswith("about:")
+                or lv.startswith("chrome://")
+                or lv.startswith("edge://")
+                or lv.startswith("brave://")
+                or lv.startswith("file://")
+                or lv.startswith("ftp://")
+            ):
+                return v
+
+        return None
+    except Exception as e:
+        logger.debug("UIA address-bar lookup failed: %s", e)
+        return None
+
+
+# ─── Per-(hwnd, title) cache ────────────────────────────────────────
+
+_cache_lock = threading.Lock()
+_cache_key: tuple[int | None, str | None] = (None, None)
+_cache_value: BrowserPageInfo = _EMPTY
+
+
+def get_browser_page(
+    *,
+    hwnd: int | None,
+    process_name: str | None,
+    window_title: str | None,
+) -> BrowserPageInfo:
+    """Return the URL + page title for the foreground browser tab, if any.
+
+    Callers pass the already-resolved foreground HWND/title/process_name so
+    this service doesn't re-walk Win32 to find them. Returns ``_EMPTY`` for
+    non-browser processes or when UIA can't resolve the URL.
+    """
+    if not is_browser_process(process_name):
+        return _EMPTY
+    if platform.system() != "Windows":
+        # macOS/Linux paths not implemented in this iteration.
+        return _EMPTY
+    if not hwnd:
+        return _EMPTY
+
+    global _cache_key, _cache_value
+    key = (hwnd, window_title)
+    with _cache_lock:
+        if key == _cache_key and _cache_value is not _EMPTY:
+            return _cache_value
+
+    url = _find_address_bar_value(hwnd) if _UIA_ENABLED else None
+    page_title = _strip_browser_suffix(window_title, process_name)
+    info = BrowserPageInfo(url=url, page_title=page_title)
+
+    with _cache_lock:
+        _cache_key = key
+        _cache_value = info
+    return info
+
+
+def reset_cache() -> None:
+    """Reset the cache. Useful in tests."""
+    global _cache_key, _cache_value
+    with _cache_lock:
+        _cache_key = (None, None)
+        _cache_value = _EMPTY

media_server/services/display_service.py

@@ -0,0 +1,676 @@
+"""Display brightness, power, contrast, input-source and color-preset control."""
+
+import ctypes
+import ctypes.wintypes
+import logging
+import platform
+import struct
+import time
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+# VCP 0xDC "Display Application" — picture / scene mode.
+# Vendors deviate from the MCCS spec, but these labels match the standard
+# meanings and cover what most monitors report through their capability
+# string. Unknown codes fall back to "Mode <n>".
+PICTURE_MODE_VCP = 0xDC
+PICTURE_MODE_LABELS: dict[int, str] = {
+    0x00: "Default",
+    0x01: "Standalone",
+    0x02: "Mixed",
+    0x03: "Productivity",
+    0x04: "Movie",
+    0x05: "Game",
+    0x06: "Sports",
+    0x07: "Professional",
+    0x08: "Standard",
+    0x09: "Default",
+    0x0A: "Movie (Reduced Effects)",
+    0x0B: "Movie (Enhanced)",
+    0x0C: "User 1",
+    0x0D: "User 2",
+    0x0E: "User 3",
+}
+
+_sbc = None
+_monitorcontrol = None
+
+
+def _load_sbc():
+    global _sbc
+    if _sbc is None:
+        try:
+            import screen_brightness_control as sbc
+            _sbc = sbc
+        except ImportError:
+            logger.warning("screen_brightness_control not installed - brightness control unavailable")
+    return _sbc
+
+
+def _load_monitorcontrol():
+    global _monitorcontrol
+    if _monitorcontrol is None:
+        try:
+            import monitorcontrol
+            _monitorcontrol = monitorcontrol
+        except ImportError:
+            logger.warning("monitorcontrol not installed - DDC/CI control unavailable")
+    return _monitorcontrol
+
+
+def _parse_edid_resolution(edid_hex: str) -> str | None:
+    """Parse resolution from EDID hex string (first detailed timing descriptor)."""
+    try:
+        edid = bytes.fromhex(edid_hex)
+        if len(edid) < 58:
+            return None
+        dtd = edid[54:]
+        pixel_clock = struct.unpack('<H', dtd[0:2])[0]
+        if pixel_clock == 0:
+            return None
+        h_active = dtd[2] | ((dtd[4] >> 4) << 8)
+        v_active = dtd[5] | ((dtd[7] >> 4) << 8)
+        return f"{h_active}x{v_active}"
+    except Exception:
+        return None
+
+
+@dataclass
+class MonitorInfo:
+    id: int
+    name: str
+    brightness: int | None
+    power_supported: bool
+    power_on: bool = True
+    model: str = ""
+    manufacturer: str = ""
+    resolution: str | None = None
+    is_primary: bool = False
+    contrast: int | None = None
+    contrast_supported: bool = False
+    input_source: str | None = None
+    available_input_sources: list[str] = field(default_factory=list)
+    input_source_supported: bool = False
+    color_preset: str | None = None
+    available_color_presets: list[str] = field(default_factory=list)
+    color_preset_supported: bool = False
+    picture_mode: str | None = None
+    picture_mode_code: int | None = None
+    available_picture_modes: list[dict] = field(default_factory=list)
+    picture_mode_supported: bool = False
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "brightness": self.brightness,
+            "power_supported": self.power_supported,
+            "power_on": self.power_on,
+            "model": self.model,
+            "manufacturer": self.manufacturer,
+            "resolution": self.resolution,
+            "is_primary": self.is_primary,
+            "contrast": self.contrast,
+            "contrast_supported": self.contrast_supported,
+            "input_source": self.input_source,
+            "available_input_sources": self.available_input_sources,
+            "input_source_supported": self.input_source_supported,
+            "color_preset": self.color_preset,
+            "available_color_presets": self.available_color_presets,
+            "color_preset_supported": self.color_preset_supported,
+            "picture_mode": self.picture_mode,
+            "picture_mode_code": self.picture_mode_code,
+            "available_picture_modes": self.available_picture_modes,
+            "picture_mode_supported": self.picture_mode_supported,
+        }
+
+
+def _detect_primary_resolution() -> str | None:
+    """Detect the primary display resolution via Windows API."""
+    if platform.system() != "Windows":
+        return None
+    try:
+        class MONITORINFO(ctypes.Structure):
+            _fields_ = [
+                ("cbSize", ctypes.wintypes.DWORD),
+                ("rcMonitor", ctypes.wintypes.RECT),
+                ("rcWork", ctypes.wintypes.RECT),
+                ("dwFlags", ctypes.wintypes.DWORD),
+            ]
+
+        MONITORINFOF_PRIMARY = 1
+        primary_res = None
+
+        def callback(hmon, hdc, rect, data):
+            nonlocal primary_res
+            mi = MONITORINFO()
+            mi.cbSize = ctypes.sizeof(mi)
+            ctypes.windll.user32.GetMonitorInfoW(hmon, ctypes.byref(mi))
+            if mi.dwFlags & MONITORINFOF_PRIMARY:
+                w = mi.rcMonitor.right - mi.rcMonitor.left
+                h = mi.rcMonitor.bottom - mi.rcMonitor.top
+                primary_res = f"{w}x{h}"
+            return True
+
+        MONITORENUMPROC = ctypes.WINFUNCTYPE(
+            ctypes.c_int,
+            ctypes.wintypes.HMONITOR,
+            ctypes.wintypes.HDC,
+            ctypes.POINTER(ctypes.wintypes.RECT),
+            ctypes.wintypes.LPARAM,
+        )
+        ctypes.windll.user32.EnumDisplayMonitors(
+            None, None, MONITORENUMPROC(callback), 0
+        )
+        return primary_res
+    except Exception:
+        return None
+
+
+def _mark_primary(monitors: list[MonitorInfo]) -> None:
+    """Mark the primary display in the monitor list."""
+    if not monitors:
+        return
+
+    primary_res = _detect_primary_resolution()
+    if primary_res:
+        for m in monitors:
+            if m.resolution == primary_res:
+                m.is_primary = True
+                return
+
+    # Fallback: mark first monitor as primary
+    monitors[0].is_primary = True
+
+
+# Short TTL cache of the assembled monitor list (full response).
+_monitor_cache: list[MonitorInfo] | None = None
+_cache_time: float = 0
+_CACHE_TTL = 5.0  # seconds
+
+# Per-monitor cache of static capabilities (option lists + support flags).
+# DDC/CI capability discovery is the slow part — it only changes when a
+# monitor is replaced or rewired, so we probe it once per monitor and reuse
+# it across refreshes. Keyed by a stable identity tuple
+# (manufacturer, model, edid_hash) so that hot-plug swaps where the new
+# topology has the same number of monitors but different devices still
+# refresh the cache for the new monitor instead of serving stale capabilities.
+_static_cache: dict[tuple, dict] = {}
+
+
+def _enum_name(value, enum_cls=None) -> str | None:
+    """Best-effort name for an enum or raw int returned by monitorcontrol.
+
+    monitorcontrol's getters sometimes hand back raw ints when the monitor
+    reports a value the library wraps incompletely. Re-map those through the
+    matching enum class so HA selects still receive symbolic option names.
+    """
+    if value is None:
+        return None
+    name = getattr(value, "name", None)
+    if name:
+        return name
+    if enum_cls is not None:
+        try:
+            return enum_cls(value).name
+        except (ValueError, KeyError):
+            pass
+    return str(value)
+
+
+def _probe_static_open(mon, mc, monitor_id: int) -> dict:
+    """Probe per-monitor static capabilities.
+
+    Must be called inside an open `with mon:` DDC/CI context. Tries each
+    feature once to confirm the monitor responds, and enumerates option
+    lists from the capability string. Heavy: this is what the cache is for.
+    """
+    static = {
+        "contrast_supported": False,
+        "input_source_supported": False,
+        "available_input_sources": [],
+        "color_preset_supported": False,
+        "available_color_presets": [],
+        "picture_mode_supported": False,
+        "available_picture_modes": [],
+    }
+
+    try:
+        caps = mon.get_vcp_capabilities() or {}
+    except Exception as e:
+        caps = {}
+        logger.debug("Monitor %d: get_vcp_capabilities failed: %s", monitor_id, e)
+
+    try:
+        mon.get_contrast()
+        static["contrast_supported"] = True
+    except Exception as e:
+        logger.debug("Monitor %d: contrast unsupported: %s", monitor_id, e)
+
+    try:
+        mon.get_input_source()
+        static["input_source_supported"] = True
+    except Exception as e:
+        logger.debug("Monitor %d: input_source unsupported: %s", monitor_id, e)
+
+    inputs = caps.get("inputs") or []
+    input_enum = mc.InputSource if mc else None
+    static["available_input_sources"] = [
+        n for n in (_enum_name(s, input_enum) for s in inputs) if n is not None
+    ]
+
+    try:
+        mon.get_color_preset()
+        static["color_preset_supported"] = True
+        if mc is not None:
+            static["available_color_presets"] = [p.name for p in mc.ColorPreset]
+    except Exception as e:
+        logger.debug("Monitor %d: color_preset unsupported: %s", monitor_id, e)
+
+    # Picture / scene mode (VCP 0xDC). Trickier than color preset because
+    # many monitors (LG ultrawides included) respond to READS but silently
+    # drop every WRITE - they implement the register but not the feature.
+    # The capability string is the most reliable signal: a monitor that
+    # really implements picture mode declares its supported codes under
+    # cmds[0xDC]. If 0xDC isn't declared, treat the feature as unsupported
+    # to avoid exposing a non-functional select.
+    cmds = caps.get("cmds") or {}
+    declared = cmds.get(PICTURE_MODE_VCP)
+    if declared:
+        try:
+            mon.vcp.get_vcp_feature(PICTURE_MODE_VCP)
+            static["picture_mode_supported"] = True
+            static["available_picture_modes"] = [
+                {"code": c, "label": PICTURE_MODE_LABELS.get(c, f"Mode {c}")}
+                for c in sorted(declared)
+            ]
+        except Exception as e:
+            logger.debug("Monitor %d: picture_mode declared but unreadable: %s", monitor_id, e)
+    else:
+        logger.debug("Monitor %d: picture_mode (VCP 0xDC) not declared in capability string", monitor_id)
+
+    return static
+
+
+def _probe_dynamic_open(mon, mc, monitor_id: int, static: dict) -> dict:
+    """Read current values for features known to be supported.
+
+    Must be called inside an open `with mon:` context. Skips reads for
+    unsupported features (saves one I2C roundtrip each), so the warm path
+    only touches features the monitor actually responds to.
+    """
+    dynamic = {
+        "power_on": True,
+        "contrast": None,
+        "input_source": None,
+        "color_preset": None,
+        "picture_mode": None,
+        "picture_mode_code": None,
+    }
+
+    try:
+        dynamic["power_on"] = mon.get_power_mode() == mc.PowerMode.on
+    except Exception as e:
+        logger.debug("Monitor %d: power readback failed: %s", monitor_id, e)
+
+    if static.get("contrast_supported"):
+        try:
+            dynamic["contrast"] = mon.get_contrast()
+        except Exception as e:
+            logger.debug("Monitor %d: contrast readback failed: %s", monitor_id, e)
+
+    if static.get("input_source_supported"):
+        try:
+            src = mon.get_input_source()
+            dynamic["input_source"] = _enum_name(src, mc.InputSource if mc else None)
+        except Exception as e:
+            logger.debug("Monitor %d: input_source readback failed: %s", monitor_id, e)
+
+    if static.get("color_preset_supported"):
+        try:
+            preset = mon.get_color_preset()
+            dynamic["color_preset"] = _enum_name(preset, mc.ColorPreset if mc else None)
+        except Exception as e:
+            logger.debug("Monitor %d: color_preset readback failed: %s", monitor_id, e)
+
+    if static.get("picture_mode_supported"):
+        try:
+            current, _maximum = mon.vcp.get_vcp_feature(PICTURE_MODE_VCP)
+            dynamic["picture_mode_code"] = current
+            dynamic["picture_mode"] = PICTURE_MODE_LABELS.get(current, f"Mode {current}")
+        except Exception as e:
+            logger.debug("Monitor %d: picture_mode readback failed: %s", monitor_id, e)
+
+    return dynamic
+
+
+def list_monitors(force_refresh: bool = False, rediscover: bool = False) -> list[MonitorInfo]:
+    """List all connected monitors with their current state.
+
+    Args:
+        force_refresh: bypass the short TTL response cache.
+        rediscover: also drop the per-monitor static capability cache, so the
+            next probe re-runs DDC/CI capability discovery. Use after hot-plug
+            or when a monitor's reported capabilities change.
+    """
+    global _monitor_cache, _cache_time
+
+    if (
+        not force_refresh
+        and not rediscover
+        and _monitor_cache is not None
+        and (time.time() - _cache_time) < _CACHE_TTL
+    ):
+        return _monitor_cache
+
+    sbc = _load_sbc()
+    if sbc is None:
+        return []
+
+    monitors = []
+    try:
+        info_list = sbc.list_monitors_info()
+        brightnesses = sbc.get_brightness()
+
+        # Explicit rediscover wipes the whole cache; otherwise rely on stable
+        # per-monitor keys (manufacturer|model|edid_hash) so a hot-plug swap
+        # invalidates the entry for the missing monitor automatically.
+        if rediscover:
+            _static_cache.clear()
+
+        mc = _load_monitorcontrol()
+        ddc_monitors = []
+        if mc:
+            try:
+                ddc_monitors = mc.get_monitors()
+            except Exception:
+                pass
+
+        import hashlib
+
+        seen_keys: set[tuple] = set()
+        for i, info in enumerate(info_list):
+            name = info.get("name", f"Monitor {i}")
+            model = info.get("model", "")
+            manufacturer = info.get("manufacturer", "")
+            brightness = brightnesses[i] if i < len(brightnesses) else None
+            # VCP method monitors support DDC/CI power control
+            method = str(info.get("method", "")).lower()
+            power_supported = "vcp" in method
+
+            # Parse resolution from EDID
+            edid = info.get("edid", "")
+            resolution = _parse_edid_resolution(edid) if edid else None
+
+            # Stable cache key — EDID hash is unique per physical monitor.
+            # Fall back to (manufacturer, model, serial-ish) when EDID is
+            # missing, then to the legacy index as a last resort.
+            if edid:
+                edid_hash = hashlib.blake2b(
+                    edid.encode("utf-8") if isinstance(edid, str) else bytes(edid),
+                    digest_size=8,
+                ).hexdigest()
+                cache_key: tuple = ("edid", edid_hash)
+            elif manufacturer or model:
+                cache_key = ("mm", manufacturer, model, name)
+            else:
+                cache_key = ("idx", i)
+            seen_keys.add(cache_key)
+
+            static: dict = {}
+            dynamic: dict = {}
+
+            # Open the DDC handle ONCE; do static probe (if needed) + dynamic
+            # readback inside the same context. Opening the handle is the
+            # expensive part — keep both phases under one open.
+            if power_supported and i < len(ddc_monitors):
+                try:
+                    with ddc_monitors[i] as mon:
+                        if cache_key not in _static_cache:
+                            _static_cache[cache_key] = _probe_static_open(mon, mc, i)
+                        static = _static_cache[cache_key]
+                        dynamic = _probe_dynamic_open(mon, mc, i, static)
+                except Exception as e:
+                    logger.debug("Monitor %d: DDC/CI session failed: %s", i, e)
+                    static = _static_cache.get(cache_key, {})
+
+            monitors.append(MonitorInfo(
+                id=i,
+                name=name,
+                brightness=brightness,
+                power_supported=power_supported,
+                power_on=dynamic.get("power_on", True),
+                model=model,
+                manufacturer=manufacturer,
+                resolution=resolution,
+                contrast=dynamic.get("contrast"),
+                contrast_supported=static.get("contrast_supported", False),
+                input_source=dynamic.get("input_source"),
+                available_input_sources=static.get("available_input_sources", []),
+                input_source_supported=static.get("input_source_supported", False),
+                color_preset=dynamic.get("color_preset"),
+                available_color_presets=static.get("available_color_presets", []),
+                color_preset_supported=static.get("color_preset_supported", False),
+                picture_mode=dynamic.get("picture_mode"),
+                picture_mode_code=dynamic.get("picture_mode_code"),
+                available_picture_modes=static.get("available_picture_modes", []),
+                picture_mode_supported=static.get("picture_mode_supported", False),
+            ))
+        # Evict cache entries for monitors that disappeared from this scan so
+        # the next hot-plug of a different monitor with the same identity
+        # tuple (e.g. same model) doesn't hit a stale entry first.
+        for stale_key in list(_static_cache.keys()):
+            if stale_key not in seen_keys:
+                _static_cache.pop(stale_key, None)
+    except Exception as e:
+        logger.error("Failed to enumerate monitors: %s", e)
+
+    _mark_primary(monitors)
+    _monitor_cache = monitors
+    _cache_time = time.time()
+    return monitors
+
+
+def get_brightness(monitor_id: int) -> int | None:
+    """Get brightness for a specific monitor."""
+    sbc = _load_sbc()
+    if sbc is None:
+        return None
+    try:
+        result = sbc.get_brightness(display=monitor_id)
+        if isinstance(result, list):
+            return result[0] if result else None
+        return result
+    except Exception as e:
+        logger.error("Failed to get brightness for monitor %d: %s", monitor_id, e)
+        return None
+
+
+def set_brightness(monitor_id: int, value: int) -> bool:
+    """Set brightness for a specific monitor (0-100)."""
+    sbc = _load_sbc()
+    if sbc is None:
+        return False
+
+    value = max(0, min(100, value))
+    try:
+        sbc.set_brightness(value, display=monitor_id)
+        _invalidate_cache()
+        return True
+    except Exception as e:
+        logger.error("Failed to set brightness for monitor %d: %s", monitor_id, e)
+        return False
+
+
+def set_power(monitor_id: int, on: bool) -> bool:
+    """Turn a monitor on or off via DDC/CI."""
+    mc = _load_monitorcontrol()
+    if mc is None:
+        logger.error("monitorcontrol not available for power control")
+        return False
+
+    try:
+        ddc_monitors = mc.get_monitors()
+        if monitor_id >= len(ddc_monitors):
+            logger.error("Monitor %d not found in DDC/CI monitors", monitor_id)
+            return False
+
+        with ddc_monitors[monitor_id] as monitor:
+            if on:
+                monitor.set_power_mode(mc.PowerMode.on)
+            else:
+                monitor.set_power_mode(mc.PowerMode.off_soft)
+
+        _invalidate_cache()
+        return True
+    except Exception as e:
+        logger.error("Failed to set power for monitor %d: %s", monitor_id, e)
+        return False
+
+
+def _verify_after_set(getter, expected, *, retries: int = 3, delay: float = 0.1) -> bool:
+    """Poll a DDC/CI getter to confirm the monitor actually applied a write.
+
+    DDC/CI writes are fire-and-forget at the protocol level: a successful
+    send does not mean the monitor honored the value. Many monitors silently
+    drop writes for codes their firmware doesn't really implement (LG's
+    ColorPreset / Picture Mode are common offenders). Without this check the
+    API would report `success: true` while the monitor sat unchanged.
+
+    Compares both raw and `.value` forms so enum/int mismatches don't flag a
+    spurious failure.
+    """
+    expected_int = getattr(expected, "value", expected)
+    for _ in range(retries):
+        time.sleep(delay)
+        try:
+            actual = getter()
+        except Exception:
+            continue
+        actual_int = getattr(actual, "value", actual)
+        if actual == expected or actual_int == expected_int:
+            return True
+    return False
+
+
+def set_contrast(monitor_id: int, value: int) -> bool:
+    """Set contrast for a specific monitor (0-100) via DDC/CI."""
+    mc = _load_monitorcontrol()
+    if mc is None:
+        return False
+
+    value = max(0, min(100, value))
+    try:
+        ddc_monitors = mc.get_monitors()
+        if monitor_id >= len(ddc_monitors):
+            return False
+        with ddc_monitors[monitor_id] as monitor:
+            monitor.set_contrast(value)
+            if not _verify_after_set(monitor.get_contrast, value):
+                logger.warning("Monitor %d: contrast %d not applied", monitor_id, value)
+                return False
+        _invalidate_cache()
+        return True
+    except Exception as e:
+        logger.error("Failed to set contrast for monitor %d: %s", monitor_id, e)
+        return False
+
+
+def set_input_source(monitor_id: int, source: str) -> bool:
+    """Set the DDC/CI input source by enum name (e.g. 'HDMI1', 'DP1')."""
+    mc = _load_monitorcontrol()
+    if mc is None:
+        return False
+
+    try:
+        target = mc.InputSource[source]
+    except KeyError:
+        logger.error("Unknown input source: %s", source)
+        return False
+
+    try:
+        ddc_monitors = mc.get_monitors()
+        if monitor_id >= len(ddc_monitors):
+            return False
+        with ddc_monitors[monitor_id] as monitor:
+            monitor.set_input_source(target)
+            # Source switches can briefly disrupt the DDC/CI link; allow a
+            # longer settle window before declaring failure.
+            if not _verify_after_set(monitor.get_input_source, target, retries=5, delay=0.2):
+                logger.warning("Monitor %d: input source %s not applied", monitor_id, source)
+                return False
+        _invalidate_cache()
+        return True
+    except Exception as e:
+        logger.error("Failed to set input source for monitor %d: %s", monitor_id, e)
+        return False
+
+
+def set_color_preset(monitor_id: int, preset: str) -> bool:
+    """Set the DDC/CI color preset by enum name (e.g. 'COLOR_TEMP_6500K')."""
+    mc = _load_monitorcontrol()
+    if mc is None:
+        return False
+
+    try:
+        target = mc.ColorPreset[preset]
+    except KeyError:
+        logger.error("Unknown color preset: %s", preset)
+        return False
+
+    try:
+        ddc_monitors = mc.get_monitors()
+        if monitor_id >= len(ddc_monitors):
+            return False
+        with ddc_monitors[monitor_id] as monitor:
+            monitor.set_color_preset(target)
+            if not _verify_after_set(monitor.get_color_preset, target):
+                logger.warning(
+                    "Monitor %d: color preset %s not applied (monitor silently rejected)",
+                    monitor_id, preset,
+                )
+                return False
+        _invalidate_cache()
+        return True
+    except Exception as e:
+        logger.error("Failed to set color preset for monitor %d: %s", monitor_id, e)
+        return False
+
+
+def set_picture_mode(monitor_id: int, code: int) -> bool:
+    """Set the DDC/CI picture/scene mode (VCP 0xDC) by raw code."""
+    mc = _load_monitorcontrol()
+    if mc is None:
+        return False
+
+    if not 0 <= code <= 255:
+        logger.error("Picture mode code %d out of range", code)
+        return False
+
+    try:
+        ddc_monitors = mc.get_monitors()
+        if monitor_id >= len(ddc_monitors):
+            return False
+        with ddc_monitors[monitor_id] as monitor:
+            monitor.vcp.set_vcp_feature(PICTURE_MODE_VCP, code)
+            # Raw VCP read returns (current, maximum) — only compare current.
+            def _read_picture_mode():
+                current, _ = monitor.vcp.get_vcp_feature(PICTURE_MODE_VCP)
+                return current
+            if not _verify_after_set(_read_picture_mode, code):
+                logger.warning(
+                    "Monitor %d: picture mode code %d not applied (monitor silently rejected)",
+                    monitor_id, code,
+                )
+                return False
+        _invalidate_cache()
+        return True
+    except Exception as e:
+        logger.error("Failed to set picture mode for monitor %d: %s", monitor_id, e)
+        return False
+
+
+def _invalidate_cache() -> None:
+    global _monitor_cache
+    _monitor_cache = None

media_server/services/foreground_service.py

@@ -0,0 +1,543 @@
+"""Foreground (topmost) window/process tracking.
+
+Reports the process that currently owns the foreground window, plus useful
+metadata (window title, executable path, monitor index, whether the window
+covers a full monitor, process start time).
+
+All probes happen behind a short TTL cache so the WebSocket status poll and
+per-entity HA polls don't pay the OS call cost on every tick.
+
+Windows uses the Win32 API via ``ctypes`` (no extra dependency) and falls back
+gracefully when individual probes fail. Linux/macOS implementations are
+best-effort and return ``available=False`` when the required tooling is
+missing, so the rest of the stack keeps working.
+"""
+
+from __future__ import annotations
+
+import logging
+import platform
+import threading
+import time
+from dataclasses import asdict, dataclass, field
+
+logger = logging.getLogger(__name__)
+
+_CACHE_TTL = 0.5  # seconds — fast enough for WebSocket broadcast loop
+
+
+@dataclass(frozen=True)
+class ForegroundInfo:
+    """Snapshot of the foreground window/process."""
+
+    available: bool
+    pid: int | None = None
+    process_name: str | None = None
+    executable_path: str | None = None
+    window_title: str | None = None
+    window_handle: int | None = None
+    is_fullscreen: bool = False
+    is_minimized: bool = False
+    monitor_id: int | None = None
+    monitor_geometry: dict[str, int] | None = None
+    window_geometry: dict[str, int] | None = None
+    started_at: float | None = None
+    platform: str = field(default_factory=lambda: platform.system())
+    error: str | None = None
+    # Populated only when the foreground process is a recognised web
+    # browser. ``browser_page_title`` is derived from the window title
+    # (suffix stripped); ``browser_url`` requires UIA to succeed.
+    is_browser: bool = False
+    browser_url: str | None = None
+    browser_page_title: str | None = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+_UNAVAILABLE = ForegroundInfo(available=False)
+
+
+class _Cache:
+    """Single-slot TTL cache shared across callers."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._value: ForegroundInfo | None = None
+        self._fetched_at: float = 0.0
+
+    def get(self, ttl: float, fetch) -> ForegroundInfo:
+        with self._lock:
+            now = time.monotonic()
+            if self._value is not None and (now - self._fetched_at) < ttl:
+                return self._value
+        # Fetch outside the lock — OS calls can take tens of ms.
+        value = fetch()
+        with self._lock:
+            self._value = value
+            self._fetched_at = time.monotonic()
+        return value
+
+    def invalidate(self) -> None:
+        with self._lock:
+            self._value = None
+            self._fetched_at = 0.0
+
+
+_cache = _Cache()
+
+# Win32 handles + signatures are declared once at module load (when running on
+# Windows). The TTL cache fires this hundreds of times per minute; redoing the
+# DLL load + ~10 argtype assignments per call was the largest chunk of probe
+# cost. Keep these guarded behind a lazy init so non-Windows platforms don't
+# pay the import.
+_WIN32_INITIALIZED = False
+_win32_user32 = None
+_win32_kernel32 = None
+_win32_psapi = None
+
+
+def _init_win32_apis() -> None:
+    """Declare ctypes argtypes/restype on every Win32 call we make.
+
+    CRITICAL: ctypes defaults to `c_int` (32-bit) for HANDLE/HWND/HMONITOR
+    which silently truncates 64-bit pointer values on x64 — that corrupts the
+    handle so `CloseHandle()` can either fail or close the wrong kernel
+    object, and pointer-equality comparisons (monitor index lookup) miss.
+    """
+    global _WIN32_INITIALIZED, _win32_user32, _win32_kernel32, _win32_psapi
+    if _WIN32_INITIALIZED:
+        return
+
+    import ctypes
+    import ctypes.wintypes as wt
+
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    psapi = ctypes.WinDLL("psapi", use_last_error=True)
+
+    user32.GetForegroundWindow.restype = wt.HWND
+    user32.GetWindowThreadProcessId.argtypes = [wt.HWND, ctypes.POINTER(wt.DWORD)]
+    user32.GetWindowThreadProcessId.restype = wt.DWORD
+    user32.GetWindowTextLengthW.argtypes = [wt.HWND]
+    user32.GetWindowTextLengthW.restype = ctypes.c_int
+    user32.GetWindowTextW.argtypes = [wt.HWND, wt.LPWSTR, ctypes.c_int]
+    user32.GetWindowTextW.restype = ctypes.c_int
+    user32.IsIconic.argtypes = [wt.HWND]
+    user32.IsIconic.restype = wt.BOOL
+    user32.GetWindowRect.argtypes = [wt.HWND, ctypes.POINTER(wt.RECT)]
+    user32.GetWindowRect.restype = wt.BOOL
+    user32.MonitorFromWindow.argtypes = [wt.HWND, wt.DWORD]
+    user32.MonitorFromWindow.restype = wt.HMONITOR
+    user32.GetMonitorInfoW.argtypes = [wt.HMONITOR, ctypes.c_void_p]
+    user32.GetMonitorInfoW.restype = wt.BOOL
+
+    kernel32.OpenProcess.argtypes = [wt.DWORD, wt.BOOL, wt.DWORD]
+    kernel32.OpenProcess.restype = wt.HANDLE
+    kernel32.CloseHandle.argtypes = [wt.HANDLE]
+    kernel32.CloseHandle.restype = wt.BOOL
+    kernel32.QueryFullProcessImageNameW.argtypes = [
+        wt.HANDLE, wt.DWORD, wt.LPWSTR, ctypes.POINTER(wt.DWORD)
+    ]
+    kernel32.QueryFullProcessImageNameW.restype = wt.BOOL
+    kernel32.GetProcessTimes.argtypes = [
+        wt.HANDLE,
+        ctypes.POINTER(wt.FILETIME),
+        ctypes.POINTER(wt.FILETIME),
+        ctypes.POINTER(wt.FILETIME),
+        ctypes.POINTER(wt.FILETIME),
+    ]
+    kernel32.GetProcessTimes.restype = wt.BOOL
+
+    psapi.GetModuleFileNameExW.argtypes = [wt.HANDLE, wt.HMODULE, wt.LPWSTR, wt.DWORD]
+    psapi.GetModuleFileNameExW.restype = wt.DWORD
+
+    _win32_user32, _win32_kernel32, _win32_psapi = user32, kernel32, psapi
+    _WIN32_INITIALIZED = True
+
+
+def _probe_windows() -> ForegroundInfo:
+    """Probe foreground window state on Windows via Win32 API."""
+    import ctypes
+    import ctypes.wintypes as wt
+
+    _init_win32_apis()
+    user32 = _win32_user32
+    kernel32 = _win32_kernel32
+    psapi = _win32_psapi
+
+    hwnd = user32.GetForegroundWindow()
+    if not hwnd:
+        return ForegroundInfo(available=True, error="no foreground window")
+
+    # PID + window thread.
+    pid = wt.DWORD(0)
+    user32.GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
+    pid_val = int(pid.value) if pid.value else None
+
+    # Window title — Unicode.
+    length = user32.GetWindowTextLengthW(hwnd)
+    title_buf = ctypes.create_unicode_buffer(length + 1)
+    user32.GetWindowTextW(hwnd, title_buf, length + 1)
+    window_title = title_buf.value or None
+
+    # Minimized flag.
+    is_minimized = bool(user32.IsIconic(hwnd))
+
+    # Window rect (screen coords).
+    rect = wt.RECT()
+    window_geometry: dict[str, int] | None = None
+    if user32.GetWindowRect(hwnd, ctypes.byref(rect)):
+        window_geometry = {
+            "left": int(rect.left),
+            "top": int(rect.top),
+            "right": int(rect.right),
+            "bottom": int(rect.bottom),
+            "width": int(rect.right - rect.left),
+            "height": int(rect.bottom - rect.top),
+        }
+
+    # Monitor under the window + its geometry.
+    monitor_geometry: dict[str, int] | None = None
+    monitor_id: int | None = None
+    is_fullscreen = False
+    try:
+        MONITOR_DEFAULTTONEAREST = 2
+
+        class MONITORINFO(ctypes.Structure):
+            _fields_ = [
+                ("cbSize", wt.DWORD),
+                ("rcMonitor", wt.RECT),
+                ("rcWork", wt.RECT),
+                ("dwFlags", wt.DWORD),
+            ]
+
+        hmon = user32.MonitorFromWindow(hwnd, MONITOR_DEFAULTTONEAREST)
+        if hmon:
+            mi = MONITORINFO()
+            mi.cbSize = ctypes.sizeof(mi)
+            if user32.GetMonitorInfoW(hmon, ctypes.byref(mi)):
+                monitor_geometry = {
+                    "left": int(mi.rcMonitor.left),
+                    "top": int(mi.rcMonitor.top),
+                    "right": int(mi.rcMonitor.right),
+                    "bottom": int(mi.rcMonitor.bottom),
+                    "width": int(mi.rcMonitor.right - mi.rcMonitor.left),
+                    "height": int(mi.rcMonitor.bottom - mi.rcMonitor.top),
+                }
+                # Fullscreen heuristic: window rect equals monitor rect AND
+                # not minimized. Many media players (VLC, browser fullscreen)
+                # set themselves to exactly the monitor bounds.
+                if window_geometry and not is_minimized:
+                    is_fullscreen = (
+                        window_geometry["left"] == monitor_geometry["left"]
+                        and window_geometry["top"] == monitor_geometry["top"]
+                        and window_geometry["right"] == monitor_geometry["right"]
+                        and window_geometry["bottom"] == monitor_geometry["bottom"]
+                    )
+
+            # Resolve monitor index by enumerating displays in order. Coerce
+            # both the foreground hmon and the per-enum hmon to int so the
+            # equality compare uses 64-bit values consistently regardless of
+            # how ctypes represents the handle internally.
+            try:
+                indexed: list[int] = []
+
+                def _cb(hm, _hdc, _rect, _data):
+                    indexed.append(int(hm) if hm else 0)
+                    return True
+
+                MONITORENUMPROC = ctypes.WINFUNCTYPE(
+                    ctypes.c_int,
+                    wt.HMONITOR,
+                    wt.HDC,
+                    ctypes.POINTER(wt.RECT),
+                    wt.LPARAM,
+                )
+                user32.EnumDisplayMonitors.argtypes = [
+                    wt.HDC, ctypes.POINTER(wt.RECT), MONITORENUMPROC, wt.LPARAM
+                ]
+                user32.EnumDisplayMonitors.restype = wt.BOOL
+                user32.EnumDisplayMonitors(None, None, MONITORENUMPROC(_cb), 0)
+                target = int(hmon) if hmon else 0
+                if target and target in indexed:
+                    monitor_id = indexed.index(target)
+            except Exception as e:
+                logger.debug("Monitor index resolution failed: %s", e)
+    except Exception as e:
+        logger.debug("Monitor info probe failed: %s", e)
+
+    # Process executable path + start time.
+    executable_path: str | None = None
+    process_name: str | None = None
+    started_at: float | None = None
+    if pid_val:
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        h_proc = kernel32.OpenProcess(
+            PROCESS_QUERY_LIMITED_INFORMATION, False, pid_val
+        )
+        if h_proc:
+            try:
+                # Image filename — full path. QueryFullProcessImageNameW works
+                # across 32/64-bit boundaries, unlike GetModuleFileNameExW.
+                buf = ctypes.create_unicode_buffer(1024)
+                size = wt.DWORD(len(buf))
+                if kernel32.QueryFullProcessImageNameW(
+                    h_proc, 0, buf, ctypes.byref(size)
+                ):
+                    executable_path = buf.value or None
+                else:
+                    # Fallback via psapi. Return value is the length copied
+                    # into the buffer (0 on failure); ignoring it would leave
+                    # `executable_path` as an empty string from the freshly
+                    # allocated buffer instead of None.
+                    written = psapi.GetModuleFileNameExW(h_proc, None, buf, len(buf))
+                    if written:
+                        executable_path = buf.value or None
+                    else:
+                        logger.debug(
+                            "QueryFullProcessImageNameW + psapi fallback both "
+                            "failed for pid=%s (err=%d)",
+                            pid_val,
+                            ctypes.get_last_error(),
+                        )
+
+                if executable_path:
+                    import os
+                    process_name = os.path.basename(executable_path)
+
+                # Process creation time (FILETIME, 100ns ticks since 1601).
+                creation = wt.FILETIME()
+                exit_t = wt.FILETIME()
+                kernel_t = wt.FILETIME()
+                user_t = wt.FILETIME()
+                if kernel32.GetProcessTimes(
+                    h_proc,
+                    ctypes.byref(creation),
+                    ctypes.byref(exit_t),
+                    ctypes.byref(kernel_t),
+                    ctypes.byref(user_t),
+                ):
+                    ticks = (creation.dwHighDateTime << 32) | creation.dwLowDateTime
+                    # Convert to Unix epoch seconds (1601-01-01 → 1970-01-01).
+                    if ticks:
+                        started_at = (ticks - 116444736000000000) / 10_000_000
+            finally:
+                kernel32.CloseHandle(h_proc)
+
+    return ForegroundInfo(
+        available=True,
+        pid=pid_val,
+        process_name=process_name,
+        executable_path=executable_path,
+        window_title=window_title,
+        window_handle=int(hwnd) if hwnd else None,
+        is_fullscreen=is_fullscreen,
+        is_minimized=is_minimized,
+        monitor_id=monitor_id,
+        monitor_geometry=monitor_geometry,
+        window_geometry=window_geometry,
+        started_at=started_at,
+    )
+
+
+def _probe_macos() -> ForegroundInfo:
+    """Best-effort probe on macOS via AppKit (PyObjC).
+
+    Returns ``available=False`` when PyObjC is not installed — we don't take
+    a hard dependency on it because the typical macOS install path uses pip
+    + the standalone wheel.
+    """
+    try:
+        from AppKit import NSWorkspace  # type: ignore
+        from Quartz import (  # type: ignore
+            CGWindowListCopyWindowInfo,
+            kCGNullWindowID,
+            kCGWindowListOptionOnScreenOnly,
+        )
+    except Exception:
+        return ForegroundInfo(available=False, error="AppKit/Quartz not available")
+
+    try:
+        ws = NSWorkspace.sharedWorkspace()
+        app = ws.frontmostApplication()
+        if app is None:
+            return ForegroundInfo(available=True, error="no frontmost app")
+
+        pid = int(app.processIdentifier())
+        process_name = str(app.localizedName() or "")
+        bundle_url = app.bundleURL()
+        executable_path = str(bundle_url.path()) if bundle_url else None
+        started_at = None
+        launch_date = app.launchDate()
+        if launch_date is not None:
+            started_at = float(launch_date.timeIntervalSince1970())
+
+        # Window title — frontmost on-screen window owned by this PID.
+        window_title: str | None = None
+        try:
+            windows = CGWindowListCopyWindowInfo(
+                kCGWindowListOptionOnScreenOnly, kCGNullWindowID
+            )
+            for w in windows or []:
+                if int(w.get("kCGWindowOwnerPID", -1)) == pid:
+                    name = w.get("kCGWindowName")
+                    if name:
+                        window_title = str(name)
+                        break
+        except Exception as e:
+            logger.debug("CGWindowListCopyWindowInfo failed: %s", e)
+
+        return ForegroundInfo(
+            available=True,
+            pid=pid,
+            process_name=process_name,
+            executable_path=executable_path,
+            window_title=window_title,
+            started_at=started_at,
+        )
+    except Exception as e:
+        logger.debug("macOS foreground probe failed: %s", e)
+        return ForegroundInfo(available=False, error=str(e))
+
+
+def _probe_linux() -> ForegroundInfo:
+    """Best-effort probe on Linux via Xlib (X11 only).
+
+    Wayland sessions intentionally hide window/process info from unprivileged
+    clients, so this returns ``available=False`` on Wayland. The caller still
+    gets a structured response and can render "unavailable" in the UI.
+    """
+    import os
+
+    if os.environ.get("WAYLAND_DISPLAY"):
+        return ForegroundInfo(
+            available=False, error="Wayland session — foreground probe unavailable"
+        )
+
+    try:
+        from Xlib import X, display  # type: ignore  # noqa: F401
+    except Exception:
+        return ForegroundInfo(available=False, error="python-xlib not installed")
+
+    try:
+        d = display.Display()
+        root = d.screen().root
+        NET_ACTIVE_WINDOW = d.intern_atom("_NET_ACTIVE_WINDOW")
+        NET_WM_PID = d.intern_atom("_NET_WM_PID")
+        NET_WM_NAME = d.intern_atom("_NET_WM_NAME")
+        UTF8_STRING = d.intern_atom("UTF8_STRING")
+
+        active = root.get_full_property(NET_ACTIVE_WINDOW, X.AnyPropertyType)
+        if not active or not active.value:
+            return ForegroundInfo(available=True, error="no active window")
+        win_id = int(active.value[0])
+        win = d.create_resource_object("window", win_id)
+
+        pid_prop = win.get_full_property(NET_WM_PID, X.AnyPropertyType)
+        pid_val = int(pid_prop.value[0]) if pid_prop and pid_prop.value else None
+
+        name_prop = win.get_full_property(NET_WM_NAME, UTF8_STRING)
+        window_title = (
+            name_prop.value.decode("utf-8", "replace") if name_prop and name_prop.value else None
+        )
+
+        process_name: str | None = None
+        executable_path: str | None = None
+        started_at: float | None = None
+        if pid_val:
+            try:
+                exe = os.readlink(f"/proc/{pid_val}/exe")
+                executable_path = exe
+                process_name = os.path.basename(exe)
+            except OSError as e:
+                logger.debug("readlink /proc/%d/exe failed: %s", pid_val, e)
+            try:
+                started_at = os.stat(f"/proc/{pid_val}").st_ctime
+            except OSError as e:
+                logger.debug("stat /proc/%d failed: %s", pid_val, e)
+
+        return ForegroundInfo(
+            available=True,
+            pid=pid_val,
+            process_name=process_name,
+            executable_path=executable_path,
+            window_title=window_title,
+            window_handle=win_id,
+            started_at=started_at,
+        )
+    except Exception as e:
+        logger.debug("Linux foreground probe failed: %s", e)
+        return ForegroundInfo(available=False, error=str(e))
+
+
+def _enrich_browser(info: ForegroundInfo) -> ForegroundInfo:
+    """If ``info`` describes a focused browser, attach URL + page title.
+
+    The UIA lookup is wrapped in its own try/except so a failure here can't
+    take down the rest of the foreground probe.
+    """
+    try:
+        from . import browser_url_service as bus
+    except Exception as e:
+        logger.debug("browser_url_service unavailable: %s", e)
+        return info
+
+    if not info.available or not bus.is_browser_process(info.process_name):
+        return info
+
+    try:
+        page = bus.get_browser_page(
+            hwnd=info.window_handle,
+            process_name=info.process_name,
+            window_title=info.window_title,
+        )
+    except Exception as e:
+        logger.debug("Browser URL enrichment failed: %s", e)
+        return info
+
+    # ``dataclasses.replace`` keeps the frozen-dataclass contract.
+    from dataclasses import replace
+    return replace(
+        info,
+        is_browser=True,
+        browser_url=page.url,
+        browser_page_title=page.page_title,
+    )
+
+
+def _probe() -> ForegroundInfo:
+    system = platform.system()
+    try:
+        if system == "Windows":
+            info = _probe_windows()
+        elif system == "Darwin":
+            info = _probe_macos()
+        elif system == "Linux":
+            info = _probe_linux()
+        else:
+            return ForegroundInfo(
+                available=False, error=f"unsupported platform: {system}"
+            )
+        return _enrich_browser(info)
+    except Exception as e:
+        logger.warning("Foreground probe crashed: %s", e)
+        return ForegroundInfo(available=False, error=str(e))
+
+
+def get_foreground_info(force_refresh: bool = False) -> ForegroundInfo:
+    """Return the current foreground window/process snapshot.
+
+    Args:
+        force_refresh: bypass the short TTL cache. WebSocket broadcast loop
+            should leave this False; the REST endpoint accepts ?refresh=1
+            for callers that want a fresh probe.
+    """
+    if force_refresh:
+        _cache.invalidate()
+    return _cache.get(_CACHE_TTL, _probe)
+
+
+def reset_cache() -> None:
+    """Reset the cache. Useful in tests."""
+    _cache.invalidate()

media_server/services/gitea_release_provider.py

@@ -0,0 +1,86 @@
+"""Gitea release provider implementation."""
+
+import json
+import logging
+import re
+import urllib.error
+import urllib.request
+from typing import Optional
+
+from .release_provider import ReleaseInfo, ReleaseProvider
+
+logger = logging.getLogger(__name__)
+
+# Default repository coordinates
+_DEFAULT_BASE_URL = "https://git.dolgolyov-family.by"
+_DEFAULT_OWNER = "alexei.dolgolyov"
+_DEFAULT_REPO = "media-player-server"
+
+# Restrictive tag whitelist — prevents a hostile Gitea response (or MITM) from
+# injecting `..`, slashes, or URL-altering characters into the release URL we
+# broadcast to clients. SemVer + pre-release suffix only.
+_TAG_RE = re.compile(r"^v?\d+\.\d+\.\d+(?:[\w.\-+]{0,32})?$")
+
+
+class GiteaReleaseProvider(ReleaseProvider):
+    """Fetches the latest release from a Gitea repository."""
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_BASE_URL,
+        owner: str = _DEFAULT_OWNER,
+        repo: str = _DEFAULT_REPO,
+        timeout: float = 10.0,
+    ) -> None:
+        self._api_url = f"{base_url}/api/v1/repos/{owner}/{repo}/releases"
+        self._release_page_url = f"{base_url}/{owner}/{repo}/releases/tag"
+        self._timeout = timeout
+
+    async def get_latest_release(self) -> Optional[ReleaseInfo]:
+        """Fetch the latest stable release from Gitea API.
+
+        Returns:
+            ReleaseInfo for the latest non-prerelease, or None on failure.
+        """
+        import asyncio
+
+        try:
+            data = await asyncio.to_thread(self._fetch_releases)
+        except Exception as e:
+            logger.warning("Failed to check for updates: %s", e)
+            return None
+
+        if not data:
+            return None
+
+        # Find the first non-prerelease, non-draft release
+        for release in data:
+            if release.get("draft") or release.get("prerelease"):
+                continue
+
+            tag = release.get("tag_name", "")
+            if not isinstance(tag, str) or not _TAG_RE.match(tag):
+                logger.warning("Rejecting malformed release tag from upstream: %r", tag)
+                continue
+            version = tag.lstrip("v")
+            if not version:
+                continue
+
+            return ReleaseInfo(
+                version=version,
+                url=f"{self._release_page_url}/{tag}",
+                prerelease=False,
+            )
+
+        logger.debug("No stable releases found")
+        return None
+
+    def _fetch_releases(self) -> list[dict]:
+        """Synchronous HTTP fetch of releases (run in thread)."""
+        url = f"{self._api_url}?limit=5"
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                return json.loads(resp.read().decode())
+        except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError, OSError) as e:
+            raise RuntimeError(f"Gitea API request failed: {e}") from e

media_server/services/linux_media.py

@@ -2,14 +2,23 @@
 
 import asyncio
 import logging
+import os
 import subprocess
-from typing import Optional, Any
+import threading
+from typing import Any, Optional
+from urllib.parse import unquote, urlparse
 
 from ..models import MediaState, MediaStatus
 from .media_controller import MediaController
 
 logger = logging.getLogger(__name__)
 
+# Cap remote artwork downloads so a hostile / huge Spotify image can't
+# blow up RAM. Real album art rarely exceeds ~2 MB; 8 MB is a comfortable
+# upper bound that also covers loss-less PNGs.
+_MAX_ART_BYTES = 8 * 1024 * 1024
+_ART_FETCH_TIMEOUT = 5.0  # seconds
+
 # Linux-specific imports
 try:
     import dbus
@@ -35,13 +44,54 @@ class LinuxMediaController(MediaController):
                 "Linux media control requires dbus-python package. "
                 "Install with: sudo apt-get install python3-dbus"
             )
-        DBusGMainLoop(set_as_default=True)
-        self._bus = dbus.SessionBus()
+        # The session-bus connection is deferred until first use. Connecting
+        # in __init__ raised during app startup whenever the user's session
+        # bus wasn't ready yet — common under systemd (service starts
+        # before logind set up /run/user/<uid>/bus), under SSH-without-X11,
+        # and in headless CI. Failing here killed the whole lifespan; now
+        # MPRIS calls return "idle" until the bus appears, and other
+        # endpoints (health, scripts, browser, …) keep working.
+        self._bus_lock = threading.Lock()
+        self._bus = None  # type: ignore[assignment]
+        self._bus_init_logged = False
+        # Cached art bytes keyed by the mpris:artUrl currently in flight.
+        # Lock guards the swap from the status thread vs the artwork handler.
+        self._art_lock = threading.Lock()
+        self._art_url: Optional[str] = None
+        self._art_bytes: Optional[bytes] = None
+
+    def _get_bus(self):
+        """Lazily connect to the session bus; returns None if unavailable."""
+        if self._bus is not None:
+            return self._bus
+        with self._bus_lock:
+            if self._bus is not None:
+                return self._bus
+            try:
+                DBusGMainLoop(set_as_default=True)
+                self._bus = dbus.SessionBus()
+                logger.info("Connected to D-Bus session bus")
+                return self._bus
+            except Exception as e:
+                # Log once at INFO to avoid log spam if every status poll fails.
+                if not self._bus_init_logged:
+                    logger.info(
+                        "D-Bus session bus not available (%s). "
+                        "MPRIS calls will return 'idle' until DBUS_SESSION_BUS_ADDRESS"
+                        " is set and the bus is reachable. Under systemd, ensure"
+                        " `loginctl enable-linger <user>` is set.",
+                        e,
+                    )
+                    self._bus_init_logged = True
+                return None
 
     def _get_active_player(self) -> Optional[str]:
         """Find an active MPRIS media player on the bus."""
+        bus = self._get_bus()
+        if bus is None:
+            return None
         try:
-            bus_names = self._bus.list_names()
+            bus_names = bus.list_names()
             mpris_players = [
                 name for name in bus_names if name.startswith(self.MPRIS_PREFIX)
             ]
@@ -151,22 +201,19 @@ class LinuxMediaController(MediaController):
             logger.error(f"Failed to toggle mute: {e}")
             return False
 
-    async def get_status(self) -> MediaStatus:
-        """Get current media playback status."""
+    def _sync_get_status(self) -> MediaStatus:
+        """Synchronous status read (called from a worker thread)."""
         status = MediaStatus()
 
-        # Get system volume
         volume, muted = self._get_volume_pulseaudio()
         status.volume = volume
         status.muted = muted
 
-        # Get active player
         player_name = self._get_active_player()
         if player_name is None:
             status.state = MediaState.IDLE
             return status
 
-        # Get playback status
         playback_status = self._get_property(player_name, "PlaybackStatus")
         if playback_status == "Playing":
             status.state = MediaState.PLAYING
@@ -177,114 +224,78 @@ class LinuxMediaController(MediaController):
         else:
             status.state = MediaState.IDLE
 
-        # Get metadata
         metadata = self._get_property(player_name, "Metadata")
         if metadata:
             status.title = str(metadata.get("xesam:title", "")) or None
-
             artists = metadata.get("xesam:artist", [])
             if artists:
                 status.artist = str(artists[0]) if isinstance(artists, list) else str(artists)
-
             status.album = str(metadata.get("xesam:album", "")) or None
-            status.album_art_url = str(metadata.get("mpris:artUrl", "")) or None
-
-            # Duration in microseconds
+            art_url = str(metadata.get("mpris:artUrl", "")) or None
+            status.album_art_url = art_url
+            # Invalidate cached bytes when the track changes. Real fetch
+            # happens lazily in get_album_art() so the status hot path
+            # never blocks on HTTP.
+            with self._art_lock:
+                if art_url != self._art_url:
+                    self._art_url = art_url
+                    self._art_bytes = None
             length = metadata.get("mpris:length", 0)
             if length:
                 status.duration = int(length) / 1_000_000
 
-        # Get position (in microseconds)
         position = self._get_property(player_name, "Position")
         if position is not None:
             status.position = int(position) / 1_000_000
 
-        # Get source name
         status.source = player_name.replace(self.MPRIS_PREFIX, "")
-
         return status
 
-    async def play(self) -> bool:
-        """Resume playback."""
+    async def get_status(self) -> MediaStatus:
+        """Get current media playback status (off the event loop)."""
+        # pactl + DBus calls each take 5-100ms on a Pi and would block every
+        # other coroutine on the server. Run them in a worker thread.
+        return await asyncio.to_thread(self._sync_get_status)
+
+    def _call_player(self, method_name: str) -> bool:
         player_name = self._get_active_player()
         if player_name is None:
             return False
         try:
             player = self._get_player_interface(player_name)
-            player.Play()
+            getattr(player, method_name)()
             return True
         except Exception as e:
-            logger.error(f"Failed to play: {e}")
+            logger.error(f"Failed to call player.{method_name}: {e}")
             return False
 
+    async def play(self) -> bool:
+        return await asyncio.to_thread(self._call_player, "Play")
+
     async def pause(self) -> bool:
-        """Pause playback."""
-        player_name = self._get_active_player()
-        if player_name is None:
-            return False
-        try:
-            player = self._get_player_interface(player_name)
-            player.Pause()
-            return True
-        except Exception as e:
-            logger.error(f"Failed to pause: {e}")
-            return False
+        return await asyncio.to_thread(self._call_player, "Pause")
 
     async def stop(self) -> bool:
-        """Stop playback."""
-        player_name = self._get_active_player()
-        if player_name is None:
-            return False
-        try:
-            player = self._get_player_interface(player_name)
-            player.Stop()
-            return True
-        except Exception as e:
-            logger.error(f"Failed to stop: {e}")
-            return False
+        return await asyncio.to_thread(self._call_player, "Stop")
 
     async def next_track(self) -> bool:
-        """Skip to next track."""
-        player_name = self._get_active_player()
-        if player_name is None:
-            return False
-        try:
-            player = self._get_player_interface(player_name)
-            player.Next()
-            return True
-        except Exception as e:
-            logger.error(f"Failed to skip next: {e}")
-            return False
+        return await asyncio.to_thread(self._call_player, "Next")
 
     async def previous_track(self) -> bool:
-        """Go to previous track."""
-        player_name = self._get_active_player()
-        if player_name is None:
-            return False
-        try:
-            player = self._get_player_interface(player_name)
-            player.Previous()
-            return True
-        except Exception as e:
-            logger.error(f"Failed to skip previous: {e}")
-            return False
+        return await asyncio.to_thread(self._call_player, "Previous")
 
     async def set_volume(self, volume: int) -> bool:
-        """Set system volume."""
-        return self._set_volume_pulseaudio(volume)
+        return await asyncio.to_thread(self._set_volume_pulseaudio, volume)
 
     async def toggle_mute(self) -> bool:
-        """Toggle mute state."""
-        return self._toggle_mute_pulseaudio()
+        return await asyncio.to_thread(self._toggle_mute_pulseaudio)
 
-    async def seek(self, position: float) -> bool:
-        """Seek to position in seconds."""
+    def _sync_seek(self, position: float) -> bool:
         player_name = self._get_active_player()
         if player_name is None:
             return False
         try:
             player = self._get_player_interface(player_name)
-            # MPRIS expects position in microseconds
             player.SetPosition(
                 self._get_property(player_name, "Metadata").get("mpris:trackid", "/"),
                 int(position * 1_000_000),
@@ -293,3 +304,88 @@ class LinuxMediaController(MediaController):
         except Exception as e:
             logger.error(f"Failed to seek: {e}")
             return False
+
+    async def seek(self, position: float) -> bool:
+        return await asyncio.to_thread(self._sync_seek, position)
+
+    async def open_file(self, file_path: str) -> bool:
+        """Open a media file with the default system player (Linux).
+
+        Uses xdg-open to open the file with the default application.
+
+        Args:
+            file_path: Absolute path to the media file
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            process = await asyncio.create_subprocess_exec(
+                'xdg-open', file_path,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL
+            )
+            await process.wait()
+            logger.info(f"Opened file with default player: {file_path}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to open file {file_path}: {e}")
+            return False
+
+    def _fetch_art_sync(self, url: str) -> Optional[bytes]:
+        """Resolve an ``mpris:artUrl`` to raw bytes (file://, http(s)://).
+
+        Other schemes (data:, ftp:, …) are rejected — we only support the
+        two cases real-world MPRIS providers use. The HTTP path is capped
+        at _MAX_ART_BYTES and the file path is read with a size guard so a
+        symlink to /dev/zero can't OOM the server.
+        """
+        try:
+            parsed = urlparse(url)
+        except ValueError:
+            return None
+
+        scheme = parsed.scheme.lower()
+        if scheme == "file":
+            path = unquote(parsed.path)
+            try:
+                size = os.stat(path).st_size
+                if size <= 0 or size > _MAX_ART_BYTES:
+                    return None
+                with open(path, "rb") as f:
+                    return f.read(_MAX_ART_BYTES)
+            except OSError as e:
+                logger.debug("Could not read local art %s: %s", path, e)
+                return None
+
+        if scheme in ("http", "https"):
+            import urllib.error
+            import urllib.request
+
+            req = urllib.request.Request(url, headers={"User-Agent": "media-server/0.x"})
+            try:
+                with urllib.request.urlopen(req, timeout=_ART_FETCH_TIMEOUT) as resp:
+                    # Cap reads to defend against unbounded responses.
+                    return resp.read(_MAX_ART_BYTES + 1)[:_MAX_ART_BYTES] or None
+            except (urllib.error.URLError, urllib.error.HTTPError, OSError) as e:
+                logger.debug("Could not fetch remote art %s: %s", url, e)
+                return None
+
+        logger.debug("Unsupported art URL scheme: %s", scheme)
+        return None
+
+    async def get_album_art(self) -> Optional[bytes]:
+        """Return cached MPRIS art, fetching on first access per track."""
+        with self._art_lock:
+            url = self._art_url
+            cached = self._art_bytes
+        if cached is not None:
+            return cached
+        if not url:
+            return None
+        data = await asyncio.to_thread(self._fetch_art_sync, url)
+        # Store even on None so we don't re-hammer a 404 every second.
+        with self._art_lock:
+            if url == self._art_url:
+                self._art_bytes = data
+        return data

media_server/services/macos_media.py

@@ -3,7 +3,7 @@
 import asyncio
 import logging
 import subprocess
-import json
+import threading
 from typing import Optional
 
 from ..models import MediaState, MediaStatus
@@ -11,10 +11,20 @@ from .media_controller import MediaController
 
 logger = logging.getLogger(__name__)
 
+# Cap remote artwork downloads (Spotify's artwork url is http(s)://).
+_MAX_ART_BYTES = 8 * 1024 * 1024
+_ART_FETCH_TIMEOUT = 5.0  # seconds
+
 
 class MacOSMediaController(MediaController):
     """Media controller for macOS using osascript and system commands."""
 
+    def __init__(self) -> None:
+        # Cached art bytes keyed by the active art URL.
+        self._art_lock = threading.Lock()
+        self._art_url: Optional[str] = None
+        self._art_bytes: Optional[bytes] = None
+
     def _run_osascript(self, script: str) -> Optional[str]:
         """Run an AppleScript and return the output."""
         try:
@@ -194,20 +204,63 @@ class MacOSMediaController(MediaController):
             status.album = info.get("album")
             status.duration = info.get("duration")
             status.position = info.get("position")
-            status.album_art_url = info.get("art_url")
+            art_url = info.get("art_url")
+            status.album_art_url = art_url
+            # Track changes invalidate the cached image bytes — actual
+            # fetch happens lazily in get_album_art().
+            with self._art_lock:
+                if art_url != self._art_url:
+                    self._art_url = art_url
+                    self._art_bytes = None
         else:
             status.state = MediaState.IDLE
 
         return status
 
+    def _fetch_art_sync(self, url: str) -> Optional[bytes]:
+        """Resolve a Spotify/Music art URL (http(s)://) to bytes.
+
+        File-scheme URLs aren't expected on macOS (AppleScript apps return
+        artwork as remote URLs), so only http(s) is supported.
+        """
+        try:
+            from urllib.parse import urlparse
+            parsed = urlparse(url)
+        except ValueError:
+            return None
+
+        if parsed.scheme.lower() not in ("http", "https"):
+            return None
+
+        import urllib.error
+        import urllib.request
+
+        req = urllib.request.Request(url, headers={"User-Agent": "media-server/0.x"})
+        try:
+            with urllib.request.urlopen(req, timeout=_ART_FETCH_TIMEOUT) as resp:
+                return resp.read(_MAX_ART_BYTES + 1)[:_MAX_ART_BYTES] or None
+        except (urllib.error.URLError, urllib.error.HTTPError, OSError) as e:
+            logger.debug("Could not fetch macOS art %s: %s", url, e)
+            return None
+
+    async def get_album_art(self) -> Optional[bytes]:
+        """Return cached art bytes, fetching once per track URL."""
+        with self._art_lock:
+            url = self._art_url
+            cached = self._art_bytes
+        if cached is not None:
+            return cached
+        if not url:
+            return None
+        data = await asyncio.to_thread(self._fetch_art_sync, url)
+        with self._art_lock:
+            if url == self._art_url:
+                self._art_bytes = data
+        return data
+
     async def play(self) -> bool:
         """Resume playback using media key simulation."""
         # Use system media key
-        script = '''
-            tell application "System Events"
-                key code 16 using {command down, option down}
-            end tell
-        '''
         # Fallback: try specific app
         active_app = self._get_active_app()
         if active_app == "Spotify":
@@ -270,8 +323,12 @@ class MacOSMediaController(MediaController):
 
     async def set_volume(self, volume: int) -> bool:
         """Set system volume."""
-        result = self._run_osascript(f"set volume output volume {volume}")
-        return result is not None or True  # osascript returns empty on success
+        # osascript returns empty string on success and None on failure (the
+        # _run_osascript helper catches subprocess errors). The previous
+        # `result is not None or True` always returned True regardless of
+        # outcome — surface real failures so the route can return 503.
+        result = self._run_osascript(f"set volume output volume {int(volume)}")
+        return result is not None
 
     async def toggle_mute(self) -> bool:
         """Toggle mute state."""
@@ -294,3 +351,27 @@ class MacOSMediaController(MediaController):
             )
             return True
         return False
+
+    async def open_file(self, file_path: str) -> bool:
+        """Open a media file with the default system player (macOS).
+
+        Uses the 'open' command to open the file with the default application.
+
+        Args:
+            file_path: Absolute path to the media file
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            process = await asyncio.create_subprocess_exec(
+                'open', file_path,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL
+            )
+            await process.wait()
+            logger.info(f"Opened file with default player: {file_path}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to open file {file_path}: {e}")
+            return False

media_server/services/media_controller.py

@@ -94,3 +94,24 @@ class MediaController(ABC):
             True if successful, False otherwise
         """
         pass
+
+    @abstractmethod
+    async def open_file(self, file_path: str) -> bool:
+        """Open a media file with the default system player.
+
+        Args:
+            file_path: Absolute path to the media file
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+
+    async def get_album_art(self) -> bytes | None:
+        """Return the current album art bytes, or ``None`` when unavailable.
+
+        Default impl returns ``None`` — controllers that can produce art
+        (Windows via SMTC thumbnail, Linux via mpris:artUrl, macOS via the
+        Spotify/Music artwork-url field) override this.
+        """
+        return None

media_server/services/metadata_service.py

@@ -0,0 +1,203 @@
+"""Metadata extraction service for media files."""
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class MetadataService:
+    """Service for extracting metadata from media files."""
+
+    @staticmethod
+    def extract_audio_metadata(file_path: Path) -> dict:
+        """Extract metadata from an audio file.
+
+        Args:
+            file_path: Path to the audio file.
+
+        Returns:
+            Dictionary with audio metadata.
+        """
+        try:
+            from mutagen import File as MutagenFile
+
+            audio = MutagenFile(str(file_path), easy=True)
+            if audio is None:
+                return {"error": "Unable to read audio file"}
+
+            try:
+                metadata = {
+                    "type": "audio",
+                    "filename": file_path.name,
+                    "path": str(file_path),
+                }
+
+                # Extract duration
+                if hasattr(audio.info, "length"):
+                    metadata["duration"] = round(audio.info.length, 2)
+
+                # Extract bitrate
+                if hasattr(audio.info, "bitrate"):
+                    metadata["bitrate"] = audio.info.bitrate
+
+                # Extract sample rate
+                if hasattr(audio.info, "sample_rate"):
+                    metadata["sample_rate"] = audio.info.sample_rate
+                elif hasattr(audio.info, "samplerate"):
+                    metadata["sample_rate"] = audio.info.samplerate
+
+                # Extract channels
+                if hasattr(audio.info, "channels"):
+                    metadata["channels"] = audio.info.channels
+
+                # Extract tags (use easy=True for consistent tag names)
+                if audio is not None and hasattr(audio, "tags") and audio.tags:
+                    # Easy tags provide lists, so we take the first item
+                    tags = audio.tags
+
+                    if "title" in tags:
+                        metadata["title"] = tags["title"][0] if isinstance(tags["title"], list) else tags["title"]
+
+                    if "artist" in tags:
+                        metadata["artist"] = tags["artist"][0] if isinstance(tags["artist"], list) else tags["artist"]
+
+                    if "album" in tags:
+                        metadata["album"] = tags["album"][0] if isinstance(tags["album"], list) else tags["album"]
+
+                    if "albumartist" in tags:
+                        metadata["album_artist"] = (
+                            tags["albumartist"][0] if isinstance(tags["albumartist"], list) else tags["albumartist"]
+                        )
+
+                    if "date" in tags:
+                        metadata["date"] = tags["date"][0] if isinstance(tags["date"], list) else tags["date"]
+
+                    if "genre" in tags:
+                        metadata["genre"] = tags["genre"][0] if isinstance(tags["genre"], list) else tags["genre"]
+
+                    if "tracknumber" in tags:
+                        metadata["track_number"] = (
+                            tags["tracknumber"][0] if isinstance(tags["tracknumber"], list) else tags["tracknumber"]
+                        )
+
+                # If no title tag, use filename
+                if "title" not in metadata:
+                    metadata["title"] = file_path.stem
+
+                return metadata
+            finally:
+                if hasattr(audio, 'close'):
+                    audio.close()
+
+        except ImportError:
+            logger.error("mutagen library not installed, cannot extract metadata")
+            return {"error": "mutagen library not installed"}
+        except Exception as e:
+            logger.error(f"Error extracting audio metadata from {file_path}: {e}")
+            return {
+                "error": str(e),
+                "filename": file_path.name,
+                "title": file_path.stem,
+            }
+
+    @staticmethod
+    def extract_video_metadata(file_path: Path) -> dict:
+        """Extract basic metadata from a video file.
+
+        Args:
+            file_path: Path to the video file.
+
+        Returns:
+            Dictionary with video metadata.
+        """
+        try:
+            from mutagen import File as MutagenFile
+
+            video = MutagenFile(str(file_path))
+            if video is None:
+                return {
+                    "type": "video",
+                    "filename": file_path.name,
+                    "title": file_path.stem,
+                }
+
+            try:
+                metadata = {
+                    "type": "video",
+                    "filename": file_path.name,
+                    "path": str(file_path),
+                }
+
+                # Extract duration
+                if hasattr(video.info, "length"):
+                    metadata["duration"] = round(video.info.length, 2)
+
+                # Extract bitrate
+                if hasattr(video.info, "bitrate"):
+                    metadata["bitrate"] = video.info.bitrate
+
+                # Extract video-specific properties if available
+                if hasattr(video.info, "width"):
+                    metadata["width"] = video.info.width
+
+                if hasattr(video.info, "height"):
+                    metadata["height"] = video.info.height
+
+                # Try to extract title from tags
+                if hasattr(video, "tags") and video.tags:
+                    tags = video.tags
+                    if hasattr(tags, "get"):
+                        title = tags.get("title") or tags.get("TITLE") or tags.get("\xa9nam")
+                        if title:
+                            metadata["title"] = title[0] if isinstance(title, list) else str(title)
+
+                # If no title tag, use filename
+                if "title" not in metadata:
+                    metadata["title"] = file_path.stem
+
+                return metadata
+            finally:
+                if hasattr(video, 'close'):
+                    video.close()
+
+        except ImportError:
+            logger.error("mutagen library not installed, cannot extract metadata")
+            return {
+                "error": "mutagen library not installed",
+                "type": "video",
+                "filename": file_path.name,
+                "title": file_path.stem,
+            }
+        except Exception as e:
+            logger.debug(f"Error extracting video metadata from {file_path}: {e}")
+            # Return basic metadata
+            return {
+                "type": "video",
+                "filename": file_path.name,
+                "title": file_path.stem,
+            }
+
+    @staticmethod
+    def extract_metadata(file_path: Path) -> dict:
+        """Extract metadata from a media file (auto-detect type).
+
+        Args:
+            file_path: Path to the media file.
+
+        Returns:
+            Dictionary with media metadata.
+        """
+        from .browser_service import AUDIO_EXTENSIONS, VIDEO_EXTENSIONS
+
+        suffix = file_path.suffix.lower()
+
+        if suffix in AUDIO_EXTENSIONS:
+            return MetadataService.extract_audio_metadata(file_path)
+        elif suffix in VIDEO_EXTENSIONS:
+            return MetadataService.extract_video_metadata(file_path)
+        else:
+            return {
+                "error": "Unsupported file type",
+                "filename": file_path.name,
+            }

media_server/services/rate_limit.py

@@ -0,0 +1,95 @@
+"""In-process token-bucket rate limiter.
+
+Light enough for a single-process app: one dict keyed by ``(bucket, peer)``
+guarded by a thread lock. No extra dependency, no Redis. Good enough for
+defeating credential-stuffing and runaway clients on a LAN; not a substitute
+for an upstream WAF in a public deployment.
+
+Buckets:
+    auth        — failed-auth attempts, 5/min/peer (used in auth middleware)
+    execute     — script + callback execute calls, 10/min/peer (LAN-friendly)
+    default     — generic POST/DELETE writes, 60/min/peer
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BucketConfig:
+    capacity: float       # max tokens (= burst size)
+    refill_per_sec: float # tokens added per second
+
+
+# Defaults — tuned for "trusted LAN" use; operator can override via Settings.
+BUCKETS: dict[str, BucketConfig] = {
+    "auth":    BucketConfig(capacity=5,  refill_per_sec=5 / 60),     # 5/min
+    "execute": BucketConfig(capacity=10, refill_per_sec=10 / 60),    # 10/min
+    "default": BucketConfig(capacity=60, refill_per_sec=60 / 60),    # 60/min
+}
+
+
+_state: dict[tuple[str, str], tuple[float, float]] = {}
+_lock = threading.Lock()
+_LAST_CLEANUP = 0.0
+
+
+def _evict_stale_locked(now: float) -> None:
+    """Drop entries whose buckets are full (= idle for capacity / refill seconds)."""
+    global _LAST_CLEANUP
+    if now - _LAST_CLEANUP < 60:
+        return
+    _LAST_CLEANUP = now
+    stale = []
+    for key, (tokens, last) in _state.items():
+        bucket = BUCKETS.get(key[0])
+        if bucket is None:
+            continue
+        if tokens >= bucket.capacity and (now - last) > 3600:
+            stale.append(key)
+    for key in stale:
+        _state.pop(key, None)
+
+
+def check(bucket: str, peer: str) -> tuple[bool, Optional[float]]:
+    """Try to consume one token from ``(bucket, peer)``.
+
+    Returns:
+        (allowed, retry_after_seconds). When allowed=True retry_after is None.
+        When allowed=False, retry_after is the seconds to wait for one more token.
+    """
+    cfg = BUCKETS.get(bucket) or BUCKETS["default"]
+    now = time.monotonic()
+    with _lock:
+        _evict_stale_locked(now)
+        tokens, last = _state.get((bucket, peer), (cfg.capacity, now))
+        elapsed = max(0.0, now - last)
+        tokens = min(cfg.capacity, tokens + elapsed * cfg.refill_per_sec)
+        if tokens >= 1:
+            tokens -= 1
+            _state[(bucket, peer)] = (tokens, now)
+            return True, None
+        deficit = 1 - tokens
+        retry = deficit / cfg.refill_per_sec if cfg.refill_per_sec > 0 else 60
+        _state[(bucket, peer)] = (tokens, now)
+        return False, retry
+
+
+def get_peer(request) -> str:
+    """Best-effort peer identifier from a Starlette request.
+
+    Honors X-Forwarded-For (only when settings.proxy_headers is True, which is
+    already enforced by uvicorn's middleware) so a reverse-proxied install
+    still rate-limits per real client.
+    """
+    client = getattr(request, "client", None)
+    if client and client.host:
+        return client.host
+    return "unknown"

media_server/services/release_provider.py

@@ -0,0 +1,29 @@
+"""Abstract release provider interface for version checking."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class ReleaseInfo:
+    """Version-provider-agnostic release metadata."""
+
+    version: str  # e.g. "1.1.0" (no "v" prefix)
+    url: str  # release page URL
+    prerelease: bool
+
+
+class ReleaseProvider(Protocol):
+    """Abstract interface for fetching the latest release.
+
+    Implement this protocol to support different hosting platforms
+    (Gitea, GitHub, GitLab, etc.).
+    """
+
+    async def get_latest_release(self) -> ReleaseInfo | None:
+        """Fetch the latest stable release.
+
+        Returns:
+            ReleaseInfo if a release was found, None on failure.
+        """
+        ...

media_server/services/thumbnail_service.py

@@ -0,0 +1,405 @@
+"""Thumbnail generation and caching service."""
+
+import asyncio
+import hashlib
+import logging
+import shutil
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Thumbnail sizes
+THUMBNAIL_SIZES = {
+    "small": (150, 150),
+    "medium": (300, 300),
+}
+
+# Cache size limit (500MB)
+CACHE_SIZE_LIMIT = 500 * 1024 * 1024  # 500MB in bytes
+
+
+class ThumbnailService:
+    """Service for generating and caching thumbnails."""
+
+    @staticmethod
+    def get_cache_dir() -> Path:
+        """Get the thumbnail cache directory path.
+
+        Returns user-writable platform cache dir so installs under
+        ``%PROGRAMFILES%`` / ``/opt`` work without elevated permissions.
+        Mirrors the platform branching of ``config.get_config_dir``.
+        """
+        import os
+
+        if os.name == "nt":
+            # %LOCALAPPDATA% so the cache survives roaming-profile sync.
+            base = Path(os.environ.get("LOCALAPPDATA")
+                        or os.environ.get("APPDATA")
+                        or Path.home() / "AppData" / "Local")
+            cache_dir = base / "media-server" / "cache" / "thumbnails"
+        else:
+            # XDG_CACHE_HOME convention; falls back to ~/.cache.
+            xdg = os.environ.get("XDG_CACHE_HOME")
+            base = Path(xdg) if xdg else Path.home() / ".cache"
+            cache_dir = base / "media-server" / "thumbnails"
+
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        return cache_dir
+
+    @staticmethod
+    def get_cache_key(file_path: Path) -> str:
+        """Generate cache key from file path.
+
+        Args:
+            file_path: Path to the media file.
+
+        Returns:
+            SHA256 hash of the absolute file path.
+        """
+        absolute_path = str(file_path.resolve())
+        return hashlib.sha256(absolute_path.encode()).hexdigest()
+
+    # Sentinel value indicating "no thumbnail available" is cached
+    NO_THUMBNAIL = b""
+
+    @staticmethod
+    def get_cached_thumbnail(file_path: Path, size: str) -> Optional[bytes]:
+        """Get cached thumbnail if valid.
+
+        Args:
+            file_path: Path to the media file.
+            size: Thumbnail size ("small" or "medium").
+
+        Returns:
+            Thumbnail bytes if cached, empty bytes if cached as "no thumbnail",
+            None if not cached.
+        """
+        cache_dir = ThumbnailService.get_cache_dir()
+        cache_key = ThumbnailService.get_cache_key(file_path)
+        cache_folder = cache_dir / cache_key
+        cache_path = cache_folder / f"{size}.jpg"
+        no_thumb_path = cache_folder / ".no_thumbnail"
+
+        # Check negative cache first (no thumbnail available)
+        if no_thumb_path.exists():
+            try:
+                file_mtime = file_path.stat().st_mtime
+                cache_mtime = no_thumb_path.stat().st_mtime
+                if file_mtime <= cache_mtime:
+                    return ThumbnailService.NO_THUMBNAIL
+            except (OSError, PermissionError):
+                pass
+
+        if not cache_path.exists():
+            return None
+
+        # Check if file has been modified since cache was created
+        try:
+            file_mtime = file_path.stat().st_mtime
+            cache_mtime = cache_path.stat().st_mtime
+
+            if file_mtime > cache_mtime:
+                logger.debug(f"Cache invalidated for {file_path.name} (file modified)")
+                return None
+
+            # Read cached thumbnail
+            with open(cache_path, "rb") as f:
+                return f.read()
+
+        except (OSError, PermissionError) as e:
+            logger.error(f"Error reading cached thumbnail: {e}")
+            return None
+
+    @staticmethod
+    def cache_thumbnail(file_path: Path, size: str, image_data: bytes) -> None:
+        """Cache a thumbnail.
+
+        Args:
+            file_path: Path to the media file.
+            size: Thumbnail size ("small" or "medium").
+            image_data: Thumbnail image data (JPEG bytes).
+        """
+        cache_dir = ThumbnailService.get_cache_dir()
+        cache_key = ThumbnailService.get_cache_key(file_path)
+        cache_folder = cache_dir / cache_key
+        cache_folder.mkdir(parents=True, exist_ok=True)
+
+        cache_path = cache_folder / f"{size}.jpg"
+
+        try:
+            with open(cache_path, "wb") as f:
+                f.write(image_data)
+            logger.debug(f"Cached thumbnail for {file_path.name} ({size})")
+        except (OSError, PermissionError) as e:
+            logger.error(f"Error caching thumbnail: {e}")
+
+    @staticmethod
+    def cache_no_thumbnail(file_path: Path) -> None:
+        """Cache that a file has no thumbnail (negative cache)."""
+        cache_dir = ThumbnailService.get_cache_dir()
+        cache_key = ThumbnailService.get_cache_key(file_path)
+        cache_folder = cache_dir / cache_key
+        cache_folder.mkdir(parents=True, exist_ok=True)
+
+        try:
+            (cache_folder / ".no_thumbnail").touch()
+            logger.debug(f"Cached no-thumbnail for {file_path.name}")
+        except (OSError, PermissionError) as e:
+            logger.error(f"Error caching no-thumbnail marker: {e}")
+
+    @staticmethod
+    def generate_audio_thumbnail(file_path: Path, size: str) -> Optional[bytes]:
+        """Generate thumbnail from audio file (extract album art).
+
+        Args:
+            file_path: Path to the audio file.
+            size: Thumbnail size ("small" or "medium").
+
+        Returns:
+            Thumbnail bytes (JPEG) or None if no album art.
+        """
+        try:
+            from io import BytesIO
+
+            from mutagen import File as MutagenFile
+            from PIL import Image
+
+            audio = MutagenFile(str(file_path))
+            if audio is None:
+                return None
+
+            # Extract album art
+            art_data = None
+
+            # Try different tag types for album art
+            if hasattr(audio, "pictures") and audio.pictures:
+                # FLAC, Ogg Vorbis
+                art_data = audio.pictures[0].data
+            elif hasattr(audio, "tags"):
+                tags = audio.tags
+                if tags is not None:
+                    # MP3 (ID3)
+                    if hasattr(tags, "getall"):
+                        apic_frames = tags.getall("APIC")
+                        if apic_frames:
+                            art_data = apic_frames[0].data
+                    # MP4/M4A
+                    elif "covr" in tags:
+                        art_data = bytes(tags["covr"][0])
+                    # Try other common keys
+                    elif "APIC:" in tags:
+                        art_data = tags["APIC:"].data
+
+            if art_data is None:
+                return None
+
+            # Resize image
+            img = Image.open(BytesIO(art_data))
+
+            # Convert to RGB if necessary (handle RGBA, grayscale, etc.)
+            if img.mode not in ("RGB", "L"):
+                img = img.convert("RGB")
+
+            # Resize with maintaining aspect ratio and center crop
+            target_size = THUMBNAIL_SIZES[size]
+            img.thumbnail((target_size[0] * 2, target_size[1] * 2), Image.Resampling.LANCZOS)
+
+            # Center crop to square
+            width, height = img.size
+            min_dim = min(width, height)
+            left = (width - min_dim) // 2
+            top = (height - min_dim) // 2
+            right = left + min_dim
+            bottom = top + min_dim
+            img = img.crop((left, top, right, bottom))
+
+            # Final resize
+            img = img.resize(target_size, Image.Resampling.LANCZOS)
+
+            # Save as JPEG
+            output = BytesIO()
+            img.save(output, format="JPEG", quality=85, optimize=True)
+            return output.getvalue()
+
+        except ImportError:
+            logger.error("Required libraries (mutagen, Pillow) not installed")
+            return None
+        except Exception as e:
+            logger.debug(f"Error generating audio thumbnail for {file_path.name}: {e}")
+            return None
+
+    @staticmethod
+    async def generate_video_thumbnail(file_path: Path, size: str) -> Optional[bytes]:
+        """Generate thumbnail from video file using ffmpeg.
+
+        Args:
+            file_path: Path to the video file.
+            size: Thumbnail size ("small" or "medium").
+
+        Returns:
+            Thumbnail bytes (JPEG) or None if ffmpeg not available.
+        """
+        try:
+            from io import BytesIO
+
+            from PIL import Image
+
+            # Check if ffmpeg is available
+            if not shutil.which("ffmpeg"):
+                logger.debug("ffmpeg not available, cannot generate video thumbnail")
+                return None
+
+            # Extract frame at 10% duration
+            target_size = THUMBNAIL_SIZES[size]
+
+            # Use ffmpeg to extract a frame
+            cmd = [
+                "ffmpeg",
+                "-i", str(file_path),
+                "-vf", (
+                    f"thumbnail,scale={target_size[0]}:{target_size[1]}"
+                    f":force_original_aspect_ratio=increase"
+                    f",crop={target_size[0]}:{target_size[1]}"
+                ),
+                "-frames:v", "1",
+                "-f", "image2pipe",
+                "-vcodec", "mjpeg",
+                "-"
+            ]
+
+            # Run ffmpeg with timeout
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+
+            try:
+                stdout, _ = await asyncio.wait_for(process.communicate(), timeout=10.0)
+                if process.returncode == 0 and stdout:
+                    # ffmpeg output is already JPEG, but let's ensure proper quality
+                    img = Image.open(BytesIO(stdout))
+
+                    # Convert to RGB if necessary
+                    if img.mode != "RGB":
+                        img = img.convert("RGB")
+
+                    # Save as JPEG with consistent quality
+                    output = BytesIO()
+                    img.save(output, format="JPEG", quality=85, optimize=True)
+                    return output.getvalue()
+
+            except asyncio.TimeoutError:
+                logger.warning(f"ffmpeg timeout for {file_path.name}")
+                process.kill()
+                await process.wait()
+
+            return None
+
+        except ImportError:
+            logger.error("Pillow library not installed")
+            return None
+        except Exception as e:
+            logger.debug(f"Error generating video thumbnail for {file_path.name}: {e}")
+            return None
+
+    @staticmethod
+    async def get_thumbnail(file_path: Path, size: str = "medium") -> Optional[bytes]:
+        """Get thumbnail for a media file (from cache or generate).
+
+        Args:
+            file_path: Path to the media file.
+            size: Thumbnail size ("small" or "medium").
+
+        Returns:
+            Thumbnail bytes (JPEG) or None if unavailable.
+        """
+        from .browser_service import AUDIO_EXTENSIONS, VIDEO_EXTENSIONS
+
+        # Validate size
+        if size not in THUMBNAIL_SIZES:
+            size = "medium"
+
+        # Check cache first (returns bytes, empty bytes for negative cache, or None)
+        cached = ThumbnailService.get_cached_thumbnail(file_path, size)
+        if cached is not None:
+            return cached if cached else None
+
+        # Generate thumbnail based on file type
+        suffix = file_path.suffix.lower()
+        thumbnail_data = None
+
+        if suffix in AUDIO_EXTENSIONS:
+            # Audio files - run in executor (sync operation)
+            loop = asyncio.get_running_loop()
+            thumbnail_data = await loop.run_in_executor(
+                None,
+                ThumbnailService.generate_audio_thumbnail,
+                file_path,
+                size,
+            )
+        elif suffix in VIDEO_EXTENSIONS:
+            # Video files - already async
+            thumbnail_data = await ThumbnailService.generate_video_thumbnail(file_path, size)
+
+        # Cache result (positive or negative)
+        if thumbnail_data:
+            ThumbnailService.cache_thumbnail(file_path, size, thumbnail_data)
+        else:
+            ThumbnailService.cache_no_thumbnail(file_path)
+
+        return thumbnail_data
+
+    @staticmethod
+    def cleanup_cache() -> None:
+        """Clean up cache if it exceeds size limit.
+
+        Removes oldest thumbnails by access time.
+        """
+        cache_dir = ThumbnailService.get_cache_dir()
+
+        try:
+            # Calculate total cache size
+            total_size = 0
+            cache_items = []
+
+            for folder in cache_dir.iterdir():
+                if folder.is_dir():
+                    for file in folder.iterdir():
+                        if file.is_file():
+                            stat = file.stat()
+                            total_size += stat.st_size
+                            cache_items.append((file, stat.st_atime, stat.st_size))
+
+            # If cache is within limit, no cleanup needed
+            if total_size <= CACHE_SIZE_LIMIT:
+                return
+
+            logger.info(f"Cache size {total_size / 1024 / 1024:.2f}MB exceeds limit, cleaning up...")
+
+            # Sort by access time (oldest first)
+            cache_items.sort(key=lambda x: x[1])
+
+            # Remove oldest items until under limit
+            for file, _, size in cache_items:
+                if total_size <= CACHE_SIZE_LIMIT:
+                    break
+
+                try:
+                    file.unlink()
+                    total_size -= size
+                    logger.debug(f"Removed cached thumbnail: {file}")
+
+                    # Remove empty parent folder
+                    parent = file.parent
+                    if parent != cache_dir and not any(parent.iterdir()):
+                        parent.rmdir()
+
+                except (OSError, PermissionError) as e:
+                    logger.error(f"Error removing cache file: {e}")
+
+            logger.info(f"Cache cleanup complete, new size: {total_size / 1024 / 1024:.2f}MB")
+
+        except Exception as e:
+            logger.error(f"Error during cache cleanup: {e}")

media_server/services/update_checker.py

@@ -0,0 +1,169 @@
+"""Provider-agnostic update checker service."""
+
+import asyncio
+import logging
+import re
+from functools import total_ordering
+from typing import Any, Optional
+
+from .release_provider import ReleaseProvider
+from .websocket_manager import ws_manager
+
+logger = logging.getLogger(__name__)
+
+_PRE_PATTERN = re.compile(
+    r"^(\d+\.\d+\.\d+)[-.]?(alpha|beta|rc)[.-]?(\d+)$", re.IGNORECASE
+)
+_PRE_ORDER = {"alpha": 0, "beta": 1, "rc": 2}
+
+
+@total_ordering
+class _Version:
+    """Lightweight PEP 440-ish version for comparison without packaging dep.
+
+    Supports: X.Y.Z and X.Y.Z-{alpha,beta,rc}.N
+    Pre-releases sort before the corresponding stable release.
+    """
+
+    __slots__ = ("_release", "_pre")
+
+    def __init__(self, release: tuple[int, ...], pre: Optional[tuple[int, int]]) -> None:
+        self._release = release
+        self._pre = pre
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _Version):
+            return NotImplemented
+        return self._release == other._release and self._pre == other._pre
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, _Version):
+            return NotImplemented
+        if self._release != other._release:
+            return self._release < other._release
+        # No pre-release (stable) is greater than any pre-release
+        if self._pre is None and other._pre is None:
+            return False
+        if self._pre is not None and other._pre is None:
+            return True
+        if self._pre is None and other._pre is not None:
+            return False
+        return self._pre < other._pre  # type: ignore[operator]
+
+    def __repr__(self) -> str:
+        v = ".".join(str(p) for p in self._release)
+        if self._pre is not None:
+            labels = {0: "alpha", 1: "beta", 2: "rc"}
+            v += f"-{labels[self._pre[0]]}.{self._pre[1]}"
+        return f"_Version('{v}')"
+
+
+def _parse_version(raw: str) -> _Version:
+    """Parse a version tag for comparison.
+
+    Examples:
+        v0.3.0-alpha.1 → (0,3,0) pre=(0,1)  (sorts below 0.3.0)
+        v0.3.0-rc.3    → (0,3,0) pre=(2,3)
+        v1.0.0         → (1,0,0) pre=None
+    """
+    cleaned = raw.lstrip("v").strip()
+    m = _PRE_PATTERN.match(cleaned)
+    if m:
+        base = tuple(int(x) for x in m.group(1).split("."))
+        pre_label = m.group(2).lower()
+        pre_num = int(m.group(3))
+        return _Version(base, (_PRE_ORDER[pre_label], pre_num))
+    release = tuple(int(x) for x in cleaned.split("."))
+    return _Version(release, None)
+
+
+class UpdateChecker:
+    """Periodically checks for new releases using a ReleaseProvider."""
+
+    def __init__(self, provider: ReleaseProvider, current_version: str) -> None:
+        self._provider = provider
+        self._current_version = current_version
+        self._current_parsed = _parse_version(current_version)
+        self._task: Optional[asyncio.Task] = None
+        self._cached_update: Optional[dict[str, Any]] = None
+
+    @property
+    def cached_update(self) -> Optional[dict[str, Any]]:
+        """Return the cached update info, or None if up-to-date."""
+        return self._cached_update
+
+    async def check_for_update(self) -> Optional[dict[str, Any]]:
+        """Check for a newer release.
+
+        Returns:
+            Dict with current/latest/url if an update exists, None otherwise.
+        """
+        release = await self._provider.get_latest_release()
+        if release is None:
+            return None
+
+        latest_parsed = _parse_version(release.version)
+        if latest_parsed <= self._current_parsed:
+            return None
+
+        return {
+            "current": self._current_version,
+            "latest": release.version,
+            "url": release.url,
+        }
+
+    async def start(self, interval: int) -> None:
+        """Start periodic update checking.
+
+        Checks immediately on start, then every `interval` seconds.
+        """
+        if self._task is not None:
+            return
+
+        self._task = asyncio.create_task(self._check_loop(interval))
+        logger.info("Update checker started (interval: %ds)", interval)
+
+    async def stop(self) -> None:
+        """Stop periodic update checking."""
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+            logger.info("Update checker stopped")
+
+    async def _check_loop(self, interval: int) -> None:
+        """Background loop that checks for updates periodically."""
+        # Initial check with a small delay to let the server finish starting
+        await asyncio.sleep(5)
+
+        while True:
+            try:
+                update = await self.check_for_update()
+
+                if update and update != self._cached_update:
+                    self._cached_update = update
+                    logger.info(
+                        "New version available: %s → %s (%s)",
+                        update["current"],
+                        update["latest"],
+                        update["url"],
+                    )
+                    await ws_manager.broadcast(
+                        {"type": "update_available", "data": update}
+                    )
+                elif update is None and self._cached_update is not None:
+                    # Version was updated (or release removed) — clear cache
+                    self._cached_update = None
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.warning("Update check failed: %s", e)
+
+            try:
+                await asyncio.sleep(interval)
+            except asyncio.CancelledError:
+                break

media_server/services/websocket_manager.py

@@ -1,6 +1,7 @@
 """WebSocket connection manager and status broadcaster."""
 
 import asyncio
+import json
 import logging
 import time
 from typing import Any, Callable, Coroutine
@@ -18,15 +19,29 @@ class ConnectionManager:
         self._active_connections: set[WebSocket] = set()
         self._lock = asyncio.Lock()
         self._last_status: dict[str, Any] | None = None
+        self._last_foreground: dict[str, Any] | None = None
+        self._foreground_poll_interval: float = 1.0
+        self._last_foreground_poll: float = 0.0
+        self._get_status_func: Callable[[], Coroutine[Any, Any, Any]] | None = None
         self._broadcast_task: asyncio.Task | None = None
         self._poll_interval: float = 0.5  # Internal poll interval for change detection
         self._position_broadcast_interval: float = 5.0  # Send position updates every 5s during playback
         self._last_broadcast_time: float = 0.0
         self._running: bool = False
+        # Audio visualizer
+        self._visualizer_subscribers: set[WebSocket] = set()
+        self._audio_task: asyncio.Task | None = None
+        self._audio_analyzer = None
 
-    async def connect(self, websocket: WebSocket) -> None:
-        """Accept a new WebSocket connection."""
-        await websocket.accept()
+    async def connect(self, websocket: WebSocket, already_accepted: bool = False) -> None:
+        """Accept a new WebSocket connection.
+
+        ``already_accepted=True`` is for callers that needed to call
+        ``websocket.accept(subprotocol=...)`` themselves (token-via-subprotocol
+        auth path).
+        """
+        if not already_accepted:
+            await websocket.accept()
         async with self._lock:
             self._active_connections.add(websocket)
         logger.info(
@@ -34,39 +49,243 @@ class ConnectionManager:
         )
 
         # Send current status immediately upon connection
-        if self._last_status:
+        status = self._last_status
+        if not status and self._get_status_func:
             try:
-                await websocket.send_json({"type": "status", "data": self._last_status})
+                result = await self._get_status_func()
+                status = result.model_dump()
+                self._last_status = status
+            except Exception as e:
+                logger.debug("Failed to fetch initial status: %s", e)
+        if status:
+            try:
+                await websocket.send_json({"type": "status", "data": status})
             except Exception as e:
                 logger.debug("Failed to send initial status: %s", e)
 
+        # Push a fresh foreground snapshot on connect so the UI can render
+        # the tile immediately instead of waiting for the next change.
+        try:
+            from .foreground_service import get_foreground_info
+
+            fg = await asyncio.to_thread(get_foreground_info)
+            fg_dict = fg.to_dict()
+            self._last_foreground = fg_dict
+            await websocket.send_json({"type": "foreground", "data": fg_dict})
+        except Exception as e:
+            logger.debug("Failed to send initial foreground snapshot: %s", e)
+
     async def disconnect(self, websocket: WebSocket) -> None:
-        """Remove a WebSocket connection."""
+        """Remove a WebSocket connection. Stops audio capture if last visualizer subscriber."""
+        should_stop = False
         async with self._lock:
             self._active_connections.discard(websocket)
+            was_subscriber = websocket in self._visualizer_subscribers
+            self._visualizer_subscribers.discard(websocket)
+            if was_subscriber and len(self._visualizer_subscribers) == 0:
+                should_stop = True
+        if should_stop:
+            await self._maybe_stop_capture()
         logger.info(
             "WebSocket client disconnected. Total: %d", len(self._active_connections)
         )
 
     async def broadcast(self, message: dict[str, Any]) -> None:
-        """Broadcast a message to all connected clients."""
+        """Broadcast a message to all connected clients concurrently.
+
+        The payload is serialized once and pushed via ``send_text`` to every
+        client, instead of having Starlette/Pydantic encode it N times via
+        ``send_json``.
+        """
         async with self._lock:
             connections = list(self._active_connections)
 
         if not connections:
             return
 
-        disconnected = []
-        for websocket in connections:
+        try:
+            payload = json.dumps(message, default=str)
+        except (TypeError, ValueError) as e:
+            logger.error("Failed to encode broadcast message: %s", e)
+            return
+
+        async def _send(ws: WebSocket) -> WebSocket | None:
             try:
-                await websocket.send_json(message)
+                await ws.send_text(payload)
+                return None
             except Exception as e:
                 logger.debug("Failed to send to client: %s", e)
-                disconnected.append(websocket)
+                return ws
+
+        results = await asyncio.gather(*(_send(ws) for ws in connections))
 
         # Clean up disconnected clients
-        for ws in disconnected:
-            await self.disconnect(ws)
+        for ws in results:
+            if ws is not None:
+                await self.disconnect(ws)
+
+    async def broadcast_scripts_changed(self) -> None:
+        """Notify all connected clients that scripts have changed."""
+        message = {"type": "scripts_changed", "data": {}}
+        await self.broadcast(message)
+        logger.info("Broadcast sent: scripts_changed")
+
+    async def broadcast_links_changed(self) -> None:
+        """Notify all connected clients that links have changed."""
+        message = {"type": "links_changed", "data": {}}
+        await self.broadcast(message)
+        logger.info("Broadcast sent: links_changed")
+
+    def foreground_changed(
+        self, old: dict[str, Any] | None, new: dict[str, Any]
+    ) -> bool:
+        """Detect a meaningful change in the foreground process snapshot.
+
+        The probe also returns ``window_geometry`` which jitters on every
+        pixel of cursor drag — comparing the whole dict would flood clients.
+        We only diff the fields a user (or HA automation) would actually act
+        on. ``window_geometry``/``monitor_geometry``/``started_at`` are still
+        delivered in the payload, but they don't drive broadcast cadence.
+        """
+        if old is None:
+            return True
+        diff_fields = (
+            "pid",
+            "process_name",
+            "executable_path",
+            "window_title",
+            "is_fullscreen",
+            "is_minimized",
+            "monitor_id",
+            "available",
+            "error",
+        )
+        for f in diff_fields:
+            if old.get(f) != new.get(f):
+                return True
+        return False
+
+    async def subscribe_visualizer(self, websocket: WebSocket) -> None:
+        """Subscribe a client to audio visualizer data. Starts capture on first subscriber."""
+        should_start = False
+        async with self._lock:
+            self._visualizer_subscribers.add(websocket)
+            if len(self._visualizer_subscribers) == 1 and self._audio_analyzer:
+                should_start = True
+        if should_start:
+            await self._maybe_start_capture()
+        logger.debug("Visualizer subscriber added. Total: %d", len(self._visualizer_subscribers))
+
+    async def unsubscribe_visualizer(self, websocket: WebSocket) -> None:
+        """Unsubscribe a client from audio visualizer data. Stops capture on last subscriber."""
+        should_stop = False
+        async with self._lock:
+            self._visualizer_subscribers.discard(websocket)
+            if len(self._visualizer_subscribers) == 0:
+                should_stop = True
+        if should_stop:
+            await self._maybe_stop_capture()
+        logger.debug("Visualizer subscriber removed. Total: %d", len(self._visualizer_subscribers))
+
+    async def _maybe_start_capture(self) -> None:
+        """Start audio capture if not already running (called on first subscriber)."""
+        if self._audio_analyzer and not self._audio_analyzer.running:
+            loop = asyncio.get_running_loop()
+            started = await loop.run_in_executor(None, self._audio_analyzer.start)
+            if started:
+                logger.info("Audio capture started (first subscriber)")
+            else:
+                logger.warning("Audio capture failed to start")
+
+    async def _maybe_stop_capture(self) -> None:
+        """Stop audio capture if running (called when last subscriber leaves)."""
+        if self._audio_analyzer and self._audio_analyzer.running:
+            loop = asyncio.get_running_loop()
+            await loop.run_in_executor(None, self._audio_analyzer.stop)
+            logger.info("Audio capture stopped (no subscribers)")
+
+    async def start_audio_monitor(self, analyzer) -> None:
+        """Register the audio analyzer. Capture starts on-demand when clients subscribe."""
+        self._audio_analyzer = analyzer
+        if analyzer and analyzer.available:
+            self._audio_task = asyncio.create_task(self._audio_broadcast_loop())
+            logger.info("Audio visualizer broadcast loop started (capture on-demand)")
+
+    async def stop_audio_monitor(self) -> None:
+        """Stop audio frequency broadcasting."""
+        if self._audio_task:
+            self._audio_task.cancel()
+            try:
+                await self._audio_task
+            except asyncio.CancelledError:
+                pass
+            self._audio_task = None
+
+    async def _audio_broadcast_loop(self) -> None:
+        """Background loop: read frequency data from analyzer and broadcast to subscribers.
+
+        Event-driven: blocks on the analyzer's data_event so it wakes up
+        exactly once per produced frame, instead of polling on a timer.
+        Backstop sleep applies when capture is idle / has no subscribers.
+        """
+        from ..config import settings
+        idle_interval = 1.0 / max(1, settings.visualizer_fps)
+        # Bounded wait so we still notice subscribe/unsubscribe transitions.
+        wake_timeout = max(0.05, idle_interval)
+        loop = asyncio.get_running_loop()
+
+        last_seq = -1
+
+        while True:
+            try:
+                async with self._lock:
+                    subscribers = list(self._visualizer_subscribers)
+
+                analyzer = self._audio_analyzer
+                if not subscribers or not analyzer or not analyzer.running:
+                    await asyncio.sleep(idle_interval)
+                    continue
+
+                # Wait off-loop for a fresh frame. The capture thread sets
+                # data_event after each FFT update; we clear it before the
+                # next wait so we never burn a wake on stale data.
+                ev = analyzer.data_event
+
+                def _wait() -> bool:
+                    return ev.wait(wake_timeout)
+
+                got = await loop.run_in_executor(None, _wait)
+                if not got:
+                    # Timeout — loop around to re-check subscriber state.
+                    continue
+                ev.clear()
+
+                data, seq = analyzer.get_frequency_data_versioned()
+                if data is None or seq == last_seq:
+                    continue
+                last_seq = seq
+
+                # Pre-serialize once for all subscribers (avoids per-client JSON encoding)
+                text = json.dumps({"type": "audio_data", "data": data}, separators=(',', ':'))
+
+                async def _send(ws: WebSocket) -> WebSocket | None:
+                    try:
+                        await ws.send_text(text)
+                        return None
+                    except Exception:
+                        return ws
+
+                results = await asyncio.gather(*(_send(ws) for ws in subscribers))
+
+                failed = [ws for ws in results if ws is not None]
+                for ws in failed:
+                    await self.disconnect(ws)
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error("Error in audio broadcast: %s", e)
+                await asyncio.sleep(idle_interval)
 
     def status_changed(
         self, old: dict[str, Any] | None, new: dict[str, Any]
@@ -122,6 +341,7 @@ class ConnectionManager:
         if self._running:
             return
 
+        self._get_status_func = get_status_func
         self._running = True
         self._broadcast_task = asyncio.create_task(
             self._status_monitor_loop(get_status_func)
@@ -144,32 +364,57 @@ class ConnectionManager:
         get_status_func: Callable[[], Coroutine[Any, Any, Any]],
     ) -> None:
         """Background loop that polls for status changes and broadcasts."""
+        # Foreground tracker is imported lazily so unit tests of the WS
+        # manager don't drag in platform-specific probe code.
+        from .foreground_service import get_foreground_info
+
         while self._running:
             try:
                 # Only poll if we have connected clients
                 async with self._lock:
                     has_clients = len(self._active_connections) > 0
 
-                if has_clients:
-                    status = await get_status_func()
-                    status_dict = status.model_dump()
+                if not has_clients:
+                    await asyncio.sleep(2.0)  # Sleep longer when no clients connected
+                    continue
 
-                    # Only broadcast on actual state changes
-                    # Let HA handle position interpolation during playback
-                    if self.status_changed(self._last_status, status_dict):
-                        self._last_status = status_dict
-                        self._last_broadcast_time = time.time()
-                        await self.broadcast(
-                            {"type": "status_update", "data": status_dict}
-                        )
-                        logger.debug("Broadcast sent: status change")
-                    else:
-                        # Update cached status even without broadcast
-                        self._last_status = status_dict
+                status = await get_status_func()
+                status_dict = status.model_dump()
+
+                # Only broadcast on actual state changes
+                # Let HA handle position interpolation during playback
+                if self.status_changed(self._last_status, status_dict):
+                    self._last_status = status_dict
+                    self._last_broadcast_time = time.time()
+                    await self.broadcast(
+                        {"type": "status_update", "data": status_dict}
+                    )
+                    logger.debug("Broadcast sent: status change")
                 else:
-                    # Still update cache for when clients connect
-                    status = await get_status_func()
-                    self._last_status = status.model_dump()
+                    # Update cached status even without broadcast
+                    self._last_status = status_dict
+
+                # Foreground process — poll at a coarser interval than media
+                # status. Broadcasts only fire on a real change, so a quiet
+                # desktop costs nothing.
+                now = time.time()
+                if (
+                    now - self._last_foreground_poll
+                ) >= self._foreground_poll_interval:
+                    self._last_foreground_poll = now
+                    try:
+                        fg = await asyncio.to_thread(get_foreground_info)
+                        fg_dict = fg.to_dict()
+                        if self.foreground_changed(self._last_foreground, fg_dict):
+                            self._last_foreground = fg_dict
+                            await self.broadcast(
+                                {"type": "foreground_update", "data": fg_dict}
+                            )
+                            logger.debug("Broadcast sent: foreground change")
+                        else:
+                            self._last_foreground = fg_dict
+                    except Exception as e:
+                        logger.debug("Foreground poll failed: %s", e)
 
                 await asyncio.sleep(self._poll_interval)
 

media_server/services/windows_media.py

@@ -2,8 +2,10 @@
 
 import asyncio
 import logging
+import threading
+import time as _time
 from concurrent.futures import ThreadPoolExecutor
-from typing import Optional, Any
+from typing import Any
 
 from ..models import MediaState, MediaStatus
 from .media_controller import MediaController
@@ -13,11 +15,36 @@ logger = logging.getLogger(__name__)
 # Thread pool for WinRT operations (they don't play well with asyncio)
 _executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="winrt")
 
-# Global storage for current album art (as bytes)
+# Cache an asyncio event loop per worker thread so the 500ms status poll
+# doesn't allocate + tear down a new loop on every tick. Creating a loop
+# every 0.5s churns CPU and leaks finalized loop references that linger in
+# WinRT callbacks. With this helper a thread reuses one loop forever and
+# we only pay the setup cost once per worker.
+_thread_local = threading.local()
+
+
+def _thread_loop() -> asyncio.AbstractEventLoop:
+    loop = getattr(_thread_local, "loop", None)
+    if loop is None or loop.is_closed():
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        _thread_local.loop = loop
+    return loop
+
+# Global storage for current album art (as bytes). Guarded by _art_lock so the
+# WinRT polling thread and the FastAPI handler thread don't race on swap.
 _current_album_art_bytes: bytes | None = None
+_art_lock = threading.Lock()
+
+# Identity of the track whose art is currently in _current_album_art_bytes.
+# Used to gate the expensive WinRT thumbnail.open_read_async() so the bytes
+# aren't re-decoded on every 500ms status poll.
+_current_album_art_key: tuple | None = None
+
+# Lock protecting _position_cache and _track_skip_pending from concurrent access
+_position_lock = threading.Lock()
 
 # Global storage for position tracking
-import time as _time
 _position_cache = {
     "track_id": "",
     "base_position": 0.0,
@@ -36,13 +63,16 @@ _track_skip_pending = {
 
 
 def get_current_album_art() -> bytes | None:
-    """Get the current album art bytes."""
-    return _current_album_art_bytes
+    """Get the current album art bytes (thread-safe snapshot)."""
+    with _art_lock:
+        return _current_album_art_bytes
 
 # Windows-specific imports
 try:
     from winsdk.windows.media.control import (
         GlobalSystemMediaTransportControlsSessionManager as MediaManager,
+    )
+    from winsdk.windows.media.control import (
         GlobalSystemMediaTransportControlsSessionPlaybackStatus as PlaybackStatus,
     )
 
@@ -54,41 +84,100 @@ except ImportError:
 # Volume control imports
 PYCAW_AVAILABLE = False
 _volume_control = None
+_configured_device_name: str | None = None
 
 try:
-    from ctypes import cast, POINTER
-    from comtypes import CLSCTX_ALL, CoInitialize, CoUninitialize
-    from pycaw.pycaw import AudioUtilities, IAudioEndpointVolume
+    import warnings
+    from ctypes import POINTER, cast
 
-    def _init_volume_control():
-        """Initialize volume control interface."""
-        global _volume_control
-        if _volume_control is not None:
-            return _volume_control
+    from comtypes import CLSCTX_ALL
+    from pycaw.pycaw import AudioUtilities, IAudioEndpointVolume
+    # Suppress pycaw warnings about missing device properties
+    warnings.filterwarnings("ignore", category=UserWarning, module="pycaw")
+
+    def _get_all_audio_devices() -> list[dict[str, str]]:
+        """Get list of all audio output devices."""
+        devices = []
         try:
-            devices = AudioUtilities.GetSpeakers()
-            interface = devices.Activate(IAudioEndpointVolume._iid_, CLSCTX_ALL, None)
+            # Use pycaw's GetAllDevices which handles property retrieval
+            all_devices = AudioUtilities.GetAllDevices()
+            for device in all_devices:
+                # Only include render (output) devices with valid names
+                # Render devices have IDs starting with {0.0.0
+                if device.FriendlyName and device.id and device.id.startswith("{0.0.0"):
+                    devices.append({
+                        "id": device.id,
+                        "name": device.FriendlyName,
+                    })
+        except Exception as e:
+            logger.error(f"Error enumerating audio devices: {e}")
+        return devices
+
+    def _find_device_by_name(device_name: str):
+        """Find an audio device by its friendly name (partial match).
+
+        Returns the AudioDevice wrapper for the matched device.
+        """
+        try:
+            # Get all devices and find matching one
+            all_devices = AudioUtilities.GetAllDevices()
+            for device in all_devices:
+                if device.FriendlyName and device_name.lower() in device.FriendlyName.lower():
+                    logger.info(f"Found audio device: {device.FriendlyName}")
+                    return device
+        except Exception as e:
+            logger.error(f"Error finding device by name: {e}")
+        return None
+
+    def _init_volume_control(device_name: str | None = None):
+        """Initialize volume control interface.
+
+        Args:
+            device_name: Name of the audio device to control (partial match).
+                        If None, uses the default audio device.
+        """
+        global _volume_control, _configured_device_name
+        if _volume_control is not None and device_name == _configured_device_name:
+            return _volume_control
+
+        _configured_device_name = device_name
+
+        try:
+            if device_name:
+                # Find specific device by name
+                device = _find_device_by_name(device_name)
+                if device is None:
+                    logger.warning(f"Audio device '{device_name}' not found, using default")
+                    device = AudioUtilities.GetSpeakers()
+            else:
+                # Use default device
+                device = AudioUtilities.GetSpeakers()
+
+            if hasattr(device, 'Activate'):
+                interface = device.Activate(IAudioEndpointVolume._iid_, CLSCTX_ALL, None)
+            elif hasattr(device, '_dev'):
+                interface = device._dev.Activate(IAudioEndpointVolume._iid_, CLSCTX_ALL, None)
+            else:
+                logger.warning("Could not activate audio device")
+                return None
+
             _volume_control = cast(interface, POINTER(IAudioEndpointVolume))
             return _volume_control
-        except AttributeError:
-            # Try accessing the underlying device
-            try:
-                devices = AudioUtilities.GetSpeakers()
-                if hasattr(devices, '_dev'):
-                    interface = devices._dev.Activate(IAudioEndpointVolume._iid_, CLSCTX_ALL, None)
-                    _volume_control = cast(interface, POINTER(IAudioEndpointVolume))
-                    return _volume_control
-            except Exception as e:
-                logger.debug(f"Volume control init failed: {e}")
         except Exception as e:
-            logger.debug(f"Volume control init error: {e}")
+            logger.error(f"Volume control init error: {e}")
         return None
 
     PYCAW_AVAILABLE = True
 except ImportError as e:
     logger.warning(f"pycaw not available: {e}")
 
-    def _init_volume_control():
+    def _get_all_audio_devices() -> list[dict[str, str]]:
+        return []
+
+    def _find_device_by_name(device_name: str):
+        return None
+
+    def _init_volume_control(device_name: str | None = None):
         return None
 
 WINDOWS_AVAILABLE = WINSDK_AVAILABLE
@@ -96,8 +185,6 @@ WINDOWS_AVAILABLE = WINSDK_AVAILABLE
 
 def _sync_get_media_status() -> dict[str, Any]:
     """Synchronously get media status (runs in thread pool)."""
-    import asyncio
-
     result = {
         "state": "idle",
         "title": None,
@@ -109,9 +196,7 @@ def _sync_get_media_status() -> dict[str, Any]:
     }
 
     try:
-        # Create a new event loop for this thread
-        loop = asyncio.new_event_loop()
-        asyncio.set_event_loop(loop)
+        loop = _thread_loop()
 
         try:
             # Get media session manager
@@ -165,156 +250,191 @@ def _sync_get_media_status() -> dict[str, Any]:
                         is_playing = result["state"] == "playing"
                         current_title = result.get('title', '')
 
-                        # Check if track skip is pending and title changed
-                        skip_just_completed = False
-                        if _track_skip_pending["active"]:
-                            if current_title and current_title != _track_skip_pending["old_title"]:
-                                # Title changed - clear the skip flag and start grace period
-                                _track_skip_pending["active"] = False
-                                _track_skip_pending["old_title"] = ""
-                                _track_skip_pending["grace_until"] = current_time + 300.0  # Long grace period
-                                _track_skip_pending["stale_pos"] = -999  # Reset stale position tracking
-                                skip_just_completed = True
-                                # Reset position cache for new track
-                                new_track_id = f"{current_title}:{result.get('artist', '')}:{result.get('duration', 0)}"
-                                _position_cache["track_id"] = new_track_id
+                        with _position_lock:
+                            # Check if track skip is pending and title changed
+                            skip_just_completed = False
+                            if _track_skip_pending["active"]:
+                                if current_title and current_title != _track_skip_pending["old_title"]:
+                                    # Title changed - clear the skip flag and start grace period
+                                    _track_skip_pending["active"] = False
+                                    _track_skip_pending["old_title"] = ""
+                                    _track_skip_pending["grace_until"] = current_time + 300.0  # Long grace period
+                                    _track_skip_pending["stale_pos"] = -999  # Reset stale position tracking
+                                    skip_just_completed = True
+                                    # Reset position cache for new track
+                                    new_track_id = (
+                                        f"{current_title}:{result.get('artist', '')}:{result.get('duration', 0)}"
+                                    )
+                                    _position_cache["track_id"] = new_track_id
+                                    _position_cache["base_position"] = 0.0
+                                    _position_cache["base_time"] = current_time
+                                    _position_cache["last_smtc_pos"] = -999  # Force fresh start
+                                    _position_cache["is_playing"] = is_playing
+                                    logger.debug(
+                                        f"Track skip complete, new title: {current_title},"
+                                        f" grace until: {_track_skip_pending['grace_until']}"
+                                    )
+                                elif current_time - _track_skip_pending["skip_time"] > 5.0:
+                                    # Timeout after 5 seconds
+                                    _track_skip_pending["active"] = False
+                                    logger.debug("Track skip timeout")
+
+                            # Check if we're in grace period (after skip, ignore high SMTC positions)
+                            in_grace_period = current_time < _track_skip_pending.get("grace_until", 0)
+
+                            # If track skip is pending or just completed, use cached/reset position
+                            if _track_skip_pending["active"]:
+                                pos = 0.0
                                 _position_cache["base_position"] = 0.0
                                 _position_cache["base_time"] = current_time
-                                _position_cache["last_smtc_pos"] = -999  # Force fresh start
                                 _position_cache["is_playing"] = is_playing
-                                logger.debug(f"Track skip complete, new title: {current_title}, grace until: {_track_skip_pending['grace_until']}")
-                            elif current_time - _track_skip_pending["skip_time"] > 5.0:
-                                # Timeout after 5 seconds
-                                _track_skip_pending["active"] = False
-                                logger.debug("Track skip timeout")
+                            elif skip_just_completed:
+                                # Just completed skip - interpolate from 0
+                                if is_playing:
+                                    elapsed = current_time - _position_cache["base_time"]
+                                    pos = elapsed
+                                else:
+                                    pos = 0.0
+                            elif in_grace_period:
+                                # Grace period after track skip
+                                # SMTC position is stale (from old track) and won't update until seek/pause
+                                # We interpolate from 0 and only trust SMTC when it changes or reports low value
 
-                        # Check if we're in grace period (after skip, ignore high SMTC positions)
-                        in_grace_period = current_time < _track_skip_pending.get("grace_until", 0)
+                                # Calculate interpolated position from start of new track
+                                if is_playing:
+                                    elapsed = current_time - _position_cache.get("base_time", current_time)
+                                    interpolated_pos = _position_cache.get("base_position", 0.0) + elapsed
+                                else:
+                                    interpolated_pos = _position_cache.get("base_position", 0.0)
 
-                        # If track skip is pending or just completed, use cached/reset position
-                        if _track_skip_pending["active"]:
-                            pos = 0.0
-                            _position_cache["base_position"] = 0.0
-                            _position_cache["base_time"] = current_time
-                            _position_cache["is_playing"] = is_playing
-                        elif skip_just_completed:
-                            # Just completed skip - interpolate from 0
-                            if is_playing:
-                                elapsed = current_time - _position_cache["base_time"]
-                                pos = elapsed
+                                # Get the stale position we've been tracking
+                                stale_pos = _track_skip_pending.get("stale_pos", -999)
+
+                                # Detect if SMTC position changed significantly from the stale value (user seeked)
+                                smtc_changed = stale_pos >= 0 and abs(smtc_pos - stale_pos) > 3.0
+
+                                # Trust SMTC if:
+                                # 1. It reports a low position (indicating new track started)
+                                # 2. It changed from the stale value (user seeked)
+                                if smtc_pos < 10.0 or smtc_changed:
+                                    # SMTC is now trustworthy
+                                    _position_cache["base_position"] = smtc_pos
+                                    _position_cache["base_time"] = current_time
+                                    _position_cache["last_smtc_pos"] = smtc_pos
+                                    _position_cache["is_playing"] = is_playing
+                                    pos = smtc_pos
+                                    _track_skip_pending["grace_until"] = 0
+                                    _track_skip_pending["stale_pos"] = -999
+                                    logger.debug(
+                                        f"Grace period: accepting SMTC pos {smtc_pos}"
+                                        f" (low={smtc_pos < 10}, changed={smtc_changed})"
+                                    )
+                                else:
+                                    # SMTC is stale - keep interpolating
+                                    pos = interpolated_pos
+                                    # Record the stale position for change detection
+                                    if stale_pos < 0:
+                                        _track_skip_pending["stale_pos"] = smtc_pos
+                                    # Keep grace period active indefinitely while SMTC is stale
+                                    _track_skip_pending["grace_until"] = current_time + 300.0
+                                    logger.debug(
+                                        f"Grace period: SMTC stale ({smtc_pos}),"
+                                        f" using interpolated {interpolated_pos}"
+                                    )
                             else:
-                                pos = 0.0
-                        elif in_grace_period:
-                            # Grace period after track skip
-                            # SMTC position is stale (from old track) and won't update until seek/pause
-                            # We interpolate from 0 and only trust SMTC when it changes or reports low value
+                                # Normal position tracking
+                                # Create track ID from title + artist + duration
+                                track_id = f"{current_title}:{result.get('artist', '')}:{result.get('duration', 0)}"
 
-                            # Calculate interpolated position from start of new track
-                            if is_playing:
-                                elapsed = current_time - _position_cache.get("base_time", current_time)
-                                interpolated_pos = _position_cache.get("base_position", 0.0) + elapsed
-                            else:
-                                interpolated_pos = _position_cache.get("base_position", 0.0)
+                                # Detect if SMTC position changed (new track, seek, or state change)
+                                smtc_pos_changed = abs(smtc_pos - _position_cache.get("last_smtc_pos", -999)) > 0.5
+                                track_changed = track_id != _position_cache.get("track_id", "")
 
-                            # Get the stale position we've been tracking
-                            stale_pos = _track_skip_pending.get("stale_pos", -999)
+                                if smtc_pos_changed or track_changed:
+                                    # SMTC updated - store new baseline
+                                    _position_cache["track_id"] = track_id
+                                    _position_cache["last_smtc_pos"] = smtc_pos
+                                    _position_cache["base_position"] = smtc_pos
+                                    _position_cache["base_time"] = current_time
+                                    _position_cache["is_playing"] = is_playing
+                                    pos = smtc_pos
+                                elif is_playing:
+                                    # Interpolate position based on elapsed time
+                                    elapsed = current_time - _position_cache.get("base_time", current_time)
+                                    pos = _position_cache.get("base_position", smtc_pos) + elapsed
+                                else:
+                                    # Paused - use base position
+                                    pos = _position_cache.get("base_position", smtc_pos)
 
-                            # Detect if SMTC position changed significantly from the stale value (user seeked)
-                            smtc_changed = stale_pos >= 0 and abs(smtc_pos - stale_pos) > 3.0
+                                # Update playing state
+                                if _position_cache.get("is_playing") != is_playing:
+                                    _position_cache["base_position"] = (
+                                        pos if is_playing else _position_cache.get("base_position", smtc_pos)
+                                    )
+                                    _position_cache["base_time"] = current_time
+                                    _position_cache["is_playing"] = is_playing
 
-                            # Trust SMTC if:
-                            # 1. It reports a low position (indicating new track started)
-                            # 2. It changed from the stale value (user seeked)
-                            if smtc_pos < 10.0 or smtc_changed:
-                                # SMTC is now trustworthy
-                                _position_cache["base_position"] = smtc_pos
-                                _position_cache["base_time"] = current_time
-                                _position_cache["last_smtc_pos"] = smtc_pos
-                                _position_cache["is_playing"] = is_playing
-                                pos = smtc_pos
-                                _track_skip_pending["grace_until"] = 0
-                                _track_skip_pending["stale_pos"] = -999
-                                logger.debug(f"Grace period: accepting SMTC pos {smtc_pos} (low={smtc_pos < 10}, changed={smtc_changed})")
-                            else:
-                                # SMTC is stale - keep interpolating
-                                pos = interpolated_pos
-                                # Record the stale position for change detection
-                                if stale_pos < 0:
-                                    _track_skip_pending["stale_pos"] = smtc_pos
-                                # Keep grace period active indefinitely while SMTC is stale
-                                _track_skip_pending["grace_until"] = current_time + 300.0
-                                logger.debug(f"Grace period: SMTC stale ({smtc_pos}), using interpolated {interpolated_pos}")
-                        else:
-                            # Normal position tracking
-                            # Create track ID from title + artist + duration
-                            track_id = f"{current_title}:{result.get('artist', '')}:{result.get('duration', 0)}"
-
-                            # Detect if SMTC position changed (new track, seek, or state change)
-                            smtc_pos_changed = abs(smtc_pos - _position_cache.get("last_smtc_pos", -999)) > 0.5
-                            track_changed = track_id != _position_cache.get("track_id", "")
-
-                            if smtc_pos_changed or track_changed:
-                                # SMTC updated - store new baseline
-                                _position_cache["track_id"] = track_id
-                                _position_cache["last_smtc_pos"] = smtc_pos
-                                _position_cache["base_position"] = smtc_pos
-                                _position_cache["base_time"] = current_time
-                                _position_cache["is_playing"] = is_playing
-                                pos = smtc_pos
-                            elif is_playing:
-                                # Interpolate position based on elapsed time
-                                elapsed = current_time - _position_cache.get("base_time", current_time)
-                                pos = _position_cache.get("base_position", smtc_pos) + elapsed
-                            else:
-                                # Paused - use base position
-                                pos = _position_cache.get("base_position", smtc_pos)
-
-                            # Update playing state
-                            if _position_cache.get("is_playing") != is_playing:
-                                _position_cache["base_position"] = pos if is_playing else _position_cache.get("base_position", smtc_pos)
-                                _position_cache["base_time"] = current_time
-                                _position_cache["is_playing"] = is_playing
-
-                        # Sanity check: position should be non-negative and <= duration
-                        if pos >= 0:
-                            if result["duration"] and pos <= result["duration"]:
-                                result["position"] = pos
-                            elif result["duration"] and pos > result["duration"]:
-                                result["position"] = result["duration"]
-                            elif not result["duration"]:
-                                result["position"] = pos
+                            # Sanity check: position should be non-negative and <= duration
+                            if pos >= 0:
+                                if result["duration"] and pos <= result["duration"]:
+                                    result["position"] = pos
+                                elif result["duration"] and pos > result["duration"]:
+                                    result["position"] = result["duration"]
+                                elif not result["duration"]:
+                                    result["position"] = pos
 
                     logger.debug(f"Timeline: duration={result['duration']}, position={result['position']}")
                 except Exception as e:
                     logger.debug(f"Timeline parse error: {e}")
 
-            # Try to get album art (requires media_props)
+            # Try to get album art (requires media_props). Gated by track key so
+            # the WinRT IPC + bytes copy only runs when the track actually
+            # changes; otherwise we just preserve the existing cached bytes.
             if media_props:
-                try:
-                    thumbnail = media_props.thumbnail
-                    if thumbnail:
-                        stream = loop.run_until_complete(thumbnail.open_read_async())
-                        if stream:
-                            size = stream.size
-                            if size > 0 and size < 10 * 1024 * 1024:  # Max 10MB
-                                from winsdk.windows.storage.streams import DataReader
-                                reader = DataReader(stream)
-                                loop.run_until_complete(reader.load_async(size))
-                                buffer = bytearray(size)
-                                reader.read_bytes(buffer)
-                                reader.close()
-                                stream.close()
+                track_key = (
+                    getattr(media_props, "title", "") or "",
+                    getattr(media_props, "artist", "") or "",
+                    getattr(media_props, "album_title", "") or "",
+                )
+                global _current_album_art_bytes, _current_album_art_key
+                if track_key == _current_album_art_key and _current_album_art_bytes:
+                    # Same track — reuse cached art bytes without touching WinRT.
+                    result["album_art_url"] = "/api/media/artwork"
+                else:
+                    try:
+                        thumbnail = media_props.thumbnail
+                        if thumbnail:
+                            stream = loop.run_until_complete(thumbnail.open_read_async())
+                            if stream:
+                                size = stream.size
+                                if size > 0 and size < 10 * 1024 * 1024:  # Max 10MB
+                                    from winsdk.windows.storage.streams import DataReader
+                                    reader = DataReader(stream)
+                                    loop.run_until_complete(reader.load_async(size))
+                                    buffer = bytearray(size)
+                                    reader.read_bytes(buffer)
+                                    reader.close()
+                                    stream.close()
 
-                                global _current_album_art_bytes
-                                _current_album_art_bytes = bytes(buffer)
-                                result["album_art_url"] = "/api/media/artwork"
-                except Exception as e:
-                    logger.debug(f"Failed to get album art: {e}")
+                                    with _art_lock:
+                                        _current_album_art_bytes = bytes(buffer)
+                                        _current_album_art_key = track_key
+                                    result["album_art_url"] = "/api/media/artwork"
+                        else:
+                            # No thumbnail on this track — drop stale bytes so
+                            # the ETag flips and clients don't keep showing the
+                            # previous album's cover.
+                            with _art_lock:
+                                _current_album_art_bytes = None
+                                _current_album_art_key = track_key
+                    except Exception as e:
+                        logger.debug(f"Failed to get album art: {e}")
 
             result["source"] = session.source_app_user_model_id
 
         finally:
-            loop.close()
+            # Reuse the loop across calls — see _thread_loop above.
+            pass
 
     except Exception as e:
         logger.error(f"Error getting media status: {e}")
@@ -360,35 +480,28 @@ def _find_best_session(manager, loop):
 
 def _sync_media_command(command: str) -> bool:
     """Synchronously execute a media command (runs in thread pool)."""
-    import asyncio
-
     try:
-        loop = asyncio.new_event_loop()
-        asyncio.set_event_loop(loop)
-
-        try:
-            manager = loop.run_until_complete(MediaManager.request_async())
-            if manager is None:
-                return False
-
-            session = _find_best_session(manager, loop)
-            if session is None:
-                return False
-
-            if command == "play":
-                return loop.run_until_complete(session.try_play_async())
-            elif command == "pause":
-                return loop.run_until_complete(session.try_pause_async())
-            elif command == "stop":
-                return loop.run_until_complete(session.try_stop_async())
-            elif command == "next":
-                return loop.run_until_complete(session.try_skip_next_async())
-            elif command == "previous":
-                return loop.run_until_complete(session.try_skip_previous_async())
-
+        loop = _thread_loop()
+        manager = loop.run_until_complete(MediaManager.request_async())
+        if manager is None:
             return False
-        finally:
-            loop.close()
+
+        session = _find_best_session(manager, loop)
+        if session is None:
+            return False
+
+        if command == "play":
+            return loop.run_until_complete(session.try_play_async())
+        elif command == "pause":
+            return loop.run_until_complete(session.try_pause_async())
+        elif command == "stop":
+            return loop.run_until_complete(session.try_stop_async())
+        elif command == "next":
+            return loop.run_until_complete(session.try_skip_next_async())
+        elif command == "previous":
+            return loop.run_until_complete(session.try_skip_previous_async())
+
+        return False
 
     except Exception as e:
         logger.error(f"Error executing media command {command}: {e}")
@@ -397,55 +510,66 @@ def _sync_media_command(command: str) -> bool:
 
 def _sync_seek(position: float) -> bool:
     """Synchronously seek to position."""
-    import asyncio
-
     try:
-        loop = asyncio.new_event_loop()
-        asyncio.set_event_loop(loop)
+        loop = _thread_loop()
+        manager = loop.run_until_complete(MediaManager.request_async())
+        if manager is None:
+            return False
 
-        try:
-            manager = loop.run_until_complete(MediaManager.request_async())
-            if manager is None:
-                return False
+        session = _find_best_session(manager, loop)
+        if session is None:
+            return False
 
-            session = _find_best_session(manager, loop)
-            if session is None:
-                return False
-
-            position_ticks = int(position * 10_000_000)
-            return loop.run_until_complete(
-                session.try_change_playback_position_async(position_ticks)
-            )
-        finally:
-            loop.close()
+        position_ticks = int(position * 10_000_000)
+        return loop.run_until_complete(
+            session.try_change_playback_position_async(position_ticks)
+        )
 
     except Exception as e:
         logger.error(f"Error seeking: {e}")
         return False
 
 
+def shutdown_executor() -> None:
+    """Shut down the WinRT thread pool executor."""
+    _executor.shutdown(wait=False)
+
+
 class WindowsMediaController(MediaController):
     """Media controller for Windows using WinRT and pycaw."""
 
-    def __init__(self):
+    def __init__(self, audio_device: str | None = None):
+        """Initialize the Windows media controller.
+
+        Args:
+            audio_device: Name of the audio device to control (partial match).
+                         If None, uses the default audio device.
+        """
         if not WINDOWS_AVAILABLE:
             raise RuntimeError(
                 "Windows media control requires winsdk, pycaw, and comtypes packages"
             )
         self._volume_interface = None
         self._volume_init_attempted = False
+        self._audio_device = audio_device
 
     def _get_volume_interface(self):
         """Get the audio endpoint volume interface."""
         if not self._volume_init_attempted:
             self._volume_init_attempted = True
-            self._volume_interface = _init_volume_control()
+            self._volume_interface = _init_volume_control(self._audio_device)
             if self._volume_interface:
-                logger.info("Volume control initialized successfully")
+                device_info = f" (device: {self._audio_device})" if self._audio_device else " (default device)"
+                logger.info(f"Volume control initialized successfully{device_info}")
             else:
                 logger.warning("Volume control not available")
         return self._volume_interface
 
+    @staticmethod
+    def get_audio_devices() -> list[dict[str, str]]:
+        """Get list of available audio output devices."""
+        return _get_all_audio_devices()
+
     async def get_status(self) -> MediaStatus:
         """Get current media playback status."""
         status = MediaStatus()
@@ -462,7 +586,7 @@ class WindowsMediaController(MediaController):
 
         # Get media info in thread pool (avoids asyncio/WinRT issues)
         try:
-            loop = asyncio.get_event_loop()
+            loop = asyncio.get_running_loop()
             media_info = await asyncio.wait_for(
                 loop.run_in_executor(_executor, _sync_get_media_status),
                 timeout=5.0
@@ -495,7 +619,7 @@ class WindowsMediaController(MediaController):
     async def _run_command(self, command: str) -> bool:
         """Run a media command in the thread pool."""
         try:
-            loop = asyncio.get_event_loop()
+            loop = asyncio.get_running_loop()
             return await asyncio.wait_for(
                 loop.run_in_executor(_executor, _sync_media_command, command),
                 timeout=5.0
@@ -519,41 +643,30 @@ class WindowsMediaController(MediaController):
         """Stop playback."""
         return await self._run_command("stop")
 
-    async def next_track(self) -> bool:
-        """Skip to next track."""
-        # Get current title before skipping
-        try:
-            status = await self.get_status()
-            old_title = status.title or ""
-        except Exception:
-            old_title = ""
+    async def _skip_track(self, command: str) -> bool:
+        # Read the current title from the position cache instead of doing a
+        # full WinRT round-trip (which can take up to 5s) just for one field.
+        with _position_lock:
+            track_id = _position_cache.get("track_id") or ""
+        # track_id is "title:artist:duration" — extract just the title.
+        old_title = track_id.split(":", 1)[0] if track_id else ""
 
-        result = await self._run_command("next")
+        result = await self._run_command(command)
         if result:
-            # Set flag to force position to 0 until title changes
-            _track_skip_pending["active"] = True
-            _track_skip_pending["old_title"] = old_title
-            _track_skip_pending["skip_time"] = _time.time()
+            with _position_lock:
+                _track_skip_pending["active"] = True
+                _track_skip_pending["old_title"] = old_title
+                _track_skip_pending["skip_time"] = _time.time()
             logger.debug(f"Track skip initiated, old title: {old_title}")
         return result
 
+    async def next_track(self) -> bool:
+        """Skip to next track."""
+        return await self._skip_track("next")
+
     async def previous_track(self) -> bool:
         """Go to previous track."""
-        # Get current title before skipping
-        try:
-            status = await self.get_status()
-            old_title = status.title or ""
-        except Exception:
-            old_title = ""
-
-        result = await self._run_command("previous")
-        if result:
-            # Set flag to force position to 0 until title changes
-            _track_skip_pending["active"] = True
-            _track_skip_pending["old_title"] = old_title
-            _track_skip_pending["skip_time"] = _time.time()
-            logger.debug(f"Track skip initiated, old title: {old_title}")
-        return result
+        return await self._skip_track("previous")
 
     async def set_volume(self, volume: int) -> bool:
         """Set system volume."""
@@ -583,7 +696,7 @@ class WindowsMediaController(MediaController):
     async def seek(self, position: float) -> bool:
         """Seek to position in seconds."""
         try:
-            loop = asyncio.get_event_loop()
+            loop = asyncio.get_running_loop()
             return await asyncio.wait_for(
                 loop.run_in_executor(_executor, _sync_seek, position),
                 timeout=5.0
@@ -594,3 +707,24 @@ class WindowsMediaController(MediaController):
         except Exception as e:
             logger.error(f"Failed to seek: {e}")
             return False
+
+    async def open_file(self, file_path: str) -> bool:
+        """Open a media file with the default system player (Windows).
+
+        Uses os.startfile() to open the file with the default application.
+
+        Args:
+            file_path: Absolute path to the media file
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            import os
+            loop = asyncio.get_running_loop()
+            await loop.run_in_executor(None, lambda: os.startfile(file_path))
+            logger.info(f"Opened file with default player: {file_path}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to open file {file_path}: {e}")
+            return False

media_server/static/icons/icon.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-label="Media Server">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%"  stop-color="#0B3D3B"/>
+      <stop offset="100%" stop-color="#1A6B5E"/>
+    </linearGradient>
+    <linearGradient id="sheen" x1="50%" y1="0%" x2="50%" y2="100%">
+      <stop offset="0%"  stop-color="#FFFFFF" stop-opacity="0.18"/>
+      <stop offset="55%" stop-color="#FFFFFF" stop-opacity="0"/>
+    </linearGradient>
+    <filter id="triShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="3"/>
+      <feOffset dx="3" dy="5"/>
+      <feComponentTransfer><feFuncA type="linear" slope="0.45"/></feComponentTransfer>
+      <feMerge><feMergeNode/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+    <clipPath id="clip"><rect x="0" y="0" width="256" height="256" rx="58" ry="58"/></clipPath>
+  </defs>
+  <g clip-path="url(#clip)">
+    <rect width="256" height="256" fill="url(#bg)"/>
+    <rect width="256" height="256" fill="url(#sheen)"/>
+    <g stroke="#F5F1E8" stroke-width="4.6" stroke-linecap="round" stroke-linejoin="round" fill="none" opacity="0.18">
+      <polyline points="66,72 105,128 66,184"/>
+      <polyline points="85,82 124,128 85,174" opacity="0.6"/>
+    </g>
+    <path d="M88.3 55 L88.3 201 L193.3 128 Z"
+          fill="#F5F1E8"
+          stroke="#F5F1E8" stroke-width="9" stroke-linejoin="round"
+          filter="url(#triShadow)"/>
+  </g>
+  <rect x="0.5" y="0.5" width="255" height="255" rx="58" ry="58"
+        fill="none" stroke="#000000" stroke-opacity="0.18" stroke-width="1"/>
+</svg>

media_server/static/js/app.js

@@ -0,0 +1,591 @@
+// ============================================================
+// App: Entry point — imports all modules, registers window globals,
+// and orchestrates initialization (replaces main.js)
+// ============================================================
+
+// Layer 0: Core state & utilities
+import {
+    cacheDom, dom, registerUpdateCallbacks,
+    initLocale, fetchVersion, formatTime, setupIconPreview,
+    isUserAdjustingVolume, setIsUserAdjustingVolume,
+    volumeUpdateTimer, setVolumeUpdateTimer,
+    currentDuration, currentPosition, setVolume, seek,
+    togglePlayPause, nextTrack, previousTrack, toggleMute,
+    VOLUME_THROTTLE_MS, VOLUME_RELEASE_DELAY_MS,
+    changeLocale, t,
+    setAuthRequired,
+    showAboutDialog, closeAboutDialog,
+} from './core.js';
+
+// Layer 1: Player (tabs, theme, accent, vinyl, visualizer, UI)
+import {
+    activeTab, switchTab, updateTabIndicator, setMiniPlayerVisible,
+    initTheme, toggleTheme, initAccentColor, applyAccentColor,
+    renderAccentSwatches, selectAccentColor, toggleAccentPicker, lightenColor,
+    visualizerEnabled, visualizerAvailable, setVisualizerEnabled,
+    checkVisualizerAvailability, toggleVisualizer, applyVisualizerMode,
+    loadAudioDevices, onAudioDeviceChanged,
+    setupProgressDrag, updateUI, updatePlaybackState, stopPositionInterpolation,
+    togglePlayerFullscreen, initPlayerFullscreen,
+} from './player.js';
+
+// Layer 2: WebSocket
+import {
+    connectWebSocket, showAuthForm, authenticate, clearToken,
+    manualReconnect, updateConnectionStatus,
+} from './websocket.js';
+
+// Layer 3: Features
+import {
+    loadScripts, loadScriptsTable, displayQuickAccess,
+    showAddScriptDialog, showEditScriptDialog, closeScriptDialog, saveScript,
+    deleteScriptConfirm, executeScriptDebug, executeCallbackDebug,
+    closeExecutionDialog, scriptFormDirty, setScriptFormDirty,
+    addParameterRow, closeScriptParamsDialog, submitScriptWithParams,
+} from './scripts.js';
+
+import {
+    loadCallbacksTable,
+    showAddCallbackDialog, showEditCallbackDialog, closeCallbackDialog,
+    saveCallback, deleteCallbackConfirm,
+    callbackFormDirty, setCallbackFormDirty,
+} from './callbacks.js';
+
+import {
+    loadMediaFolders, initBrowserToolbar, thumbnailCache,
+    setViewMode, refreshBrowser, playAllFolder,
+    previousPage, nextPage, goToPage,
+    onBrowserSearch, clearBrowserSearch, onItemsPerPageChanged,
+    downloadFile, closeFolderDialog, saveFolder,
+    showManageFoldersDialog,
+    showAddFolderDialog, showEditFolderDialog, deleteFolderConfirm,
+} from './browser.js';
+
+import {
+    loadDisplayMonitors, onDisplayBrightnessInput, onDisplayBrightnessChange,
+    onDisplayContrastInput, onDisplayContrastChange,
+    onDisplayInputSourceChange, onDisplayColorPresetChange, onDisplayPictureModeChange,
+    toggleDisplayPower, loadHeaderLinks, loadLinksTable,
+    showAddLinkDialog, showEditLinkDialog, closeLinkDialog, saveLink, deleteLinkConfirm,
+    linkFormDirty, setLinkFormDirty,
+} from './links.js';
+
+import {
+    toggleDynamicBackground, applyDynamicBackground, updateBackgroundColors,
+} from './background.js';
+
+import {
+    updateForegroundUI, loadForegroundProcess,
+} from './foreground.js';
+
+// ============================================================
+// Register late-bound callbacks for core's updateAllText()
+// ============================================================
+
+registerUpdateCallbacks({
+    updatePlaybackState,
+    updateConnectionStatus,
+    loadScriptsTable,
+    loadCallbacksTable,
+    loadLinksTable,
+    displayQuickAccess,
+    renderAccentSwatches,
+});
+
+// ============================================================
+// Register all functions on window for HTML onclick handlers
+// ============================================================
+
+Object.assign(window, {
+    // Player controls
+    togglePlayPause, nextTrack, previousTrack, toggleMute, seek,
+    // Tabs
+    switchTab,
+    // Theme & accent
+    toggleTheme, toggleAccentPicker, selectAccentColor, lightenColor,
+    // Visualizer (vinyl spin is structural CSS — no toggle)
+    toggleVisualizer,
+    // Background
+    toggleDynamicBackground,
+    // Fullscreen
+    togglePlayerFullscreen,
+    // Auth
+    authenticate, clearToken, manualReconnect,
+    // Locale
+    changeLocale,
+    // Scripts
+    showAddScriptDialog, showEditScriptDialog, closeScriptDialog, saveScript,
+    deleteScriptConfirm, executeScriptDebug, executeCallbackDebug,
+    closeExecutionDialog,
+    addParameterRow, closeScriptParamsDialog, submitScriptWithParams,
+    // Callbacks
+    showAddCallbackDialog, showEditCallbackDialog, closeCallbackDialog,
+    saveCallback, deleteCallbackConfirm,
+    // Browser
+    setViewMode, refreshBrowser, playAllFolder,
+    previousPage, nextPage, goToPage,
+    onBrowserSearch, clearBrowserSearch, onItemsPerPageChanged,
+    downloadFile, closeFolderDialog, saveFolder,
+    showManageFoldersDialog,
+    showAddFolderDialog, showEditFolderDialog, deleteFolderConfirm,
+    // Links
+    showAddLinkDialog, showEditLinkDialog, closeLinkDialog,
+    saveLink, deleteLinkConfirm,
+    // Display
+    loadDisplayMonitors, onDisplayBrightnessInput, onDisplayBrightnessChange,
+    onDisplayContrastInput, onDisplayContrastChange,
+    onDisplayInputSourceChange, onDisplayColorPresetChange, onDisplayPictureModeChange,
+    toggleDisplayPower,
+    // Audio device
+    onAudioDeviceChanged,
+    // About
+    showAboutDialog, closeAboutDialog,
+    // Foreground
+    loadForegroundProcess,
+});
+
+// ============================================================
+// Initialization (DOMContentLoaded)
+// ============================================================
+
+// Prevent <dialog>.showModal() from auto-focusing the first input field.
+// On touch devices this pops up the on-screen keyboard, which is confusing
+// when the user just opened a dialog. Force focus onto the dialog itself.
+const _origShowModal = HTMLDialogElement.prototype.showModal;
+HTMLDialogElement.prototype.showModal = function (...args) {
+    if (!this.hasAttribute('tabindex')) {
+        this.setAttribute('tabindex', '-1');
+    }
+    const result = _origShowModal.apply(this, args);
+    const active = document.activeElement;
+    if (active && active !== this && this.contains(active)) {
+        active.blur();
+        this.focus({ preventScroll: true });
+    }
+    return result;
+};
+
+// CSP-safe replacement for inline on* handlers. HTML uses data-onclick,
+// data-onchange, data-oninput, data-onsubmit with simple call expressions
+// like "fn()", "fn('arg')", "fn(event)". We parse those at startup and
+// attach proper addEventListener calls so script-src 'self' stays strict.
+const INLINE_HANDLER_EVENTS = {
+    'data-onclick': 'click',
+    'data-onchange': 'change',
+    'data-oninput': 'input',
+    'data-onsubmit': 'submit',
+};
+
+function parseInlineHandlerArg(token) {
+    const t = token.trim();
+    if (t === '') return { kind: 'empty' };
+    if (t === 'event') return { kind: 'event' };
+    if (t === 'true') return { kind: 'literal', value: true };
+    if (t === 'false') return { kind: 'literal', value: false };
+    if (t === 'null') return { kind: 'literal', value: null };
+    if (/^-?\d+(\.\d+)?$/.test(t)) return { kind: 'literal', value: Number(t) };
+    if ((t.startsWith("'") && t.endsWith("'")) || (t.startsWith('"') && t.endsWith('"'))) {
+        return { kind: 'literal', value: t.slice(1, -1) };
+    }
+    console.warn('inline-handler: unsupported arg token', token);
+    return { kind: 'literal', value: undefined };
+}
+
+function compileInlineHandler(expr) {
+    const m = expr.match(/^\s*([A-Za-z_$][\w$]*)\s*\((.*)\)\s*;?\s*$/s);
+    if (!m) {
+        console.warn('inline-handler: unparsable expression', expr);
+        return null;
+    }
+    const fnName = m[1];
+    const argsRaw = m[2].trim();
+    const argTokens = argsRaw === '' ? [] : argsRaw.split(',').map(s => s.trim());
+    const parsedArgs = argTokens.map(parseInlineHandlerArg);
+    return function (event) {
+        const fn = window[fnName];
+        if (typeof fn !== 'function') {
+            console.error('inline-handler: missing global function', fnName);
+            return;
+        }
+        const args = parsedArgs.map(a => a.kind === 'event' ? event : a.value);
+        return fn.apply(this, args);
+    };
+}
+
+function wireInlineHandlers(root) {
+    for (const [attr, eventName] of Object.entries(INLINE_HANDLER_EVENTS)) {
+        const nodes = root.querySelectorAll(`[${attr}]`);
+        for (const el of nodes) {
+            const expr = el.getAttribute(attr);
+            const handler = compileInlineHandler(expr);
+            if (handler) el.addEventListener(eventName, handler);
+            el.removeAttribute(attr);
+        }
+    }
+}
+
+window.addEventListener('DOMContentLoaded', async () => {
+    // Cache DOM references
+    cacheDom();
+
+    // Wire CSP-safe inline-handler stand-ins from index.html
+    wireInlineHandlers(document);
+
+    // Initialize theme and accent color
+    initTheme();
+    initAccentColor();
+    initPlayerFullscreen();
+
+    // Register service worker for PWA installability
+    if ('serviceWorker' in navigator) {
+        navigator.serviceWorker.register('/sw.js').catch(() => {});
+    }
+
+    // Build the editorial spectrum bars. Fewer, fatter bars read better
+    // than many thin ones at this column width. JS-managed so we can
+    // drive heights from real audio data when available.
+    const spectrumRoot = document.getElementById('player-spectrum');
+    if (spectrumRoot && !spectrumRoot.children.length) {
+        const SPECTRUM_BARS = 40;
+        // CSS repeat() doesn't accept a var() for its count — set the
+        // grid column template from JS so it always matches the bar
+        // count and stretches each bar to claim 1fr of the row.
+        spectrumRoot.style.gridTemplateColumns =
+            `repeat(${SPECTRUM_BARS}, minmax(0, 1fr))`;
+        const frag = document.createDocumentFragment();
+        for (let i = 0; i < SPECTRUM_BARS; i++) {
+            const s = document.createElement('span');
+            // Pseudo-random initial scaleY for the synthetic CSS-only
+            // animation (used while no real audio is flowing).
+            const scale = (0.25 + Math.abs(Math.sin(i * 0.7)) * 0.70).toFixed(2);
+            s.style.setProperty('--bar-h-scale', scale);
+            s.style.setProperty('--bar-delay', (-Math.random() * 1.1).toFixed(2) + 's');
+            frag.appendChild(s);
+        }
+        spectrumRoot.appendChild(frag);
+    }
+
+    // Initialize audio visualizer — auto-enable when supported so the
+    // spectrum shows real audio out of the box.
+    checkVisualizerAvailability().then(() => {
+        if (!visualizerAvailable) return;
+        // First install: opt the user in by default since the spectrum
+        // is the centerpiece of the player view.
+        const stored = localStorage.getItem('visualizerEnabled');
+        const shouldEnable = stored === null ? true : stored === 'true';
+        if (shouldEnable) {
+            setVisualizerEnabled(true);   // updates the let in player.js
+            applyVisualizerMode();
+        }
+    });
+
+    // Initialize dynamic background
+    applyDynamicBackground();
+
+    // Initialize locale (async - loads JSON file)
+    await initLocale();
+
+    // Load version from health endpoint
+    fetchVersion();
+
+    // Check if authentication is required
+    let authReq = true;
+    try {
+        const healthResp = await fetch('/api/health');
+        const healthData = await healthResp.json();
+        authReq = healthData.auth_required !== false;
+    } catch { /* assume auth required on error */ }
+    setAuthRequired(authReq);
+
+    const token = localStorage.getItem('media_server_token');
+    if (!authReq) {
+        // No auth required — connect directly without token
+        connectWebSocket('');
+        loadScripts();
+        loadScriptsTable();
+        loadCallbacksTable();
+        loadLinksTable();
+        loadAudioDevices();
+    } else if (token) {
+        connectWebSocket(token);
+        loadScripts();
+        loadScriptsTable();
+        loadCallbacksTable();
+        loadLinksTable();
+        loadAudioDevices();
+    } else {
+        showAuthForm();
+    }
+
+    // Shared volume slider setup (avoids duplicate handler code)
+    function setupVolumeSlider(sliderId) {
+        const slider = document.getElementById(sliderId);
+        slider.addEventListener('input', (e) => {
+            setIsUserAdjustingVolume(true);
+            const volume = parseInt(e.target.value);
+            // Sync both sliders and displays
+            dom.volumeDisplay.textContent = `${volume}%`;
+            dom.miniVolumeDisplay.textContent = `${volume}%`;
+            dom.volumeSlider.value = volume;
+            dom.miniVolumeSlider.value = volume;
+
+            if (volumeUpdateTimer) clearTimeout(volumeUpdateTimer);
+            setVolumeUpdateTimer(setTimeout(() => {
+                setVolume(volume);
+                setVolumeUpdateTimer(null);
+            }, VOLUME_THROTTLE_MS));
+        });
+
+        slider.addEventListener('change', (e) => {
+            if (volumeUpdateTimer) {
+                clearTimeout(volumeUpdateTimer);
+                setVolumeUpdateTimer(null);
+            }
+            const volume = parseInt(e.target.value);
+            setVolume(volume);
+            setTimeout(() => { setIsUserAdjustingVolume(false); }, VOLUME_RELEASE_DELAY_MS);
+        });
+    }
+
+    setupVolumeSlider('volume-slider');
+    setupVolumeSlider('mini-volume-slider');
+
+    // Restore saved tab (migrate old tab names)
+    let savedTab = localStorage.getItem('activeTab') || 'player';
+    if (['scripts', 'callbacks', 'links'].includes(savedTab)) savedTab = 'settings';
+    switchTab(savedTab);
+    // Snap indicator to initial position without animation
+    const initialActiveBtn = document.querySelector('.tab-btn.active');
+    if (initialActiveBtn) updateTabIndicator(initialActiveBtn, false);
+
+    // Re-position tab indicator on window resize
+    window.addEventListener('resize', () => {
+        const activeBtn = document.querySelector('.tab-btn.active');
+        if (activeBtn) updateTabIndicator(activeBtn, false);
+    });
+
+    // Mini Player: Intersection Observer to show/hide when main player scrolls out of view
+    const playerContainer = document.querySelector('.player-container');
+
+    const observer = new IntersectionObserver((entries) => {
+        entries.forEach(entry => {
+            if (activeTab !== 'player') return;
+            setMiniPlayerVisible(!entry.isIntersecting);
+        });
+    }, { threshold: 0.1 });
+    observer.observe(playerContainer);
+
+    // Drag-to-seek for progress bars
+    setupProgressDrag(
+        document.getElementById('mini-progress-bar'),
+        document.getElementById('mini-progress-fill')
+    );
+    setupProgressDrag(
+        document.getElementById('progress-bar'),
+        document.getElementById('progress-fill')
+    );
+
+    // Enter key in token input
+    document.getElementById('token-input').addEventListener('keypress', (e) => {
+        if (e.key === 'Enter') {
+            authenticate();
+        }
+    });
+
+    // Script form dirty state tracking
+    const scriptForm = document.getElementById('scriptForm');
+    scriptForm.addEventListener('input', () => {
+        setScriptFormDirty(true);
+    });
+    scriptForm.addEventListener('change', () => {
+        setScriptFormDirty(true);
+    });
+
+    // Callback form dirty state tracking
+    const callbackForm = document.getElementById('callbackForm');
+    callbackForm.addEventListener('input', () => {
+        setCallbackFormDirty(true);
+    });
+    callbackForm.addEventListener('change', () => {
+        setCallbackFormDirty(true);
+    });
+
+    // Script dialog backdrop click to close
+    const scriptDialog = document.getElementById('scriptDialog');
+    scriptDialog.addEventListener('click', (e) => {
+        if (e.target === scriptDialog) {
+            closeScriptDialog();
+        }
+    });
+
+    // Callback dialog backdrop click to close
+    const callbackDialog = document.getElementById('callbackDialog');
+    callbackDialog.addEventListener('click', (e) => {
+        if (e.target === callbackDialog) {
+            closeCallbackDialog();
+        }
+    });
+
+    // Delegated click handlers for script table actions (XSS-safe)
+    document.getElementById('scriptsTableBody').addEventListener('click', (e) => {
+        const btn = e.target.closest('[data-action]');
+        if (!btn) return;
+        const action = btn.dataset.action;
+        const name = btn.dataset.scriptName;
+        if (action === 'execute') executeScriptDebug(name);
+        else if (action === 'edit') showEditScriptDialog(name);
+        else if (action === 'delete') deleteScriptConfirm(name);
+    });
+
+    // Delegated click handlers for callback table actions (XSS-safe)
+    document.getElementById('callbacksTableBody').addEventListener('click', (e) => {
+        const btn = e.target.closest('[data-action]');
+        if (!btn) return;
+        const action = btn.dataset.action;
+        const name = btn.dataset.callbackName;
+        if (action === 'execute') executeCallbackDebug(name);
+        else if (action === 'edit') showEditCallbackDialog(name);
+        else if (action === 'delete') deleteCallbackConfirm(name);
+    });
+
+    // Folder dialog backdrop click to close
+    const folderDialog = document.getElementById('folderDialog');
+    folderDialog.addEventListener('click', (e) => {
+        if (e.target === folderDialog) {
+            closeFolderDialog();
+        }
+    });
+
+    // Delegated click handlers for folder table actions
+    document.getElementById('foldersTableBody').addEventListener('click', (e) => {
+        const btn = e.target.closest('[data-action]');
+        if (!btn) return;
+        const action = btn.dataset.action;
+        const folderId = btn.dataset.folderId;
+        if (action === 'edit') showEditFolderDialog(folderId);
+        else if (action === 'delete') deleteFolderConfirm(folderId);
+    });
+
+    // Link dialog backdrop click to close
+    const linkDialog = document.getElementById('linkDialog');
+    linkDialog.addEventListener('click', (e) => {
+        if (e.target === linkDialog) {
+            closeLinkDialog();
+        }
+    });
+
+    // About dialog backdrop click to close
+    const aboutDialog = document.getElementById('aboutDialog');
+    if (aboutDialog) {
+        aboutDialog.addEventListener('click', (e) => {
+            if (e.target === aboutDialog) {
+                closeAboutDialog();
+            }
+        });
+    }
+
+    // Delegated click handlers for link table actions (XSS-safe)
+    document.getElementById('linksTableBody').addEventListener('click', (e) => {
+        const btn = e.target.closest('[data-action]');
+        if (!btn) return;
+        const action = btn.dataset.action;
+        const name = btn.dataset.linkName;
+        if (action === 'edit') showEditLinkDialog(name);
+        else if (action === 'delete') deleteLinkConfirm(name);
+    });
+
+    // Track link form dirty state
+    const linkForm = document.getElementById('linkForm');
+    linkForm.addEventListener('input', () => {
+        setLinkFormDirty(true);
+    });
+    linkForm.addEventListener('change', () => {
+        setLinkFormDirty(true);
+    });
+
+    // Initialize browser toolbar and load folders
+    initBrowserToolbar();
+    if (!authReq || token) {
+        loadMediaFolders();
+    }
+
+    // Icon preview for script and link dialogs
+    setupIconPreview('scriptIcon', 'scriptIconPreview');
+    setupIconPreview('linkIcon', 'linkIconPreview');
+
+    // Settings sections: restore collapse state and persist on toggle
+    document.querySelectorAll('.settings-section').forEach(details => {
+        const key = `settings_section_${details.querySelector('summary')?.getAttribute('data-i18n') || ''}`;
+        const saved = localStorage.getItem(key);
+        if (saved === 'closed') details.removeAttribute('open');
+        else if (saved === 'open') details.setAttribute('open', '');
+        details.addEventListener('toggle', () => {
+            localStorage.setItem(key, details.open ? 'open' : 'closed');
+        });
+    });
+
+    // Cleanup blob URLs on page unload
+    window.addEventListener('beforeunload', () => {
+        thumbnailCache.forEach(url => URL.revokeObjectURL(url));
+        thumbnailCache.clear();
+    });
+
+    // Tab bar keyboard navigation (WAI-ARIA Tabs pattern)
+    document.getElementById('tabBar').addEventListener('keydown', (e) => {
+        const tabs = Array.from(document.querySelectorAll('.tab-btn'));
+        const currentIdx = tabs.indexOf(document.activeElement);
+        if (currentIdx === -1) return;
+
+        let newIdx;
+        if (e.key === 'ArrowRight') {
+            newIdx = (currentIdx + 1) % tabs.length;
+        } else if (e.key === 'ArrowLeft') {
+            newIdx = (currentIdx - 1 + tabs.length) % tabs.length;
+        } else if (e.key === 'Home') {
+            newIdx = 0;
+        } else if (e.key === 'End') {
+            newIdx = tabs.length - 1;
+        } else {
+            return;
+        }
+
+        e.preventDefault();
+        tabs[newIdx].focus();
+        switchTab(tabs[newIdx].dataset.tab);
+    });
+
+    // Global keyboard shortcuts
+    document.addEventListener('keydown', (e) => {
+        // Skip when typing in inputs, textareas, selects, or when a dialog is open
+        const tag = e.target.tagName;
+        if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+        if (document.querySelector('dialog[open]')) return;
+
+        switch (e.key) {
+            case ' ':
+                e.preventDefault();
+                togglePlayPause();
+                break;
+            case 'ArrowLeft':
+                e.preventDefault();
+                if (currentDuration > 0) seek(Math.max(0, currentPosition - 5));
+                break;
+            case 'ArrowRight':
+                e.preventDefault();
+                if (currentDuration > 0) seek(Math.min(currentDuration, currentPosition + 5));
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                setVolume(Math.min(100, parseInt(dom.volumeSlider.value) + 5));
+                break;
+            case 'ArrowDown':
+                e.preventDefault();
+                setVolume(Math.max(0, parseInt(dom.volumeSlider.value) - 5));
+                break;
+            case 'm':
+            case 'M':
+                toggleMute();
+                break;
+        }
+    });
+});

media_server/static/js/background.js

@@ -0,0 +1,342 @@
+// ============================================================
+// Background: WebGL shader-based dynamic background
+// ============================================================
+
+import { frequencyData } from './player.js';
+
+let bgCanvas = null;
+let bgGL = null;
+let bgProgram = null;
+let bgUniforms = null;       // Cached uniform locations
+let bgAnimFrame = null;
+let bgEnabled = localStorage.getItem('dynamicBackground') === 'true';
+let bgStartTime = 0;
+let bgSmoothedBands = new Float32Array(16);
+let bgSmoothedBass = 0;
+let bgAccentRGB = [0.114, 0.725, 0.329]; // Cached accent color (default green)
+let bgBgColorRGB = [0.071, 0.071, 0.071]; // Cached page background (#121212)
+
+const BG_BAND_COUNT = 16;
+const BG_SMOOTHING = 0.12;
+
+// ---- Shaders ----
+
+const BG_VERT_SRC = `
+attribute vec2 a_position;
+void main() {
+    gl_Position = vec4(a_position, 0.0, 1.0);
+}
+`;
+
+const BG_FRAG_SRC = `
+precision mediump float;
+
+uniform vec2 u_resolution;
+uniform float u_time;
+uniform float u_bass;
+uniform float u_bands[16];
+uniform vec3 u_accent;
+uniform vec3 u_bgColor;
+
+// Smooth noise
+float hash(vec2 p) {
+    return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);
+}
+
+float noise(vec2 p) {
+    vec2 i = floor(p);
+    vec2 f = fract(p);
+    f = f * f * (3.0 - 2.0 * f);
+    float a = hash(i);
+    float b = hash(i + vec2(1.0, 0.0));
+    float c = hash(i + vec2(0.0, 1.0));
+    float d = hash(i + vec2(1.0, 1.0));
+    return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
+}
+
+void main() {
+    vec2 uv = gl_FragCoord.xy / u_resolution;
+    float aspect = u_resolution.x / u_resolution.y;
+
+    // Center coordinates for radial effects
+    vec2 center = (uv - 0.5) * vec2(aspect, 1.0);
+    float dist = length(center);
+    float angle = atan(center.y, center.x);
+
+    // Slow base animation
+    float t = u_time * 0.15;
+
+    // === Layer 1: Flowing wave field ===
+    float waves = 0.0;
+    for (int i = 0; i < 5; i++) {
+        float fi = float(i);
+        float freq = 1.5 + fi * 0.8;
+        float speed = t * (0.6 + fi * 0.15);
+        // Sample a band for this wave layer
+        int bandIdx = i * 3;
+        float bandVal = 0.0;
+        // Manual indexing (GLSL ES doesn't allow variable array index in some drivers)
+        for (int j = 0; j < 16; j++) {
+            if (j == bandIdx) bandVal = u_bands[j];
+        }
+        float amp = 0.015 + bandVal * 0.06;
+        waves += amp * sin(uv.x * freq * 6.2832 + speed + sin(uv.y * 3.0 + t) * 2.0);
+        waves += amp * 0.5 * sin(uv.y * freq * 4.0 - speed * 0.7 + cos(uv.x * 2.5 + t) * 1.5);
+    }
+
+    // === Layer 2: Radial pulse (bass-driven) ===
+    float pulse = smoothstep(0.6 + u_bass * 0.3, 0.0, dist) * (0.08 + u_bass * 0.15);
+
+    // === Layer 3: Frequency ring arcs ===
+    float rings = 0.0;
+    for (int i = 0; i < 8; i++) {
+        float fi = float(i);
+        float bandVal = 0.0;
+        for (int j = 0; j < 16; j++) {
+            if (j == i * 2) bandVal = u_bands[j];
+        }
+        float radius = 0.15 + fi * 0.1;
+        float ringWidth = 0.008 + bandVal * 0.025;
+        float ring = smoothstep(ringWidth, 0.0, abs(dist - radius - bandVal * 0.05));
+        // Fade ring by angle sector for variety
+        float angleFade = 0.5 + 0.5 * sin(angle * (2.0 + fi) + t * (1.0 + fi * 0.3));
+        rings += ring * angleFade * (0.3 + bandVal * 0.7);
+    }
+
+    // === Layer 4: Subtle noise texture ===
+    float n = noise(uv * 4.0 + t * 0.5) * 0.03;
+
+    // Combine layers
+    float intensity = waves + pulse + rings * 0.5 + n;
+
+    // Color: accent color with varying brightness
+    vec3 col = u_accent * intensity;
+
+    // Subtle secondary hue shift for depth
+    vec3 shifted = u_accent.gbr;  // Rotated accent
+    col += shifted * rings * 0.15;
+
+    // Vignette
+    float vignette = 1.0 - smoothstep(0.3, 1.2, dist);
+    col *= vignette;
+
+    // Blend over page background
+    col = clamp(col, 0.0, 1.0);
+    float colBright = (col.r + col.g + col.b) / 3.0;
+    float bgLum = dot(u_bgColor, vec3(0.299, 0.587, 0.114));
+    // Dark bg: add accent light.  Light bg: tint white toward accent via multiply.
+    vec3 darkResult  = u_bgColor + col;
+    vec3 lightResult = u_bgColor * mix(vec3(1.0), u_accent, colBright * 2.0);
+    vec3 finalColor = clamp(mix(darkResult, lightResult, bgLum), 0.0, 1.0);
+
+    gl_FragColor = vec4(finalColor, 1.0);
+}
+`;
+
+// ---- WebGL setup ----
+
+function initBackgroundGL() {
+    bgCanvas = document.getElementById('bg-shader-canvas');
+    if (!bgCanvas) return false;
+
+    bgGL = bgCanvas.getContext('webgl', { alpha: false, antialias: false, depth: false, stencil: false });
+    if (!bgGL) {
+        console.warn('WebGL not available for background shader');
+        return false;
+    }
+
+    const gl = bgGL;
+
+    // Compile shaders
+    const vs = gl.createShader(gl.VERTEX_SHADER);
+    gl.shaderSource(vs, BG_VERT_SRC);
+    gl.compileShader(vs);
+    if (!gl.getShaderParameter(vs, gl.COMPILE_STATUS)) {
+        console.error('BG vertex shader:', gl.getShaderInfoLog(vs));
+        return false;
+    }
+
+    const fs = gl.createShader(gl.FRAGMENT_SHADER);
+    gl.shaderSource(fs, BG_FRAG_SRC);
+    gl.compileShader(fs);
+    if (!gl.getShaderParameter(fs, gl.COMPILE_STATUS)) {
+        console.error('BG fragment shader:', gl.getShaderInfoLog(fs));
+        return false;
+    }
+
+    bgProgram = gl.createProgram();
+    gl.attachShader(bgProgram, vs);
+    gl.attachShader(bgProgram, fs);
+    gl.linkProgram(bgProgram);
+    if (!gl.getProgramParameter(bgProgram, gl.LINK_STATUS)) {
+        console.error('BG program link:', gl.getProgramInfoLog(bgProgram));
+        return false;
+    }
+
+    // Fullscreen quad
+    const buf = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
+        -1, -1,  1, -1,  -1, 1,
+        -1,  1,  1, -1,   1, 1
+    ]), gl.STATIC_DRAW);
+
+    const aPos = gl.getAttribLocation(bgProgram, 'a_position');
+    gl.enableVertexAttribArray(aPos);
+    gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 0, 0);
+
+    gl.useProgram(bgProgram);
+
+    // Cache uniform locations once (avoids per-frame lookups)
+    bgUniforms = {
+        resolution: gl.getUniformLocation(bgProgram, 'u_resolution'),
+        time:       gl.getUniformLocation(bgProgram, 'u_time'),
+        bass:       gl.getUniformLocation(bgProgram, 'u_bass'),
+        bands:      gl.getUniformLocation(bgProgram, 'u_bands'),
+        accent:     gl.getUniformLocation(bgProgram, 'u_accent'),
+        bgColor:    gl.getUniformLocation(bgProgram, 'u_bgColor'),
+    };
+
+    bgStartTime = performance.now() / 1000;
+    updateBackgroundColors();
+    resizeBackgroundCanvas();
+    window.addEventListener('resize', resizeBackgroundCanvas);
+
+    return true;
+}
+
+function resizeBackgroundCanvas() {
+    if (!bgCanvas) return;
+    const dpr = Math.min(window.devicePixelRatio || 1, 1.5); // Cap DPR for performance
+    const w = Math.floor(window.innerWidth * dpr);
+    const h = Math.floor(window.innerHeight * dpr);
+    if (bgCanvas.width !== w || bgCanvas.height !== h) {
+        bgCanvas.width = w;
+        bgCanvas.height = h;
+    }
+}
+
+// ---- Cached color/theme updates (called on accent or theme change, not per-frame) ----
+
+export function updateBackgroundColors() {
+    const style = getComputedStyle(document.documentElement);
+    const accentHex = style.getPropertyValue('--accent').trim();
+    if (accentHex && accentHex.length >= 7) {
+        bgAccentRGB[0] = parseInt(accentHex.slice(1, 3), 16) / 255;
+        bgAccentRGB[1] = parseInt(accentHex.slice(3, 5), 16) / 255;
+        bgAccentRGB[2] = parseInt(accentHex.slice(5, 7), 16) / 255;
+    }
+    const bgHex = style.getPropertyValue('--bg-primary').trim();
+    if (bgHex && bgHex.length >= 7) {
+        bgBgColorRGB[0] = parseInt(bgHex.slice(1, 3), 16) / 255;
+        bgBgColorRGB[1] = parseInt(bgHex.slice(3, 5), 16) / 255;
+        bgBgColorRGB[2] = parseInt(bgHex.slice(5, 7), 16) / 255;
+    }
+}
+
+// ---- Render loop ----
+
+// Cached step into the bins array; recomputed only when bins.length
+// changes (which happens at most once after the first audio frame
+// arrives or when num_bins is reconfigured).
+let bgBinsLength = -1;
+let bgBinsStep = 1;
+// Last applied resolution — drawing with stale viewport is harmless,
+// but we still need to refresh the uniform after the resize listener
+// has updated the canvas.
+let bgLastResW = -1;
+let bgLastResH = -1;
+
+function renderBackgroundFrame() {
+    bgAnimFrame = requestAnimationFrame(renderBackgroundFrame);
+
+    const gl = bgGL;
+    if (!gl || !bgUniforms) return;
+
+    // Resize listener already keeps canvas dimensions in sync — only
+    // touch the viewport when the canvas actually changed size, so the
+    // per-frame path doesn't read window.innerWidth (a layout-flushing
+    // property).
+    if (bgCanvas.width !== bgLastResW || bgCanvas.height !== bgLastResH) {
+        bgLastResW = bgCanvas.width;
+        bgLastResH = bgCanvas.height;
+        gl.viewport(0, 0, bgLastResW, bgLastResH);
+        gl.uniform2f(bgUniforms.resolution, bgLastResW, bgLastResH);
+    }
+
+    const time = performance.now() / 1000 - bgStartTime;
+
+    // Smooth audio data from the imported frequencyData (shared with visualizer).
+    // Backend may send float bins (legacy) or int×1000 (new); .scale tells us which.
+    if (frequencyData && frequencyData.frequencies) {
+        const bins = frequencyData.frequencies;
+        const scale = frequencyData.scale && frequencyData.scale > 0
+            ? 1.0 / frequencyData.scale : 1.0;
+        if (bins.length !== bgBinsLength) {
+            bgBinsLength = bins.length;
+            bgBinsStep = Math.max(1, Math.floor(bgBinsLength / BG_BAND_COUNT));
+        }
+        const step = bgBinsStep;
+        for (let i = 0; i < BG_BAND_COUNT; i++) {
+            let idx = i * step;
+            if (idx >= bgBinsLength) idx = bgBinsLength - 1;
+            const target = (bins[idx] || 0) * scale;
+            bgSmoothedBands[i] += (target - bgSmoothedBands[i]) * (1 - BG_SMOOTHING);
+        }
+        const targetBass = (frequencyData.bass || 0) * scale;
+        bgSmoothedBass += (targetBass - bgSmoothedBass) * (1 - BG_SMOOTHING);
+    } else {
+        // Gentle decay when no audio
+        for (let i = 0; i < BG_BAND_COUNT; i++) {
+            bgSmoothedBands[i] *= 0.95;
+        }
+        bgSmoothedBass *= 0.95;
+    }
+
+    // Set uniforms (locations cached at init, colors cached on change)
+    gl.uniform1f(bgUniforms.time, time);
+    gl.uniform1f(bgUniforms.bass, bgSmoothedBass);
+    gl.uniform1fv(bgUniforms.bands, bgSmoothedBands);
+    gl.uniform3f(bgUniforms.accent, bgAccentRGB[0], bgAccentRGB[1], bgAccentRGB[2]);
+    gl.uniform3f(bgUniforms.bgColor, bgBgColorRGB[0], bgBgColorRGB[1], bgBgColorRGB[2]);
+
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+}
+
+function startBackground() {
+    if (bgAnimFrame) return;
+    if (!bgGL && !initBackgroundGL()) return;
+    bgCanvas.classList.add('visible');
+    document.body.classList.add('dynamic-bg-active');
+    renderBackgroundFrame();
+}
+
+function stopBackground() {
+    if (bgAnimFrame) {
+        cancelAnimationFrame(bgAnimFrame);
+        bgAnimFrame = null;
+    }
+    if (bgCanvas) {
+        bgCanvas.classList.remove('visible');
+    }
+    document.body.classList.remove('dynamic-bg-active');
+}
+
+// ---- Public API ----
+
+export function toggleDynamicBackground() {
+    bgEnabled = !bgEnabled;
+    localStorage.setItem('dynamicBackground', bgEnabled);
+    applyDynamicBackground();
+}
+
+export function applyDynamicBackground() {
+    const btn = document.getElementById('bgToggle');
+    if (bgEnabled) {
+        startBackground();
+        if (btn) btn.classList.add('active');
+    } else {
+        stopBackground();
+        if (btn) btn.classList.remove('active');
+    }
+}

media_server/static/js/callbacks.js

@@ -0,0 +1,233 @@
+// ============================================================
+// Callbacks: CRUD management
+// ============================================================
+
+import { t, showToast, escapeHtml, closeDialog, showConfirm, getAuthHeaders, hasCredentials } from './core.js';
+import { IconSelect } from './icon-select.js';
+import { callbackEventIcons } from './icons.js';
+
+export let callbackFormDirty = false;
+export function setCallbackFormDirty(value) { callbackFormDirty = value; }
+
+let _callbackEventIconSelect = null;
+
+function _ensureCallbackEventIconSelect() {
+    if (_callbackEventIconSelect) return;
+    const select = document.getElementById('callbackName');
+    if (!select) return;
+
+    const items = Object.entries(callbackEventIcons).map(([value, icon]) => ({
+        value,
+        icon,
+        label: value,
+    }));
+
+    _callbackEventIconSelect = new IconSelect({
+        target: select,
+        items,
+        columns: 3,
+        placeholder: t('callbacks.placeholder.event'),
+        onChange: () => { callbackFormDirty = true; },
+    });
+}
+
+let _loadCallbacksPromise = null;
+export async function loadCallbacksTable() {
+    if (_loadCallbacksPromise) return _loadCallbacksPromise;
+    _loadCallbacksPromise = _loadCallbacksTableImpl();
+    _loadCallbacksPromise.finally(() => { _loadCallbacksPromise = null; });
+    return _loadCallbacksPromise;
+}
+
+async function _loadCallbacksTableImpl() {
+    const tbody = document.getElementById('callbacksTableBody');
+
+    try {
+        const response = await fetch('/api/callbacks/list', {
+            headers: getAuthHeaders()
+        });
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch callbacks');
+        }
+
+        const callbacksList = await response.json();
+
+        if (callbacksList.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="4" class="empty-state"><div class="empty-state-illustration"><svg viewBox="0 0 64 64"><circle cx="32" cy="32" r="24"/><path d="M32 20v12l8 8"/></svg><p>' + t('callbacks.empty') + '</p></div></td></tr>';
+            return;
+        }
+
+        tbody.innerHTML = callbacksList.map(callback => `
+            <tr>
+                <td><code>${escapeHtml(callback.name)}</code></td>
+                <td style="max-width: 200px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;"
+                    title="${escapeHtml(callback.command)}">${escapeHtml(callback.command)}</td>
+                <td>${callback.timeout}s</td>
+                <td>
+                    <div class="action-buttons">
+                        <button class="action-btn execute" data-action="execute" data-callback-name="${escapeHtml(callback.name)}" title="Execute callback">
+                            <svg viewBox="0 0 24 24"><path d="M8 5v14l11-7z"/></svg>
+                        </button>
+                        <button class="action-btn" data-action="edit" data-callback-name="${escapeHtml(callback.name)}" title="Edit callback">
+                            <svg viewBox="0 0 24 24"><path d="M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25zM20.71 7.04c.39-.39.39-1.02 0-1.41l-2.34-2.34c-.39-.39-1.02-.39-1.41 0l-1.83 1.83 3.75 3.75 1.83-1.83z"/></svg>
+                        </button>
+                        <button class="action-btn delete" data-action="delete" data-callback-name="${escapeHtml(callback.name)}" title="Delete callback">
+                            <svg viewBox="0 0 24 24"><path d="M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6v12zM19 4h-3.5l-1-1h-5l-1 1H5v2h14V4z"/></svg>
+                        </button>
+                    </div>
+                </td>
+            </tr>
+        `).join('');
+    } catch (error) {
+        console.error('Error loading callbacks:', error);
+        tbody.innerHTML = `<tr><td colspan="4" class="empty-state" style="color: var(--error);">${escapeHtml(t('callbacks.msg.load_failed'))}</td></tr>`;
+    }
+}
+
+export function showAddCallbackDialog() {
+    const dialog = document.getElementById('callbackDialog');
+    const form = document.getElementById('callbackForm');
+    const title = document.getElementById('callbackDialogTitle');
+
+    form.reset();
+    document.getElementById('callbackIsEdit').value = 'false';
+    document.getElementById('callbackName').disabled = false;
+    title.textContent = t('callbacks.dialog.add');
+
+    _ensureCallbackEventIconSelect();
+    if (_callbackEventIconSelect) _callbackEventIconSelect.setValue('', false);
+
+    callbackFormDirty = false;
+
+    document.body.classList.add('dialog-open');
+    dialog.showModal();
+}
+
+export async function showEditCallbackDialog(callbackName) {
+    const dialog = document.getElementById('callbackDialog');
+    const title = document.getElementById('callbackDialogTitle');
+
+    try {
+        const response = await fetch('/api/callbacks/list', {
+            headers: getAuthHeaders()
+        });
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch callback details');
+        }
+
+        const callbacksList = await response.json();
+        const callback = callbacksList.find(c => c.name === callbackName);
+
+        if (!callback) {
+            showToast(t('callbacks.msg.not_found'), 'error');
+            return;
+        }
+
+        document.getElementById('callbackIsEdit').value = 'true';
+        document.getElementById('callbackName').value = callbackName;
+        document.getElementById('callbackName').disabled = true;
+
+        _ensureCallbackEventIconSelect();
+        if (_callbackEventIconSelect) _callbackEventIconSelect.setValue(callbackName, false);
+        document.getElementById('callbackCommand').value = callback.command;
+        document.getElementById('callbackTimeout').value = callback.timeout;
+        document.getElementById('callbackWorkingDir').value = callback.working_dir || '';
+
+        title.textContent = t('callbacks.dialog.edit');
+        callbackFormDirty = false;
+
+        document.body.classList.add('dialog-open');
+        dialog.showModal();
+    } catch (error) {
+        console.error('Error loading callback for edit:', error);
+        showToast(t('callbacks.msg.load_failed'), 'error');
+    }
+}
+
+export async function closeCallbackDialog() {
+    if (callbackFormDirty) {
+        if (!await showConfirm(t('callbacks.confirm.unsaved'))) {
+            return;
+        }
+    }
+
+    const dialog = document.getElementById('callbackDialog');
+    callbackFormDirty = false;
+    closeDialog(dialog);
+    document.body.classList.remove('dialog-open');
+}
+
+export async function saveCallback(event) {
+    event.preventDefault();
+
+    const submitBtn = event.target.querySelector('button[type="submit"]');
+    if (submitBtn) submitBtn.disabled = true;
+
+    const isEdit = document.getElementById('callbackIsEdit').value === 'true';
+    const callbackName = document.getElementById('callbackName').value;
+
+    const data = {
+        command: document.getElementById('callbackCommand').value,
+        timeout: parseInt(document.getElementById('callbackTimeout').value) || 30,
+        working_dir: document.getElementById('callbackWorkingDir').value || null,
+        shell: true
+    };
+
+    const encodedName = encodeURIComponent(callbackName);
+    const endpoint = isEdit ?
+        `/api/callbacks/update/${encodedName}` :
+        `/api/callbacks/create/${encodedName}`;
+
+    const method = isEdit ? 'PUT' : 'POST';
+
+    try {
+        const response = await fetch(endpoint, {
+            method,
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify(data)
+        });
+
+        const result = await response.json();
+
+        if (response.ok && result.success) {
+            showToast(t(isEdit ? 'callbacks.msg.updated' : 'callbacks.msg.created'), 'success');
+            callbackFormDirty = false;
+            closeCallbackDialog();
+            loadCallbacksTable();
+        } else {
+            showToast(result.detail || t(isEdit ? 'callbacks.msg.update_failed' : 'callbacks.msg.create_failed'), 'error');
+        }
+    } catch (error) {
+        console.error('Error saving callback:', error);
+        showToast(t(isEdit ? 'callbacks.msg.update_failed' : 'callbacks.msg.create_failed'), 'error');
+    } finally {
+        if (submitBtn) submitBtn.disabled = false;
+    }
+}
+
+export async function deleteCallbackConfirm(callbackName) {
+    if (!await showConfirm(t('callbacks.confirm.delete').replace('{name}', callbackName))) {
+        return;
+    }
+
+    try {
+        const response = await fetch(`/api/callbacks/delete/${encodeURIComponent(callbackName)}`, {
+            method: 'DELETE',
+            headers: getAuthHeaders()
+        });
+
+        const result = await response.json();
+
+        if (response.ok && result.success) {
+            showToast(t('callbacks.msg.deleted'), 'success');
+            loadCallbacksTable();
+        } else {
+            showToast(result.detail || t('callbacks.msg.delete_failed'), 'error');
+        }
+    } catch (error) {
+        console.error('Error deleting callback:', error);
+        showToast(t('callbacks.msg.delete_failed'), 'error');
+    }
+}

media_server/static/js/core.js

@@ -0,0 +1,643 @@
+// ============================================================
+// Core: Shared state, constants, utilities, i18n, API commands
+// ============================================================
+
+// SVG path constants (avoid rebuilding innerHTML on every state update)
+export const SVG_PLAY = '<path d="M8 5v14l11-7z"/>';
+export const SVG_PAUSE = '<path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z"/>';
+export const SVG_STOP = '<path d="M6 6h12v12H6z"/>';
+export const SVG_IDLE = '<path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 14.5v-9l6 4.5-6 4.5z"/>';
+export const SVG_MUTED = '<path d="M16.5 12c0-1.77-1.02-3.29-2.5-4.03v2.21l2.45 2.45c.03-.2.05-.41.05-.63zm2.5 0c0 .94-.2 1.82-.54 2.64l1.51 1.51C20.63 14.91 21 13.5 21 12c0-4.28-2.99-7.86-7-8.77v2.06c2.89.86 5 3.54 5 6.71zM4.27 3L3 4.27 7.73 9H3v6h4l5 5v-6.73l4.25 4.25c-.67.52-1.42.93-2.25 1.18v2.06c1.38-.31 2.63-.95 3.69-1.81L19.73 21 21 19.73l-9-9L4.27 3zM12 4L9.91 6.09 12 8.18V4z"/>';
+export const SVG_UNMUTED = '<path d="M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02z"/>';
+
+// Empty state illustration SVGs
+export const EMPTY_SVG_FOLDER = '<svg viewBox="0 0 64 64"><path d="M8 16h20l4-6h20a4 4 0 014 4v36a4 4 0 01-4 4H8a4 4 0 01-4-4V20a4 4 0 014-4z"/><path d="M4 24h56" stroke-dasharray="4 3" opacity="0.4"/></svg>';
+export const EMPTY_SVG_FILE = '<svg viewBox="0 0 64 64"><path d="M16 4h22l14 14v38a4 4 0 01-4 4H16a4 4 0 01-4-4V8a4 4 0 014-4z"/><path d="M38 4v14h14"/><path d="M22 32h20M22 40h14" opacity="0.5"/></svg>';
+export function emptyStateHtml(svgStr, text) {
+    return `<div class="empty-state-illustration">${svgStr}<p>${text}</p></div>`;
+}
+
+// Media source registry: substring key → { name, icon }
+export const MEDIA_SOURCES = {
+    'spotify': {
+        name: 'Spotify',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#1DB954" d="M12 0C5.4 0 0 5.4 0 12s5.4 12 12 12 12-5.4 12-12S18.66 0 12 0zm5.521 17.34c-.24.359-.66.48-1.021.24-2.82-1.74-6.36-2.101-10.561-1.141-.418.122-.779-.179-.899-.539-.12-.421.18-.78.54-.9 4.56-1.021 8.52-.6 11.64 1.32.42.18.479.659.301 1.02zm1.44-3.3c-.301.42-.841.6-1.262.3-3.239-1.98-8.159-2.58-11.939-1.38-.479.12-1.02-.12-1.14-.6-.12-.48.12-1.021.6-1.141C9.6 9.9 15 10.561 18.72 12.84c.361.181.54.78.241 1.2zm.12-3.36C15.24 8.4 8.82 8.16 5.16 9.301c-.6.179-1.2-.181-1.38-.721-.18-.601.18-1.2.72-1.381 4.26-1.26 11.28-1.02 15.721 1.621.539.3.719 1.02.419 1.56-.299.421-1.02.599-1.559.3z"/></svg>'
+    },
+    'yandex music': {
+        name: 'Yandex Music',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#FFCC00" d="M12 0C5.376 0 0 5.376 0 12s5.376 12 12 12 12-5.376 12-12S18.624 0 12 0zm0 2.4a9.6 9.6 0 110 19.2 9.6 9.6 0 010-19.2z"/><path fill="#FFCC00" d="M13.2 6h-2.4v7.2L7.2 6H4.8l5.4 12h1.2l.6-1.35V6z"/></svg>'
+    },
+    'яндекс музыка': {
+        name: 'Яндекс Музыка',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#FFCC00" d="M12 0C5.376 0 0 5.376 0 12s5.376 12 12 12 12-5.376 12-12S18.624 0 12 0zm0 2.4a9.6 9.6 0 110 19.2 9.6 9.6 0 010-19.2z"/><path fill="#FFCC00" d="M13.2 6h-2.4v7.2L7.2 6H4.8l5.4 12h1.2l.6-1.35V6z"/></svg>'
+    },
+    'chrome': {
+        name: 'Google Chrome',
+        icon: '<svg viewBox="0 0 24 24"><circle fill="#4587F3" cx="12" cy="12" r="11"/><path fill="#DB4437" d="M12 1C7.2 1 3.1 3.8 1.3 7.9L7.7 12l1.8-3.1c.7-1.1 1.9-1.9 3.3-1.9h9.7C21 3.5 16.9 1 12 1z"/><path fill="#0F9D58" d="M7.7 12L1.3 7.9C.5 9.2 0 10.6 0 12c0 4.5 2.8 8.4 6.8 10l3.8-6.6L7.7 12z"/><path fill="#FFCD40" d="M6.8 22c2.7 1.5 6.4 1.7 9.4.2 2.8-1.4 4.9-3.9 5.8-6.8l-6.5-3.4-1.8 3.1c-.7 1.1-1.9 1.9-3.3 1.9-.9 0-1.7-.3-2.4-.7L6.8 22z"/><circle fill="#F1F1F1" cx="12" cy="12" r="4.8"/><circle fill="#4587F3" cx="12" cy="12" r="3.8"/></svg>'
+    },
+    'msedge': {
+        name: 'Microsoft Edge',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#0078D4" d="M21.86 17.86q.14 0 .25-.12.1-.13.1-.25 0-.06 0-.13-.12-.76-.39-1.49-.26-.72-.65-1.39-.4-.66-.92-1.25-.53-.58-1.15-1.06-.61-.48-1.3-.85-.69-.37-1.44-.6-.75-.22-1.53-.3-.8-.07-1.6 0h-.04q-.51.03-1.03.14-.5.12-1 .31-.49.2-.95.46-.46.27-.89.6-.42.32-.8.7-.37.4-.69.83-.31.44-.57.92-.25.49-.44 1 .09-.14.21-.28.12-.14.26-.27.14-.12.3-.23.16-.1.33-.18.18-.08.37-.14.18-.06.38-.08.2-.02.4-.01.21.01.41.06.28.07.53.2.25.12.47.3.21.18.39.4.18.21.32.45.14.25.23.52.1.26.14.54.04.28.02.56-.02.36-.12.72-.1.35-.27.68-.17.33-.4.62-.24.3-.52.56-.28.25-.6.46-.32.2-.67.35.44.1.9.14.44.03.89-.02.45-.05.88-.17.44-.12.85-.3.41-.2.79-.44.37-.25.71-.55.34-.3.63-.65.3-.35.54-.73.24-.39.42-.8.18-.42.3-.86.12-.43.18-.88.06-.45.06-.9 0-.48-.07-.95-.07-.47-.22-.93z"/><path fill="#50E6FF" d="M11.89.03Q10.03.17 8.3.88 6.57 1.59 5.1 2.77 3.65 3.94 2.55 5.5 1.44 7.06.79 8.88.14 10.7 0 12.65q.01.22.02.45 0 .22.03.44.04.42.12.83.08.42.2.83.12.4.28.79.16.39.36.76.2.37.43.72.24.34.51.66.27.32.57.6.3.29.63.54.33.25.68.46.35.21.72.38.38.17.77.28.39.12.79.18.41.06.82.05.41 0 .82-.07.41-.08.79-.22.39-.14.74-.34.36-.2.68-.44.33-.25.6-.54.28-.3.5-.63.23-.33.4-.7.17-.36.27-.75-1.1.9-2.44 1.36-1.33.46-2.77.46-1.26 0-2.44-.39-1.18-.39-2.17-1.08-1-1.08-1.6-2.02-.6-.94-.87-2-.27-1.07-.25-2.2.02-.55.12-1.08.1-.54.29-1.05.18-.52.44-1 .27-.49.6-.94.34-.44.74-.83.4-.38.85-.71.45-.32.94-.57.49-.25 1.02-.42.52-.16 1.07-.24.55-.07 1.1-.05.81.04 1.57.25.77.2 1.46.56.7.36 1.29.85.6.5 1.07 1.1.48.6.82 1.29.34.69.54 1.44.2.76.24 1.55.04.79-.08 1.57-.11.78-.37 1.52-.26.74-.66 1.4-.39.67-.91 1.24-.52.57-1.14 1.02-.62.44-1.32.76-.7.32-1.45.49-.75.16-1.52.18z"/></svg>'
+    },
+    'firefox': {
+        name: 'Firefox',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#FF7139" d="M12 0C5.37 0 0 5.37 0 12s5.37 12 12 12 12-5.37 12-12S18.63 0 12 0zm6.73 7.27c-.47-.77-1.22-1.6-1.7-1.87.54.97.86 2.07.93 3.15 0 0-.02.03-.02.05-.38-1.34-1.14-2.15-1.78-3.05-.03-.05-.06-.1-.1-.15-.03-.05-.05-.1-.06-.15 0-.02-.01-.04-.02-.05l-.01.02c-.02.03-.03.05-.04.08 0 0 0 .01-.01.02l.01-.02c-.64 1.07-1.72 2.2-2.1 3.56-.46.01-.9.09-1.32.23l-.06.03c-.03-.2-.04-.4-.04-.6 0-.67.15-1.3.4-1.87-1.08.4-1.93 1.12-2.53 1.72-.33-.36-.36-1.56-.34-1.8-.01 0-.03.02-.04.02-.27.2-.52.42-.75.66-.28.3-.53.62-.76.96-.12.2-.24.4-.34.6-.15.32-.27.66-.36 1-.02.07-.03.14-.05.21v.03c-.06.3-.1.6-.12.9v.1c0 .07 0 .14-.01.21C7.3 13.8 7.52 16.37 9 18.26l.04.05c-1.55-1-2.57-2.64-2.87-4.42-.04.2-.06.4-.07.6-.01.2-.02.4-.01.6.02.6.13 1.2.3 1.77.2.57.46 1.12.8 1.62.17.25.36.48.56.7.2.22.42.43.66.62 1.83 1.47 4.17 1.87 6.34 1.21.26-.08.5-.17.74-.28 1.1-.5 2.06-1.27 2.78-2.23.03-.03.05-.07.07-.1.08-.1.15-.2.22-.32.5-.77.84-1.62 1.02-2.5.02-.1.04-.2.05-.3.1-.57.14-1.15.12-1.73 0-.1-.01-.19-.02-.29.06-1.2-.15-2.42-.63-3.53-.1-.23-.2-.45-.32-.67z"/></svg>'
+    },
+    'opera': {
+        name: 'Opera',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#FF1B2D" d="M12 0C5.37 0 0 5.37 0 12s5.37 12 12 12c2.75 0 5.28-.93 7.3-2.49-1.24.77-2.68 1.22-4.22 1.22-2.2 0-4.17-1.1-5.55-2.83C8.1 18.1 7.2 15.22 7.2 12s.9-6.1 2.33-7.9C10.91 2.37 12.88 1.27 15.08 1.27c1.54 0 2.98.45 4.22 1.22C17.28.93 14.75 0 12 0z"/><path fill="#FF1B2D" d="M15.08 1.27c-2.2 0-4.17 1.1-5.55 2.83C8.1 5.9 7.2 8.78 7.2 12s.9 6.1 2.33 7.9c1.38 1.73 3.35 2.83 5.55 2.83 2.2 0 4.17-1.1 5.55-2.83C22.06 18.1 22.96 15.22 22.96 12s-.9-6.1-2.33-7.9c-1.38-1.73-3.35-2.83-5.55-2.83z" opacity=".75"/></svg>'
+    },
+    'brave': {
+        name: 'Brave',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#FB542B" d="M12 0L3.6 4.8v9.6L12 24l8.4-9.6V4.8L12 0zm5.7 14.1l-1.2 1.8c-.3.3-.6.6-.9.9l-2.1 1.5-1.5.9-1.5-.9-2.1-1.5c-.3-.3-.6-.6-.9-.9l-1.2-1.8c-.3-.6-.3-1.2 0-1.5l.6-1.5.6-1.2.6-1.2.3-.6c.15-.3.45-.3.6 0l.6.9c.15.3.45.3.6 0l.6-.9.6-.9c.15-.3.45-.3.6 0l.6.9.6.9c.15.3.45.3.6 0l.6-.9c.15-.3.45-.3.6 0l.3.6.6 1.2.6 1.2.6 1.5c.3.3.3.9 0 1.5z"/></svg>'
+    },
+    'yandex': {
+        name: 'Yandex Browser',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#FF0000" d="M12 0C5.37 0 0 5.37 0 12s5.37 12 12 12 12-5.37 12-12S18.63 0 12 0z"/><path fill="#FFF" d="M13.5 5h-2.1l-3.9 8.1V5H5.4v14h2.1l4.05-8.55V19h2.1V5z"/></svg>'
+    },
+    'vlc': {
+        name: 'VLC',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#FF8800" d="M12 1.5L7.5 16h9L12 1.5z"/><path fill="#FF5722" d="M6 18.5c-1.5 0-2.5.5-2.5 1.5s2.5 2.5 8.5 2.5 8.5-1.5 8.5-2.5-1-1.5-2.5-1.5H6z"/><path fill="#FF8800" d="M6 18.5h12l-1.5-2.5h-9L6 18.5z"/></svg>'
+    },
+    'aimp': {
+        name: 'AIMP',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#F7A600" d="M12 0C5.37 0 0 5.37 0 12s5.37 12 12 12 12-5.37 12-12S18.63 0 12 0z"/><path fill="#FFF" d="M12 4l-7 14h3l1.5-3h5l1.5 3h3L12 4zm0 5l1.75 3.5h-3.5L12 9z"/></svg>'
+    },
+    'foobar': {
+        name: 'foobar2000',
+        icon: '<svg viewBox="0 0 24 24"><rect fill="#1F1A17" width="24" height="24" rx="4"/><path fill="#D89B2B" d="M6 6h3v12H6V6zm4.5 0H13v12h-2.5V6zm4 0H17v12h-2.5V6z"/></svg>'
+    },
+    'music.ui': {
+        name: 'Groove Music',
+        icon: '<svg viewBox="0 0 24 24"><circle fill="#7B83EB" cx="12" cy="12" r="11"/><path fill="#FFF" d="M15 7v7a3 3 0 11-2-2.83V7h2z"/></svg>'
+    },
+    'itunes': {
+        name: 'iTunes',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#EA4CC0" d="M12 0C5.37 0 0 5.37 0 12s5.37 12 12 12 12-5.37 12-12S18.63 0 12 0z"/><path fill="#FFF" d="M16.5 6.5l-7 1.75v7.25a2.5 2.5 0 11-1.5-2.29V9.5l7-1.75v4.75a2.5 2.5 0 11-1.5-2.29V6.5z" opacity=".9"/></svg>'
+    },
+    'apple music': {
+        name: 'Apple Music',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#FC3C44" d="M12 0C5.37 0 0 5.37 0 12s5.37 12 12 12 12-5.37 12-12S18.63 0 12 0z"/><path fill="#FFF" d="M16.5 6.5l-7 1.75v7.25a2.5 2.5 0 11-1.5-2.29V9.5l7-1.75v4.75a2.5 2.5 0 11-1.5-2.29V6.5z" opacity=".9"/></svg>'
+    },
+    'deezer': {
+        name: 'Deezer',
+        icon: '<svg viewBox="0 0 24 24"><rect fill="#000" width="24" height="24" rx="4"/><g fill="#A238FF"><rect x="2" y="16" width="3" height="2" rx=".5"/><rect x="6.5" y="14" width="3" height="4" rx=".5"/><rect x="11" y="10" width="3" height="8" rx=".5"/><rect x="15.5" y="12" width="3" height="6" rx=".5"/><rect x="19" y="8" width="3" height="10" rx=".5"/></g></svg>'
+    },
+    'tidal': {
+        name: 'TIDAL',
+        icon: '<svg viewBox="0 0 24 24"><path fill="#000" d="M12 4.8L8 8.8l4 4-4 4-4-4 4-4-4-4 4-4 4 4zm4 0l4 4-4 4-4-4 4-4z"/></svg>'
+    },
+};
+
+export function resolveMediaSource(raw) {
+    if (!raw) return null;
+    const lower = raw.toLowerCase();
+    for (const [key, info] of Object.entries(MEDIA_SOURCES)) {
+        if (lower.includes(key)) return info;
+    }
+    return { name: raw.replace(/\.exe$/i, ''), icon: null };
+}
+
+// Cached DOM references (populated once after DOMContentLoaded)
+export const dom = {};
+export function cacheDom() {
+    dom.trackTitle = document.getElementById('track-title');
+    dom.artist = document.getElementById('artist');
+    dom.album = document.getElementById('album');
+    dom.miniTrackTitle = document.getElementById('mini-track-title');
+    dom.miniArtist = document.getElementById('mini-artist');
+    dom.albumArt = document.getElementById('album-art');
+    dom.albumArtGlow = document.getElementById('album-art-glow');
+    dom.miniAlbumArt = document.getElementById('mini-album-art');
+    dom.volumeSlider = document.getElementById('volume-slider');
+    dom.volumeDisplay = document.getElementById('volume-display');
+    dom.miniVolumeSlider = document.getElementById('mini-volume-slider');
+    dom.miniVolumeDisplay = document.getElementById('mini-volume-display');
+    dom.progressFill = document.getElementById('progress-fill');
+    dom.currentTime = document.getElementById('current-time');
+    dom.totalTime = document.getElementById('total-time');
+    dom.metaElapsed = document.getElementById('meta-elapsed');
+    dom.metaLength = document.getElementById('meta-length');
+    dom.progressBar = document.getElementById('progress-bar');
+    dom.miniProgressFill = document.getElementById('mini-progress-fill');
+    dom.miniCurrentTime = document.getElementById('mini-current-time');
+    dom.miniTotalTime = document.getElementById('mini-total-time');
+    dom.playbackState = document.getElementById('playback-state');
+    dom.stateIcon = document.getElementById('state-icon');
+    dom.playPauseIcon = document.getElementById('play-pause-icon');
+    dom.miniPlayPauseIcon = document.getElementById('mini-play-pause-icon');
+    dom.muteIcon = document.getElementById('mute-icon');
+    dom.miniMuteIcon = document.getElementById('mini-mute-icon');
+    dom.statusDot = document.getElementById('status-dot');
+    dom.source = document.getElementById('source');
+    dom.sourceIcon = document.getElementById('sourceIcon');
+    dom.btnPlayPause = document.getElementById('btn-play-pause');
+    dom.btnNext = document.getElementById('btn-next');
+    dom.btnPrevious = document.getElementById('btn-previous');
+    dom.miniBtnPlayPause = document.getElementById('mini-btn-play-pause');
+    dom.miniPlayer = document.getElementById('mini-player');
+}
+
+// Timing constants
+export const VOLUME_THROTTLE_MS = 16;
+// 250ms is plenty for sub-second progress; the inline updateProgress
+// also short-circuits when the rounded second hasn't moved, so there's
+// no visible difference for the user.
+export const POSITION_INTERPOLATION_MS = 250;
+export const SEARCH_DEBOUNCE_MS = 200;
+export const TOAST_DURATION_MS = 3000;
+export const WS_BACKOFF_BASE_MS = 3000;
+export const WS_BACKOFF_MAX_MS = 30000;
+export const WS_MAX_RECONNECT_ATTEMPTS = 20;
+export const WS_PING_INTERVAL_MS = 30000;
+export const VOLUME_RELEASE_DELAY_MS = 500;
+
+// Shared state (accessed across multiple modules)
+export let ws = null;
+export function setWs(value) { ws = value; }
+export function getWs() { return ws; }
+export let currentState = 'idle';
+export function setCurrentState(value) { currentState = value; }
+export let currentDuration = 0;
+export function setCurrentDuration(value) { currentDuration = value; }
+export let currentPosition = 0;
+export function setCurrentPosition(value) { currentPosition = value; }
+export let isUserAdjustingVolume = false;
+export function setIsUserAdjustingVolume(value) { isUserAdjustingVolume = value; }
+export let volumeUpdateTimer = null;
+export function setVolumeUpdateTimer(value) { volumeUpdateTimer = value; }
+export let scripts = [];
+export function setScripts(value) { scripts = value; }
+export let lastStatus = null;
+export function setLastStatus(value) { lastStatus = value; }
+export let currentPlayState = 'idle';
+export function setCurrentPlayState(value) { currentPlayState = value; }
+
+// ============================================================
+// Internationalization (i18n)
+// ============================================================
+
+let currentLocale = 'en';
+let translations = {};
+const supportedLocales = {
+    'en': 'English',
+    'ru': 'Русский'
+};
+
+// Minimal inline fallback for critical UI elements
+const fallbackTranslations = {
+    'app.title': 'Media Server',
+    'auth.connect': 'Connect',
+    'auth.placeholder': 'Enter API Token',
+    'player.status.connected': 'Connected',
+    'player.status.disconnected': 'Disconnected'
+};
+
+export function t(key, params = {}) {
+    let text = translations[key] || fallbackTranslations[key] || key;
+    Object.keys(params).forEach(param => {
+        text = text.replace(new RegExp(`\\{${param}\\}`, 'g'), params[param]);
+    });
+    return text;
+}
+
+async function loadTranslations(locale) {
+    try {
+        const response = await fetch(`/static/locales/${locale}.json`);
+        if (!response.ok) {
+            throw new Error(`Failed to load ${locale}.json`);
+        }
+        return await response.json();
+    } catch (error) {
+        console.error(`Error loading translations for ${locale}:`, error);
+        if (locale !== 'en') {
+            return await loadTranslations('en');
+        }
+        return {};
+    }
+}
+
+function detectBrowserLocale() {
+    const browserLang = navigator.language || navigator.languages?.[0] || 'en';
+    const langCode = browserLang.split('-')[0];
+    return supportedLocales[langCode] ? langCode : 'en';
+}
+
+export async function initLocale() {
+    const savedLocale = localStorage.getItem('locale') || detectBrowserLocale();
+    await setLocale(savedLocale);
+}
+
+async function setLocale(locale) {
+    if (!supportedLocales[locale]) {
+        locale = 'en';
+    }
+    translations = await loadTranslations(locale);
+    currentLocale = locale;
+    document.documentElement.setAttribute('data-locale', locale);
+    document.documentElement.setAttribute('lang', locale);
+    localStorage.setItem('locale', locale);
+    updateAllText();
+    updateLocaleSelect();
+    document.body.classList.remove('loading-translations');
+    document.body.classList.add('translations-loaded');
+}
+
+export function changeLocale() {
+    const select = document.getElementById('locale-select');
+    const newLocale = select.value;
+    if (newLocale && newLocale !== currentLocale) {
+        localStorage.setItem('locale', newLocale);
+        setLocale(newLocale);
+    }
+}
+
+function updateLocaleSelect() {
+    const select = document.getElementById('locale-select');
+    if (select) {
+        select.value = currentLocale;
+    }
+}
+
+// Note: updateAllText calls functions from other modules via late-bound references.
+// These are set from app.js after all modules are loaded.
+let _updatePlaybackState = null;
+let _updateConnectionStatus = null;
+let _loadScriptsTable = null;
+let _loadCallbacksTable = null;
+let _loadLinksTable = null;
+let _displayQuickAccess = null;
+let _renderAccentSwatches = null;
+
+export function registerUpdateCallbacks(callbacks) {
+    _updatePlaybackState = callbacks.updatePlaybackState;
+    _updateConnectionStatus = callbacks.updateConnectionStatus;
+    _loadScriptsTable = callbacks.loadScriptsTable;
+    _loadCallbacksTable = callbacks.loadCallbacksTable;
+    _loadLinksTable = callbacks.loadLinksTable;
+    _displayQuickAccess = callbacks.displayQuickAccess;
+    _renderAccentSwatches = callbacks.renderAccentSwatches;
+}
+
+function updateAllText() {
+    document.querySelectorAll('[data-i18n]').forEach(el => {
+        const key = el.getAttribute('data-i18n');
+        el.textContent = t(key);
+    });
+    document.querySelectorAll('[data-i18n-placeholder]').forEach(el => {
+        const key = el.getAttribute('data-i18n-placeholder');
+        el.placeholder = t(key);
+    });
+    document.querySelectorAll('[data-i18n-title]').forEach(el => {
+        const key = el.getAttribute('data-i18n-title');
+        el.title = t(key);
+    });
+
+    // Re-apply dynamic content with new translations
+    if (_updatePlaybackState) _updatePlaybackState(currentState);
+    const connected = ws && ws.readyState === WebSocket.OPEN;
+    if (_updateConnectionStatus) _updateConnectionStatus(connected);
+
+    if (lastStatus) {
+        const fallbackTitle = lastStatus.state === 'idle' ? t('player.no_media') : t('player.title_unavailable');
+        document.getElementById('track-title').textContent = lastStatus.title || fallbackTitle;
+        const initSrc = resolveMediaSource(lastStatus.source);
+        document.getElementById('source').textContent = initSrc ? initSrc.name : t('player.unknown_source');
+        document.getElementById('sourceIcon').innerHTML = initSrc?.icon || '';
+    }
+
+    if (hasCredentials()) {
+        if (_loadScriptsTable) _loadScriptsTable();
+        if (_loadCallbacksTable) _loadCallbacksTable();
+        if (_loadLinksTable) _loadLinksTable();
+        if (_displayQuickAccess) _displayQuickAccess();
+    }
+    if (_renderAccentSwatches) _renderAccentSwatches();
+}
+
+export async function fetchVersion() {
+    try {
+        const response = await fetch('/api/health');
+        if (response.ok) {
+            const data = await response.json();
+            const label = document.getElementById('version-label');
+            if (data.version) {
+                label.textContent = `v${data.version}`;
+                const folioVersion = document.getElementById('folio-version');
+                if (folioVersion) folioVersion.textContent = `v${data.version}`;
+            }
+            if (data.update_available) {
+                showUpdateBanner(data.update_available);
+            }
+        }
+    } catch (error) {
+        console.error('Error fetching version:', error);
+    }
+}
+
+export function showUpdateBanner(update) {
+    const dismissed = sessionStorage.getItem('update_dismissed');
+    if (dismissed === update.latest) return;
+
+    const banner = document.getElementById('updateBanner');
+    const text = document.getElementById('updateBannerText');
+    const link = document.getElementById('updateBannerLink');
+    const closeBtn = document.getElementById('updateBannerClose');
+
+    text.textContent = t('update.available', { version: update.latest });
+    link.href = update.url;
+    link.textContent = t('update.view_release');
+    banner.classList.remove('hidden');
+
+    closeBtn.onclick = () => {
+        banner.classList.add('hidden');
+        sessionStorage.setItem('update_dismissed', update.latest);
+    };
+}
+
+// ============================================================
+// Shared Utilities
+// ============================================================
+
+export function formatTime(seconds) {
+    if (!seconds || seconds < 0) return '0:00';
+    const mins = Math.floor(seconds / 60);
+    const secs = Math.floor(seconds % 60);
+    return `${mins}:${secs.toString().padStart(2, '0')}`;
+}
+
+export function escapeHtml(text) {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+}
+
+export function showToast(message, type = 'success') {
+    const container = document.getElementById('toast-container');
+    const toast = document.createElement('div');
+    toast.className = `toast ${type}`;
+    toast.textContent = message;
+    container.appendChild(toast);
+
+    requestAnimationFrame(() => {
+        toast.classList.add('show');
+    });
+
+    setTimeout(() => {
+        toast.classList.remove('show');
+        toast.addEventListener('transitionend', () => toast.remove(), { once: true });
+        setTimeout(() => { if (toast.parentNode) toast.remove(); }, 500);
+    }, TOAST_DURATION_MS);
+}
+
+export function closeDialog(dialog) {
+    dialog.classList.add('dialog-closing');
+    dialog.addEventListener('animationend', () => {
+        dialog.classList.remove('dialog-closing');
+        dialog.close();
+    }, { once: true });
+}
+
+export function showAboutDialog() {
+    const dialog = document.getElementById('aboutDialog');
+    if (dialog) dialog.showModal();
+}
+
+export function closeAboutDialog() {
+    const dialog = document.getElementById('aboutDialog');
+    if (dialog) closeDialog(dialog);
+}
+
+export function showConfirm(message) {
+    return new Promise((resolve) => {
+        const dialog = document.getElementById('confirmDialog');
+        const msg = document.getElementById('confirmDialogMessage');
+        const btnCancel = document.getElementById('confirmDialogCancel');
+        const btnConfirm = document.getElementById('confirmDialogConfirm');
+
+        msg.textContent = message;
+
+        function cleanup() {
+            btnCancel.removeEventListener('click', onCancel);
+            btnConfirm.removeEventListener('click', onConfirm);
+            dialog.removeEventListener('close', onClose);
+            closeDialog(dialog);
+        }
+
+        function onCancel() { cleanup(); resolve(false); }
+        function onConfirm() { cleanup(); resolve(true); }
+        function onClose() { cleanup(); resolve(false); }
+
+        btnCancel.addEventListener('click', onCancel);
+        btnConfirm.addEventListener('click', onConfirm);
+        dialog.addEventListener('close', onClose);
+
+        dialog.showModal();
+    });
+}
+
+// ============================================================
+// Auth Helpers
+// ============================================================
+
+// Set to false when server reports auth_required: false
+export let authRequired = true;
+export function setAuthRequired(value) { authRequired = value; }
+
+/**
+ * Build Authorization headers for API requests.
+ * Returns empty object when auth is disabled or no token is stored.
+ */
+export function getAuthHeaders() {
+    const token = localStorage.getItem('media_server_token');
+    return token ? { 'Authorization': `Bearer ${token}` } : {};
+}
+
+/**
+ * Check if we have sufficient credentials to call the API.
+ * True when auth is disabled OR a token is stored.
+ */
+export function hasCredentials() {
+    return !authRequired || !!localStorage.getItem('media_server_token');
+}
+
+// ============================================================
+// API Commands
+// ============================================================
+
+export async function sendCommand(endpoint, body = null) {
+    const options = {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+    };
+
+    if (body) {
+        options.body = JSON.stringify(body);
+    }
+
+    try {
+        const response = await fetch(`/api/media/${endpoint}`, options);
+        if (!response.ok) {
+            const data = await response.json().catch(() => ({}));
+            console.error(`Command ${endpoint} failed:`, response.status);
+            showToast(data.detail || `Command failed: ${endpoint}`, 'error');
+        }
+    } catch (error) {
+        console.error(`Error sending command ${endpoint}:`, error);
+        showToast(`Connection error: ${endpoint}`, 'error');
+    }
+}
+
+export function togglePlayPause() {
+    if (currentState === 'playing') {
+        sendCommand('pause');
+    } else {
+        sendCommand('play');
+    }
+}
+
+export function nextTrack() {
+    sendCommand('next');
+}
+
+export function previousTrack() {
+    sendCommand('previous');
+}
+
+let lastSentVolume = -1;
+export function setVolume(volume) {
+    if (volume === lastSentVolume) return;
+    lastSentVolume = volume;
+    if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'volume', volume: volume }));
+    } else {
+        sendCommand('volume', { volume: volume });
+    }
+}
+// Reset the de-dupe cache whenever the server reports a fresh volume value
+// (e.g., another client moved the slider). Otherwise the user can end up
+// unable to "set volume back to the value we last sent" after a remote change.
+export function notifyRemoteVolume(volume) {
+    lastSentVolume = volume;
+}
+
+export function toggleMute() {
+    sendCommand('mute');
+}
+
+export function seek(position) {
+    sendCommand('seek', { position: position });
+}
+
+// ============================================================
+// MDI Icon System
+// ============================================================
+
+const mdiIconCache = (() => {
+    try {
+        return JSON.parse(localStorage.getItem('mdiIconCache') || '{}');
+    } catch { return {}; }
+})();
+
+function _persistMdiCache() {
+    try { localStorage.setItem('mdiIconCache', JSON.stringify(mdiIconCache)); } catch {}
+}
+
+// Strict iconify MDI slug — used to reject anything that could be path-traversal
+// or query injection before we even hit the network.
+const MDI_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+function sanitizeSvg(rawSvg) {
+    // Parse the SVG and strip anything that could execute script. Anything
+    // unparseable returns null so callers fall back to the placeholder.
+    try {
+        const doc = new DOMParser().parseFromString(rawSvg, 'image/svg+xml');
+        const root = doc.documentElement;
+        if (!root || root.tagName.toLowerCase() !== 'svg' || root.querySelector('parsererror')) {
+            return null;
+        }
+        const walker = doc.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+        const toRemove = [];
+        let node = walker.currentNode;
+        while (node) {
+            const tag = node.tagName?.toLowerCase();
+            if (tag === 'script' || tag === 'foreignobject') {
+                toRemove.push(node);
+            } else if (node.attributes) {
+                for (const attr of Array.from(node.attributes)) {
+                    const name = attr.name.toLowerCase();
+                    if (name.startsWith('on') ||
+                        ((name === 'href' || name === 'xlink:href') &&
+                            /^\s*(javascript|data):/i.test(attr.value))) {
+                        node.removeAttribute(attr.name);
+                    }
+                }
+            }
+            node = walker.nextNode();
+        }
+        toRemove.forEach((el) => el.remove());
+        return root.outerHTML;
+    } catch {
+        return null;
+    }
+}
+
+const PLACEHOLDER_SVG = '<svg viewBox="0 0 24 24" width="16" height="16"><path fill="currentColor" d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"/></svg>';
+
+export async function fetchMdiIcon(iconName) {
+    const name = String(iconName || '').replace(/^mdi:/, '');
+    if (!MDI_SLUG_RE.test(name)) return PLACEHOLDER_SVG;
+    if (mdiIconCache[name]) return mdiIconCache[name];
+
+    try {
+        const response = await fetch(`https://api.iconify.design/mdi/${encodeURIComponent(name)}.svg?width=16&height=16`);
+        if (response.ok) {
+            const raw = await response.text();
+            const safe = sanitizeSvg(raw);
+            if (safe) {
+                mdiIconCache[name] = safe;
+                _persistMdiCache();
+                return safe;
+            }
+        }
+    } catch (e) {
+        console.warn('Failed to fetch MDI icon:', name, e);
+    }
+
+    return PLACEHOLDER_SVG;
+}
+
+export async function resolveMdiIcons(container) {
+    const els = container.querySelectorAll('[data-mdi-icon]');
+    await Promise.all(Array.from(els).map(async (el) => {
+        const icon = el.dataset.mdiIcon;
+        if (icon) {
+            el.innerHTML = await fetchMdiIcon(icon);
+        }
+    }));
+}
+
+export function setupIconPreview(inputId, previewId) {
+    const input = document.getElementById(inputId);
+    const preview = document.getElementById(previewId);
+    if (!input || !preview) return;
+
+    let debounceTimer = null;
+
+    input.addEventListener('input', () => {
+        clearTimeout(debounceTimer);
+        const value = input.value.trim();
+
+        if (!value) {
+            preview.innerHTML = '';
+            return;
+        }
+
+        debounceTimer = setTimeout(async () => {
+            const svg = await fetchMdiIcon(value);
+            if (input.value.trim() === value) {
+                preview.innerHTML = svg;
+            }
+        }, 400);
+    });
+}

media_server/static/js/foreground.js

@@ -0,0 +1,188 @@
+// ============================================================
+// Foreground: Currently-focused desktop process card (rendered at
+// the top of the Display tab)
+// ============================================================
+
+import { t } from './core.js';
+
+let latestForeground = null;
+let agoTickTimer = null;
+
+function escapeHtml(s) {
+    if (s === null || s === undefined) return '';
+    return String(s)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+function formatAgo(epoch) {
+    if (!epoch) return '';
+    const now = Date.now() / 1000;
+    const diff = Math.max(0, now - epoch);
+    if (diff < 60) {
+        return t('foreground.ago.seconds', { n: Math.floor(diff) });
+    }
+    if (diff < 3600) {
+        return t('foreground.ago.minutes', { n: Math.floor(diff / 60) });
+    }
+    if (diff < 86400) {
+        const h = Math.floor(diff / 3600);
+        const m = Math.floor((diff % 3600) / 60);
+        return t('foreground.ago.hours', { n: h, m: m });
+    }
+    return t('foreground.ago.days', { n: Math.floor(diff / 86400) });
+}
+
+function formatGeometry(g) {
+    if (!g) return '—';
+    const w = g.width ?? (g.right - g.left);
+    const h = g.height ?? (g.bottom - g.top);
+    return `${w}×${h} @ (${g.left}, ${g.top})`;
+}
+
+function truncatePath(p, max = 64) {
+    if (!p) return '';
+    if (p.length <= max) return p;
+    // Keep the tail (filename) visible — that's the part the user cares about.
+    return '…' + p.slice(-(max - 1));
+}
+
+function renderEmpty(message, errorMsg) {
+    const stage = document.getElementById('foregroundStage');
+    if (!stage) return;
+    stage.innerHTML = `
+        <div class="empty-state-illustration foreground-empty">
+            <svg viewBox="0 0 64 64"><rect x="6" y="12" width="52" height="36" rx="3" fill="none" stroke="currentColor" stroke-width="2"/><line x1="6" y1="20" x2="58" y2="20" stroke="currentColor" stroke-width="2"/><circle cx="11" cy="16" r="1.4" fill="currentColor"/><circle cx="15" cy="16" r="1.4" fill="currentColor"/><circle cx="19" cy="16" r="1.4" fill="currentColor"/></svg>
+            <p>${escapeHtml(message)}</p>
+            ${errorMsg ? `<p class="foreground-empty-error">${escapeHtml(errorMsg)}</p>` : ''}
+        </div>
+    `;
+}
+
+function renderTile(data) {
+    const stage = document.getElementById('foregroundStage');
+    if (!stage) return;
+
+    const procName = data.process_name || '—';
+    const winTitle = data.window_title || '';
+    const execPath = data.executable_path || '';
+    const pid = data.pid ?? '—';
+    const startedEpoch = data.started_at;
+    const startedAgo = startedEpoch ? formatAgo(startedEpoch) : '—';
+    const startedAbs = startedEpoch
+        ? new Date(startedEpoch * 1000).toLocaleString()
+        : '';
+    const geom = formatGeometry(data.window_geometry);
+    const platform = data.platform || '—';
+    const monitorId = data.monitor_id;
+
+    // Chips: only render ones that apply
+    const chips = [];
+    if (data.is_fullscreen) {
+        chips.push(`<span class="fg-chip fg-chip-accent">${escapeHtml(t('foreground.fullscreen'))}</span>`);
+    } else if (!data.is_minimized) {
+        chips.push(`<span class="fg-chip">${escapeHtml(t('foreground.windowed'))}</span>`);
+    }
+    if (data.is_minimized) {
+        chips.push(`<span class="fg-chip fg-chip-mute">${escapeHtml(t('foreground.minimized'))}</span>`);
+    }
+    if (monitorId !== null && monitorId !== undefined) {
+        chips.push(`<span class="fg-chip">${escapeHtml(t('foreground.monitor', { n: monitorId + 1 }))}</span>`);
+    }
+    if (data.is_browser) {
+        chips.push(`<span class="fg-chip fg-chip-mute">${escapeHtml(t('foreground.browser'))}</span>`);
+    }
+
+    // Optional browser-only detail rows (page title + URL when available)
+    const browserRows = [];
+    if (data.is_browser) {
+        if (data.browser_page_title) {
+            browserRows.push(`
+                <div class="fg-row">
+                    <dt>${escapeHtml(t('foreground.page_title'))}</dt>
+                    <dd title="${escapeHtml(data.browser_page_title)}">${escapeHtml(data.browser_page_title)}</dd>
+                </div>
+            `);
+        }
+        if (data.browser_url) {
+            browserRows.push(`
+                <div class="fg-row">
+                    <dt>${escapeHtml(t('foreground.url'))}</dt>
+                    <dd title="${escapeHtml(data.browser_url)}"><span class="fg-mono">${escapeHtml(truncatePath(data.browser_url, 80))}</span></dd>
+                </div>
+            `);
+        }
+    }
+
+    stage.innerHTML = `
+        <article class="foreground-card" data-fullscreen="${data.is_fullscreen ? '1' : '0'}">
+            <div class="fg-kicker">
+                <span data-i18n="foreground.kicker">Foreground</span>
+            </div>
+            <h1 class="fg-process" title="${escapeHtml(procName)}">${escapeHtml(procName)}</h1>
+            <div class="fg-window-title" title="${escapeHtml(winTitle)}">${escapeHtml(winTitle)}</div>
+
+            <div class="fg-chips">${chips.join('')}</div>
+
+            <dl class="fg-details">
+                ${browserRows.join('')}
+                <div class="fg-row">
+                    <dt>${escapeHtml(t('foreground.executable'))}</dt>
+                    <dd title="${escapeHtml(execPath)}"><span class="fg-mono">${escapeHtml(truncatePath(execPath))}</span></dd>
+                </div>
+                <div class="fg-row">
+                    <dt>${escapeHtml(t('foreground.pid'))}</dt>
+                    <dd><span class="fg-mono">${escapeHtml(String(pid))}</span></dd>
+                </div>
+                <div class="fg-row">
+                    <dt>${escapeHtml(t('foreground.started'))}</dt>
+                    <dd title="${escapeHtml(startedAbs)}"><span class="fg-ago" data-started="${startedEpoch ?? ''}">${escapeHtml(startedAgo)}</span></dd>
+                </div>
+                <div class="fg-row">
+                    <dt>${escapeHtml(t('foreground.geometry'))}</dt>
+                    <dd><span class="fg-mono">${escapeHtml(geom)}</span></dd>
+                </div>
+                <div class="fg-row">
+                    <dt>${escapeHtml(t('foreground.platform'))}</dt>
+                    <dd>${escapeHtml(platform)}</dd>
+                </div>
+            </dl>
+        </article>
+    `;
+}
+
+function startAgoTicker() {
+    if (agoTickTimer) return;
+    agoTickTimer = setInterval(() => {
+        const el = document.querySelector('.fg-ago[data-started]');
+        if (!el) return;
+        const epoch = parseFloat(el.getAttribute('data-started'));
+        if (!epoch) return;
+        el.textContent = formatAgo(epoch);
+    }, 15000);
+}
+
+export function updateForegroundUI(data) {
+    latestForeground = data;
+
+    if (!data || data.available === false) {
+        const errMsg = data && data.error ? data.error : '';
+        renderEmpty(t('foreground.unavailable'), errMsg);
+    } else if (!data.process_name && !data.pid) {
+        renderEmpty(t('foreground.no_process'), '');
+    } else {
+        renderTile(data);
+        startAgoTicker();
+    }
+}
+
+export function loadForegroundProcess() {
+    // Push-only — just render the cached state. If nothing has arrived
+    // yet, leave the loading placeholder visible.
+    if (latestForeground !== null) {
+        updateForegroundUI(latestForeground);
+    }
+}

media_server/static/js/icon-select.js

@@ -0,0 +1,160 @@
+// ============================================================
+// IconSelect: visual icon-grid selector (replaces <select>)
+// Ported from wled-screen-controller (TypeScript → vanilla JS)
+//
+// Trigger replaces the <select> inline. Popup is absolutely
+// positioned inside a wrapper that sits next to the trigger.
+// Works inside <dialog showModal()> — dialog must have
+// overflow: visible.
+// ============================================================
+
+const POPUP_CLASS = 'icon-select-popup';
+
+let _globalListenerAdded = false;
+
+export function closeAllIconSelects() {
+    document.querySelectorAll(`.${POPUP_CLASS}.open`).forEach(p => {
+        p.classList.remove('open');
+    });
+}
+
+function _ensureGlobalListener() {
+    if (_globalListenerAdded) return;
+    _globalListenerAdded = true;
+    document.addEventListener('click', (e) => {
+        if (!e.target.closest(`.${POPUP_CLASS}`) && !e.target.closest('.icon-select-trigger')) {
+            closeAllIconSelects();
+        }
+    });
+    document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape') closeAllIconSelects();
+    });
+}
+
+export class IconSelect {
+    constructor({ target, items, onChange, columns = 2, placeholder = '', horizontal = false }) {
+        _ensureGlobalListener();
+
+        this._select = target;
+        this._items = items;
+        this._onChange = onChange;
+        this._columns = columns;
+        this._placeholder = placeholder;
+        this._horizontal = horizontal;
+
+        // Hide native select
+        this._select.style.display = 'none';
+
+        // Trigger button (replaces select visually)
+        this._trigger = document.createElement('button');
+        this._trigger.type = 'button';
+        this._trigger.className = 'icon-select-trigger';
+        this._trigger.addEventListener('click', (e) => {
+            e.stopPropagation();
+            this._toggle();
+        });
+        this._select.parentNode.insertBefore(this._trigger, this._select.nextSibling);
+
+        // Popup — absolutely positioned, appended to dialog (overflow:visible)
+        // or body, escaping any scrollable ancestors
+        this._popup = document.createElement('div');
+        this._popup.className = POPUP_CLASS;
+        this._popup.addEventListener('click', (e) => e.stopPropagation());
+        this._popup.innerHTML = this._buildGrid();
+
+        const portal = this._select.closest('dialog') || document.body;
+        portal.appendChild(this._popup);
+
+        this._bindCells();
+        this._syncTrigger();
+    }
+
+    _buildGrid() {
+        const cells = this._items.map(item =>
+            `<div class="icon-select-cell" data-value="${item.value}">
+                <span class="icon-select-cell-icon">${item.icon}</span>
+                <span class="icon-select-cell-label">${item.label}</span>
+                ${item.desc ? `<span class="icon-select-cell-desc">${item.desc}</span>` : ''}
+            </div>`
+        ).join('');
+
+        const cls = 'icon-select-grid' + (this._horizontal ? ' icon-select-grid--horizontal' : '');
+        return `<div class="${cls}" style="grid-template-columns:repeat(${this._columns},1fr)">${cells}</div>`;
+    }
+
+    _bindCells() {
+        this._popup.querySelectorAll('.icon-select-cell').forEach(cell => {
+            cell.addEventListener('click', () => {
+                this.setValue(cell.dataset.value, true);
+                this._popup.classList.remove('open');
+            });
+        });
+    }
+
+    _syncTrigger() {
+        const val = this._select.value;
+        const item = this._items.find(i => i.value === val);
+        if (item) {
+            this._trigger.innerHTML =
+                `<span class="icon-select-trigger-icon">${item.icon}</span>` +
+                `<span class="icon-select-trigger-label">${item.label}</span>` +
+                `<span class="icon-select-trigger-arrow">&#x25BE;</span>`;
+        } else if (this._placeholder) {
+            this._trigger.innerHTML =
+                `<span class="icon-select-trigger-label">${this._placeholder}</span>` +
+                `<span class="icon-select-trigger-arrow">&#x25BE;</span>`;
+        }
+        this._popup.querySelectorAll('.icon-select-cell').forEach(cell => {
+            cell.classList.toggle('active', cell.dataset.value === val);
+        });
+    }
+
+    _positionPopup() {
+        // Get trigger position relative to the popup's offset parent
+        // (the dialog or body). Use getBoundingClientRect for both and
+        // compute the offset.
+        const triggerRect = this._trigger.getBoundingClientRect();
+        const parentRect = this._popup.offsetParent
+            ? this._popup.offsetParent.getBoundingClientRect()
+            : { left: 0, top: 0 };
+
+        const relTop = triggerRect.bottom - parentRect.top;
+        const relLeft = triggerRect.left - parentRect.left;
+        const popupW = Math.max(triggerRect.width, 200);
+
+        this._popup.style.left = relLeft + 'px';
+        this._popup.style.top = (relTop + 4) + 'px';
+        this._popup.style.width = popupW + 'px';
+    }
+
+    _toggle() {
+        const wasOpen = this._popup.classList.contains('open');
+        closeAllIconSelects();
+        if (!wasOpen) {
+            this._positionPopup();
+            this._popup.classList.add('open');
+        }
+    }
+
+    setValue(value, fireChange = false) {
+        this._select.value = value;
+        this._syncTrigger();
+        if (fireChange) {
+            this._select.dispatchEvent(new Event('change', { bubbles: true }));
+            if (this._onChange) this._onChange(value);
+        }
+    }
+
+    updateItems(items) {
+        this._items = items;
+        this._popup.innerHTML = this._buildGrid();
+        this._bindCells();
+        this._syncTrigger();
+    }
+
+    destroy() {
+        this._trigger.remove();
+        this._popup.remove();
+        this._select.style.display = '';
+    }
+}

media_server/static/js/icons.js

@@ -0,0 +1,31 @@
+// ============================================================
+// SVG icon library for icon-select grids
+// Simple inline SVGs (24x24 viewBox, fill="currentColor")
+// ============================================================
+
+const _svg = (path) =>
+    `<svg viewBox="0 0 24 24" fill="currentColor" xmlns="http://www.w3.org/2000/svg">${path}</svg>`;
+
+// Parameter types
+export const paramTypeIcons = {
+    string:  _svg('<path d="M3 7V5h18v2H3zm0 12v-2h12v2H3zm0-6v-2h18v2H3z"/>'),
+    integer: _svg('<path d="M4 17V7h2v4h3V7h2v10h-2v-4H6v4H4zm10-1h2v1h2v-4h-2v1h-2V9h6v8h-6v-1z"/>'),
+    float:   _svg('<path d="M5 17V7h2v4h3V7h2v10H9v-4H7v4H5zm9.5 0v-2a1 1 0 1 1 0-2h1v-2h-1a3 3 0 0 0 0 6h1v2h-1zm3-6v2h1a1 1 0 1 1 0 2h-1v2h1a3 3 0 0 0 0-6h-1z"/>'),
+    boolean: _svg('<path d="M17 7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h10c2.76 0 5-2.24 5-5s-2.24-5-5-5zm0 8c-1.66 0-3-1.34-3-3s1.34-3 3-3 3 1.34 3 3-1.34 3-3 3z"/>'),
+    select:  _svg('<path d="M3 5h18v2H3V5zm4 6h10v2H7v-2zm-4 6h18v2H3v-2z"/><path d="M7 7l5 5 5-5"/>'),
+};
+
+// Callback events
+export const callbackEventIcons = {
+    on_play:     _svg('<path d="M8 5v14l11-7z"/>'),
+    on_pause:    _svg('<path d="M6 4h4v16H6V4zm8 0h4v16h-4V4z"/>'),
+    on_stop:     _svg('<path d="M6 6h12v12H6z"/>'),
+    on_next:     _svg('<path d="M6 18l8.5-6L6 6v12zM16 6v12h2V6h-2z"/>'),
+    on_previous: _svg('<path d="M6 6h2v12H6V6zm3.5 6l8.5 6V6l-8.5 6z"/>'),
+    on_volume:   _svg('<path d="M3 9v6h4l5 5V4L7 9H3zm13.5 3A4.5 4.5 0 0 0 14 8.5v7a4.5 4.5 0 0 0 2.5-3.5zM14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.85-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77z"/>'),
+    on_mute:     _svg('<path d="M16.5 12A4.5 4.5 0 0 0 14 8.5v2.09l2.41 2.41c.06-.31.09-.65.09-1zM19 12c0 .94-.2 1.82-.54 2.64l1.51 1.51A8.796 8.796 0 0 0 21 12c0-4.28-2.99-7.86-7-8.77v2.06c2.89.86 5 3.54 5 6.71zM4.27 3L3 4.27 7.73 9H3v6h4l5 5v-6.73l4.25 4.25c-.67.52-1.42.93-2.25 1.18v2.06a8.99 8.99 0 0 0 3.69-1.81L19.73 21 21 19.73l-9-9L4.27 3zM12 4L9.91 6.09 12 8.18V4z"/>'),
+    on_seek:     _svg('<path d="M12 5V1L7 6l5 5V7c3.31 0 6 2.69 6 6s-2.69 6-6 6-6-2.69-6-6H4c0 4.42 3.58 8 8 8s8-3.58 8-8-3.58-8-8-8z"/>'),
+    on_turn_on:  _svg('<path d="M13 3h-2v10h2V3zm4.83 2.17l-1.42 1.42A6.92 6.92 0 0 1 19 12c0 3.87-3.13 7-7 7s-7-3.13-7-7c0-2.27 1.08-4.28 2.76-5.56L6.34 5.02A8.96 8.96 0 0 0 3 12c0 4.97 4.03 9 9 9s9-4.03 9-9a8.96 8.96 0 0 0-3.17-6.83z"/>'),
+    on_turn_off: _svg('<path d="M13 3h-2v10h2V3zm4.83 2.17l-1.42 1.42A6.92 6.92 0 0 1 19 12c0 3.87-3.13 7-7 7s-7-3.13-7-7c0-2.27 1.08-4.28 2.76-5.56L6.34 5.02A8.96 8.96 0 0 0 3 12c0 4.97 4.03 9 9 9s9-4.03 9-9a8.96 8.96 0 0 0-3.17-6.83z"/>'),
+    on_toggle:   _svg('<path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z"/>'),
+};

media_server/static/js/links.js

@@ -0,0 +1,765 @@
+// ============================================================
+// Display Brightness, Power, Contrast, Input Source, Color Preset,
+// Picture Mode Control + Links Management
+// ============================================================
+
+import { t, showToast, escapeHtml, closeDialog, showConfirm, resolveMdiIcons, fetchMdiIcon, getAuthHeaders, hasCredentials } from './core.js';
+import { IconSelect } from './icon-select.js';
+
+let displayBrightnessTimers = {};
+let displayContrastTimers = {};
+let _displayIconSelects = [];
+const DISPLAY_THROTTLE_MS = 50;
+
+// ─── Icon palette for the tuning IconSelects ───────────────────────────
+// All SVGs are 24x24 monochrome — IconSelect's CSS fills them with currentColor.
+
+const ICON_PORT_GENERIC =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M4 8h16v8H4V8zm2 2v4h12v-4H6zm2 1h2v2H8v-2zm4 0h2v2h-2v-2zm-9 6h18v2H3v-2z"/></svg>';
+const ICON_PORT_HDMI =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M3 9l2-2h14l2 2v5l-2 2h-3l-1 1H9l-1-1H5l-2-2V9zm2.5.5v4l1 1h2l1 1h7l1-1h2l1-1v-4l-1-.5H6.5l-1 .5z"/></svg>';
+const ICON_PORT_DP =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M4 8l2-2h12l2 2v8l-2 2H6l-2-2V8zm2 .5V15l1 1h10l1-1V8.5L17 8H7l-1 .5zM8 10h2v4H8v-4zm6 0h2v4h-2v-4z"/></svg>';
+const ICON_PORT_DVI =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M3 8h18v8H3V8zm2 1.5v5h14v-5H5zM7 11h1.5v2H7v-2zm3 0h1.5v2H10v-2zm3 0h1.5v2H13v-2zm3 0h1.5v2H16v-2z"/></svg>';
+const ICON_PORT_VGA =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M5 7h14a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2V9a2 2 0 012-2zm0 2v6h14V9H5zm2 1.5a.75.75 0 100 1.5.75.75 0 000-1.5zm3 0a.75.75 0 100 1.5.75.75 0 000-1.5zm3 0a.75.75 0 100 1.5.75.75 0 000-1.5zm3 0a.75.75 0 100 1.5.75.75 0 000-1.5z"/></svg>';
+const ICON_PORT_USBC =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M5 10a3 3 0 013-3h8a3 3 0 013 3v4a3 3 0 01-3 3H8a3 3 0 01-3-3v-4zm3-1.5A1.5 1.5 0 006.5 10v4A1.5 1.5 0 008 15.5h8a1.5 1.5 0 001.5-1.5v-4A1.5 1.5 0 0016 8.5H8zm1 2h6v3H9v-3z"/></svg>';
+
+const ICON_THERMOMETER =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M12 3a3 3 0 00-3 3v8.17A4 4 0 1015 14.17V6a3 3 0 00-3-3zm-1.5 3a1.5 1.5 0 113 0v8.76a2.5 2.5 0 11-3 0V6zm1.5 5a1 1 0 011 1v2.27a1.5 1.5 0 11-2 0V12a1 1 0 011-1z"/></svg>';
+
+const ICON_MODE_MOVIE =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M4 5h16v14H4V5zm2 2v2h2V7H6zm0 4v2h2v-2H6zm0 4v2h2v-2H6zm10-8v2h2V7h-2zm0 4v2h2v-2h-2zm0 4v2h2v-2h-2zm-6-7h4v8h-4V8z"/></svg>';
+const ICON_MODE_GAME =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M7 8a5 5 0 00-5 5 4 4 0 007.4 2.1L11 14h2l1.6 1.1A4 4 0 0022 13a5 5 0 00-5-5H7zm1 3v1H7v-1H6v-1h1V9h1v1h1v1H8zm7 0a1 1 0 110-2 1 1 0 010 2zm2 2a1 1 0 110-2 1 1 0 010 2z"/></svg>';
+const ICON_MODE_SPORT =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M12 2a10 10 0 100 20 10 10 0 000-20zm0 2c1.7 0 3.3.5 4.6 1.4l-1.4 2.4L12 6.5l-3.2 1.3-1.4-2.4A8 8 0 0112 4zm-7.6 4l2.5 1.3-.5 3.5L4 16.4A8 8 0 014.4 8zm15.2 0a8 8 0 01.4 8.4l-2.4-1.6-.5-3.5L19.6 8zM12 8.7l3 1.2.6 3.2L13 15h-2l-2.6-1.9.6-3.2L12 8.7zm-5.3 8.8L9 16.5l2.4 1h1.2l2.4-1 2.3 1A8 8 0 016.7 17.5z"/></svg>';
+const ICON_MODE_PRO =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M3 4h18v12H13v2h4v2H7v-2h4v-2H3V4zm2 2v8h14V6H5zm2 2h6v2H7V8zm0 3h10v2H7v-2z"/></svg>';
+const ICON_MODE_DOCS =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M6 3h9l4 4v14H6V3zm2 2v14h10V9h-4V5H8zm2 6h6v2h-6v-2zm0 3h6v2h-6v-2z"/></svg>';
+const ICON_MODE_USER =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M12 3a4 4 0 100 8 4 4 0 000-8zm0 2a2 2 0 110 4 2 2 0 010-4zm0 8c-3.3 0-7 1.5-7 4.5V20h14v-2.5c0-3-3.7-4.5-7-4.5z"/></svg>';
+const ICON_MODE_DEFAULT =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M3 5h18v12H3V5zm2 2v8h14V7H5zm-2 12h18v2H3v-2z"/></svg>';
+const ICON_MODE_MIXED =
+    '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M3 5h18v14H3V5zm2 2v10h7V7H5zm9 0v10h5V7h-5z"/></svg>';
+
+function inputSourceIcon(src) {
+    const s = String(src || '').toUpperCase();
+    if (s.startsWith('HDMI'))  return ICON_PORT_HDMI;
+    if (s.startsWith('DP'))    return ICON_PORT_DP;
+    if (s.startsWith('DVI'))   return ICON_PORT_DVI;
+    if (s.startsWith('VGA'))   return ICON_PORT_VGA;
+    if (s.startsWith('USB'))   return ICON_PORT_USBC;
+    return ICON_PORT_GENERIC;
+}
+
+function pictureModeIcon(label) {
+    const k = String(label || '').toLowerCase();
+    if (k.includes('movie'))         return ICON_MODE_MOVIE;
+    if (k.includes('game'))          return ICON_MODE_GAME;
+    if (k.includes('sport'))         return ICON_MODE_SPORT;
+    if (k.includes('professional'))  return ICON_MODE_PRO;
+    if (k.includes('productivity'))  return ICON_MODE_DOCS;
+    if (k.includes('user'))          return ICON_MODE_USER;
+    if (k.includes('mixed'))         return ICON_MODE_MIXED;
+    return ICON_MODE_DEFAULT;
+}
+
+// Humanise enum-style identifiers returned by monitorcontrol so users
+// don't see SHOUT_CASE strings in the UI.
+function humanizeInputSource(raw) {
+    if (!raw) return '';
+    // OFF / RESERVED → "Off" / "Reserved"
+    // VGA1 → "VGA 1", HDMI1 → "HDMI 1", DP1 → "DisplayPort 1"
+    const map = { DP: 'DisplayPort', DVI: 'DVI', HDMI: 'HDMI', VGA: 'VGA', USBC: 'USB-C' };
+    const m = String(raw).toUpperCase().match(/^(DP|DVI|HDMI|VGA|USBC|USB_C)(\d*)$/);
+    if (m) {
+        const key = m[1] === 'USB_C' ? 'USBC' : m[1];
+        return `${map[key]}${m[2] ? ' ' + m[2] : ''}`;
+    }
+    return String(raw)
+        .replace(/_/g, ' ')
+        .toLowerCase()
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+
+function humanizeColorPreset(raw) {
+    if (!raw) return '';
+    // COLOR_TEMP_6500K → "6500 K", COLOR_TEMP_NATIVE → "Native",
+    // COLOR_TEMP_USER1 → "User 1"
+    const s = String(raw).replace(/^COLOR_TEMP_?/i, '');
+    const kelvin = s.match(/^(\d{4,5})K?$/);
+    if (kelvin) return `${kelvin[1]} K`;
+    const user = s.match(/^USER\s*_?(\d+)$/i);
+    if (user) return `User ${user[1]}`;
+    return s
+        .replace(/_/g, ' ')
+        .toLowerCase()
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+
+export async function loadDisplayMonitors() {
+    if (!hasCredentials()) return;
+
+    const container = document.getElementById('displayMonitors');
+    if (!container) return;
+
+    try {
+        const response = await fetch('/api/display/monitors', {
+            headers: getAuthHeaders()
+        });
+
+        if (!response.ok) {
+            container.innerHTML = `<div class="empty-state-illustration">
+                <svg viewBox="0 0 64 64"><rect x="8" y="10" width="48" height="32" rx="3" fill="none" stroke="currentColor" stroke-width="2"/><line x1="32" y1="42" x2="32" y2="50" stroke="currentColor" stroke-width="2"/><line x1="22" y1="50" x2="42" y2="50" stroke="currentColor" stroke-width="2"/></svg>
+                <p data-i18n="display.error">Failed to load monitors</p>
+            </div>`;
+            return;
+        }
+
+        const monitors = await response.json();
+
+        if (monitors.length === 0) {
+            container.innerHTML = `<div class="empty-state-illustration">
+                <svg viewBox="0 0 64 64"><rect x="8" y="10" width="48" height="32" rx="3" fill="none" stroke="currentColor" stroke-width="2"/><line x1="32" y1="42" x2="32" y2="50" stroke="currentColor" stroke-width="2"/><line x1="22" y1="50" x2="42" y2="50" stroke="currentColor" stroke-width="2"/></svg>
+                <p data-i18n="display.no_monitors">No monitors detected</p>
+            </div>`;
+            return;
+        }
+
+        // Destroy IconSelects from a previous render so listeners + popups
+        // don't pile up.
+        _displayIconSelects.forEach(inst => { try { inst.destroy(); } catch (_) {} });
+        _displayIconSelects = [];
+
+        container.innerHTML = '';
+        const pendingIconSelects = [];
+        monitors.forEach(monitor => {
+            const card = document.createElement('div');
+            card.className = 'display-monitor-card';
+            card.id = `monitor-card-${monitor.id}`;
+
+            const brightnessValue = monitor.brightness !== null ? monitor.brightness : 0;
+            const brightnessDisabled = monitor.brightness === null ? 'disabled' : '';
+
+            let powerBtn = '';
+            if (monitor.power_supported) {
+                // Inline onclick with string-interpolated monitor.name is a DOM-XSS
+                // foot-gun if the OS ever reports a name containing quotes / angle
+                // brackets. Use a delegated click handler bound to data-* attrs.
+                powerBtn = `
+                    <button class="display-power-btn ${monitor.power_on ? 'on' : 'off'}" id="power-btn-${monitor.id}"
+                            data-action="toggle-power" data-monitor-id="${monitor.id}"
+                            title="${escapeHtml(monitor.power_on ? t('display.power_off') : t('display.power_on'))}">
+                        <svg viewBox="0 0 24 24" width="18" height="18"><path fill="currentColor" d="M13 3h-2v10h2V3zm4.83 2.17l-1.42 1.42A6.92 6.92 0 0119 12c0 3.87-3.13 7-7 7s-7-3.13-7-7c0-2.27 1.08-4.28 2.76-5.56L6.34 5.02A8.95 8.95 0 003 12c0 4.97 4.03 9 9 9s9-4.03 9-9a8.95 8.95 0 00-3.17-6.83z"/></svg>
+                    </button>`;
+            }
+
+            const details = [monitor.resolution, monitor.manufacturer].filter(Boolean).join(' \u00B7 ');
+            const detailsHtml = details ? `<span class="display-monitor-details">${escapeHtml(details)}</span>` : '';
+            const primaryBadge = monitor.is_primary
+                ? `<span class="display-primary-badge" title="${t('display.primary')}" aria-label="${t('display.primary')}">
+                       <svg viewBox="0 0 24 24" width="14" height="14" aria-hidden="true">
+                           <path fill="currentColor" d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>
+                       </svg>
+                   </span>`
+                : '';
+
+            // Contrast (DDC/CI) — render only if the monitor reports it.
+            let contrastRow = '';
+            if (monitor.contrast_supported) {
+                const contrastValue = monitor.contrast !== null && monitor.contrast !== undefined
+                    ? monitor.contrast : 50;
+                contrastRow = `
+                <div class="display-slider-row">
+                    <svg class="display-slider-icon" viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+                        <path fill="currentColor" d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18V4c4.41 0 8 3.59 8 8s-3.59 8-8 8z"/>
+                    </svg>
+                    <span class="display-slider-label" data-i18n="display.contrast">${t('display.contrast')}</span>
+                    <input type="range" class="display-slider display-contrast-slider"
+                           min="0" max="100" value="${contrastValue}"
+                           data-display-slider="contrast" data-monitor-id="${monitor.id}">
+                    <span class="display-slider-value" id="contrast-val-${monitor.id}">${contrastValue}%</span>
+                </div>`;
+            }
+
+            // Build the picture-tuning selects (input source / color preset / picture mode).
+            const tuningRows = [];
+
+            // Each tuning field renders a hidden <select> (state holder)
+            // which IconSelect then enhances after the card lands in the DOM.
+            const tuningTargets = [];
+
+            if (monitor.input_source_supported && monitor.available_input_sources.length > 0) {
+                const current = monitor.input_source;
+                const options = monitor.available_input_sources.map(src => {
+                    const selected = src === current ? 'selected' : '';
+                    return `<option value="${escapeHtml(src)}" ${selected}>${escapeHtml(humanizeInputSource(src))}</option>`;
+                }).join('');
+                tuningRows.push(`
+                <div class="display-tuning-field">
+                    <span class="display-tuning-label" data-i18n="display.input_source">${t('display.input_source')}</span>
+                    <select data-display-select="input" data-monitor-id="${monitor.id}"
+                            aria-label="${t('display.input_source')}">
+                        ${options}
+                    </select>
+                </div>`);
+                tuningTargets.push({
+                    kind: 'input',
+                    monitorId: monitor.id,
+                    items: monitor.available_input_sources.map(src => ({
+                        value: src,
+                        icon: inputSourceIcon(src),
+                        label: humanizeInputSource(src),
+                    })),
+                });
+            }
+
+            if (monitor.color_preset_supported && monitor.available_color_presets.length > 0) {
+                const current = monitor.color_preset;
+                const options = monitor.available_color_presets.map(p => {
+                    const selected = p === current ? 'selected' : '';
+                    return `<option value="${escapeHtml(p)}" ${selected}>${escapeHtml(humanizeColorPreset(p))}</option>`;
+                }).join('');
+                tuningRows.push(`
+                <div class="display-tuning-field">
+                    <span class="display-tuning-label" data-i18n="display.color_preset">${t('display.color_preset')}</span>
+                    <select data-display-select="color" data-monitor-id="${monitor.id}"
+                            aria-label="${t('display.color_preset')}">
+                        ${options}
+                    </select>
+                </div>`);
+                tuningTargets.push({
+                    kind: 'color',
+                    monitorId: monitor.id,
+                    items: monitor.available_color_presets.map(p => ({
+                        value: p,
+                        icon: ICON_THERMOMETER,
+                        label: humanizeColorPreset(p),
+                    })),
+                });
+            }
+
+            if (monitor.picture_mode_supported && monitor.available_picture_modes.length > 0) {
+                const current = monitor.picture_mode_code;
+                const options = monitor.available_picture_modes.map(m => {
+                    const selected = m.code === current ? 'selected' : '';
+                    return `<option value="${m.code}" ${selected}>${escapeHtml(m.label)}</option>`;
+                }).join('');
+                tuningRows.push(`
+                <div class="display-tuning-field">
+                    <span class="display-tuning-label" data-i18n="display.picture_mode">${t('display.picture_mode')}</span>
+                    <select data-display-select="mode" data-monitor-id="${monitor.id}"
+                            aria-label="${t('display.picture_mode')}">
+                        ${options}
+                    </select>
+                </div>`);
+                tuningTargets.push({
+                    kind: 'mode',
+                    monitorId: monitor.id,
+                    items: monitor.available_picture_modes.map(m => ({
+                        value: String(m.code),
+                        icon: pictureModeIcon(m.label),
+                        label: m.label,
+                    })),
+                });
+            }
+
+            pendingIconSelects.push(...tuningTargets);
+
+            const tuningBlock = tuningRows.length > 0
+                ? `<div class="display-tuning">
+                       <div class="display-tuning-title" data-i18n="display.tuning">${t('display.tuning')}</div>
+                       <div class="display-tuning-grid">${tuningRows.join('')}</div>
+                   </div>`
+                : '';
+
+            card.innerHTML = `
+                <div class="display-monitor-header">
+                    <svg class="display-monitor-icon" viewBox="0 0 24 24" width="20" height="20">
+                        <path fill="currentColor" d="M20 3H4c-1.1 0-2 .9-2 2v10c0 1.1.9 2 2 2h6v2H8v2h8v-2h-2v-2h6c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm0 12H4V5h16v10z"/>
+                    </svg>
+                    <div class="display-monitor-info">
+                        <span class="display-monitor-name"><span class="display-monitor-name-text">${escapeHtml(monitor.name)}</span>${primaryBadge}</span>
+                        ${detailsHtml}
+                    </div>
+                    ${powerBtn}
+                </div>
+                <div class="display-slider-row display-brightness-control">
+                    <svg class="display-slider-icon display-brightness-icon" viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+                        <path fill="currentColor" d="M20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12 20 8.69zM12 18c-3.31 0-6-2.69-6-6s2.69-6 6-6 6 2.69 6 6-2.69 6-6 6zm0-10c-2.21 0-4 1.79-4 4s1.79 4 4 4 4-1.79 4-4-1.79-4-4-4z"/>
+                    </svg>
+                    <span class="display-slider-label" data-i18n="display.brightness">${t('display.brightness')}</span>
+                    <input type="range" class="display-slider display-brightness-slider" min="0" max="100" value="${brightnessValue}" ${brightnessDisabled}
+                           data-display-slider="brightness" data-monitor-id="${monitor.id}">
+                    <span class="display-slider-value display-brightness-value" id="brightness-val-${monitor.id}">${brightnessValue}%</span>
+                </div>
+                ${contrastRow}
+                ${tuningBlock}`;
+
+            container.appendChild(card);
+        });
+
+        // Bind a single delegated click handler for the power buttons,
+        // plus input/change handlers for the brightness & contrast sliders.
+        // Avoids inline on* attributes (blocked by script-src 'self' CSP).
+        container.removeEventListener('click', _onPowerButtonClick);
+        container.addEventListener('click', _onPowerButtonClick);
+        container.removeEventListener('input', _onDisplaySliderInput);
+        container.addEventListener('input', _onDisplaySliderInput);
+        container.removeEventListener('change', _onDisplaySliderChange);
+        container.addEventListener('change', _onDisplaySliderChange);
+
+        // Enhance every tuning <select> with an IconSelect now that the
+        // cards are in the DOM (IconSelect needs offsetParent + sibling).
+        pendingIconSelects.forEach(({ kind, monitorId, items }) => {
+            const sel = container.querySelector(
+                `select[data-display-select="${kind}"][data-monitor-id="${monitorId}"]`
+            );
+            if (!sel) return;
+            const handler = kind === 'input' ? onDisplayInputSourceChange
+                : kind === 'color' ? onDisplayColorPresetChange
+                : onDisplayPictureModeChange;
+            _displayIconSelects.push(new IconSelect({
+                target: sel,
+                items,
+                columns: 1,
+                horizontal: true,
+                onChange: (value) => handler(monitorId, value),
+            }));
+        });
+    } catch (e) {
+        console.error('Failed to load display monitors:', e);
+    }
+}
+
+export function onDisplayBrightnessInput(monitorId, value) {
+    const label = document.getElementById(`brightness-val-${monitorId}`);
+    if (label) label.textContent = `${value}%`;
+
+    if (displayBrightnessTimers[monitorId]) clearTimeout(displayBrightnessTimers[monitorId]);
+    displayBrightnessTimers[monitorId] = setTimeout(() => {
+        sendDisplayBrightness(monitorId, parseInt(value));
+        displayBrightnessTimers[monitorId] = null;
+    }, DISPLAY_THROTTLE_MS);
+}
+
+export function onDisplayBrightnessChange(monitorId, value) {
+    if (displayBrightnessTimers[monitorId]) {
+        clearTimeout(displayBrightnessTimers[monitorId]);
+        displayBrightnessTimers[monitorId] = null;
+    }
+    sendDisplayBrightness(monitorId, parseInt(value));
+}
+
+async function sendDisplayBrightness(monitorId, brightness) {
+    try {
+        await fetch(`/api/display/brightness/${monitorId}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify({ brightness })
+        });
+    } catch (e) {
+        console.error('Failed to set brightness:', e);
+    }
+}
+
+export function onDisplayContrastInput(monitorId, value) {
+    const label = document.getElementById(`contrast-val-${monitorId}`);
+    if (label) label.textContent = `${value}%`;
+
+    if (displayContrastTimers[monitorId]) clearTimeout(displayContrastTimers[monitorId]);
+    displayContrastTimers[monitorId] = setTimeout(() => {
+        sendDisplayContrast(monitorId, parseInt(value));
+        displayContrastTimers[monitorId] = null;
+    }, DISPLAY_THROTTLE_MS);
+}
+
+export function onDisplayContrastChange(monitorId, value) {
+    if (displayContrastTimers[monitorId]) {
+        clearTimeout(displayContrastTimers[monitorId]);
+        displayContrastTimers[monitorId] = null;
+    }
+    sendDisplayContrast(monitorId, parseInt(value));
+}
+
+async function sendDisplayContrast(monitorId, contrast) {
+    try {
+        const r = await fetch(`/api/display/contrast/${monitorId}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify({ contrast })
+        });
+        const data = await r.json().catch(() => ({}));
+        if (!data.success) showToast(t('display.msg.contrast_failed'), 'error');
+    } catch (e) {
+        console.error('Failed to set contrast:', e);
+        showToast(t('display.msg.contrast_failed'), 'error');
+    }
+}
+
+export async function onDisplayInputSourceChange(monitorId, source) {
+    try {
+        const r = await fetch(`/api/display/input_source/${monitorId}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify({ source })
+        });
+        const data = await r.json().catch(() => ({}));
+        if (data.success) showToast(t('display.msg.input_changed'), 'success');
+        else showToast(t('display.msg.input_failed'), 'error');
+    } catch (e) {
+        console.error('Failed to set input source:', e);
+        showToast(t('display.msg.input_failed'), 'error');
+    }
+}
+
+export async function onDisplayColorPresetChange(monitorId, preset) {
+    try {
+        const r = await fetch(`/api/display/color_preset/${monitorId}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify({ preset })
+        });
+        const data = await r.json().catch(() => ({}));
+        if (data.success) showToast(t('display.msg.color_changed'), 'success');
+        else showToast(t('display.msg.color_failed'), 'error');
+    } catch (e) {
+        console.error('Failed to set color preset:', e);
+        showToast(t('display.msg.color_failed'), 'error');
+    }
+}
+
+export async function onDisplayPictureModeChange(monitorId, codeRaw) {
+    const code = parseInt(codeRaw, 10);
+    if (Number.isNaN(code)) return;
+    try {
+        const r = await fetch(`/api/display/picture_mode/${monitorId}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify({ code })
+        });
+        const data = await r.json().catch(() => ({}));
+        if (data.success) showToast(t('display.msg.mode_changed'), 'success');
+        else showToast(t('display.msg.mode_failed'), 'error');
+    } catch (e) {
+        console.error('Failed to set picture mode:', e);
+        showToast(t('display.msg.mode_failed'), 'error');
+    }
+}
+
+function _onPowerButtonClick(event) {
+    const btn = event.target.closest('[data-action="toggle-power"]');
+    if (!btn) return;
+    const id = Number(btn.dataset.monitorId);
+    if (Number.isFinite(id)) toggleDisplayPower(id);
+}
+
+function _onDisplaySliderInput(event) {
+    const el = event.target.closest('input[data-display-slider]');
+    if (!el) return;
+    const id = Number(el.dataset.monitorId);
+    if (!Number.isFinite(id)) return;
+    if (el.dataset.displaySlider === 'brightness') {
+        onDisplayBrightnessInput(id, el.value);
+    } else if (el.dataset.displaySlider === 'contrast') {
+        onDisplayContrastInput(id, el.value);
+    }
+}
+
+function _onDisplaySliderChange(event) {
+    const el = event.target.closest('input[data-display-slider]');
+    if (!el) return;
+    const id = Number(el.dataset.monitorId);
+    if (!Number.isFinite(id)) return;
+    if (el.dataset.displaySlider === 'brightness') {
+        onDisplayBrightnessChange(id, el.value);
+    } else if (el.dataset.displaySlider === 'contrast') {
+        onDisplayContrastChange(id, el.value);
+    }
+}
+
+export async function toggleDisplayPower(monitorId) {
+    const btn = document.getElementById(`power-btn-${monitorId}`);
+    const isOn = btn && btn.classList.contains('on');
+    const newState = !isOn;
+
+    try {
+        const response = await fetch(`/api/display/power/${monitorId}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify({ on: newState })
+        });
+        const data = await response.json();
+        if (data.success) {
+            if (btn) {
+                btn.classList.toggle('on', newState);
+                btn.classList.toggle('off', !newState);
+                btn.title = newState ? t('display.power_off') : t('display.power_on');
+            }
+            showToast(t(newState ? 'display.msg.power_on' : 'display.msg.power_off'), 'success');
+        } else {
+            showToast(t('display.msg.power_failed'), 'error');
+        }
+    } catch (e) {
+        console.error('Failed to set display power:', e);
+        showToast(t('display.msg.power_failed'), 'error');
+    }
+}
+
+// ============================================================
+// Header Quick Links
+// ============================================================
+
+export async function loadHeaderLinks() {
+    if (!hasCredentials()) return;
+
+    const container = document.getElementById('headerLinks');
+    if (!container) return;
+
+    try {
+        const response = await fetch('/api/links/list', {
+            headers: getAuthHeaders()
+        });
+
+        if (!response.ok) return;
+
+        const links = await response.json();
+        container.innerHTML = '';
+
+        for (const link of links) {
+            const a = document.createElement('a');
+            a.href = link.url;
+            a.target = '_blank';
+            a.rel = 'noopener noreferrer';
+            // Prevent leaking the WebUI URL (with ?token=) via Referer.
+            a.referrerPolicy = 'no-referrer';
+            a.className = 'header-link';
+            a.title = link.label || link.url;
+
+            const iconSvg = await fetchMdiIcon(link.icon || 'mdi:link');
+            a.innerHTML = iconSvg;
+
+            container.appendChild(a);
+        }
+    } catch (e) {
+        console.warn('Failed to load header links:', e);
+    }
+}
+
+// ============================================================
+// Links Management
+// ============================================================
+
+let _loadLinksPromise = null;
+export let linkFormDirty = false;
+export function setLinkFormDirty(value) { linkFormDirty = value; }
+
+export async function loadLinksTable() {
+    if (_loadLinksPromise) return _loadLinksPromise;
+    _loadLinksPromise = _loadLinksTableImpl();
+    _loadLinksPromise.finally(() => { _loadLinksPromise = null; });
+    return _loadLinksPromise;
+}
+
+async function _loadLinksTableImpl() {
+    const tbody = document.getElementById('linksTableBody');
+
+    try {
+        const response = await fetch('/api/links/list', {
+            headers: getAuthHeaders()
+        });
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch links');
+        }
+
+        const linksList = await response.json();
+
+        if (linksList.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="4" class="empty-state"><div class="empty-state-illustration"><svg viewBox="0 0 64 64"><path d="M26 20a10 10 0 010 14l-6 6a10 10 0 01-14-14l6-6a10 10 0 0114 0" fill="none" stroke="currentColor" stroke-width="2"/><path d="M38 44a10 10 0 010-14l6-6a10 10 0 0114 14l-6 6a10 10 0 01-14 0" fill="none" stroke="currentColor" stroke-width="2"/><path d="M24 40l16-16" stroke="currentColor" stroke-width="2"/></svg><p>' + t('links.empty') + '</p></div></td></tr>';
+            return;
+        }
+
+        tbody.innerHTML = linksList.map(link => `
+            <tr>
+                <td><span class="name-with-icon"><span class="table-icon" data-mdi-icon="${escapeHtml(link.icon || 'mdi:link')}"></span><code>${escapeHtml(link.name)}</code></span></td>
+                <td style="max-width: 200px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;"
+                    title="${escapeHtml(link.url)}">${escapeHtml(link.url)}</td>
+                <td>${escapeHtml(link.label || '')}</td>
+                <td>
+                    <div class="action-buttons">
+                        <button class="action-btn" data-action="edit" data-link-name="${escapeHtml(link.name)}" title="${t('links.button.edit')}">
+                            <svg viewBox="0 0 24 24"><path d="M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25zM20.71 7.04c.39-.39.39-1.02 0-1.41l-2.34-2.34c-.39-.39-1.02-.39-1.41 0l-1.83 1.83 3.75 3.75 1.83-1.83z"/></svg>
+                        </button>
+                        <button class="action-btn delete" data-action="delete" data-link-name="${escapeHtml(link.name)}" title="${t('links.button.delete')}">
+                            <svg viewBox="0 0 24 24"><path d="M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6v12zM19 4h-3.5l-1-1h-5l-1 1H5v2h14V4z"/></svg>
+                        </button>
+                    </div>
+                </td>
+            </tr>
+        `).join('');
+        resolveMdiIcons(tbody);
+    } catch (error) {
+        console.error('Error loading links:', error);
+        tbody.innerHTML = `<tr><td colspan="4" class="empty-state" style="color: var(--error);">${escapeHtml(t('links.msg.load_failed'))}</td></tr>`;
+    }
+}
+
+export function showAddLinkDialog() {
+    const dialog = document.getElementById('linkDialog');
+    const form = document.getElementById('linkForm');
+    const title = document.getElementById('linkDialogTitle');
+
+    form.reset();
+    document.getElementById('linkOriginalName').value = '';
+    document.getElementById('linkIsEdit').value = 'false';
+    document.getElementById('linkName').disabled = false;
+    document.getElementById('linkIconPreview').innerHTML = '';
+    title.textContent = t('links.dialog.add');
+
+    linkFormDirty = false;
+
+    document.body.classList.add('dialog-open');
+    dialog.showModal();
+}
+
+export async function showEditLinkDialog(linkName) {
+    const dialog = document.getElementById('linkDialog');
+    const title = document.getElementById('linkDialogTitle');
+
+    try {
+        const response = await fetch('/api/links/list', {
+            headers: getAuthHeaders()
+        });
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch link details');
+        }
+
+        const linksList = await response.json();
+        const link = linksList.find(l => l.name === linkName);
+
+        if (!link) {
+            showToast(t('links.msg.not_found'), 'error');
+            return;
+        }
+
+        document.getElementById('linkOriginalName').value = linkName;
+        document.getElementById('linkIsEdit').value = 'true';
+        document.getElementById('linkName').value = linkName;
+        document.getElementById('linkName').disabled = true;
+        document.getElementById('linkUrl').value = link.url;
+        document.getElementById('linkIcon').value = link.icon || '';
+        document.getElementById('linkLabel').value = link.label || '';
+        document.getElementById('linkDescription').value = link.description || '';
+
+        // Update icon preview
+        const preview = document.getElementById('linkIconPreview');
+        if (link.icon) {
+            fetchMdiIcon(link.icon).then(svg => { preview.innerHTML = svg; });
+        } else {
+            preview.innerHTML = '';
+        }
+
+        title.textContent = t('links.dialog.edit');
+
+        linkFormDirty = false;
+
+        document.body.classList.add('dialog-open');
+        dialog.showModal();
+    } catch (error) {
+        console.error('Error loading link for edit:', error);
+        showToast(t('links.msg.load_failed'), 'error');
+    }
+}
+
+export async function closeLinkDialog() {
+    if (linkFormDirty) {
+        if (!await showConfirm(t('links.confirm.unsaved'))) {
+            return;
+        }
+    }
+
+    const dialog = document.getElementById('linkDialog');
+    linkFormDirty = false;
+    closeDialog(dialog);
+    document.body.classList.remove('dialog-open');
+}
+
+export async function saveLink(event) {
+    event.preventDefault();
+
+    const submitBtn = event.target.querySelector('button[type="submit"]');
+    if (submitBtn) submitBtn.disabled = true;
+
+    const isEdit = document.getElementById('linkIsEdit').value === 'true';
+    const linkName = isEdit ?
+        document.getElementById('linkOriginalName').value :
+        document.getElementById('linkName').value;
+
+    const data = {
+        url: document.getElementById('linkUrl').value,
+        icon: document.getElementById('linkIcon').value || 'mdi:link',
+        label: document.getElementById('linkLabel').value || '',
+        description: document.getElementById('linkDescription').value || ''
+    };
+
+    const encodedName = encodeURIComponent(linkName);
+    const endpoint = isEdit ?
+        `/api/links/update/${encodedName}` :
+        `/api/links/create/${encodedName}`;
+
+    const method = isEdit ? 'PUT' : 'POST';
+
+    try {
+        const response = await fetch(endpoint, {
+            method,
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify(data)
+        });
+
+        const result = await response.json();
+
+        if (response.ok && result.success) {
+            showToast(t(isEdit ? 'links.msg.updated' : 'links.msg.created'), 'success');
+            linkFormDirty = false;
+            closeLinkDialog();
+        } else {
+            showToast(result.detail || t(isEdit ? 'links.msg.update_failed' : 'links.msg.create_failed'), 'error');
+        }
+    } catch (error) {
+        console.error('Error saving link:', error);
+        showToast(t(isEdit ? 'links.msg.update_failed' : 'links.msg.create_failed'), 'error');
+    } finally {
+        if (submitBtn) submitBtn.disabled = false;
+    }
+}
+
+export async function deleteLinkConfirm(linkName) {
+    if (!await showConfirm(t('links.confirm.delete').replace('{name}', linkName))) {
+        return;
+    }
+
+    try {
+        const response = await fetch(`/api/links/delete/${encodeURIComponent(linkName)}`, {
+            method: 'DELETE',
+            headers: getAuthHeaders()
+        });
+
+        const result = await response.json();
+
+        if (response.ok && result.success) {
+            showToast(t('links.msg.deleted'), 'success');
+        } else {
+            showToast(result.detail || t('links.msg.delete_failed'), 'error');
+        }
+    } catch (error) {
+        console.error('Error deleting link:', error);
+        showToast(t('links.msg.delete_failed'), 'error');
+    }
+}

media_server/static/js/scripts.js

@@ -0,0 +1,859 @@
+// ============================================================
+// Scripts: CRUD, quick access, execution dialog
+// ============================================================
+
+import {
+    t, showToast, escapeHtml, closeDialog, showConfirm,
+    resolveMdiIcons, fetchMdiIcon,
+    scripts, setScripts,
+    getAuthHeaders, hasCredentials,
+} from './core.js';
+import { IconSelect } from './icon-select.js';
+import { paramTypeIcons } from './icons.js';
+
+export let scriptFormDirty = false;
+export function setScriptFormDirty(value) { scriptFormDirty = value; }
+
+export async function loadScripts() {
+    try {
+        const response = await fetch('/api/scripts/list', {
+            headers: getAuthHeaders()
+        });
+
+        if (response.ok) {
+            setScripts(await response.json());
+            displayQuickAccess();
+        }
+    } catch (error) {
+        console.error('Error loading scripts:', error);
+    }
+}
+
+let _quickAccessGen = 0;
+export async function displayQuickAccess() {
+    const gen = ++_quickAccessGen;
+    const grid = document.getElementById('scripts-grid');
+
+    const fragment = document.createDocumentFragment();
+    const hasScripts = scripts.length > 0;
+    let hasLinks = false;
+
+    scripts.forEach(script => {
+        const button = document.createElement('button');
+        button.className = 'script-btn';
+        button.onclick = () => executeScript(script.name, button);
+
+        if (script.icon) {
+            const iconEl = document.createElement('div');
+            iconEl.className = 'script-icon';
+            iconEl.setAttribute('data-mdi-icon', script.icon);
+            button.appendChild(iconEl);
+        }
+
+        const label = document.createElement('div');
+        label.className = 'script-label';
+        label.textContent = script.label || script.name;
+        button.appendChild(label);
+
+        if (script.description) {
+            const description = document.createElement('div');
+            description.className = 'script-description';
+            description.textContent = script.description;
+            button.appendChild(description);
+        }
+
+        fragment.appendChild(button);
+    });
+
+    try {
+        if (hasCredentials()) {
+            const response = await fetch('/api/links/list', {
+                headers: getAuthHeaders()
+            });
+            if (gen !== _quickAccessGen) return;
+            if (response.ok) {
+                const links = await response.json();
+                hasLinks = links.length > 0;
+                links.forEach(link => {
+                    const card = document.createElement('a');
+                    card.className = 'script-btn link-card';
+                    card.href = link.url;
+                    card.target = '_blank';
+                    card.rel = 'noopener noreferrer';
+                    // Prevent the WebUI's URL (which may carry ?token=...) from
+                    // leaking to third-party sites via Referer.
+                    card.referrerPolicy = 'no-referrer';
+
+                    if (link.icon) {
+                        const iconEl = document.createElement('div');
+                        iconEl.className = 'script-icon';
+                        iconEl.setAttribute('data-mdi-icon', link.icon);
+                        card.appendChild(iconEl);
+                    }
+
+                    const label = document.createElement('div');
+                    label.className = 'script-label';
+                    label.textContent = link.label || link.name;
+                    card.appendChild(label);
+
+                    if (link.description) {
+                        const desc = document.createElement('div');
+                        desc.className = 'script-description';
+                        desc.textContent = link.description;
+                        card.appendChild(desc);
+                    }
+
+                    fragment.appendChild(card);
+                });
+            }
+        }
+    } catch (e) {
+        if (gen !== _quickAccessGen) return;
+        console.warn('Failed to load links for quick access:', e);
+    }
+
+    if (!hasScripts && !hasLinks) {
+        const empty = document.createElement('div');
+        empty.className = 'scripts-empty empty-state-illustration';
+        empty.innerHTML = `<svg viewBox="0 0 64 64"><path d="M20 8l-8 48"/><path d="M44 8l8 48"/><path d="M10 24h44"/><path d="M8 40h44"/></svg><p>${t('quick_access.no_items')}</p>`;
+        fragment.prepend(empty);
+    }
+
+    grid.innerHTML = '';
+    grid.appendChild(fragment);
+    resolveMdiIcons(grid);
+}
+
+function _getScriptParams(scriptName) {
+    const script = scripts.find(s => s.name === scriptName);
+    return (script && script.parameters) ? script.parameters : {};
+}
+
+async function executeScript(scriptName, buttonElement) {
+    const paramDefs = _getScriptParams(scriptName);
+    if (Object.keys(paramDefs).length > 0) {
+        _showParamsInputDialog(scriptName, paramDefs, async (params) => {
+            buttonElement.classList.add('executing');
+            try {
+                await _doExecuteScript(scriptName, params);
+            } finally {
+                buttonElement.classList.remove('executing');
+            }
+        });
+        return;
+    }
+
+    buttonElement.classList.add('executing');
+    try {
+        await _doExecuteScript(scriptName, {});
+    } finally {
+        buttonElement.classList.remove('executing');
+    }
+}
+
+async function _doExecuteScript(scriptName, params) {
+    try {
+        const response = await fetch(`/api/scripts/execute/${encodeURIComponent(scriptName)}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify({ params })
+        });
+
+        const result = await response.json();
+
+        if (response.ok && result.success) {
+            showToast(t('scripts.msg.executed', { name: scriptName }), 'success');
+        } else {
+            showToast(result.detail || t('scripts.msg.execute_failed', { name: scriptName }), 'error');
+        }
+    } catch (error) {
+        console.error(`Error executing script ${scriptName}:`, error);
+        showToast(t('scripts.msg.execute_error', { name: scriptName }), 'error');
+    }
+}
+
+// ============================================================
+// Script Parameters Input Dialog (execution-time)
+// ============================================================
+
+let _paramsCallback = null;
+let _paramsScriptName = null;
+let _paramsIconSelects = null;
+
+function _showParamsInputDialog(scriptName, paramDefs, callback) {
+    _paramsCallback = callback;
+    _paramsScriptName = scriptName;
+
+    const dialog = document.getElementById('scriptParamsDialog');
+    const title = document.getElementById('scriptParamsDialogTitle');
+    const container = document.getElementById('scriptParamsInputs');
+
+    const script = scripts.find(s => s.name === scriptName);
+    title.textContent = script ? (script.label || scriptName) : scriptName;
+    container.innerHTML = '';
+
+    // Track IconSelect instances for cleanup
+    if (!_paramsIconSelects) _paramsIconSelects = [];
+
+    for (const [pname, pdef] of Object.entries(paramDefs)) {
+        const wrapper = document.createElement('label');
+
+        const labelText = document.createElement('span');
+        labelText.textContent = pname + (pdef.required ? ' *' : '');
+        wrapper.appendChild(labelText);
+
+        if (pdef.description) {
+            const hint = document.createElement('small');
+            hint.className = 'param-hint';
+            hint.textContent = pdef.description;
+            wrapper.appendChild(hint);
+        }
+
+        let input;
+        if (pdef.type === 'select' && pdef.options) {
+            input = document.createElement('select');
+            if (!pdef.required) {
+                const opt = document.createElement('option');
+                opt.value = '';
+                opt.textContent = '—';
+                input.appendChild(opt);
+            }
+            for (const optVal of pdef.options) {
+                const opt = document.createElement('option');
+                opt.value = optVal;
+                opt.textContent = optVal;
+                if (pdef.default !== undefined && pdef.default !== null && String(pdef.default) === optVal) {
+                    opt.selected = true;
+                }
+                input.appendChild(opt);
+            }
+            input.dataset.paramName = pname;
+            input.dataset.paramType = pdef.type;
+            if (pdef.required) input.required = true;
+            wrapper.appendChild(input);
+
+            // Enhance with icon grid if few options
+            if (pdef.options.length <= 10) {
+                const selItems = pdef.options.map(o => ({ value: o, icon: '', label: o }));
+                const cols = Math.min(pdef.options.length, 4);
+                const isel = new IconSelect({ target: input, items: selItems, columns: cols });
+                _paramsIconSelects.push(isel);
+            }
+        } else if (pdef.type === 'boolean') {
+            const boolSvgTrue = '<svg viewBox="0 0 24 24" fill="currentColor"><path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/></svg>';
+            const boolSvgFalse = '<svg viewBox="0 0 24 24" fill="currentColor"><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>';
+
+            input = document.createElement('select');
+            const optTrue = document.createElement('option');
+            optTrue.value = 'true';
+            optTrue.textContent = 'true';
+            const optFalse = document.createElement('option');
+            optFalse.value = 'false';
+            optFalse.textContent = 'false';
+            input.appendChild(optTrue);
+            input.appendChild(optFalse);
+            if (pdef.default !== undefined && pdef.default !== null) {
+                input.value = String(pdef.default);
+            }
+            input.dataset.paramName = pname;
+            input.dataset.paramType = pdef.type;
+            if (pdef.required) input.required = true;
+            wrapper.appendChild(input);
+
+            // Enhance with icon grid
+            const isel = new IconSelect({
+                target: input,
+                items: [
+                    { value: 'true', icon: boolSvgTrue, label: 'True' },
+                    { value: 'false', icon: boolSvgFalse, label: 'False' },
+                ],
+                columns: 2,
+            });
+            _paramsIconSelects.push(isel);
+        } else if (pdef.type === 'integer' || pdef.type === 'float') {
+            input = document.createElement('input');
+            input.type = 'number';
+            if (pdef.type === 'float') input.step = 'any';
+            if (pdef.min !== undefined && pdef.min !== null) input.min = pdef.min;
+            if (pdef.max !== undefined && pdef.max !== null) input.max = pdef.max;
+            if (pdef.default !== undefined && pdef.default !== null) input.value = pdef.default;
+            input.dataset.paramName = pname;
+            input.dataset.paramType = pdef.type;
+            if (pdef.required) input.required = true;
+            wrapper.appendChild(input);
+        } else {
+            input = document.createElement('input');
+            input.type = 'text';
+            if (pdef.default !== undefined && pdef.default !== null) input.value = pdef.default;
+            input.dataset.paramName = pname;
+            input.dataset.paramType = pdef.type;
+            if (pdef.required) input.required = true;
+            wrapper.appendChild(input);
+        }
+
+        container.appendChild(wrapper);
+    }
+
+    document.body.classList.add('dialog-open');
+    dialog.showModal();
+}
+
+export function closeScriptParamsDialog() {
+    const dialog = document.getElementById('scriptParamsDialog');
+    _paramsCallback = null;
+    _paramsScriptName = null;
+    // Destroy icon selects from execution dialog
+    if (_paramsIconSelects) {
+        _paramsIconSelects.forEach(isel => isel.destroy());
+        _paramsIconSelects = null;
+    }
+    closeDialog(dialog);
+    document.body.classList.remove('dialog-open');
+}
+
+export async function submitScriptWithParams(event) {
+    event.preventDefault();
+    const container = document.getElementById('scriptParamsInputs');
+    const inputs = container.querySelectorAll('[data-param-name]');
+    const params = {};
+
+    for (const input of inputs) {
+        const name = input.dataset.paramName;
+        const type = input.dataset.paramType;
+        let val = input.value;
+
+        if (val === '' && !input.required) continue;
+        if (val === '') continue;
+
+        if (type === 'integer') val = parseInt(val, 10);
+        else if (type === 'float') val = parseFloat(val);
+        else if (type === 'boolean') val = val === 'true';
+
+        params[name] = val;
+    }
+
+    const callback = _paramsCallback;
+    closeScriptParamsDialog();
+
+    if (callback) {
+        await callback(params);
+    }
+}
+
+// ============================================================
+// Script Management CRUD
+// ============================================================
+
+let _loadScriptsPromise = null;
+export async function loadScriptsTable() {
+    if (_loadScriptsPromise) return _loadScriptsPromise;
+    _loadScriptsPromise = _loadScriptsTableImpl();
+    _loadScriptsPromise.finally(() => { _loadScriptsPromise = null; });
+    return _loadScriptsPromise;
+}
+
+async function _loadScriptsTableImpl() {
+    const tbody = document.getElementById('scriptsTableBody');
+
+    try {
+        const response = await fetch('/api/scripts/list', {
+            headers: getAuthHeaders()
+        });
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch scripts');
+        }
+
+        const scriptsList = await response.json();
+
+        if (scriptsList.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="5" class="empty-state"><div class="empty-state-illustration"><svg viewBox="0 0 64 64"><rect x="8" y="4" width="48" height="56" rx="4"/><path d="M20 20h24M20 32h16M20 44h20"/></svg><p>' + t('scripts.empty') + '</p></div></td></tr>';
+            return;
+        }
+
+        tbody.innerHTML = scriptsList.map(script => `
+            <tr>
+                <td><span class="name-with-icon">${script.icon ? `<span class="table-icon" data-mdi-icon="${escapeHtml(script.icon)}"></span>` : ''}<code>${escapeHtml(script.name)}</code></span></td>
+                <td>${escapeHtml(script.label || script.name)}</td>
+                <td style="max-width: 200px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;"
+                    title="${escapeHtml(script.command || 'N/A')}">${escapeHtml(script.command || 'N/A')}</td>
+                <td>${script.timeout}s</td>
+                <td>
+                    <div class="action-buttons">
+                        <button class="action-btn execute" data-action="execute" data-script-name="${escapeHtml(script.name)}" title="Execute script">
+                            <svg viewBox="0 0 24 24"><path d="M8 5v14l11-7z"/></svg>
+                        </button>
+                        <button class="action-btn" data-action="edit" data-script-name="${escapeHtml(script.name)}" title="Edit script">
+                            <svg viewBox="0 0 24 24"><path d="M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25zM20.71 7.04c.39-.39.39-1.02 0-1.41l-2.34-2.34c-.39-.39-1.02-.39-1.41 0l-1.83 1.83 3.75 3.75 1.83-1.83z"/></svg>
+                        </button>
+                        <button class="action-btn delete" data-action="delete" data-script-name="${escapeHtml(script.name)}" title="Delete script">
+                            <svg viewBox="0 0 24 24"><path d="M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6v12zM19 4h-3.5l-1-1h-5l-1 1H5v2h14V4z"/></svg>
+                        </button>
+                    </div>
+                </td>
+            </tr>
+        `).join('');
+        resolveMdiIcons(tbody);
+    } catch (error) {
+        console.error('Error loading scripts:', error);
+        tbody.innerHTML = `<tr><td colspan="5" class="empty-state" style="color: var(--error);">${escapeHtml(t('scripts.msg.load_failed'))}</td></tr>`;
+    }
+}
+
+export function showAddScriptDialog() {
+    const dialog = document.getElementById('scriptDialog');
+    const form = document.getElementById('scriptForm');
+    const title = document.getElementById('dialogTitle');
+
+    form.reset();
+    document.getElementById('scriptOriginalName').value = '';
+    document.getElementById('scriptIsEdit').value = 'false';
+    document.getElementById('scriptName').disabled = false;
+    document.getElementById('scriptIconPreview').innerHTML = '';
+    document.getElementById('scriptParamsContainer').innerHTML = '';
+    title.textContent = t('scripts.dialog.add');
+
+    scriptFormDirty = false;
+
+    document.body.classList.add('dialog-open');
+    dialog.showModal();
+}
+
+export async function showEditScriptDialog(scriptName) {
+    const dialog = document.getElementById('scriptDialog');
+    const title = document.getElementById('dialogTitle');
+
+    try {
+        const response = await fetch('/api/scripts/list', {
+            headers: getAuthHeaders()
+        });
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch script details');
+        }
+
+        const scriptsList = await response.json();
+        const script = scriptsList.find(s => s.name === scriptName);
+
+        if (!script) {
+            showToast(t('scripts.msg.not_found'), 'error');
+            return;
+        }
+
+        document.getElementById('scriptOriginalName').value = scriptName;
+        document.getElementById('scriptIsEdit').value = 'true';
+        document.getElementById('scriptName').value = scriptName;
+        document.getElementById('scriptName').disabled = true;
+        document.getElementById('scriptLabel').value = script.label || '';
+        document.getElementById('scriptCommand').value = script.command || '';
+        document.getElementById('scriptDescription').value = script.description || '';
+        document.getElementById('scriptIcon').value = script.icon || '';
+        document.getElementById('scriptTimeout').value = script.timeout || 30;
+
+        const preview = document.getElementById('scriptIconPreview');
+        if (script.icon) {
+            fetchMdiIcon(script.icon).then(svg => { preview.innerHTML = svg; });
+        } else {
+            preview.innerHTML = '';
+        }
+
+        // Populate parameters
+        const paramsContainer = document.getElementById('scriptParamsContainer');
+        paramsContainer.innerHTML = '';
+        if (script.parameters) {
+            for (const [pname, pdef] of Object.entries(script.parameters)) {
+                _addParameterRowWithData(pname, pdef);
+            }
+        }
+
+        title.textContent = t('scripts.dialog.edit');
+        scriptFormDirty = false;
+
+        document.body.classList.add('dialog-open');
+        dialog.showModal();
+    } catch (error) {
+        console.error('Error loading script for edit:', error);
+        showToast(t('scripts.msg.load_failed'), 'error');
+    }
+}
+
+export async function closeScriptDialog() {
+    if (scriptFormDirty) {
+        if (!await showConfirm(t('scripts.confirm.unsaved'))) {
+            return;
+        }
+    }
+
+    const dialog = document.getElementById('scriptDialog');
+    scriptFormDirty = false;
+    closeDialog(dialog);
+    document.body.classList.remove('dialog-open');
+}
+
+export async function saveScript(event) {
+    event.preventDefault();
+
+    const submitBtn = event.target.querySelector('button[type="submit"]');
+    if (submitBtn) submitBtn.disabled = true;
+
+    const isEdit = document.getElementById('scriptIsEdit').value === 'true';
+    const scriptName = isEdit ?
+        document.getElementById('scriptOriginalName').value :
+        document.getElementById('scriptName').value;
+
+    const data = {
+        command: document.getElementById('scriptCommand').value,
+        label: document.getElementById('scriptLabel').value || null,
+        description: document.getElementById('scriptDescription').value || '',
+        icon: document.getElementById('scriptIcon').value || null,
+        timeout: parseInt(document.getElementById('scriptTimeout').value) || 30,
+        shell: true,
+        parameters: _collectParameterDefinitions(),
+    };
+
+    const encodedName = encodeURIComponent(scriptName);
+    const endpoint = isEdit ?
+        `/api/scripts/update/${encodedName}` :
+        `/api/scripts/create/${encodedName}`;
+
+    const method = isEdit ? 'PUT' : 'POST';
+
+    try {
+        const response = await fetch(endpoint, {
+            method,
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify(data)
+        });
+
+        const result = await response.json();
+
+        if (response.ok && result.success) {
+            showToast(t(isEdit ? 'scripts.msg.updated' : 'scripts.msg.created'), 'success');
+            scriptFormDirty = false;
+            closeScriptDialog();
+        } else {
+            showToast(result.detail || t(isEdit ? 'scripts.msg.update_failed' : 'scripts.msg.create_failed'), 'error');
+        }
+    } catch (error) {
+        console.error('Error saving script:', error);
+        showToast(t(isEdit ? 'scripts.msg.update_failed' : 'scripts.msg.create_failed'), 'error');
+    } finally {
+        if (submitBtn) submitBtn.disabled = false;
+    }
+}
+
+export async function deleteScriptConfirm(scriptName) {
+    if (!await showConfirm(t('scripts.confirm.delete').replace('{name}', scriptName))) {
+        return;
+    }
+
+    try {
+        const response = await fetch(`/api/scripts/delete/${encodeURIComponent(scriptName)}`, {
+            method: 'DELETE',
+            headers: getAuthHeaders()
+        });
+
+        const result = await response.json();
+
+        if (response.ok && result.success) {
+            showToast(t('scripts.msg.deleted'), 'success');
+        } else {
+            showToast(result.detail || t('scripts.msg.delete_failed'), 'error');
+        }
+    } catch (error) {
+        console.error('Error deleting script:', error);
+        showToast(t('scripts.msg.delete_failed'), 'error');
+    }
+}
+
+// ============================================================
+// Execution Result Dialog (shared by scripts and callbacks)
+// ============================================================
+
+export function closeExecutionDialog() {
+    const dialog = document.getElementById('executionDialog');
+    closeDialog(dialog);
+    document.body.classList.remove('dialog-open');
+}
+
+function showExecutionResult(name, result, type = 'script') {
+    const dialog = document.getElementById('executionDialog');
+    const title = document.getElementById('executionDialogTitle');
+    const statusDiv = document.getElementById('executionStatus');
+    const outputSection = document.getElementById('outputSection');
+    const errorSection = document.getElementById('errorSection');
+    const outputPre = document.getElementById('executionOutput');
+    const errorPre = document.getElementById('executionError');
+
+    title.textContent = `${t('execution.result')}: ${name}`;
+
+    const success = result.success && result.exit_code === 0;
+    const statusClass = success ? 'success' : 'error';
+    const statusText = t(success ? 'execution.success' : 'execution.failed');
+
+    statusDiv.innerHTML = `
+        <div class="status-item ${statusClass}">
+            <label>${escapeHtml(t('execution.status'))}</label>
+            <value>${escapeHtml(statusText)}</value>
+        </div>
+        <div class="status-item">
+            <label>${escapeHtml(t('execution.exit_code'))}</label>
+            <value>${result.exit_code !== undefined ? result.exit_code : 'N/A'}</value>
+        </div>
+        <div class="status-item">
+            <label>${escapeHtml(t('execution.duration'))}</label>
+            <value>${result.execution_time !== undefined && result.execution_time !== null ? result.execution_time.toFixed(3) + 's' : 'N/A'}</value>
+        </div>
+    `;
+
+    outputSection.style.display = 'block';
+    if (result.stdout && result.stdout.trim()) {
+        outputPre.textContent = result.stdout;
+    } else {
+        outputPre.textContent = t('execution.no_output');
+        outputPre.style.fontStyle = 'italic';
+        outputPre.style.color = 'var(--text-secondary)';
+    }
+
+    if (result.stderr && result.stderr.trim()) {
+        errorSection.style.display = 'block';
+        errorPre.textContent = result.stderr;
+        errorPre.style.fontStyle = 'normal';
+        errorPre.style.color = 'var(--error)';
+    } else if (!success && result.error) {
+        errorSection.style.display = 'block';
+        errorPre.textContent = result.error;
+        errorPre.style.fontStyle = 'normal';
+        errorPre.style.color = 'var(--error)';
+    } else {
+        errorSection.style.display = 'none';
+    }
+
+    dialog.showModal();
+}
+
+export async function executeScriptDebug(scriptName) {
+    const paramDefs = _getScriptParams(scriptName);
+    if (Object.keys(paramDefs).length > 0) {
+        _showParamsInputDialog(scriptName, paramDefs, (params) => _executeScriptDebugWithParams(scriptName, params));
+        return;
+    }
+    await _executeScriptDebugWithParams(scriptName, {});
+}
+
+async function _executeScriptDebugWithParams(scriptName, params) {
+    const dialog = document.getElementById('executionDialog');
+    const title = document.getElementById('executionDialogTitle');
+    const statusDiv = document.getElementById('executionStatus');
+
+    title.textContent = `${t('execution.executing')}: ${scriptName}`;
+    statusDiv.innerHTML = `
+        <div class="status-item">
+            <label>${escapeHtml(t('execution.status'))}</label>
+            <value><span class="loading-spinner"></span> ${escapeHtml(t('execution.running'))}</value>
+        </div>
+    `;
+    document.getElementById('outputSection').style.display = 'none';
+    document.getElementById('errorSection').style.display = 'none';
+    document.body.classList.add('dialog-open');
+    dialog.showModal();
+
+    try {
+        const response = await fetch(`/api/scripts/execute/${scriptName}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+            body: JSON.stringify({ params })
+        });
+
+        const result = await response.json();
+
+        if (response.ok) {
+            showExecutionResult(scriptName, result, 'script');
+        } else {
+            showExecutionResult(scriptName, {
+                success: false,
+                exit_code: -1,
+                error: result.detail || 'Execution failed',
+                stderr: result.detail || 'Unknown error'
+            }, 'script');
+        }
+    } catch (error) {
+        console.error(`Error executing script ${scriptName}:`, error);
+        showExecutionResult(scriptName, {
+            success: false,
+            exit_code: -1,
+            error: error.message,
+            stderr: `Network error: ${error.message}`
+        }, 'script');
+    }
+}
+
+// ============================================================
+// Parameter Definition Editor (CRUD dialog)
+// ============================================================
+
+const PARAM_TYPES = ['string', 'integer', 'float', 'boolean', 'select'];
+
+export function addParameterRow() {
+    _addParameterRowWithData('', {});
+    scriptFormDirty = true;
+}
+
+const _paramTypeItems = PARAM_TYPES.map(pt => ({
+    value: pt,
+    icon: paramTypeIcons[pt] || '',
+    label: pt.charAt(0).toUpperCase() + pt.slice(1),
+}));
+
+function _addParameterRowWithData(name, def) {
+    const container = document.getElementById('scriptParamsContainer');
+    const row = document.createElement('div');
+    row.className = 'param-row';
+
+    row.innerHTML = `
+        <div class="param-row-header">
+            <input type="text" class="param-name" value="${escapeHtml(name)}"
+                   placeholder="${t('scripts.params.name_placeholder')}" pattern="[a-zA-Z][a-zA-Z0-9_]*">
+            <select class="param-type">
+                ${PARAM_TYPES.map(pt => `<option value="${pt}" ${def.type === pt ? 'selected' : ''}>${pt}</option>`).join('')}
+            </select>
+            <label class="param-required-label" title="${t('scripts.params.required')}">
+                <input type="checkbox" class="param-required" ${def.required ? 'checked' : ''}>
+                <span>*</span>
+            </label>
+            <button type="button" class="param-remove-btn" title="${t('scripts.params.remove')}">&times;</button>
+        </div>
+        <div class="param-row-details">
+            <input type="text" class="param-description" value="${escapeHtml(def.description || '')}"
+                   placeholder="${t('scripts.params.description_placeholder')}">
+            <div class="param-row-extra">
+                <input type="text" class="param-default" value="${def.default !== undefined && def.default !== null ? escapeHtml(String(def.default)) : ''}"
+                       placeholder="${t('scripts.params.default_placeholder')}">
+                <input type="text" class="param-min" value="${def.min !== undefined && def.min !== null ? def.min : ''}"
+                       placeholder="Min" style="display:${def.type === 'integer' || def.type === 'float' ? '' : 'none'}">
+                <input type="text" class="param-max" value="${def.max !== undefined && def.max !== null ? def.max : ''}"
+                       placeholder="Max" style="display:${def.type === 'integer' || def.type === 'float' ? '' : 'none'}">
+                <input type="text" class="param-options" value="${def.options ? def.options.join(', ') : ''}"
+                       placeholder="${t('scripts.params.options_placeholder')}" style="display:${def.type === 'select' ? '' : 'none'}">
+            </div>
+        </div>
+    `;
+
+    // Enhance the type <select> with icon grid
+    const typeSelect = row.querySelector('.param-type');
+    const iconSelect = new IconSelect({
+        target: typeSelect,
+        items: _paramTypeItems,
+        columns: 5,
+        onChange: () => {
+            const isNumeric = typeSelect.value === 'integer' || typeSelect.value === 'float';
+            const isSelect = typeSelect.value === 'select';
+            row.querySelector('.param-min').style.display = isNumeric ? '' : 'none';
+            row.querySelector('.param-max').style.display = isNumeric ? '' : 'none';
+            row.querySelector('.param-options').style.display = isSelect ? '' : 'none';
+            scriptFormDirty = true;
+        },
+    });
+
+    row.querySelector('.param-remove-btn').addEventListener('click', () => {
+        iconSelect.destroy();
+        row.remove();
+        scriptFormDirty = true;
+    });
+
+    // Mark dirty on any input change
+    row.querySelectorAll('input').forEach(el => {
+        el.addEventListener('input', () => { scriptFormDirty = true; });
+    });
+
+    container.appendChild(row);
+}
+
+function _collectParameterDefinitions() {
+    const container = document.getElementById('scriptParamsContainer');
+    const rows = container.querySelectorAll('.param-row');
+    const params = {};
+
+    for (const row of rows) {
+        const name = row.querySelector('.param-name').value.trim();
+        if (!name) continue;
+
+        const type = row.querySelector('.param-type').value;
+        const def = { type };
+
+        const description = row.querySelector('.param-description').value.trim();
+        if (description) def.description = description;
+
+        if (row.querySelector('.param-required').checked) def.required = true;
+
+        const defaultVal = row.querySelector('.param-default').value.trim();
+        if (defaultVal !== '') {
+            if (type === 'integer') def.default = parseInt(defaultVal, 10);
+            else if (type === 'float') def.default = parseFloat(defaultVal);
+            else if (type === 'boolean') def.default = defaultVal.toLowerCase() === 'true';
+            else def.default = defaultVal;
+        }
+
+        if (type === 'integer' || type === 'float') {
+            const minVal = row.querySelector('.param-min').value.trim();
+            const maxVal = row.querySelector('.param-max').value.trim();
+            if (minVal !== '') def.min = parseFloat(minVal);
+            if (maxVal !== '') def.max = parseFloat(maxVal);
+        }
+
+        if (type === 'select') {
+            const optStr = row.querySelector('.param-options').value.trim();
+            if (optStr) def.options = optStr.split(',').map(s => s.trim()).filter(Boolean);
+        }
+
+        params[name] = def;
+    }
+
+    return params;
+}
+
+export async function executeCallbackDebug(callbackName) {
+    const dialog = document.getElementById('executionDialog');
+    const title = document.getElementById('executionDialogTitle');
+    const statusDiv = document.getElementById('executionStatus');
+
+    title.textContent = `${t('execution.executing')}: ${callbackName}`;
+    statusDiv.innerHTML = `
+        <div class="status-item">
+            <label>${escapeHtml(t('execution.status'))}</label>
+            <value><span class="loading-spinner"></span> ${escapeHtml(t('execution.running'))}</value>
+        </div>
+    `;
+    document.getElementById('outputSection').style.display = 'none';
+    document.getElementById('errorSection').style.display = 'none';
+    document.body.classList.add('dialog-open');
+    dialog.showModal();
+
+    try {
+        const response = await fetch(`/api/callbacks/execute/${encodeURIComponent(callbackName)}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...getAuthHeaders() }
+        });
+
+        const result = await response.json();
+
+        if (response.ok) {
+            showExecutionResult(callbackName, result, 'callback');
+        } else {
+            showExecutionResult(callbackName, {
+                success: false,
+                exit_code: -1,
+                error: result.detail || 'Execution failed',
+                stderr: result.detail || 'Unknown error'
+            }, 'callback');
+        }
+    } catch (error) {
+        console.error(`Error executing callback ${callbackName}:`, error);
+        showExecutionResult(callbackName, {
+            success: false,
+            exit_code: -1,
+            error: error.message,
+            stderr: `Network error: ${error.message}`
+        }, 'callback');
+    }
+}

media_server/static/js/websocket.js

@@ -0,0 +1,260 @@
+// ============================================================
+// WebSocket: Connection, reconnection, authentication
+// ============================================================
+
+import {
+    dom, t, setWs, getWs,
+    WS_BACKOFF_BASE_MS, WS_BACKOFF_MAX_MS,
+    WS_MAX_RECONNECT_ATTEMPTS, WS_PING_INTERVAL_MS,
+    authRequired, showUpdateBanner,
+} from './core.js';
+import { updateUI, setFrequencyData, stopPositionInterpolation, loadAudioDevices } from './player.js';
+import { loadScripts, loadScriptsTable, displayQuickAccess } from './scripts.js';
+import { loadCallbacksTable } from './callbacks.js';
+import { loadHeaderLinks, loadLinksTable } from './links.js';
+import { updateForegroundUI } from './foreground.js';
+
+let reconnectTimeout = null;
+let wsReconnectAttempts = 0;
+// Track the ping interval against the socket that owns it so we never leak
+// a timer if connectWebSocket() is called while a previous socket is still
+// alive. The pair is wiped on close to avoid double-clear races.
+let activeSocket = null;
+let activePingInterval = null;
+
+function clearReconnect() {
+    if (reconnectTimeout) {
+        clearTimeout(reconnectTimeout);
+        reconnectTimeout = null;
+    }
+}
+
+function clearPing() {
+    if (activePingInterval) {
+        clearInterval(activePingInterval);
+        activePingInterval = null;
+    }
+}
+
+export function showAuthForm(errorMessage = '') {
+    const overlay = document.getElementById('auth-overlay');
+    overlay.classList.remove('hidden');
+
+    const errorEl = document.getElementById('auth-error');
+    if (errorMessage) {
+        errorEl.textContent = errorMessage;
+        errorEl.classList.add('visible');
+    } else {
+        errorEl.classList.remove('visible');
+    }
+}
+
+function hideAuthForm() {
+    document.getElementById('auth-overlay').classList.add('hidden');
+}
+
+export function authenticate() {
+    const token = document.getElementById('token-input').value.trim();
+    if (!token) {
+        showAuthForm(t('auth.required'));
+        return;
+    }
+
+    localStorage.setItem('media_server_token', token);
+    connectWebSocket(token);
+}
+
+export function clearToken() {
+    localStorage.removeItem('media_server_token');
+    const current = getWs();
+    if (current) {
+        try { current.close(1000, 'token cleared'); } catch { /* ignore */ }
+    }
+    showAuthForm(t('auth.cleared'));
+}
+
+export function connectWebSocket(token) {
+    // Always cancel a pending reconnect first — otherwise a user-triggered
+    // reconnect can race a scheduled one and create two live sockets.
+    clearReconnect();
+    clearPing();
+
+    // Close any previous socket cleanly before opening a new one.
+    const previous = activeSocket;
+    activeSocket = null;
+    if (previous && previous.readyState <= WebSocket.OPEN) {
+        try { previous.close(1000, 'reconnecting'); } catch { /* ignore */ }
+    }
+
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsBase = `${protocol}//${window.location.host}/api/media/ws`;
+
+    // Prefer Sec-WebSocket-Protocol-based auth so the token never appears in
+    // the URL (which would otherwise land in browser history, server access
+    // logs, and Referer headers). Keep the ?token=... fallback for clients
+    // that pre-date this change and don't speak the subprotocol.
+    let newWs;
+    if (token) {
+        try {
+            newWs = new WebSocket(wsBase, [`media-server.token.${token}`]);
+        } catch (e) {
+            console.warn('Subprotocol WS handshake failed, falling back to ?token=', e);
+            newWs = new WebSocket(`${wsBase}?token=${encodeURIComponent(token)}`);
+        }
+    } else {
+        newWs = new WebSocket(wsBase);
+    }
+    activeSocket = newWs;
+    setWs(newWs);
+
+    newWs.onopen = () => {
+        console.log('WebSocket connected');
+        wsReconnectAttempts = 0;
+        updateConnectionStatus(true);
+        hideConnectionBanner();
+        hideAuthForm();
+        loadScripts();
+        loadScriptsTable();
+        loadCallbacksTable();
+        loadLinksTable();
+        loadHeaderLinks();
+        loadAudioDevices();
+    };
+
+    newWs.onmessage = (event) => {
+        let msg;
+        try {
+            msg = JSON.parse(event.data);
+        } catch (err) {
+            console.warn('Ignoring malformed WebSocket frame:', err);
+            return;
+        }
+
+        if (msg.type === 'status' || msg.type === 'status_update') {
+            updateUI(msg.data);
+        } else if (msg.type === 'foreground' || msg.type === 'foreground_update') {
+            updateForegroundUI(msg.data);
+        } else if (msg.type === 'scripts_changed') {
+            console.log('Scripts changed, reloading...');
+            loadScripts();
+            loadScriptsTable();
+        } else if (msg.type === 'links_changed') {
+            console.log('Links changed, reloading...');
+            loadHeaderLinks();
+            loadLinksTable();
+            displayQuickAccess();
+        } else if (msg.type === 'update_available') {
+            showUpdateBanner(msg.data);
+        } else if (msg.type === 'audio_data') {
+            setFrequencyData(msg.data);
+        } else if (msg.type === 'error') {
+            console.error('WebSocket error:', msg.message);
+        }
+    };
+
+    newWs.onerror = (error) => {
+        console.error('WebSocket error:', error);
+        updateConnectionStatus(false);
+    };
+
+    newWs.onclose = (event) => {
+        console.log('WebSocket closed:', event.code);
+        updateConnectionStatus(false);
+        stopPositionInterpolation();
+
+        // Drop this socket's ping interval. Guard so we don't kill a newer
+        // socket's interval if reconnect already started.
+        if (activeSocket === newWs) {
+            clearPing();
+            activeSocket = null;
+        }
+
+        if (event.code === 4001) {
+            localStorage.removeItem('media_server_token');
+            showAuthForm(t('auth.invalid'));
+        } else if (event.code !== 1000) {
+            wsReconnectAttempts++;
+
+            if (wsReconnectAttempts <= WS_MAX_RECONNECT_ATTEMPTS) {
+                const delay = Math.min(
+                    WS_BACKOFF_BASE_MS * Math.pow(1.5, wsReconnectAttempts - 1),
+                    WS_BACKOFF_MAX_MS
+                );
+                console.log(`Reconnecting in ${Math.round(delay / 1000)}s (attempt ${wsReconnectAttempts}/${WS_MAX_RECONNECT_ATTEMPTS})...`);
+
+                if (wsReconnectAttempts >= 3) {
+                    showConnectionBanner(t('connection.reconnecting').replace('{attempt}', wsReconnectAttempts), false);
+                }
+
+                clearReconnect();
+                reconnectTimeout = setTimeout(() => {
+                    reconnectTimeout = null;
+                    const savedToken = localStorage.getItem('media_server_token');
+                    if (savedToken || !authRequired) {
+                        connectWebSocket(savedToken || '');
+                    }
+                }, delay);
+            } else {
+                showConnectionBanner(t('connection.lost'), true);
+            }
+        }
+    };
+
+    clearPing();
+    activePingInterval = setInterval(() => {
+        if (newWs.readyState === WebSocket.OPEN) {
+            try { newWs.send(JSON.stringify({ type: 'ping' })); } catch { /* ignore */ }
+        }
+    }, WS_PING_INTERVAL_MS);
+}
+
+export function updateConnectionStatus(connected) {
+    if (connected) {
+        dom.statusDot.classList.add('connected');
+    } else {
+        dom.statusDot.classList.remove('connected');
+    }
+}
+
+function showConnectionBanner(message, showButton) {
+    const banner = document.getElementById('connectionBanner');
+    const text = document.getElementById('connectionBannerText');
+    const btn = document.getElementById('connectionBannerBtn');
+    text.textContent = message;
+    btn.style.display = showButton ? '' : 'none';
+    banner.classList.remove('hidden');
+}
+
+function hideConnectionBanner() {
+    const banner = document.getElementById('connectionBanner');
+    banner.classList.add('hidden');
+}
+
+export function manualReconnect() {
+    const savedToken = localStorage.getItem('media_server_token');
+    if (savedToken || !authRequired) {
+        wsReconnectAttempts = 0;
+        hideConnectionBanner();
+        connectWebSocket(savedToken || '');
+    }
+}
+
+// When the browser regains connectivity or the tab becomes visible again,
+// drop the backoff and reconnect immediately rather than waiting out the
+// current timer.
+function reconnectIfNeeded() {
+    const current = activeSocket;
+    if (current && (current.readyState === WebSocket.OPEN || current.readyState === WebSocket.CONNECTING)) {
+        return;
+    }
+    const savedToken = localStorage.getItem('media_server_token');
+    if (savedToken || !authRequired) {
+        wsReconnectAttempts = 0;
+        connectWebSocket(savedToken || '');
+    }
+}
+
+window.addEventListener('online', reconnectIfNeeded);
+document.addEventListener('visibilitychange', () => {
+    if (!document.hidden) reconnectIfNeeded();
+});

media_server/static/locales/en.json

@@ -0,0 +1,320 @@
+{
+  "app.title": "Media Server",
+  "auth.message": "Enter your API token to connect to the media server.",
+  "auth.placeholder": "Enter API Token",
+  "auth.connect": "Connect",
+  "auth.help": "To get your token, run:",
+  "auth.logout": "Logout",
+  "auth.logout.title": "Clear saved token",
+  "auth.invalid": "Invalid token. Please try again.",
+  "auth.cleared": "Token cleared. Please enter a new token.",
+  "auth.required": "Please enter a token",
+  "player.theme": "Toggle theme",
+  "accent.custom": "Custom",
+  "player.locale": "Change language",
+  "player.previous": "Previous",
+  "player.play": "Play/Pause",
+  "player.next": "Next",
+  "player.mute": "Mute",
+  "player.status.connected": "Connected",
+  "player.status.disconnected": "Disconnected",
+  "player.no_media": "No media playing",
+  "player.kicker": "Now Playing",
+  "player.modes": "Modes",
+  "header.connected": "Connected",
+  "header.volume": "Vol. I",
+  "header.edition": "Studio Reference",
+  "header.edition_sub": "Studio Reference Edition",
+  "meta.state": "State",
+  "meta.source": "Source",
+  "player.title_unavailable": "Title unavailable",
+  "player.source": "Source:",
+  "player.unknown_source": "Unknown",
+  "player.vinyl": "Vinyl mode",
+  "player.visualizer": "Audio visualizer",
+  "player.background": "Dynamic background",
+  "player.fullscreen": "Fullscreen player",
+  "player.fullscreen.exit": "Exit fullscreen",
+  "player.fullscreen.exit_short": "Exit",
+  "state.playing": "Playing",
+  "state.paused": "Paused",
+  "state.stopped": "Stopped",
+  "state.idle": "Idle",
+  "scripts.quick_actions": "Quick Actions",
+  "scripts.no_scripts": "No scripts configured",
+  "scripts.management": "Script Management",
+  "scripts.add": "Add",
+  "scripts.table.name": "Name",
+  "scripts.table.label": "Label",
+  "scripts.table.command": "Command",
+  "scripts.table.timeout": "Timeout",
+  "scripts.table.actions": "Actions",
+  "scripts.empty": "No scripts configured. Click 'Add' to create one.",
+  "scripts.dialog.add": "Add Script",
+  "scripts.dialog.edit": "Edit Script",
+  "scripts.field.name": "Script Name *",
+  "scripts.field.label": "Label",
+  "scripts.field.command": "Command *",
+  "scripts.field.description": "Description",
+  "scripts.field.icon": "Icon (MDI)",
+  "scripts.field.timeout": "Timeout (seconds)",
+  "scripts.placeholder.name": "Only letters, numbers, and underscores allowed",
+  "scripts.placeholder.label": "Human-readable name",
+  "scripts.placeholder.command": "e.g., shutdown /s /t 0",
+  "scripts.placeholder.description": "What does this script do?",
+  "scripts.placeholder.icon": "e.g., mdi:power",
+  "scripts.button.cancel": "Cancel",
+  "scripts.button.save": "Save",
+  "scripts.button.edit": "Edit",
+  "scripts.button.delete": "Delete",
+  "scripts.msg.executed": "{name} executed successfully",
+  "scripts.msg.execute_failed": "Failed to execute {name}",
+  "scripts.msg.execute_error": "Error executing {name}",
+  "scripts.msg.created": "Script created successfully",
+  "scripts.msg.updated": "Script updated successfully",
+  "scripts.msg.create_failed": "Failed to create script",
+  "scripts.msg.update_failed": "Failed to update script",
+  "scripts.msg.deleted": "Script deleted successfully",
+  "scripts.msg.delete_failed": "Failed to delete script",
+  "scripts.msg.not_found": "Script not found",
+  "scripts.msg.load_failed": "Failed to load script details",
+  "scripts.msg.list_failed": "Failed to load scripts",
+  "scripts.confirm.delete": "Are you sure you want to delete the script \"{name}\"?",
+  "scripts.execution.title": "Execution Result",
+  "scripts.execution.output": "Output",
+  "scripts.execution.error_output": "Error Output",
+  "scripts.execution.close": "Close",
+  "scripts.confirm.unsaved": "You have unsaved changes. Are you sure you want to discard them?",
+  "scripts.field.parameters": "Parameters",
+  "scripts.params.add": "+ Add",
+  "scripts.params.remove": "Remove parameter",
+  "scripts.params.required": "Required",
+  "scripts.params.name_placeholder": "param_name",
+  "scripts.params.description_placeholder": "Parameter description",
+  "scripts.params.default_placeholder": "Default",
+  "scripts.params.options_placeholder": "option1, option2, ...",
+  "scripts.params.execute": "Execute",
+  "callbacks.management": "Callback Management",
+  "callbacks.description": "Callbacks are scripts triggered automatically by media control events (play, pause, stop, etc.)",
+  "callbacks.add": "Add",
+  "callbacks.table.event": "Event",
+  "callbacks.table.command": "Command",
+  "callbacks.table.timeout": "Timeout",
+  "callbacks.table.actions": "Actions",
+  "callbacks.empty": "No callbacks configured. Click 'Add' to create one.",
+  "callbacks.dialog.add": "Add Callback",
+  "callbacks.dialog.edit": "Edit Callback",
+  "callbacks.field.event": "Event *",
+  "callbacks.field.command": "Command *",
+  "callbacks.field.timeout": "Timeout (seconds)",
+  "callbacks.field.workdir": "Working Directory",
+  "callbacks.placeholder.event": "Select event...",
+  "callbacks.placeholder.command": "e.g., shutdown /s /t 0",
+  "callbacks.placeholder.workdir": "Optional",
+  "callbacks.button.cancel": "Cancel",
+  "callbacks.button.save": "Save",
+  "callbacks.button.edit": "Edit",
+  "callbacks.button.delete": "Delete",
+  "callbacks.event.on_play": "on_play - After play succeeds",
+  "callbacks.event.on_pause": "on_pause - After pause succeeds",
+  "callbacks.event.on_stop": "on_stop - After stop succeeds",
+  "callbacks.event.on_next": "on_next - After next track succeeds",
+  "callbacks.event.on_previous": "on_previous - After previous track succeeds",
+  "callbacks.event.on_volume": "on_volume - After volume change",
+  "callbacks.event.on_mute": "on_mute - After mute toggle",
+  "callbacks.event.on_seek": "on_seek - After seek succeeds",
+  "callbacks.event.on_turn_on": "on_turn_on - Callback-only action",
+  "callbacks.event.on_turn_off": "on_turn_off - Callback-only action",
+  "callbacks.event.on_toggle": "on_toggle - Callback-only action",
+  "callbacks.msg.created": "Callback created successfully",
+  "callbacks.msg.updated": "Callback updated successfully",
+  "callbacks.msg.create_failed": "Failed to create callback",
+  "callbacks.msg.update_failed": "Failed to update callback",
+  "callbacks.msg.deleted": "Callback deleted successfully",
+  "callbacks.msg.delete_failed": "Failed to delete callback",
+  "callbacks.msg.not_found": "Callback not found",
+  "callbacks.msg.load_failed": "Failed to load callback details",
+  "callbacks.msg.list_failed": "Failed to load callbacks",
+  "callbacks.confirm.delete": "Are you sure you want to delete the callback \"{name}\"?",
+  "callbacks.confirm.unsaved": "You have unsaved changes. Are you sure you want to discard them?",
+  "tab.player": "Now Spinning",
+  "tab.browser": "Library",
+  "tab.quick_access": "Quick Access",
+  "tab.settings": "Settings",
+  "tab.display": "Display",
+  "settings.section.scripts": "Scripts",
+  "settings.section.callbacks": "Callbacks",
+  "settings.section.links": "Links",
+  "settings.section.audio": "Audio",
+  "settings.audio.description": "Select which audio output device to capture for the visualizer.",
+  "settings.audio.device": "Loopback Device",
+  "settings.audio.auto": "Auto-detect",
+  "settings.audio.status_active": "Capturing audio",
+  "settings.audio.status_available": "Available, not capturing",
+  "settings.audio.status_unavailable": "Unavailable",
+  "settings.audio.device_changed": "Audio device changed",
+  "settings.audio.device_change_failed": "Failed to change audio device",
+  "quick_access.no_items": "No quick actions or links configured",
+  "display.loading": "Loading monitors...",
+  "display.error": "Failed to load monitors",
+  "display.no_monitors": "No monitors detected",
+  "display.power_on": "Turn on",
+  "display.power_off": "Turn off",
+  "display.primary": "Primary",
+  "display.brightness": "Brightness",
+  "display.contrast": "Contrast",
+  "display.tuning": "Picture tuning",
+  "display.input_source": "Input",
+  "display.color_preset": "Color temp",
+  "display.picture_mode": "Picture mode",
+  "display.msg.contrast_failed": "Failed to set contrast",
+  "display.msg.input_changed": "Input source switched",
+  "display.msg.input_failed": "Failed to switch input source",
+  "display.msg.color_changed": "Color preset applied",
+  "display.msg.color_failed": "Failed to apply color preset",
+  "display.msg.mode_changed": "Picture mode applied",
+  "display.msg.mode_failed": "Failed to apply picture mode",
+  "display.msg.power_on": "Monitor turned on",
+  "display.msg.power_off": "Monitor turned off",
+  "display.msg.power_failed": "Failed to change monitor power",
+  "execution.result": "Execution Result",
+  "execution.executing": "Executing",
+  "execution.status": "Status",
+  "execution.exit_code": "Exit Code",
+  "execution.duration": "Duration",
+  "execution.success": "Success",
+  "execution.failed": "Failed",
+  "execution.running": "Running...",
+  "execution.no_output": "(no output)",
+  "browser.title": "Media Browser",
+  "browser.home": "Home",
+  "browser.manage_folders": "Manage Folders",
+  "browser.select_folder": "Select a folder...",
+  "browser.select_folder_option": "Select a folder...",
+  "browser.no_folder_selected": "Select a folder to browse media files",
+  "browser.no_items": "No media files found in this folder",
+  "browser.view_grid": "Grid view",
+  "browser.view_compact": "Compact view",
+  "browser.view_list": "List view",
+  "browser.search": "Search...",
+  "browser.items_per_page": "Items per page:",
+  "browser.page": "Page",
+  "browser.previous": "Previous",
+  "browser.next": "Next",
+  "browser.download": "Download",
+  "browser.play_success": "Playing {filename}",
+  "browser.play_error": "Failed to play file",
+  "browser.play_all": "Play All",
+  "browser.play_all_success": "Playing {count} files",
+  "browser.play_all_error": "Failed to play folder",
+  "browser.error_loading": "Error loading directory",
+  "browser.error_loading_folders": "Failed to load media folders",
+  "browser.manage_folders_hint": "Folder management is disabled. Set media_folders_management: true in config.yaml to enable.",
+  "browser.unavailable": "Unavailable",
+  "browser.folder_available": "Available",
+  "browser.folder_unavailable": "Unavailable (path not reachable)",
+  "browser.folder_disabled": "disabled",
+  "browser.folder_edit": "Edit folder",
+  "browser.folder_delete": "Delete folder",
+  "browser.folder_created": "Media folder created successfully",
+  "browser.folder_updated": "Media folder updated successfully",
+  "browser.folder_deleted": "Media folder deleted successfully",
+  "browser.folder_save_error": "Failed to save media folder",
+  "browser.folder_delete_error": "Failed to delete media folder",
+  "browser.folder_confirm_delete": "Are you sure you want to delete the folder \"{name}\"?",
+  "browser.folders_description": "Media folders available for browsing. Folders on network shares show availability status.",
+  "browser.folders_empty": "No media folders configured. Click \"+\" to add one.",
+  "browser.folders_table.id": "ID",
+  "browser.folders_table.label": "Label",
+  "browser.folders_table.path": "Path",
+  "browser.folders_table.status": "Status",
+  "browser.folders_table.actions": "Actions",
+  "settings.section.media_folders": "Media Folders",
+  "browser.folder_dialog.title_add": "Add Media Folder",
+  "browser.folder_dialog.title_edit": "Edit Media Folder",
+  "browser.folder_dialog.folder_id": "Folder ID *",
+  "browser.folder_dialog.folder_id_help": "Alphanumeric and underscore only",
+  "browser.folder_dialog.label": "Label *",
+  "browser.folder_dialog.label_help": "Display name for this folder",
+  "browser.folder_dialog.path": "Path *",
+  "browser.folder_dialog.path_help": "Absolute path to media directory",
+  "browser.folder_dialog.enabled": "Enabled",
+  "browser.folder_dialog.cancel": "Cancel",
+  "browser.folder_dialog.save": "Save",
+  "browser.list_header.name": "Name",
+  "browser.list_header.bitrate": "Bitrate",
+  "browser.list_header.duration": "Duration",
+  "browser.list_header.size": "Size",
+  "browser.showing_items": "Showing {from}\u2013{to} of {total}",
+  "browser.download_error": "Failed to download file",
+  "connection.reconnecting": "Connection lost. Reconnecting (attempt {attempt})...",
+  "connection.lost": "Connection lost. Server may be unavailable.",
+  "connection.reconnect": "Reconnect",
+  "dialog.cancel": "Cancel",
+  "dialog.confirm": "Confirm",
+  "links.description": "Quick links displayed as icons in the header bar. Click an icon to open the URL in a new tab.",
+  "links.empty": "No links configured. Click 'Add' to create one.",
+  "links.table.name": "Name",
+  "links.table.url": "URL",
+  "links.table.label": "Label",
+  "links.table.actions": "Actions",
+  "links.dialog.add": "Add Link",
+  "links.dialog.edit": "Edit Link",
+  "links.field.name": "Link Name *",
+  "links.field.url": "URL *",
+  "links.field.icon": "Icon (MDI)",
+  "links.field.label": "Label",
+  "links.field.description": "Description",
+  "links.placeholder.name": "Only letters, numbers, and underscores allowed",
+  "links.placeholder.url": "https://example.com",
+  "links.placeholder.icon": "mdi:link",
+  "links.placeholder.label": "Tooltip text",
+  "links.placeholder.description": "What does this link point to?",
+  "links.button.cancel": "Cancel",
+  "links.button.save": "Save",
+  "links.button.edit": "Edit",
+  "links.button.delete": "Delete",
+  "links.msg.created": "Link created successfully",
+  "links.msg.updated": "Link updated successfully",
+  "links.msg.create_failed": "Failed to create link",
+  "links.msg.update_failed": "Failed to update link",
+  "links.msg.deleted": "Link deleted successfully",
+  "links.msg.delete_failed": "Failed to delete link",
+  "links.msg.not_found": "Link not found",
+  "links.msg.load_failed": "Failed to load link details",
+  "links.confirm.delete": "Are you sure you want to delete the link \"{name}\"?",
+  "links.confirm.unsaved": "You have unsaved changes. Are you sure you want to discard them?",
+  "about.button_title": "About",
+  "about.title": "About",
+  "about.created_by": "Created by",
+  "about.email": "Email",
+  "about.repository": "Repository",
+  "about.source_code": "Source Code",
+  "dialog.close": "Close",
+  "update.available": "Update available: v{version}",
+  "update.view_release": "View Release",
+  "tab.foreground": "Foreground",
+  "foreground.kicker": "Foreground",
+  "foreground.loading": "Waiting for foreground signal…",
+  "foreground.no_process": "No foreground process",
+  "foreground.unavailable": "Foreground tracking unavailable on this platform",
+  "foreground.process": "Process",
+  "foreground.window_title": "Window title",
+  "foreground.executable": "Executable",
+  "foreground.pid": "PID",
+  "foreground.monitor": "Monitor {n}",
+  "foreground.started": "Started",
+  "foreground.geometry": "Geometry",
+  "foreground.platform": "Platform",
+  "foreground.fullscreen": "Fullscreen",
+  "foreground.minimized": "Minimized",
+  "foreground.windowed": "Windowed",
+  "foreground.browser": "Browser",
+  "foreground.page_title": "Page title",
+  "foreground.url": "URL",
+  "foreground.badge.title": "View foreground process",
+  "foreground.ago.seconds": "{n}s ago",
+  "foreground.ago.minutes": "{n}m ago",
+  "foreground.ago.hours": "{n}h {m}m ago",
+  "foreground.ago.days": "{n}d ago"
+}

media_server/static/locales/ru.json

@@ -0,0 +1,320 @@
+{
+  "app.title": "Медиа Сервер",
+  "auth.message": "Введите API токен для подключения к медиа серверу.",
+  "auth.placeholder": "Введите API токен",
+  "auth.connect": "Подключиться",
+  "auth.help": "Чтобы получить токен, выполните:",
+  "auth.logout": "Выйти",
+  "auth.logout.title": "Очистить сохраненный токен",
+  "auth.invalid": "Неверный токен. Пожалуйста, попробуйте снова.",
+  "auth.cleared": "Токен очищен. Пожалуйста, введите новый токен.",
+  "auth.required": "Пожалуйста, введите токен",
+  "player.theme": "Переключить тему",
+  "accent.custom": "Свой цвет",
+  "player.locale": "Изменить язык",
+  "player.previous": "Предыдущий",
+  "player.play": "Воспроизвести/Пауза",
+  "player.next": "Следующий",
+  "player.mute": "Без звука",
+  "player.status.connected": "Подключено",
+  "player.status.disconnected": "Отключено",
+  "player.no_media": "Медиа не воспроизводится",
+  "player.kicker": "Сейчас играет",
+  "player.modes": "Режимы",
+  "header.connected": "Подключено",
+  "header.volume": "Том I",
+  "header.edition": "Studio Reference",
+  "header.edition_sub": "Studio Reference Edition",
+  "meta.state": "Состояние",
+  "meta.source": "Источник",
+  "player.title_unavailable": "Название недоступно",
+  "player.source": "Источник:",
+  "player.unknown_source": "Неизвестно",
+  "player.vinyl": "Режим винила",
+  "player.visualizer": "Аудио визуализатор",
+  "player.background": "Динамический фон",
+  "player.fullscreen": "Полноэкранный режим",
+  "player.fullscreen.exit": "Выйти из полного экрана",
+  "player.fullscreen.exit_short": "Выйти",
+  "state.playing": "Воспроизведение",
+  "state.paused": "Пауза",
+  "state.stopped": "Остановлено",
+  "state.idle": "Ожидание",
+  "scripts.quick_actions": "Быстрые Действия",
+  "scripts.no_scripts": "Скрипты не настроены",
+  "scripts.management": "Управление Скриптами",
+  "scripts.add": "Добавить",
+  "scripts.table.name": "Имя",
+  "scripts.table.label": "Метка",
+  "scripts.table.command": "Команда",
+  "scripts.table.timeout": "Таймаут",
+  "scripts.table.actions": "Действия",
+  "scripts.empty": "Скрипты не настроены. Нажмите 'Добавить' для создания.",
+  "scripts.dialog.add": "Добавить Скрипт",
+  "scripts.dialog.edit": "Редактировать Скрипт",
+  "scripts.field.name": "Имя Скрипта *",
+  "scripts.field.label": "Метка",
+  "scripts.field.command": "Команда *",
+  "scripts.field.description": "Описание",
+  "scripts.field.icon": "Иконка (MDI)",
+  "scripts.field.timeout": "Таймаут (секунды)",
+  "scripts.placeholder.name": "Только буквы, цифры и подчеркивания",
+  "scripts.placeholder.label": "Человеко-читаемое имя",
+  "scripts.placeholder.command": "например, shutdown /s /t 0",
+  "scripts.placeholder.description": "Что делает этот скрипт?",
+  "scripts.placeholder.icon": "например, mdi:power",
+  "scripts.button.cancel": "Отмена",
+  "scripts.button.save": "Сохранить",
+  "scripts.button.edit": "Редактировать",
+  "scripts.button.delete": "Удалить",
+  "scripts.msg.executed": "{name} выполнен успешно",
+  "scripts.msg.execute_failed": "Не удалось выполнить {name}",
+  "scripts.msg.execute_error": "Ошибка выполнения {name}",
+  "scripts.msg.created": "Скрипт создан успешно",
+  "scripts.msg.updated": "Скрипт обновлен успешно",
+  "scripts.msg.create_failed": "Не удалось создать скрипт",
+  "scripts.msg.update_failed": "Не удалось обновить скрипт",
+  "scripts.msg.deleted": "Скрипт удален успешно",
+  "scripts.msg.delete_failed": "Не удалось удалить скрипт",
+  "scripts.msg.not_found": "Скрипт не найден",
+  "scripts.msg.load_failed": "Не удалось загрузить данные скрипта",
+  "scripts.msg.list_failed": "Не удалось загрузить скрипты",
+  "scripts.confirm.delete": "Вы уверены, что хотите удалить скрипт \"{name}\"?",
+  "scripts.execution.title": "Результат выполнения",
+  "scripts.execution.output": "Вывод",
+  "scripts.execution.error_output": "Вывод ошибок",
+  "scripts.execution.close": "Закрыть",
+  "scripts.confirm.unsaved": "У вас есть несохраненные изменения. Вы уверены, что хотите отменить их?",
+  "scripts.field.parameters": "Параметры",
+  "scripts.params.add": "+ Добавить",
+  "scripts.params.remove": "Удалить параметр",
+  "scripts.params.required": "Обязательный",
+  "scripts.params.name_placeholder": "имя_параметра",
+  "scripts.params.description_placeholder": "Описание параметра",
+  "scripts.params.default_placeholder": "По умолчанию",
+  "scripts.params.options_placeholder": "вариант1, вариант2, ...",
+  "scripts.params.execute": "Выполнить",
+  "callbacks.management": "Управление Обратными Вызовами",
+  "callbacks.description": "Обратные вызовы - это скрипты, автоматически запускаемые при событиях управления медиа (воспроизведение, пауза, остановка и т.д.)",
+  "callbacks.add": "Добавить",
+  "callbacks.table.event": "Событие",
+  "callbacks.table.command": "Команда",
+  "callbacks.table.timeout": "Таймаут",
+  "callbacks.table.actions": "Действия",
+  "callbacks.empty": "Обратные вызовы не настроены. Нажмите 'Добавить' для создания.",
+  "callbacks.dialog.add": "Добавить Обратный Вызов",
+  "callbacks.dialog.edit": "Редактировать Обратный Вызов",
+  "callbacks.field.event": "Событие *",
+  "callbacks.field.command": "Команда *",
+  "callbacks.field.timeout": "Таймаут (секунды)",
+  "callbacks.field.workdir": "Рабочая Директория",
+  "callbacks.placeholder.event": "Выберите событие...",
+  "callbacks.placeholder.command": "например, shutdown /s /t 0",
+  "callbacks.placeholder.workdir": "Опционально",
+  "callbacks.button.cancel": "Отмена",
+  "callbacks.button.save": "Сохранить",
+  "callbacks.button.edit": "Редактировать",
+  "callbacks.button.delete": "Удалить",
+  "callbacks.event.on_play": "on_play - После успешного воспроизведения",
+  "callbacks.event.on_pause": "on_pause - После успешной паузы",
+  "callbacks.event.on_stop": "on_stop - После успешной остановки",
+  "callbacks.event.on_next": "on_next - После успешного перехода к следующему",
+  "callbacks.event.on_previous": "on_previous - После успешного перехода к предыдущему",
+  "callbacks.event.on_volume": "on_volume - После изменения громкости",
+  "callbacks.event.on_mute": "on_mute - После переключения звука",
+  "callbacks.event.on_seek": "on_seek - После успешной перемотки",
+  "callbacks.event.on_turn_on": "on_turn_on - Действие только для обратных вызовов",
+  "callbacks.event.on_turn_off": "on_turn_off - Действие только для обратных вызовов",
+  "callbacks.event.on_toggle": "on_toggle - Действие только для обратных вызовов",
+  "callbacks.msg.created": "Обратный вызов создан успешно",
+  "callbacks.msg.updated": "Обратный вызов обновлен успешно",
+  "callbacks.msg.create_failed": "Не удалось создать обратный вызов",
+  "callbacks.msg.update_failed": "Не удалось обновить обратный вызов",
+  "callbacks.msg.deleted": "Обратный вызов удален успешно",
+  "callbacks.msg.delete_failed": "Не удалось удалить обратный вызов",
+  "callbacks.msg.not_found": "Обратный вызов не найден",
+  "callbacks.msg.load_failed": "Не удалось загрузить данные обратного вызова",
+  "callbacks.msg.list_failed": "Не удалось загрузить обратные вызовы",
+  "callbacks.confirm.delete": "Вы уверены, что хотите удалить обратный вызов \"{name}\"?",
+  "callbacks.confirm.unsaved": "У вас есть несохраненные изменения. Вы уверены, что хотите отменить их?",
+  "tab.player": "Сейчас играет",
+  "tab.browser": "Библиотека",
+  "tab.quick_access": "Быстрый Доступ",
+  "tab.settings": "Настройки",
+  "tab.display": "Дисплей",
+  "settings.section.scripts": "Скрипты",
+  "settings.section.callbacks": "Колбэки",
+  "settings.section.links": "Ссылки",
+  "settings.section.audio": "Аудио",
+  "settings.audio.description": "Выберите аудиоустройство для захвата звука визуализатора.",
+  "settings.audio.device": "Устройство захвата",
+  "settings.audio.auto": "Автоопределение",
+  "settings.audio.status_active": "Захват аудио",
+  "settings.audio.status_available": "Доступно, не захватывает",
+  "settings.audio.status_unavailable": "Недоступно",
+  "settings.audio.device_changed": "Аудиоустройство изменено",
+  "settings.audio.device_change_failed": "Не удалось изменить аудиоустройство",
+  "quick_access.no_items": "Быстрые действия и ссылки не настроены",
+  "display.loading": "Загрузка мониторов...",
+  "display.error": "Не удалось загрузить мониторы",
+  "display.no_monitors": "Мониторы не обнаружены",
+  "display.power_on": "Включить",
+  "display.power_off": "Выключить",
+  "display.primary": "Основной",
+  "display.brightness": "Яркость",
+  "display.contrast": "Контраст",
+  "display.tuning": "Настройка изображения",
+  "display.input_source": "Вход",
+  "display.color_preset": "Цветовая температура",
+  "display.picture_mode": "Режим изображения",
+  "display.msg.contrast_failed": "Не удалось установить контраст",
+  "display.msg.input_changed": "Источник входа переключён",
+  "display.msg.input_failed": "Не удалось переключить источник",
+  "display.msg.color_changed": "Цветовая температура применена",
+  "display.msg.color_failed": "Не удалось применить цветовую температуру",
+  "display.msg.mode_changed": "Режим изображения применён",
+  "display.msg.mode_failed": "Не удалось применить режим изображения",
+  "display.msg.power_on": "Монитор включён",
+  "display.msg.power_off": "Монитор выключен",
+  "display.msg.power_failed": "Не удалось переключить питание монитора",
+  "execution.result": "Результат выполнения",
+  "execution.executing": "Выполняется",
+  "execution.status": "Статус",
+  "execution.exit_code": "Код выхода",
+  "execution.duration": "Длительность",
+  "execution.success": "Успешно",
+  "execution.failed": "Ошибка",
+  "execution.running": "Выполняется...",
+  "execution.no_output": "(нет вывода)",
+  "browser.title": "Медиа Браузер",
+  "browser.home": "Главная",
+  "browser.manage_folders": "Управление папками",
+  "browser.select_folder": "Выберите папку...",
+  "browser.select_folder_option": "Выберите папку...",
+  "browser.no_folder_selected": "Выберите папку для просмотра медиафайлов",
+  "browser.no_items": "В этой папке не найдено медиафайлов",
+  "browser.view_grid": "Сетка",
+  "browser.view_compact": "Компактный вид",
+  "browser.view_list": "Список",
+  "browser.search": "Поиск...",
+  "browser.items_per_page": "Элементов на странице:",
+  "browser.page": "Страница",
+  "browser.previous": "Предыдущая",
+  "browser.next": "Следующая",
+  "browser.download": "Скачать",
+  "browser.play_success": "Воспроизведение {filename}",
+  "browser.play_error": "Не удалось воспроизвести файл",
+  "browser.play_all": "Воспроизвести все",
+  "browser.play_all_success": "Воспроизведение {count} файлов",
+  "browser.play_all_error": "Не удалось воспроизвести папку",
+  "browser.error_loading": "Ошибка загрузки каталога",
+  "browser.error_loading_folders": "Не удалось загрузить медиа папки",
+  "browser.manage_folders_hint": "Управление папками отключено. Установите media_folders_management: true в config.yaml для включения.",
+  "browser.unavailable": "Недоступна",
+  "browser.folder_available": "Доступна",
+  "browser.folder_unavailable": "Недоступна (путь не найден)",
+  "browser.folder_disabled": "отключена",
+  "browser.folder_edit": "Редактировать папку",
+  "browser.folder_delete": "Удалить папку",
+  "browser.folder_created": "Медиа папка успешно создана",
+  "browser.folder_updated": "Медиа папка успешно обновлена",
+  "browser.folder_deleted": "Медиа папка успешно удалена",
+  "browser.folder_save_error": "Не удалось сохранить медиа папку",
+  "browser.folder_delete_error": "Не удалось удалить медиа папку",
+  "browser.folder_confirm_delete": "Вы уверены, что хотите удалить папку \"{name}\"?",
+  "browser.folders_description": "Медиа папки для просмотра. Для сетевых ресурсов показан статус доступности.",
+  "browser.folders_empty": "Медиа папки не настроены. Нажмите \"+\" для добавления.",
+  "browser.folders_table.id": "ID",
+  "browser.folders_table.label": "Метка",
+  "browser.folders_table.path": "Путь",
+  "browser.folders_table.status": "Статус",
+  "browser.folders_table.actions": "Действия",
+  "settings.section.media_folders": "Медиа папки",
+  "browser.folder_dialog.title_add": "Добавить медиа папку",
+  "browser.folder_dialog.title_edit": "Редактировать медиа папку",
+  "browser.folder_dialog.folder_id": "ID папки *",
+  "browser.folder_dialog.folder_id_help": "Только буквы, цифры и подчеркивание",
+  "browser.folder_dialog.label": "Метка *",
+  "browser.folder_dialog.label_help": "Отображаемое имя папки",
+  "browser.folder_dialog.path": "Путь *",
+  "browser.folder_dialog.path_help": "Абсолютный путь к медиа каталогу",
+  "browser.folder_dialog.enabled": "Включено",
+  "browser.folder_dialog.cancel": "Отмена",
+  "browser.folder_dialog.save": "Сохранить",
+  "browser.list_header.name": "Название",
+  "browser.list_header.bitrate": "Битрейт",
+  "browser.list_header.duration": "Длительность",
+  "browser.list_header.size": "Размер",
+  "browser.showing_items": "Показано {from}\u2013{to} из {total}",
+  "browser.download_error": "Не удалось скачать файл",
+  "connection.reconnecting": "Соединение потеряно. Переподключение (попытка {attempt})...",
+  "connection.lost": "Соединение потеряно. Сервер может быть недоступен.",
+  "connection.reconnect": "Переподключиться",
+  "dialog.cancel": "Отмена",
+  "dialog.confirm": "Подтвердить",
+  "links.description": "Быстрые ссылки, отображаемые в виде иконок в шапке. Нажмите на иконку, чтобы открыть URL в новой вкладке.",
+  "links.empty": "Ссылки не настроены. Нажмите 'Добавить' для создания.",
+  "links.table.name": "Имя",
+  "links.table.url": "URL",
+  "links.table.label": "Метка",
+  "links.table.actions": "Действия",
+  "links.dialog.add": "Добавить Ссылку",
+  "links.dialog.edit": "Редактировать Ссылку",
+  "links.field.name": "Имя Ссылки *",
+  "links.field.url": "URL *",
+  "links.field.icon": "Иконка (MDI)",
+  "links.field.label": "Метка",
+  "links.field.description": "Описание",
+  "links.placeholder.name": "Только буквы, цифры и подчеркивания",
+  "links.placeholder.url": "https://example.com",
+  "links.placeholder.icon": "mdi:link",
+  "links.placeholder.label": "Текст подсказки",
+  "links.placeholder.description": "Куда ведет эта ссылка?",
+  "links.button.cancel": "Отмена",
+  "links.button.save": "Сохранить",
+  "links.button.edit": "Редактировать",
+  "links.button.delete": "Удалить",
+  "links.msg.created": "Ссылка создана успешно",
+  "links.msg.updated": "Ссылка обновлена успешно",
+  "links.msg.create_failed": "Не удалось создать ссылку",
+  "links.msg.update_failed": "Не удалось обновить ссылку",
+  "links.msg.deleted": "Ссылка удалена успешно",
+  "links.msg.delete_failed": "Не удалось удалить ссылку",
+  "links.msg.not_found": "Ссылка не найдена",
+  "links.msg.load_failed": "Не удалось загрузить данные ссылки",
+  "links.confirm.delete": "Вы уверены, что хотите удалить ссылку \"{name}\"?",
+  "links.confirm.unsaved": "У вас есть несохраненные изменения. Вы уверены, что хотите отменить их?",
+  "about.button_title": "О программе",
+  "about.title": "О программе",
+  "about.created_by": "Создано",
+  "about.email": "Эл. почта",
+  "about.repository": "Репозиторий",
+  "about.source_code": "Исходный код",
+  "dialog.close": "Закрыть",
+  "update.available": "Доступно обновление: v{version}",
+  "update.view_release": "Перейти к релизу",
+  "tab.foreground": "Активное окно",
+  "foreground.kicker": "Активное окно",
+  "foreground.loading": "Ожидание сигнала об активном окне…",
+  "foreground.no_process": "Активное окно не определено",
+  "foreground.unavailable": "Отслеживание активного окна недоступно",
+  "foreground.process": "Процесс",
+  "foreground.window_title": "Заголовок окна",
+  "foreground.executable": "Путь к программе",
+  "foreground.pid": "PID",
+  "foreground.monitor": "Монитор {n}",
+  "foreground.started": "Запущено",
+  "foreground.geometry": "Геометрия",
+  "foreground.platform": "Платформа",
+  "foreground.fullscreen": "Полноэкранный",
+  "foreground.minimized": "Свёрнут",
+  "foreground.windowed": "Оконный",
+  "foreground.browser": "Браузер",
+  "foreground.page_title": "Заголовок страницы",
+  "foreground.url": "URL",
+  "foreground.badge.title": "Открыть активное окно",
+  "foreground.ago.seconds": "{n} с назад",
+  "foreground.ago.minutes": "{n} мин назад",
+  "foreground.ago.hours": "{n} ч {m} мин назад",
+  "foreground.ago.days": "{n} дн назад"
+}

media_server/static/manifest.json

@@ -0,0 +1,25 @@
+{
+  "id": "/",
+  "name": "Media Server",
+  "short_name": "Media",
+  "description": "Remote media player control and file browser",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "orientation": "any",
+  "background_color": "#0E0D0B",
+  "theme_color": "#0E0D0B",
+  "icons": [
+    {
+      "src": "/static/icons/icon.svg",
+      "sizes": "any",
+      "type": "image/svg+xml"
+    },
+    {
+      "src": "/static/icons/icon.svg",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "maskable"
+    }
+  ]
+}

media_server/static/sw.js

@@ -0,0 +1,13 @@
+// Minimal service worker for PWA installability only.
+// This app requires a live WebSocket connection, so offline caching is not useful.
+// We intentionally do NOT register a `fetch` handler — a pass-through handler
+// forces every navigation through the SW for no benefit and breaks the
+// browser's normal HTTP cache + error semantics.
+
+self.addEventListener('install', () => {
+    self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+    event.waitUntil(self.clients.claim());
+});

media_server/static/vinyl-variants-mockup.html

@@ -0,0 +1,911 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Vinyl Variants · Studio Reference</title>
+<link rel="icon" type="image/svg+xml" href="/static/icons/icon.svg">
+
+<style>
+/* ───────── Local fonts (re-using main app's woff2 files) ───── */
+@font-face {
+  font-family: 'Fraunces';
+  font-style: italic;
+  font-weight: 300 900;
+  font-display: swap;
+  src: url('/static/fonts/Fraunces-italic-latin.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Fraunces';
+  font-style: normal;
+  font-weight: 300 900;
+  font-display: swap;
+  src: url('/static/fonts/Fraunces-latin.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Geist';
+  font-style: normal;
+  font-weight: 300 700;
+  font-display: swap;
+  src: url('/static/fonts/Geist-latin.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Geist Mono';
+  font-style: normal;
+  font-weight: 300 600;
+  font-display: swap;
+  src: url('/static/fonts/GeistMono-latin.woff2') format('woff2');
+}
+
+/* ───────── Tokens (Studio Reference, dark) ───── */
+:root {
+  --bg-deep: #0E0D0B;
+  --bg-paper: #18150F;
+  --bg-card: #211E18;
+  --bg-card-2: #26211A;
+  --bg-rule: #2E2820;
+  --ink: #F2EBDC;
+  --ink-soft: #D6CDB9;
+  --ink-mute: #9C937F;
+  --ink-faint: #5C5447;
+  --ink-ghost: #3A3528;
+  --copper: #E08038;
+  --copper-hi: #F4A064;
+  --copper-lo: #B0561F;
+  --copper-glow: rgba(224, 128, 56, 0.35);
+  --rule: rgba(242, 235, 220, 0.08);
+  --rule-strong: rgba(242, 235, 220, 0.18);
+  --serif: 'Fraunces', Georgia, serif;
+  --sans: 'Geist', system-ui, sans-serif;
+  --mono: 'Geist Mono', ui-monospace, monospace;
+  --ease: cubic-bezier(.2, .7, .2, 1);
+  --ease-out: cubic-bezier(.16, 1, .3, 1);
+}
+
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+html { background: var(--bg-deep); }
+body {
+  font-family: var(--sans);
+  background: var(--bg-deep);
+  color: var(--ink);
+  min-height: 100vh;
+  padding: 56px 36px 80px;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+/* Film grain */
+body::before {
+  content: "";
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: 9999;
+  opacity: 0.05;
+  mix-blend-mode: overlay;
+  background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='200' height='200'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.95  0 0 0 0 0.92  0 0 0 0 0.86  0 0 0 0.7 0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
+}
+
+/* ───────── Page header (editorial) ───── */
+header.page-head {
+  max-width: 1320px;
+  margin: 0 auto 48px;
+  text-align: center;
+}
+.kicker {
+  font-family: var(--mono);
+  font-size: 10px;
+  letter-spacing: 0.32em;
+  text-transform: uppercase;
+  color: var(--copper);
+  display: inline-flex;
+  align-items: center;
+  gap: 14px;
+  margin-bottom: 22px;
+}
+.kicker::before, .kicker::after {
+  content: "";
+  height: 1px;
+  width: 40px;
+  background: var(--copper);
+  opacity: 0.6;
+}
+h1 {
+  font-family: var(--serif);
+  font-style: italic;
+  font-weight: 400;
+  font-size: clamp(36px, 5vw, 56px);
+  line-height: 1;
+  letter-spacing: -0.02em;
+  margin-bottom: 14px;
+  font-variation-settings: 'opsz' 144;
+}
+.subtitle {
+  font-family: var(--mono);
+  font-size: 11px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--ink-mute);
+  margin-bottom: 8px;
+}
+.return-link {
+  display: inline-block;
+  margin-top: 24px;
+  font-family: var(--mono);
+  font-size: 11px;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+  text-decoration: none;
+  border-bottom: 1px solid var(--ink-faint);
+  padding-bottom: 2px;
+  transition: all 200ms var(--ease);
+}
+.return-link:hover { color: var(--copper); border-color: var(--copper); }
+
+/* ───────── Variant grid ───── */
+.grid {
+  max-width: 1320px;
+  margin: 0 auto;
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(360px, 1fr));
+  gap: 56px 40px;
+}
+
+article.variant {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+}
+
+.stage {
+  position: relative;
+  aspect-ratio: 1;
+  width: 100%;
+  background:
+    radial-gradient(ellipse at center, var(--bg-card-2) 0%, var(--bg-deep) 80%);
+  border: 1px solid var(--rule);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: visible;
+  margin-bottom: 22px;
+}
+
+.label-row {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  border-bottom: 1px solid var(--rule);
+  padding-bottom: 10px;
+  margin-bottom: 14px;
+}
+.label-num {
+  font-family: var(--mono);
+  font-size: 10px;
+  letter-spacing: 0.2em;
+  color: var(--copper);
+}
+.label-name {
+  font-family: var(--serif);
+  font-style: italic;
+  font-size: 22px;
+  font-weight: 400;
+  font-variation-settings: 'opsz' 60;
+  flex: 1;
+}
+.label-tag {
+  font-family: var(--mono);
+  font-size: 9px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+  padding: 3px 8px;
+  border: 1px solid var(--rule-strong);
+}
+.tag-css { color: var(--jade, #7AB294); border-color: rgba(122, 178, 148, 0.3); }
+.tag-needs-js { color: var(--copper); border-color: var(--copper-lo); }
+
+p.descr {
+  font-family: var(--sans);
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--ink-soft);
+}
+p.descr strong {
+  color: var(--ink);
+  font-weight: 500;
+}
+
+/* ───────── Shared vinyl base ───── */
+.vinyl {
+  position: relative;
+  width: 86%;
+  aspect-ratio: 1;
+  border-radius: 50%;
+  background:
+    radial-gradient(circle at 50% 50%,
+      #0a0907 0%, #0a0907 18%,
+      #1a1611 18.3%, #0a0907 18.6%,
+      #14110c 22%, #0a0907 22.3%,
+      #14110c 26%, #0a0907 26.3%,
+      #14110c 30%, #0a0907 30.3%,
+      #14110c 34%, #0a0907 34.3%,
+      #14110c 38%, #0a0907 38.3%,
+      #14110c 42%, #0a0907 42.3%,
+      #14110c 46%, #0a0907 46.3%,
+      #1c1812 47%, #0a0907 100%);
+  box-shadow:
+    inset 0 0 60px rgba(0, 0, 0, 0.7),
+    0 30px 80px rgba(0, 0, 0, 0.6),
+    0 6px 20px rgba(0, 0, 0, 0.5);
+  animation: spin 14s linear infinite;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
+
+.vinyl::before {
+  content: "";
+  position: absolute;
+  inset: 12%;
+  border-radius: 50%;
+  background:
+    conic-gradient(from 0deg,
+      rgba(255,255,255,0.04) 0deg,
+      transparent 30deg,
+      rgba(255,255,255,0.06) 90deg,
+      transparent 150deg,
+      rgba(255,255,255,0.03) 210deg,
+      transparent 270deg,
+      rgba(255,255,255,0.05) 330deg,
+      transparent 360deg);
+  mix-blend-mode: screen;
+  pointer-events: none;
+}
+
+.vinyl-label {
+  position: absolute;
+  inset: 28%;
+  border-radius: 50%;
+  overflow: hidden;
+  box-shadow:
+    inset 0 0 24px rgba(0, 0, 0, 0.4),
+    0 0 0 4px var(--bg-deep),
+    0 0 0 5px var(--copper-lo);
+  background: var(--bg-card);
+  z-index: 1;
+}
+.vinyl-label::after {
+  content: "";
+  position: absolute;
+  width: 8%; height: 8%;
+  top: 46%; left: 46%;
+  border-radius: 50%;
+  background: var(--bg-deep);
+  box-shadow: inset 0 1px 2px rgba(255, 255, 255, 0.1);
+  z-index: 3;
+}
+.vinyl-label img,
+.vinyl-label svg {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+/* Album art (shared SVG used by every variant) */
+.album-art {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+/* Tonearm (decorative, on every stage so they read as "now playing") */
+.tonearm {
+  position: absolute;
+  top: -4%;
+  right: -2%;
+  width: 50%;
+  height: 50%;
+  pointer-events: none;
+  transform-origin: 88% 12%;
+  transform: rotate(0deg);
+  z-index: 5;
+  filter: drop-shadow(0 4px 12px rgba(0,0,0,0.5));
+}
+
+/* ════════════════════════════════════════════════════════════════
+   ORIGINAL  —  current shipping look (control)
+   ════════════════════════════════════════════════════════════════ */
+.v0 .stage { /* nothing extra */ }
+
+/* ════════════════════════════════════════════════════════════════
+   VARIANT 1  —  Sleeve frame
+   Vinyl peeks out of a square cardstock sleeve.
+   ════════════════════════════════════════════════════════════════ */
+.v1 .stage {
+  background:
+    radial-gradient(ellipse at center, #1a1611 0%, var(--bg-deep) 80%);
+}
+.v1 .sleeve-stage {
+  position: relative;
+  width: 90%;
+  aspect-ratio: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.v1 .sleeve {
+  position: absolute;
+  left: 0;
+  top: 6%;
+  width: 70%;
+  aspect-ratio: 1;
+  background: var(--bg-card-2);
+  box-shadow:
+    inset 0 0 0 1px rgba(0,0,0,0.4),
+    inset 4px 4px 24px rgba(0,0,0,0.35),
+    -2px 8px 24px rgba(0,0,0,0.5),
+    -4px 16px 40px rgba(0,0,0,0.35);
+  z-index: 3;
+  /* Casually-placed tilt — like a sleeve set down on a console */
+  transform: rotate(-3.2deg);
+  transform-origin: 60% 60%;
+  /* worn-edge cardstock effect */
+  filter: contrast(1.05) brightness(0.97);
+}
+.v1 .sleeve::before {
+  /* Cardstock paper grain */
+  content: "";
+  position: absolute;
+  inset: 0;
+  background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='1.2' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.10  0 0 0 0 0.08  0 0 0 0 0.06  0 0 0 0.7 0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
+  mix-blend-mode: multiply;
+  pointer-events: none;
+  opacity: 0.6;
+}
+.v1 .sleeve::after {
+  /* Ring-wear: faint circle from the LP rubbing the cardstock */
+  content: "";
+  position: absolute;
+  inset: 6%;
+  border-radius: 50%;
+  border: 1px solid rgba(0,0,0,0.25);
+  box-shadow:
+    inset 0 0 12px rgba(0,0,0,0.18),
+    inset 0 0 0 1px rgba(255,255,255,0.04);
+  pointer-events: none;
+}
+.v1 .sleeve-art {
+  position: absolute;
+  inset: 6%;
+  z-index: 1;
+  filter: contrast(0.88) saturate(0.6) brightness(0.88);
+  opacity: 0.85;
+}
+.v1 .sleeve-art svg { width: 100%; height: 100%; }
+/* Worn corner notch */
+.v1 .sleeve-corner {
+  position: absolute;
+  width: 14%;
+  height: 14%;
+  bottom: -1px;
+  right: -1px;
+  background: var(--bg-deep);
+  clip-path: polygon(100% 0, 100% 100%, 0 100%);
+  opacity: 0.7;
+  z-index: 4;
+}
+.v1 .vinyl-wrap {
+  position: absolute;
+  right: -2%;
+  top: 16%;
+  width: 70%;
+  aspect-ratio: 1;
+  z-index: 2;
+}
+.v1 .vinyl-wrap .vinyl {
+  width: 100%;
+}
+.v1 .vinyl-label {
+  /* Smaller label since the disc here is showing; album art lives on sleeve */
+  inset: 32%;
+  background: #2E2820;
+  box-shadow:
+    inset 0 0 18px rgba(0,0,0,0.4),
+    0 0 0 3px var(--bg-deep),
+    0 0 0 4px var(--copper-lo);
+}
+.v1 .vinyl-label::before {
+  /* Plain-color label with faux pressing imprint */
+  content: "REF · 24";
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-family: var(--mono);
+  font-size: 10px;
+  letter-spacing: 0.3em;
+  color: var(--copper);
+  z-index: 2;
+}
+.v1 .tonearm {
+  right: -8%;
+  top: 8%;
+  width: 44%;
+  height: 44%;
+}
+
+/* ════════════════════════════════════════════════════════════════
+   VARIANT 2  —  Sheen + paper grain + dead-wax + off-center
+   The high-impact variant.
+   ════════════════════════════════════════════════════════════════ */
+.v2 .vinyl-label {
+  /* Slightly off-center spindle for "pressed off-axis" feel */
+  inset: 27% 27% 29% 29%;
+}
+.v2 .vinyl-label::after {
+  /* Spindle hole offset 1.5% from true center */
+  top: 47%;
+  left: 47.5%;
+}
+/* Paper grain on the label, multiplied so it sits inside the print */
+.v2 .vinyl-label .label-grain {
+  position: absolute;
+  inset: 0;
+  background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='200' height='200'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='1.6' numOctaves='3' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.05  0 0 0 0 0.04  0 0 0 0 0.03  0 0 0 0.55 0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
+  mix-blend-mode: multiply;
+  pointer-events: none;
+  z-index: 4;
+}
+/* Dead-wax: micro-text engraved between the label and the run-out groove */
+.v2 .dead-wax {
+  position: absolute;
+  inset: 21%;
+  border-radius: 50%;
+  z-index: 0;
+  pointer-events: none;
+  /* Animation OFF the disc — engraving is part of the press, so it does spin with the vinyl */
+  animation: spin 14s linear infinite;
+}
+.v2 .dead-wax svg { width: 100%; height: 100%; }
+/* Reflection sweep — fixed in viewer space, not rotating with the disc */
+.v2 .sheen {
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  pointer-events: none;
+  background:
+    conic-gradient(from 110deg,
+      transparent 0deg,
+      rgba(255, 245, 220, 0) 30deg,
+      rgba(255, 245, 220, 0.07) 60deg,
+      rgba(255, 245, 220, 0.14) 80deg,
+      rgba(255, 245, 220, 0.07) 100deg,
+      transparent 140deg,
+      transparent 280deg,
+      rgba(255, 245, 220, 0.04) 305deg,
+      rgba(255, 245, 220, 0.08) 320deg,
+      rgba(255, 245, 220, 0.04) 335deg,
+      transparent 360deg);
+  mix-blend-mode: screen;
+  z-index: 4;
+}
+
+/* ════════════════════════════════════════════════════════════════
+   VARIANT 3  —  Tone-graded album art (duotone)
+   ════════════════════════════════════════════════════════════════ */
+.v3 .vinyl-label .album-art {
+  filter:
+    saturate(0.35)
+    sepia(0.45)
+    hue-rotate(345deg)
+    brightness(0.85)
+    contrast(1.18);
+}
+.v3 .vinyl-label::before {
+  /* Subtle copper duotone overlay tints the highlights */
+  content: "";
+  position: absolute;
+  inset: 0;
+  background:
+    linear-gradient(135deg,
+      rgba(224, 128, 56, 0.18) 0%,
+      rgba(31, 78, 61, 0.10) 50%,
+      rgba(0,0,0,0.18) 100%);
+  mix-blend-mode: overlay;
+  z-index: 2;
+  pointer-events: none;
+}
+.v3 .vinyl-label::after {
+  z-index: 4;
+}
+.v3 .vinyl-label .vignette {
+  position: absolute;
+  inset: 0;
+  background: radial-gradient(circle at 50% 45%,
+    transparent 35%,
+    rgba(0,0,0,0.45) 100%);
+  z-index: 3;
+  pointer-events: none;
+}
+
+/* ════════════════════════════════════════════════════════════════
+   VARIANT 4  —  Sleeve-to-disc reveal animation
+   (Hover the card to see the disc slide out)
+   ════════════════════════════════════════════════════════════════ */
+.v4 .sleeve-stage {
+  position: relative;
+  width: 90%;
+  aspect-ratio: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.v4 .sleeve {
+  position: absolute;
+  left: 14%;
+  top: 12%;
+  width: 72%;
+  aspect-ratio: 1;
+  background: var(--bg-card-2);
+  box-shadow:
+    inset 0 0 0 1px rgba(0,0,0,0.4),
+    -2px 6px 18px rgba(0,0,0,0.5);
+  z-index: 4;
+  overflow: hidden;
+}
+.v4 .sleeve::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='1.2' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.10  0 0 0 0 0.08  0 0 0 0 0.06  0 0 0 0.5 0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
+  mix-blend-mode: multiply;
+  pointer-events: none;
+  z-index: 2;
+}
+.v4 .sleeve-art {
+  width: 100%; height: 100%;
+  filter: contrast(0.92) saturate(0.7) brightness(0.92);
+  position: relative;
+  z-index: 1;
+}
+.v4 .vinyl-slot {
+  position: absolute;
+  left: 14%;
+  top: 12%;
+  width: 72%;
+  aspect-ratio: 1;
+  z-index: 3;
+  transition: transform 1.2s var(--ease-out);
+}
+.v4 .vinyl-slot .vinyl {
+  width: 100%;
+  animation-play-state: paused;
+  transition: animation-play-state 0.4s;
+}
+.v4 .stage:hover .vinyl-slot {
+  transform: translateX(46%);
+}
+.v4 .stage:hover .vinyl-slot .vinyl {
+  animation-play-state: running;
+}
+.v4 .hover-hint {
+  position: absolute;
+  bottom: 12px;
+  left: 50%;
+  transform: translateX(-50%);
+  font-family: var(--mono);
+  font-size: 9px;
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+  pointer-events: none;
+  z-index: 10;
+}
+.v4 .stage:hover .hover-hint { opacity: 0.4; }
+
+/* Note row at top of every variant */
+.note {
+  position: absolute;
+  top: 12px;
+  left: 14px;
+  font-family: var(--mono);
+  font-size: 9px;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+  z-index: 10;
+}
+
+/* ───────── Mobile ───── */
+@media (max-width: 720px) {
+  body { padding: 36px 16px 60px; }
+  .grid { gap: 36px 20px; grid-template-columns: 1fr; }
+}
+</style>
+</head>
+<body>
+
+<header class="page-head">
+  <div class="kicker">Studio Reference · Album Art Variants</div>
+  <h1>Vinyl Cover Treatments</h1>
+  <p class="subtitle">Five renderings of the same disc · Hover variant 04 for the sleeve reveal</p>
+  <a class="return-link" href="/">← Return to player</a>
+</header>
+
+<div class="grid">
+
+  <!-- ═════════ ORIGINAL ═════════ -->
+  <article class="variant v0">
+    <div class="stage">
+      <span class="note">As shipping</span>
+      <div class="vinyl">
+        <div class="vinyl-label">
+          <svg viewBox="0 0 400 400" class="album-art" xmlns="http://www.w3.org/2000/svg">
+            <defs>
+              <linearGradient id="bgA" x1="0" y1="0" x2="1" y2="1">
+                <stop offset="0%" stop-color="#1F4E3D"/>
+                <stop offset="55%" stop-color="#143E2F"/>
+                <stop offset="100%" stop-color="#0a2519"/>
+              </linearGradient>
+              <radialGradient id="vigA" cx="50%" cy="50%" r="70%">
+                <stop offset="55%" stop-color="rgba(0,0,0,0)"/>
+                <stop offset="100%" stop-color="rgba(0,0,0,0.55)"/>
+              </radialGradient>
+            </defs>
+            <rect width="400" height="400" fill="url(#bgA)"/>
+            <g stroke="#e08038" stroke-width="1" fill="none" opacity="0.55">
+              <circle cx="200" cy="200" r="60"/>
+              <circle cx="200" cy="200" r="100"/>
+              <circle cx="200" cy="200" r="140"/>
+              <circle cx="200" cy="200" r="180"/>
+            </g>
+            <text x="200" y="195" text-anchor="middle" font-family="serif" font-style="italic" fill="#f2ebdc" font-size="34">Reference</text>
+            <text x="200" y="225" text-anchor="middle" font-family="monospace" fill="#e08038" font-size="11" letter-spacing="4">VOL · I</text>
+            <text x="200" y="368" text-anchor="middle" font-family="monospace" fill="#9c937f" font-size="9" letter-spacing="6" opacity="0.6">STUDIO PRESSING</text>
+            <rect width="400" height="400" fill="url(#vigA)"/>
+          </svg>
+        </div>
+      </div>
+      <svg class="tonearm" viewBox="0 0 200 200" aria-hidden="true">
+        <defs>
+          <linearGradient id="armGrad0" x1="0" x2="1">
+            <stop offset="0" stop-color="#3a3528"/>
+            <stop offset="0.5" stop-color="#9C937F"/>
+            <stop offset="1" stop-color="#5C5447"/>
+          </linearGradient>
+        </defs>
+        <circle cx="176" cy="24" r="14" fill="#1a1611" stroke="#3A3528" stroke-width="1"/>
+        <circle cx="176" cy="24" r="6" fill="#3A3528"/>
+        <circle cx="176" cy="24" r="2" fill="#E08038"/>
+        <line x1="176" y1="24" x2="64" y2="136" stroke="url(#armGrad0)" stroke-width="3.5" stroke-linecap="round"/>
+        <rect x="180" y="14" width="14" height="20" fill="#26211A" stroke="#3A3528"/>
+        <rect x="56" y="128" width="22" height="18" rx="2" fill="#26211A" stroke="#3A3528" transform="rotate(-45 67 137)"/>
+        <circle cx="62" cy="138" r="3" fill="#E08038" opacity="0.8"/>
+        <circle cx="62" cy="138" r="6" fill="none" stroke="#E08038" stroke-width="0.5" opacity="0.4"/>
+      </svg>
+    </div>
+    <div class="label-row">
+      <span class="label-num">00</span>
+      <span class="label-name">Original</span>
+      <span class="label-tag tag-css">control</span>
+    </div>
+    <p class="descr">Current shipping vinyl: pressed grooves, copper-bordered label rim, full album art on the label. Reference baseline for everything below.</p>
+  </article>
+
+  <!-- ═════════ VARIANT 1 — SLEEVE FRAME ═════════ -->
+  <article class="variant v1">
+    <div class="stage">
+      <span class="note">CSS only</span>
+      <div class="sleeve-stage">
+        <div class="sleeve">
+          <div class="sleeve-art">
+            <svg viewBox="0 0 400 400" xmlns="http://www.w3.org/2000/svg">
+              <defs>
+                <linearGradient id="bgB" x1="0" y1="0" x2="1" y2="1">
+                  <stop offset="0%" stop-color="#1F4E3D"/>
+                  <stop offset="55%" stop-color="#143E2F"/>
+                  <stop offset="100%" stop-color="#0a2519"/>
+                </linearGradient>
+              </defs>
+              <rect width="400" height="400" fill="url(#bgB)"/>
+              <g stroke="#e08038" stroke-width="1" fill="none" opacity="0.55">
+                <circle cx="200" cy="200" r="60"/>
+                <circle cx="200" cy="200" r="100"/>
+                <circle cx="200" cy="200" r="140"/>
+                <circle cx="200" cy="200" r="180"/>
+              </g>
+              <text x="200" y="195" text-anchor="middle" font-family="serif" font-style="italic" fill="#f2ebdc" font-size="34">Reference</text>
+              <text x="200" y="225" text-anchor="middle" font-family="monospace" fill="#e08038" font-size="11" letter-spacing="4">VOL · I</text>
+              <text x="200" y="368" text-anchor="middle" font-family="monospace" fill="#9c937f" font-size="9" letter-spacing="6" opacity="0.6">STUDIO PRESSING</text>
+            </svg>
+          </div>
+          <div class="sleeve-corner"></div>
+        </div>
+        <div class="vinyl-wrap">
+          <div class="vinyl">
+            <div class="vinyl-label"></div>
+          </div>
+        </div>
+      </div>
+      <svg class="tonearm" viewBox="0 0 200 200" aria-hidden="true">
+        <use href="#armGrad0"/>
+        <circle cx="176" cy="24" r="14" fill="#1a1611" stroke="#3A3528" stroke-width="1"/>
+        <circle cx="176" cy="24" r="6" fill="#3A3528"/>
+        <circle cx="176" cy="24" r="2" fill="#E08038"/>
+        <line x1="176" y1="24" x2="80" y2="120" stroke="#9C937F" stroke-width="3.5" stroke-linecap="round"/>
+        <rect x="180" y="14" width="14" height="20" fill="#26211A" stroke="#3A3528"/>
+        <rect x="72" y="112" width="22" height="18" rx="2" fill="#26211A" stroke="#3A3528" transform="rotate(-45 83 121)"/>
+        <circle cx="78" cy="122" r="3" fill="#E08038" opacity="0.8"/>
+      </svg>
+    </div>
+    <div class="label-row">
+      <span class="label-num">01</span>
+      <span class="label-name">Sleeve Frame</span>
+      <span class="label-tag tag-css">CSS only</span>
+    </div>
+    <p class="descr">Vinyl peeks out of a square cardstock <strong>sleeve</strong> — paper grain, ring-wear circle, worn-corner notch. The album art lives on the sleeve; the disc gets a plain typographic label. Reads instantly as "record on a turntable", not "spinning disc."</p>
+  </article>
+
+  <!-- ═════════ VARIANT 2 — SHEEN + GRAIN + DEAD-WAX ═════════ -->
+  <article class="variant v2">
+    <div class="stage">
+      <span class="note">CSS only · highest ROI</span>
+      <div class="vinyl">
+        <div class="dead-wax">
+          <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+            <defs>
+              <path id="dwPath" d="M 50,50 m -36,0 a 36,36 0 1,1 72,0 a 36,36 0 1,1 -72,0"/>
+            </defs>
+            <text font-family="monospace" font-size="2.4" fill="#3a3528" letter-spacing="0.45" opacity="0.85">
+              <textPath href="#dwPath">· STUDIO REFERENCE PRESSING · A-SIDE · MASTER LACQUER 24-S · DOLG.AD MASTERED · ½ SPEED</textPath>
+            </text>
+          </svg>
+        </div>
+        <div class="vinyl-label">
+          <svg viewBox="0 0 400 400" class="album-art" xmlns="http://www.w3.org/2000/svg">
+            <defs>
+              <linearGradient id="bgC" x1="0" y1="0" x2="1" y2="1">
+                <stop offset="0%" stop-color="#1F4E3D"/>
+                <stop offset="55%" stop-color="#143E2F"/>
+                <stop offset="100%" stop-color="#0a2519"/>
+              </linearGradient>
+            </defs>
+            <rect width="400" height="400" fill="url(#bgC)"/>
+            <g stroke="#e08038" stroke-width="1" fill="none" opacity="0.55">
+              <circle cx="200" cy="200" r="60"/>
+              <circle cx="200" cy="200" r="100"/>
+              <circle cx="200" cy="200" r="140"/>
+              <circle cx="200" cy="200" r="180"/>
+            </g>
+            <text x="200" y="195" text-anchor="middle" font-family="serif" font-style="italic" fill="#f2ebdc" font-size="34">Reference</text>
+            <text x="200" y="225" text-anchor="middle" font-family="monospace" fill="#e08038" font-size="11" letter-spacing="4">VOL · I</text>
+            <text x="200" y="368" text-anchor="middle" font-family="monospace" fill="#9c937f" font-size="9" letter-spacing="6" opacity="0.6">STUDIO PRESSING</text>
+          </svg>
+          <div class="label-grain"></div>
+        </div>
+        <div class="sheen"></div>
+      </div>
+      <svg class="tonearm" viewBox="0 0 200 200" aria-hidden="true">
+        <circle cx="176" cy="24" r="14" fill="#1a1611" stroke="#3A3528" stroke-width="1"/>
+        <circle cx="176" cy="24" r="6" fill="#3A3528"/>
+        <circle cx="176" cy="24" r="2" fill="#E08038"/>
+        <line x1="176" y1="24" x2="64" y2="136" stroke="#9C937F" stroke-width="3.5" stroke-linecap="round"/>
+        <rect x="180" y="14" width="14" height="20" fill="#26211A" stroke="#3A3528"/>
+        <rect x="56" y="128" width="22" height="18" rx="2" fill="#26211A" stroke="#3A3528" transform="rotate(-45 67 137)"/>
+        <circle cx="62" cy="138" r="3" fill="#E08038" opacity="0.8"/>
+      </svg>
+    </div>
+    <div class="label-row">
+      <span class="label-num">02</span>
+      <span class="label-name">Sheen, Grain &amp; Dead-Wax</span>
+      <span class="label-tag tag-css">CSS only</span>
+    </div>
+    <p class="descr">Three layers added to the existing vinyl: a <strong>fixed reflection sweep</strong> (doesn't rotate with the disc — the studio-light look), <strong>paper grain</strong> on the label so the print sits in cardstock, and a <strong>dead-wax engraving</strong> of the master&#8209;lacquer code spinning with the disc. Off-center spindle by 1.5%. Highest visual ROI for the smallest amount of new code.</p>
+  </article>
+
+  <!-- ═════════ VARIANT 3 — TONE-GRADED ═════════ -->
+  <article class="variant v3">
+    <div class="stage">
+      <span class="note">CSS only</span>
+      <div class="vinyl">
+        <div class="vinyl-label">
+          <svg viewBox="0 0 400 400" class="album-art" xmlns="http://www.w3.org/2000/svg">
+            <defs>
+              <linearGradient id="bgD" x1="0" y1="0" x2="1" y2="1">
+                <stop offset="0%" stop-color="#1F4E3D"/>
+                <stop offset="55%" stop-color="#143E2F"/>
+                <stop offset="100%" stop-color="#0a2519"/>
+              </linearGradient>
+            </defs>
+            <rect width="400" height="400" fill="url(#bgD)"/>
+            <g stroke="#e08038" stroke-width="1" fill="none" opacity="0.55">
+              <circle cx="200" cy="200" r="60"/>
+              <circle cx="200" cy="200" r="100"/>
+              <circle cx="200" cy="200" r="140"/>
+              <circle cx="200" cy="200" r="180"/>
+            </g>
+            <text x="200" y="195" text-anchor="middle" font-family="serif" font-style="italic" fill="#f2ebdc" font-size="34">Reference</text>
+            <text x="200" y="225" text-anchor="middle" font-family="monospace" fill="#e08038" font-size="11" letter-spacing="4">VOL · I</text>
+            <text x="200" y="368" text-anchor="middle" font-family="monospace" fill="#9c937f" font-size="9" letter-spacing="6" opacity="0.6">STUDIO PRESSING</text>
+          </svg>
+          <div class="vignette"></div>
+        </div>
+      </div>
+      <svg class="tonearm" viewBox="0 0 200 200" aria-hidden="true">
+        <circle cx="176" cy="24" r="14" fill="#1a1611" stroke="#3A3528" stroke-width="1"/>
+        <circle cx="176" cy="24" r="6" fill="#3A3528"/>
+        <circle cx="176" cy="24" r="2" fill="#E08038"/>
+        <line x1="176" y1="24" x2="64" y2="136" stroke="#9C937F" stroke-width="3.5" stroke-linecap="round"/>
+        <rect x="180" y="14" width="14" height="20" fill="#26211A" stroke="#3A3528"/>
+        <rect x="56" y="128" width="22" height="18" rx="2" fill="#26211A" stroke="#3A3528" transform="rotate(-45 67 137)"/>
+        <circle cx="62" cy="138" r="3" fill="#E08038" opacity="0.8"/>
+      </svg>
+    </div>
+    <div class="label-row">
+      <span class="label-num">03</span>
+      <span class="label-name">Tone-Graded Cover</span>
+      <span class="label-tag tag-css">CSS only</span>
+    </div>
+    <p class="descr">Same disc, but the album art on the label is <strong>color-graded</strong> — duotone copper/emerald, deeper saturation drop, vignette around the label rim. Effect: every album cover ends up looking like it came from the same pressing plant, matching the Studio Reference chrome.</p>
+  </article>
+
+  <!-- ═════════ VARIANT 4 — SLEEVE-TO-DISC REVEAL ═════════ -->
+  <article class="variant v4">
+    <div class="stage">
+      <span class="note">CSS hover · JS in production</span>
+      <div class="sleeve-stage">
+        <div class="sleeve">
+          <div class="sleeve-art">
+            <svg viewBox="0 0 400 400" xmlns="http://www.w3.org/2000/svg">
+              <defs>
+                <linearGradient id="bgE" x1="0" y1="0" x2="1" y2="1">
+                  <stop offset="0%" stop-color="#1F4E3D"/>
+                  <stop offset="55%" stop-color="#143E2F"/>
+                  <stop offset="100%" stop-color="#0a2519"/>
+                </linearGradient>
+              </defs>
+              <rect width="400" height="400" fill="url(#bgE)"/>
+              <g stroke="#e08038" stroke-width="1" fill="none" opacity="0.55">
+                <circle cx="200" cy="200" r="60"/>
+                <circle cx="200" cy="200" r="100"/>
+                <circle cx="200" cy="200" r="140"/>
+                <circle cx="200" cy="200" r="180"/>
+              </g>
+              <text x="200" y="195" text-anchor="middle" font-family="serif" font-style="italic" fill="#f2ebdc" font-size="34">Reference</text>
+              <text x="200" y="225" text-anchor="middle" font-family="monospace" fill="#e08038" font-size="11" letter-spacing="4">VOL · I</text>
+              <text x="200" y="368" text-anchor="middle" font-family="monospace" fill="#9c937f" font-size="9" letter-spacing="6" opacity="0.6">STUDIO PRESSING</text>
+            </svg>
+          </div>
+        </div>
+        <div class="vinyl-slot">
+          <div class="vinyl">
+            <div class="vinyl-label"></div>
+          </div>
+        </div>
+        <span class="hover-hint">Hover to play</span>
+      </div>
+      <svg class="tonearm" viewBox="0 0 200 200" aria-hidden="true">
+        <circle cx="176" cy="24" r="14" fill="#1a1611" stroke="#3A3528" stroke-width="1"/>
+        <circle cx="176" cy="24" r="6" fill="#3A3528"/>
+        <circle cx="176" cy="24" r="2" fill="#E08038"/>
+        <line x1="176" y1="24" x2="64" y2="136" stroke="#9C937F" stroke-width="3.5" stroke-linecap="round"/>
+        <rect x="180" y="14" width="14" height="20" fill="#26211A" stroke="#3A3528"/>
+        <rect x="56" y="128" width="22" height="18" rx="2" fill="#26211A" stroke="#3A3528" transform="rotate(-45 67 137)"/>
+        <circle cx="62" cy="138" r="3" fill="#E08038" opacity="0.8"/>
+      </svg>
+    </div>
+    <div class="label-row">
+      <span class="label-num">04</span>
+      <span class="label-name">Sleeve-to-Disc Reveal</span>
+      <span class="label-tag tag-needs-js">needs JS</span>
+    </div>
+    <p class="descr"><strong>Hover this card</strong> — the disc slides out of the sleeve and starts spinning. In production, this would be wired to the play/pause state: paused = tucked-in sleeve view, playing = disc revealed and spinning. Most evocative, also the most code (animation choreography + state coupling).</p>
+  </article>
+
+</div>
+
+</body>
+</html>

media_server/tray.py

@@ -0,0 +1,228 @@
+"""System tray icon for Media Server."""
+
+import ctypes
+import io
+import logging
+import sys
+import webbrowser
+from pathlib import Path
+from typing import Callable
+
+from PIL import Image, ImageDraw
+
+logger = logging.getLogger(__name__)
+
+# pystray is optional — tray silently disabled when missing
+try:
+    import pystray
+
+    PYSTRAY_AVAILABLE = True
+except ImportError:
+    pystray = None
+    PYSTRAY_AVAILABLE = False
+
+
+# Windows-native confirmation (no tkinter needed)
+_MB_YESNO = 0x04
+_MB_ICONQUESTION = 0x20
+_MB_TOPMOST = 0x40000
+_MB_SETFOREGROUND = 0x10000
+_IDYES = 6
+
+
+def _confirm(title: str, message: str) -> bool:
+    """Show a Yes/No dialog before a destructive tray action.
+
+    Uses the native Windows MessageBox on win32; on Linux/macOS we don't
+    have a no-dependency GUI dialog available (Tk pulls in tkinter, gtk
+    pulls in PyGObject), so we log + auto-confirm — the tray menu items
+    themselves require a deliberate click already.
+    """
+    if sys.platform == "win32":
+        result = ctypes.windll.user32.MessageBoxW(
+            0,
+            message,
+            title,
+            _MB_YESNO | _MB_ICONQUESTION | _MB_TOPMOST | _MB_SETFOREGROUND,
+        )
+        return result == _IDYES
+
+    logger.info("Tray confirm (auto-yes on non-Windows): %s — %s", title, message)
+    return True
+
+
+# Frame size we ask the multi-resolution ICO for. Most Windows tray surfaces
+# show 16x16 in the notification area and 32x32 in jump lists / Alt+Tab; 64
+# gives pystray enough headroom for both without forcing it to upscale.
+_TRAY_ICON_SIZE = 64
+
+# Palette mirrors media_server/static/icons/icon.svg ("Beacon" design).
+_BG_DARK = (11, 61, 59, 255)        # #0B3D3B
+_BG_LIGHT = (26, 107, 94, 255)      # #1A6B5E
+_FG_PARCHMENT = (245, 241, 232, 255)  # #F5F1E8
+
+
+def _create_icon_image(size: int = _TRAY_ICON_SIZE) -> Image.Image:
+    """Procedural fallback when no icon file is available.
+
+    Matches the "Beacon" palette (deep teal squircle + warm parchment play
+    triangle) so a missing icon.ico does not regress us back to the old
+    Spotify-green circle.
+    """
+    img = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(img)
+
+    # Squircle background. Vertical gradient approximates the diagonal one
+    # in the real SVG well enough for a 64px fallback.
+    radius = int(size * 0.225)
+    for y in range(size):
+        t = y / max(1, size - 1)
+        color = tuple(
+            round(_BG_DARK[i] + (_BG_LIGHT[i] - _BG_DARK[i]) * t) for i in range(3)
+        ) + (255,)
+        draw.line([(0, y), (size - 1, y)], fill=color)
+    mask = Image.new("L", (size, size), 0)
+    ImageDraw.Draw(mask).rounded_rectangle((0, 0, size - 1, size - 1), radius=radius, fill=255)
+    bg = img.copy()
+    img = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    img.paste(bg, (0, 0), mask=mask)
+
+    # Play triangle, positioned to match icon.svg's geometry.
+    draw = ImageDraw.Draw(img)
+    draw.polygon(
+        [
+            (size * 0.345, size * 0.215),
+            (size * 0.345, size * 0.785),
+            (size * 0.755, size * 0.500),
+        ],
+        fill=_FG_PARCHMENT,
+    )
+    return img
+
+
+def _select_frame(image: Image.Image, target: int) -> Image.Image:
+    """Pick the best frame from a multi-resolution ICO.
+
+    Pillow's ICO loader exposes the embedded sizes via ``image.info['sizes']``.
+    We pick the smallest frame at least as large as the target (so we never
+    upscale) and resize down to ``target x target`` with LANCZOS.
+    """
+    sizes = sorted(image.info.get("sizes", []) or [], key=lambda wh: wh[0])
+    chosen = next((wh for wh in sizes if wh[0] >= target), sizes[-1] if sizes else None)
+    if chosen is not None:
+        image.size = chosen
+    frame = image.copy().convert("RGBA")
+    if frame.size != (target, target):
+        frame = frame.resize((target, target), Image.LANCZOS)
+    return frame
+
+
+def _load_icon_image(size: int = _TRAY_ICON_SIZE) -> Image.Image:
+    """Load the app icon for the tray.
+
+    Order:
+      1. ``icon.ico`` — the multi-resolution Windows icon ships with every
+         build; pick the frame closest to ``size`` and downscale if needed.
+      2. ``icon.svg`` via resvg-py (preferred) or cairosvg (legacy).
+      3. Procedural ``_create_icon_image`` fallback.
+    """
+    icons_dir = Path(__file__).parent / "static" / "icons"
+
+    ico_path = icons_dir / "icon.ico"
+    if ico_path.exists():
+        try:
+            with Image.open(ico_path) as ico:
+                return _select_frame(ico, size)
+        except Exception as exc:
+            logger.warning("Failed to load tray icon from %s: %s", ico_path, exc)
+
+    svg_path = icons_dir / "icon.svg"
+    if svg_path.exists():
+        try:
+            import resvg_py
+
+            png_data = resvg_py.svg_to_bytes(
+                svg_string=svg_path.read_text(encoding="utf-8"),
+                width=size,
+                height=size,
+            )
+            return Image.open(io.BytesIO(bytes(png_data))).convert("RGBA")
+        except ImportError:
+            pass
+        except Exception as exc:
+            logger.warning("resvg rasterization of %s failed: %s", svg_path, exc)
+
+        try:
+            import cairosvg
+
+            png_data = cairosvg.svg2png(url=str(svg_path), output_width=size, output_height=size)
+            return Image.open(io.BytesIO(png_data)).convert("RGBA")
+        except Exception:
+            pass
+
+    return _create_icon_image(size)
+
+
+class TrayManager:
+    """Manages the system tray icon and its context menu.
+
+    Call ``run()`` on the **main thread** — it blocks until ``stop()``
+    is called (from any thread) or the user picks *Shutdown* from the menu.
+    """
+
+    def __init__(self, port: int, on_exit: Callable[[], None]) -> None:
+        if not PYSTRAY_AVAILABLE:
+            raise ImportError("pystray is required for system tray support")
+
+        self._port = port
+        self._on_exit = on_exit
+        # Initialize so the property and any cross-thread reader cannot ever
+        # observe an uninitialized attribute. Set before _on_exit() fires.
+        self._restart_requested = False
+
+        menu = pystray.Menu(
+            pystray.MenuItem("Show UI", self._show_ui, default=True),
+            pystray.Menu.SEPARATOR,
+            pystray.MenuItem("Restart", self._restart),
+            pystray.MenuItem("Shutdown", self._shutdown),
+        )
+
+        self._icon = pystray.Icon(
+            name="media-server",
+            icon=_load_icon_image(),
+            title="Media Server",
+            menu=menu,
+        )
+
+    def _show_ui(self, icon: "pystray.Icon", item: "pystray.MenuItem") -> None:
+        webbrowser.open(f"http://localhost:{self._port}")
+
+    def _restart(self, icon: "pystray.Icon", item: "pystray.MenuItem") -> None:
+        if not _confirm("Media Server", "Restart the server?"):
+            return
+        logger.info("Restart requested from tray")
+        # Set the flag BEFORE signalling exit so the main thread observes it
+        # when it wakes from server_thread.join() — order matters across the
+        # tray/uvicorn handoff.
+        self._restart_requested = True
+        self._on_exit()
+        self._icon.stop()
+
+    @property
+    def restart_requested(self) -> bool:
+        return self._restart_requested
+
+    def _shutdown(self, icon: "pystray.Icon", item: "pystray.MenuItem") -> None:
+        if not _confirm("Media Server", "Shut down the server?"):
+            return
+        logger.info("Shutdown requested from tray")
+        self._on_exit()
+        self._icon.stop()
+
+    def run(self) -> None:
+        """Block the calling thread running the tray message loop."""
+        self._icon.run()
+
+    def stop(self) -> None:
+        """Stop the tray icon from any thread."""
+        self._icon.stop()

package-lock.json

@@ -0,0 +1,690 @@
+{
+  "name": "media-server-frontend",
+  "version": "0.4.0",
+  "lockfileVersion": 2,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "media-server-frontend",
+      "version": "0.4.0",
+      "devDependencies": {
+        "esbuild": "^0.27.4"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.4.tgz",
+      "integrity": "sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.4.tgz",
+      "integrity": "sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.4.tgz",
+      "integrity": "sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.4.tgz",
+      "integrity": "sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.4.tgz",
+      "integrity": "sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.4.tgz",
+      "integrity": "sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.4.tgz",
+      "integrity": "sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.4.tgz",
+      "integrity": "sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.4.tgz",
+      "integrity": "sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.4.tgz",
+      "integrity": "sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.4.tgz",
+      "integrity": "sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.4.tgz",
+      "integrity": "sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.4.tgz",
+      "integrity": "sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.4.tgz",
+      "integrity": "sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.4.tgz",
+      "integrity": "sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.4.tgz",
+      "integrity": "sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.4.tgz",
+      "integrity": "sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.4.tgz",
+      "integrity": "sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.4.tgz",
+      "integrity": "sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.4.tgz",
+      "integrity": "sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.4.tgz",
+      "integrity": "sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.4.tgz",
+      "integrity": "sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.4.tgz",
+      "integrity": "sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.4.tgz",
+      "integrity": "sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.4.tgz",
+      "integrity": "sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.4.tgz",
+      "integrity": "sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.4.tgz",
+      "integrity": "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==",
+      "dev": true,
+      "hasInstallScript": true,
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.4",
+        "@esbuild/android-arm": "0.27.4",
+        "@esbuild/android-arm64": "0.27.4",
+        "@esbuild/android-x64": "0.27.4",
+        "@esbuild/darwin-arm64": "0.27.4",
+        "@esbuild/darwin-x64": "0.27.4",
+        "@esbuild/freebsd-arm64": "0.27.4",
+        "@esbuild/freebsd-x64": "0.27.4",
+        "@esbuild/linux-arm": "0.27.4",
+        "@esbuild/linux-arm64": "0.27.4",
+        "@esbuild/linux-ia32": "0.27.4",
+        "@esbuild/linux-loong64": "0.27.4",
+        "@esbuild/linux-mips64el": "0.27.4",
+        "@esbuild/linux-ppc64": "0.27.4",
+        "@esbuild/linux-riscv64": "0.27.4",
+        "@esbuild/linux-s390x": "0.27.4",
+        "@esbuild/linux-x64": "0.27.4",
+        "@esbuild/netbsd-arm64": "0.27.4",
+        "@esbuild/netbsd-x64": "0.27.4",
+        "@esbuild/openbsd-arm64": "0.27.4",
+        "@esbuild/openbsd-x64": "0.27.4",
+        "@esbuild/openharmony-arm64": "0.27.4",
+        "@esbuild/sunos-x64": "0.27.4",
+        "@esbuild/win32-arm64": "0.27.4",
+        "@esbuild/win32-ia32": "0.27.4",
+        "@esbuild/win32-x64": "0.27.4"
+      }
+    }
+  },
+  "dependencies": {
+    "@esbuild/aix-ppc64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.4.tgz",
+      "integrity": "sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/android-arm": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.4.tgz",
+      "integrity": "sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/android-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.4.tgz",
+      "integrity": "sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/android-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.4.tgz",
+      "integrity": "sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/darwin-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.4.tgz",
+      "integrity": "sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/darwin-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.4.tgz",
+      "integrity": "sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/freebsd-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.4.tgz",
+      "integrity": "sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/freebsd-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.4.tgz",
+      "integrity": "sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/linux-arm": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.4.tgz",
+      "integrity": "sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/linux-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.4.tgz",
+      "integrity": "sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/linux-ia32": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.4.tgz",
+      "integrity": "sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/linux-loong64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.4.tgz",
+      "integrity": "sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/linux-mips64el": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.4.tgz",
+      "integrity": "sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/linux-ppc64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.4.tgz",
+      "integrity": "sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/linux-riscv64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.4.tgz",
+      "integrity": "sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/linux-s390x": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.4.tgz",
+      "integrity": "sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/linux-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.4.tgz",
+      "integrity": "sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/netbsd-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.4.tgz",
+      "integrity": "sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/netbsd-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.4.tgz",
+      "integrity": "sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/openbsd-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.4.tgz",
+      "integrity": "sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/openbsd-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.4.tgz",
+      "integrity": "sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/openharmony-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.4.tgz",
+      "integrity": "sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/sunos-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.4.tgz",
+      "integrity": "sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/win32-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.4.tgz",
+      "integrity": "sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/win32-ia32": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.4.tgz",
+      "integrity": "sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==",
+      "dev": true,
+      "optional": true
+    },
+    "@esbuild/win32-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.4.tgz",
+      "integrity": "sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==",
+      "dev": true,
+      "optional": true
+    },
+    "esbuild": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.4.tgz",
+      "integrity": "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==",
+      "dev": true,
+      "requires": {
+        "@esbuild/aix-ppc64": "0.27.4",
+        "@esbuild/android-arm": "0.27.4",
+        "@esbuild/android-arm64": "0.27.4",
+        "@esbuild/android-x64": "0.27.4",
+        "@esbuild/darwin-arm64": "0.27.4",
+        "@esbuild/darwin-x64": "0.27.4",
+        "@esbuild/freebsd-arm64": "0.27.4",
+        "@esbuild/freebsd-x64": "0.27.4",
+        "@esbuild/linux-arm": "0.27.4",
+        "@esbuild/linux-arm64": "0.27.4",
+        "@esbuild/linux-ia32": "0.27.4",
+        "@esbuild/linux-loong64": "0.27.4",
+        "@esbuild/linux-mips64el": "0.27.4",
+        "@esbuild/linux-ppc64": "0.27.4",
+        "@esbuild/linux-riscv64": "0.27.4",
+        "@esbuild/linux-s390x": "0.27.4",
+        "@esbuild/linux-x64": "0.27.4",
+        "@esbuild/netbsd-arm64": "0.27.4",
+        "@esbuild/netbsd-x64": "0.27.4",
+        "@esbuild/openbsd-arm64": "0.27.4",
+        "@esbuild/openbsd-x64": "0.27.4",
+        "@esbuild/openharmony-arm64": "0.27.4",
+        "@esbuild/sunos-x64": "0.27.4",
+        "@esbuild/win32-arm64": "0.27.4",
+        "@esbuild/win32-ia32": "0.27.4",
+        "@esbuild/win32-x64": "0.27.4"
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,13 @@
+{
+  "name": "media-server-frontend",
+  "version": "0.4.0",
+  "private": true,
+  "description": "Frontend build tooling for media server WebUI",
+  "scripts": {
+    "build": "node esbuild.mjs",
+    "watch": "node esbuild.mjs --watch"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.4"
+  }
+}

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "media-server"
-version = "1.0.0"
+version = "0.4.0"
 description = "REST API server for controlling system-wide media playback"
 readme = "README.md"
 license = { text = "MIT" }
@@ -30,19 +30,48 @@ dependencies = [
     "pydantic>=2.0",
     "pydantic-settings>=2.0",
     "pyyaml>=6.0",
+    "mutagen>=1.47.0",
+    "pillow>=10.0.0",
+    "soundcard>=0.4.0",
+    "numpy>=1.24.0,<2.0",
+    # screen-brightness-control + monitorcontrol are cross-platform
+    # (Windows / Linux i2c-dev). Kept in base deps so a plain
+    # `pip install media-server` yields a working /api/display on any
+    # platform that has the underlying hardware support.
+    "screen-brightness-control>=0.20.0",
+    "monitorcontrol>=3.0.0",
 ]
 
 [project.optional-dependencies]
 windows = [
     "winsdk>=1.0.0b10",
-    "pywin32>=306",
-    "comtypes>=1.2.0",
-    "pycaw>=20230407",
+    "pywin32>=306; sys_platform == 'win32'",
+    "comtypes>=1.2.0; sys_platform == 'win32'",
+    "pycaw>=20230407; sys_platform == 'win32'",
+    "wmi>=1.5.1; sys_platform == 'win32'",
+    "pystray>=0.19.0",
+]
+linux = [
+    # MPRIS / D-Bus media control. Requires libdbus-1-dev, libglib2.0-dev,
+    # and pkg-config installed on the host before pip install.
+    "dbus-python>=1.3.2; sys_platform == 'linux'",
+    "PyGObject>=3.46; sys_platform == 'linux'",
+    # X11 foreground-window probe (Wayland sessions degrade gracefully).
+    "python-xlib>=0.33; sys_platform == 'linux'",
+]
+macos = [
+    # PyObjC for the foreground-window + active-app probes.
+    "pyobjc-framework-Cocoa>=10.0; sys_platform == 'darwin'",
+    "pyobjc-framework-Quartz>=10.0; sys_platform == 'darwin'",
 ]
 dev = [
     "pytest>=7.0",
     "pytest-asyncio>=0.21",
     "httpx>=0.24",
+    "ruff>=0.4.0",
+    # SVG -> PNG rasterizer used by scripts/generate-icon.py to (re)build
+    # media_server/static/icons/icon.ico from icon.svg. Build-time only.
+    "resvg-py>=0.3.2",
 ]
 
 [project.urls]
@@ -59,3 +88,18 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
 include = ["media_server*"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.ruff.lint.per-file-ignores]
+# AppleScript string literals contain long lines that cannot be broken
+"media_server/services/macos_media.py" = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

scripts/generate-icon.py

@@ -0,0 +1,113 @@
+"""Generate the Media Server application icon.
+
+The SVG in ``media_server/static/icons/icon.svg`` is the single source of
+truth. This script rasterizes it at every Windows ICO size via ``resvg-py``
+(Rust-backed, identical math to Firefox's SVG renderer) and packs them all
+into a multi-resolution ``icon.ico``.
+
+This replaces the original 16x16-only ICO that Windows was upscaling into
+mush for the installer chrome, Start Menu, desktop shortcuts, and Alt+Tab.
+
+Usage:
+    python scripts/generate-icon.py
+
+Dependencies:
+    pip install resvg-py Pillow
+"""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+import resvg_py
+from PIL import Image
+
+# Sizes packed into the ICO. Windows picks the closest match per surface;
+# more sizes = sharper rendering everywhere (taskbar, installer header,
+# Alt+Tab, jump lists, Start tile, desktop, file explorer details/tiles).
+ICO_SIZES: tuple[int, ...] = (16, 20, 24, 32, 40, 48, 64, 96, 128, 256)
+
+# The SVG source. Squircle + diagonal teal gradient + warm parchment play
+# triangle with a drop shadow + ghosted echo-chevrons hinting at broadcast.
+SVG_SOURCE = """<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-label="Media Server">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%"  stop-color="#0B3D3B"/>
+      <stop offset="100%" stop-color="#1A6B5E"/>
+    </linearGradient>
+    <linearGradient id="sheen" x1="50%" y1="0%" x2="50%" y2="100%">
+      <stop offset="0%"  stop-color="#FFFFFF" stop-opacity="0.18"/>
+      <stop offset="55%" stop-color="#FFFFFF" stop-opacity="0"/>
+    </linearGradient>
+    <filter id="triShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="3"/>
+      <feOffset dx="3" dy="5"/>
+      <feComponentTransfer><feFuncA type="linear" slope="0.45"/></feComponentTransfer>
+      <feMerge><feMergeNode/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+    <clipPath id="clip"><rect x="0" y="0" width="256" height="256" rx="58" ry="58"/></clipPath>
+  </defs>
+  <g clip-path="url(#clip)">
+    <rect width="256" height="256" fill="url(#bg)"/>
+    <rect width="256" height="256" fill="url(#sheen)"/>
+    <g stroke="#F5F1E8" stroke-width="4.6" stroke-linecap="round" stroke-linejoin="round" fill="none" opacity="0.18">
+      <polyline points="66,72 105,128 66,184"/>
+      <polyline points="85,82 124,128 85,174" opacity="0.6"/>
+    </g>
+    <path d="M88.3 55 L88.3 201 L193.3 128 Z"
+          fill="#F5F1E8"
+          stroke="#F5F1E8" stroke-width="9" stroke-linejoin="round"
+          filter="url(#triShadow)"/>
+  </g>
+  <rect x="0.5" y="0.5" width="255" height="255" rx="58" ry="58"
+        fill="none" stroke="#000000" stroke-opacity="0.18" stroke-width="1"/>
+</svg>
+"""
+
+
+def _render_png(size: int) -> Image.Image:
+    """Rasterize the SVG to a PNG at ``size x size`` via resvg."""
+    data = resvg_py.svg_to_bytes(
+        svg_string=SVG_SOURCE,
+        width=size,
+        height=size,
+        shape_rendering="geometric_precision",
+    )
+    return Image.open(io.BytesIO(bytes(data))).convert("RGBA")
+
+
+def main() -> None:
+    root = Path(__file__).resolve().parent.parent
+    out_dir = root / "media_server" / "static" / "icons"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # SVG — canonical source, also used as the Web UI favicon.
+    svg_path = out_dir / "icon.svg"
+    svg_path.write_text(SVG_SOURCE, encoding="utf-8")
+    print(f"wrote {svg_path}")
+
+    # Rasterize every ICO size via resvg.
+    frames = [_render_png(size) for size in ICO_SIZES]
+
+    # Pack into a multi-resolution ICO. The "primary" image must be the
+    # largest; the rest go via append_images. Pillow's ICO writer then
+    # serializes one frame per size.
+    primary = frames[-1]
+    ico_path = out_dir / "icon.ico"
+    primary.save(
+        ico_path,
+        format="ICO",
+        sizes=[(s, s) for s in ICO_SIZES],
+        append_images=frames[:-1],
+    )
+    print(f"wrote {ico_path}  ({ico_path.stat().st_size:,} bytes, sizes={list(ICO_SIZES)})")
+
+    # Largest PNG for documentation / non-Windows surfaces.
+    png_path = out_dir / "icon-256.png"
+    primary.save(png_path, format="PNG", optimize=True)
+    print(f"wrote {png_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/install_task_windows.ps1

@@ -0,0 +1,19 @@
+Unregister-ScheduledTask -TaskName "MediaServer" -Confirm:$false -ErrorAction SilentlyContinue
+
+# Get the media-server directory (parent of scripts folder)
+$serverRoot = (Get-Item $PSScriptRoot).Parent.FullName
+$vbsPath = Join-Path $PSScriptRoot "start-hidden.vbs"
+
+if (-not (Test-Path $vbsPath)) {
+    Write-Error "start-hidden.vbs not found in scripts folder."
+    exit 1
+}
+
+# Launch via wscript + VBS to run python completely hidden (no console window)
+$action = New-ScheduledTaskAction -Execute "wscript.exe" -Argument "`"$vbsPath`"" -WorkingDirectory $serverRoot
+$trigger = New-ScheduledTaskTrigger -AtLogon -User "$env:USERNAME"
+$principal = New-ScheduledTaskPrincipal -UserId "$env:USERNAME" -LogonType Interactive -RunLevel Highest
+$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable
+Register-ScheduledTask -TaskName "MediaServer" -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Description "Media Server for Home Assistant"
+
+Write-Host "Scheduled task 'MediaServer' created with working directory: $serverRoot"

scripts/restart-server.ps1

@@ -0,0 +1,103 @@
+# Restart the Media Server.
+#
+# Robust against the two ways the server gets started:
+#   - Installer build:   %LOCALAPPDATA%\Media Server\media-server.bat
+#                        (runs as python.exe -m media_server.main)
+#   - Dev editable install: media-server console script on PATH
+#                        (runs as media-server.exe)
+#
+# The old version of this script only killed processes named 'media-server',
+# which silently missed the installer-bundled process (named 'python').
+# This version kills whatever currently owns the listen port, so it doesn't
+# matter how the previous instance was launched.
+
+param(
+    [ValidateSet('auto', 'dev', 'installer')]
+    [string]$Mode = 'auto',
+    [int]$Port = 8765
+)
+
+$InstallerLauncher = Join-Path $env:LOCALAPPDATA 'Media Server\media-server.bat'
+$InstallerDir = Join-Path $env:LOCALAPPDATA 'Media Server'
+
+# --- Resolve launch mode -----------------------------------------------------
+if ($Mode -eq 'auto') {
+    if (Test-Path $InstallerLauncher) {
+        $Mode = 'installer'
+    } else {
+        $Mode = 'dev'
+    }
+}
+
+# --- Stop whatever is listening on the port ---------------------------------
+$listenerPids = @()
+try {
+    $conns = Get-NetTCPConnection -LocalPort $Port -State Listen -ErrorAction SilentlyContinue
+    if ($conns) {
+        $listenerPids = $conns | Select-Object -ExpandProperty OwningProcess -Unique
+    }
+} catch {
+    # Get-NetTCPConnection unavailable (rare); fall back to netstat parsing
+    $listenerPids = & netstat -ano | Select-String ":$Port\s+.*LISTENING" | ForEach-Object {
+        ($_ -split '\s+')[-1]
+    } | Sort-Object -Unique
+}
+
+foreach ($targetPid in $listenerPids) {
+    $proc = Get-Process -Id $targetPid -ErrorAction SilentlyContinue
+    if ($proc) {
+        Write-Host "Stopping listener PID $($proc.Id) ($($proc.ProcessName))..."
+        Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue
+    }
+}
+
+# Also kill any orphan media-server.exe instances that didn't bind the port.
+$orphans = Get-Process -Name 'media-server' -ErrorAction SilentlyContinue
+foreach ($p in $orphans) {
+    Write-Host "Stopping orphan media-server PID $($p.Id)..."
+    Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue
+}
+
+if ($listenerPids -or $orphans) {
+    # Allow the OS to release the listen socket from TIME_WAIT.
+    Start-Sleep -Seconds 3
+}
+
+# --- Start the chosen flavour ------------------------------------------------
+if ($Mode -eq 'installer') {
+    if (-not (Test-Path $InstallerLauncher)) {
+        Write-Error "Installer launcher not found: $InstallerLauncher"
+        exit 1
+    }
+    Write-Host "Starting installer build: $InstallerLauncher"
+    Start-Process -FilePath $InstallerLauncher `
+        -WorkingDirectory $InstallerDir `
+        -WindowStyle Hidden
+} else {
+    # Merge registry PATH so newly-installed dev tools are visible.
+    $regUser = [Environment]::GetEnvironmentVariable('PATH', 'User')
+    if ($regUser) {
+        $currentDirs = $env:PATH -split ';' | ForEach-Object { $_.TrimEnd('\') }
+        foreach ($dir in ($regUser -split ';')) {
+            if ($dir -and ($currentDirs -notcontains $dir.TrimEnd('\'))) {
+                $env:PATH = "$env:PATH;$dir"
+            }
+        }
+    }
+    Write-Host "Starting dev install (PATH media-server)..."
+    Start-Process -FilePath 'media-server' `
+        -WorkingDirectory 'c:\Users\Alexei\Documents\haos-integration-media-player\media-server' `
+        -WindowStyle Hidden
+}
+
+Start-Sleep -Seconds 3
+
+# --- Verify it's listening ---------------------------------------------------
+$verify = Get-NetTCPConnection -LocalPort $Port -State Listen -ErrorAction SilentlyContinue
+if ($verify) {
+    $vpid = $verify[0].OwningProcess
+    $vproc = Get-Process -Id $vpid -ErrorAction SilentlyContinue
+    Write-Host "Server listening on port $Port (PID $vpid, $($vproc.ProcessName))"
+} else {
+    Write-Warning "Server is not listening on port $Port yet - check logs."
+}

scripts/start-hidden.vbs

@@ -0,0 +1,13 @@
+Set fso = CreateObject("Scripting.FileSystemObject")
+Set WshShell = CreateObject("WScript.Shell")
+' Get the directory of this script (scripts\), then go up to media-server root
+scriptDir = fso.GetParentFolderName(WScript.ScriptFullName)
+serverRoot = fso.GetParentFolderName(scriptDir)
+WshShell.CurrentDirectory = serverRoot
+' Use embedded Python if present (installed distribution), otherwise system Python
+embeddedPython = serverRoot & "\python\python.exe"
+If fso.FileExists(embeddedPython) Then
+    WshShell.Run """" & embeddedPython & """ -m media_server.main", 0, False
+Else
+    WshShell.Run "python -m media_server.main", 0, False
+End If