feat(soundtouch-web): add multi-room zone management

Backend:
- GET /api/zone/{id} — zone info enriched with device names and role flags
- POST /api/zone/{id}/add/{slaveId} — add slave (creates zone if standalone)
- POST /api/zone/{id}/remove/{slaveId} — remove slave from zone
- POST /api/zone/{id}/dissolve — dissolve zone to standalone
- POST /api/zone/{id}/leave — slave leaves its zone (backend finds master)

Frontend (Zone.js):
- Standalone: shows "Group with…" button, opens device picker overlay
- Master: member list with per-row Remove, Add speaker, Dissolve buttons
- Slave: shows master name, Leave zone button
- Lazy-loads on device detail open; refreshes after each zone operation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,33 @@
+# .dockerignore
+
+# Exclude large firmware files and archives
+firmware/
+data/
+
+# Exclude local build artifacts
+build/
+soundtouch-cli
+soundtouch-service
+
+# Exclude Go specific files that aren't needed for build context
+# (go.mod and go.sum ARE needed, but other local stuff isn't)
+.cache/
+vendor/
+
+# Exclude IDE and system files
+.idea/
+.vscode/
+.DS_Store
+
+# Exclude Git history
+.git/
+.gitignore
+
+# Exclude documentation and other non-essential files for the binary build
+docs/
+examples/
+scripts/
+CONTRIBUTING.md
+CODE_OF_CONDUCT.md
+LICENSE
+README.md

.docsignore

@@ -0,0 +1,5 @@
+# Files intentionally not linked in docs/SUMMARY.md.
+# Paths are relative to the docs/ directory.
+# Lines starting with # and blank lines are ignored.
+
+#analysis/bose-soundtouch-community-tools.md

.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.html]
+# HTML-specific formatting
+# Standardize on tag layout
+ij_html_do_not_indent_children_of_tags = html,body,thead,tbody,tfoot
+ij_html_keep_blank_lines = 1
+ij_html_attribute_wrap = normal
+ij_html_space_inside_empty_tag = false

.env.example

@@ -1,6 +1,10 @@
 # Bose SoundTouch Configuration
 # Copy this file to .env and customize for your setup
 
+# Docker/Service Settings
+SOUNDTOUCH_HOSTNAME=soundtouch.local
+SOUNDTOUCH_VERSION=latest
+
 # Discovery Settings
 DISCOVERY_TIMEOUT=5s
 UPNP_ENABLED=true
@@ -38,3 +42,20 @@ PREFERRED_DEVICES="Living Room@192.168.1.100:8090;Kitchen@192.168.1.101;192.168.
 # Alternative format examples:
 # PREFERRED_DEVICES="192.168.178.35;192.168.178.28"
 # PREFERRED_DEVICES="SoundTouch 10@192.168.178.35;SoundTouch 20@192.168.178.28"
+
+# Spotify Integration
+# Create an app at https://developer.spotify.com/dashboard
+# SPOTIFY_CLIENT_ID=your_client_id
+# SPOTIFY_CLIENT_SECRET=your_client_secret
+# Auth confirmation url using GET, works in browsers
+# SPOTIFY_REDIRECT_URI=https://your-server.example.com/mgmt/spotify/callback
+# Auth confirmation url using POST, works with the ueberboese-app (https://github.com/julius-d/ueberboese-app)
+# SPOTIFY_REDIRECT_URI=https://your-server.example.com/mgmt/spotify/confirm
+
+# Management API Authentication
+# Protects /mgmt/* endpoints (Spotify token access, account management)
+MGMT_USERNAME=admin
+MGMT_PASSWORD=change_me!
+
+# External base URL (required when behind a reverse proxy for OAuth callbacks)
+# BASE_URL=https://your-server.example.com

.github/dependabot.yml

@@ -77,3 +77,24 @@ updates:
           - "*scan*"
           - "securecodewarrior/*"
           - "codecov/*"
+
+  # Docker dependency updates
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "wednesday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 3
+    reviewers:
+      - "gesellix"
+    assignees:
+      - "gesellix"
+    commit-message:
+      prefix: "docker"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "docker"
+    rebase-strategy: "auto"

.github/markdown-link-check.json

@@ -25,6 +25,24 @@
     },
     {
       "pattern": "^https://pkg.go.dev.*badge"
+    },
+    {
+      "pattern": "^\\.\\./images/(dashboard-home|account-creation|account-dashboard|usb-remote-services|device-discovery|device-registration|account-migration|migration-setup|migration-progress|migration-health|migration-complete|backup-setup)\\.png$"
+    },
+    {
+      "pattern": "https://www.contributor-covenant.org/version/2/0/code_of_conduct.html"
+    },
+    {
+      "pattern": "https://www.apkmirror.com/apk/bose-corporation/bose-soundtouch/"
+    },
+    {
+      "pattern": "https://apkpure.com/bose-soundtouch/com.bose.soundtouch"
+    },
+    {
+      "pattern": "^https://bose\\.fandom\\.com/"
+    },
+    {
+      "pattern": "^https://www\\.reddit\\.com/"
     }
   ],
   "replacementPatterns": [

.github/workflows/ci.yml

@@ -1,5 +1,8 @@
 name: CI
 
+permissions:
+  contents: read
+
 on:
   push:
     branches: [main]
@@ -31,6 +34,9 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-go-
 
+      - name: Install libpcap
+        run: sudo apt-get install -y libpcap-dev
+
       - name: Download dependencies
         run: go mod download
 
@@ -40,8 +46,14 @@ jobs:
       - name: Run tests
         run: go test -v -race -coverprofile=coverage.out ./...
 
+      - name: Build service
+        run: make build-service
+
+      - name: Run HTTP client integration tests
+        run: make test-http-client
+
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           file: ./coverage.out
           flags: unittests
@@ -61,6 +73,9 @@ jobs:
         with:
           go-version-file: "go.mod"
 
+      - name: Install libpcap
+        run: sudo apt-get install -y libpcap-dev
+
       - name: Run golangci-lint
         uses: golangci/golangci-lint-action@v9
         with:
@@ -97,10 +112,10 @@ jobs:
           if [ "${{ matrix.goos }}" = "windows" ]; then
             output_name="${output_name}.exe"
           fi
-          go build -o "$output_name" ./cmd/soundtouch-cli
+          go build -trimpath -ldflags="-s -w" -o "$output_name" ./cmd/soundtouch-cli
 
       - name: Upload build artifacts
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: soundtouch-cli-${{ matrix.goos }}-${{ matrix.goarch }}
           path: soundtouch-cli-*
@@ -118,6 +133,9 @@ jobs:
         with:
           go-version-file: "go.mod"
 
+      - name: Install libpcap
+        run: sudo apt-get install -y libpcap-dev
+
       - name: Run basic vulnerability check
         run: |
           go install golang.org/x/vuln/cmd/govulncheck@latest
@@ -138,19 +156,40 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Check documentation links
-        uses: gaurav-nelson/github-action-markdown-link-check@v1
-        with:
-          use-quiet-mode: "yes"
-          use-verbose-mode: "yes"
-          config-file: ".github/markdown-link-check.json"
+        run: |
+          npm install -g markdown-link-check
+          find . -name "*.md" -not -path "./tests/*" -not -path "./node_modules/*" -print0 | xargs -0 -n1 markdown-link-check -q -v -c .github/markdown-link-check.json
+
+      - name: Warn on pending images
+        run: |
+          IMAGES=(
+            "dashboard-home.png"
+            "account-creation.png"
+            "account-dashboard.png"
+            "usb-remote-services.png"
+            "device-discovery.png"
+            "device-registration.png"
+            "account-migration.png"
+            "migration-setup.png"
+            "migration-progress.png"
+            "migration-health.png"
+            "migration-complete.png"
+            "backup-setup.png"
+          )
+
+          for img in "${IMAGES[@]}"; do
+            if [ ! -f "docs/images/$img" ]; then
+              echo "::warning file=docs/guides/MIGRATION-GUIDE.md::Pending image '$img' is missing from docs/images/"
+            fi
+          done
 
       - name: Validate API documentation
         run: |
           # Check that all documented endpoints exist in code
           echo "Validating API documentation consistency..."
 
-          # Extract endpoint patterns from cookbook
-          if [ -f "docs/API-COOKBOOK.md" ]; then
+          # Check API cookbook
+          if [ -f "docs/reference/API-COOKBOOK.md" ]; then
             echo "✓ API Cookbook exists"
           else
             echo "✗ API Cookbook missing"
@@ -158,7 +197,7 @@ jobs:
           fi
 
           # Check getting started guide
-          if [ -f "docs/GETTING-STARTED.md" ]; then
+          if [ -f "docs/guides/GETTING-STARTED.md" ]; then
             echo "✓ Getting Started guide exists"
           else
             echo "✗ Getting Started guide missing"
@@ -181,7 +220,7 @@ jobs:
 
       - name: Test CLI build and help
         run: |
-          go build -o soundtouch-cli ./cmd/soundtouch-cli
+          go build -trimpath -ldflags="-s -w" -o soundtouch-cli ./cmd/soundtouch-cli
           ./soundtouch-cli -help
 
       - name: Test library imports
@@ -218,10 +257,74 @@ jobs:
           go run test_import.go
           rm test_import.go
 
+  docker:
+    name: Docker Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for soundtouch-service
+        id: meta-service
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
+            type=ref,event=pr
+
+      - name: Build and push soundtouch-service Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: soundtouch-service
+          platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
+          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          tags: ${{ steps.meta-service.outputs.tags }}
+          labels: ${{ steps.meta-service.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Extract metadata (tags, labels) for soundtouch-web
+        id: meta-web
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}-web
+          tags: |
+            type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
+            type=ref,event=pr
+
+      - name: Build and push soundtouch-web Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: soundtouch-web
+          platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
+          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          tags: ${{ steps.meta-web.outputs.tags }}
+          labels: ${{ steps.meta-web.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
   notify:
     name: Notify Status
     runs-on: ubuntu-latest
-    needs: [test, lint, build, security, docs]
+    needs: [test, lint, build, security, docs, docker]
     if: always()
     permissions:
       statuses: write
@@ -234,7 +337,8 @@ jobs:
                 "${{ needs.lint.result }}" == "success" && \
                 "${{ needs.build.result }}" == "success" && \
                 "${{ needs.security.result }}" == "success" && \
-                "${{ needs.docs.result }}" == "success" ]]; then
+                "${{ needs.docs.result }}" == "success" && \
+                "${{ needs.docker.result }}" == "success" ]]; then
             echo "✅ All CI checks passed!"
             echo "status=success" >> $GITHUB_OUTPUT
           else
@@ -244,13 +348,14 @@ jobs:
             echo "Build: ${{ needs.build.result }}"
             echo "Security: ${{ needs.security.result }}"
             echo "Docs: ${{ needs.docs.result }}"
+            echo "Docker: ${{ needs.docker.result }}"
             echo "status=failure" >> $GITHUB_OUTPUT
           fi
         id: status
 
       - name: Update commit status
         if: always()
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             try {

.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: Deploy Documentation
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: 'docs/'
+          destination: '_site'
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: '_site'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/release.yml

@@ -13,6 +13,7 @@ on:
 permissions:
   contents: write
   actions: read
+  packages: write
 
 env:
   GO_VERSION_FILE: "go.mod"
@@ -67,6 +68,9 @@ jobs:
         with:
           go-version-file: ${{ env.GO_VERSION_FILE }}
 
+      - name: Install libpcap
+        run: sudo apt-get install -y libpcap-dev
+
       - name: Run tests before release
         run: |
           echo "Running final tests before release..."
@@ -113,100 +117,103 @@ jobs:
             ~/go/pkg/mod
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.mod') }}-${{ hashFiles('**/go.sum') }}
 
-      - name: Build binary
+      - name: Build binaries
         env:
           GOOS: ${{ matrix.goos }}
           GOARCH: ${{ matrix.goarch }}
           GOARM: ${{ matrix.goarm }}
           CGO_ENABLED: 0
         run: |
-          # Determine output filename
-          BINARY_NAME="soundtouch-cli"
+          # Common variables
           ARCH_SUFFIX="${{ matrix.goos }}-${{ matrix.goarch }}"
-
           if [[ "${{ matrix.goarm }}" != "" ]]; then
             ARCH_SUFFIX="${ARCH_SUFFIX}v${{ matrix.goarm }}"
           fi
 
-          if [[ "${{ matrix.goos }}" == "windows" ]]; then
-            OUTPUT_NAME="${BINARY_NAME}-v${{ needs.validate.outputs.version }}-${ARCH_SUFFIX}.exe"
-          else
-            OUTPUT_NAME="${BINARY_NAME}-v${{ needs.validate.outputs.version }}-${ARCH_SUFFIX}"
-          fi
+          # Function to build a binary
+          build_binary() {
+            local BINARY_NAME=$1
+            local CMD_PATH=$2
+            local OUTPUT_NAME
 
-          echo "Building: $OUTPUT_NAME"
+            # Ensure build directory exists
+            mkdir -p build
 
-          # Debug: Show current state
-          echo "Working directory: $(pwd)"
-          echo "Go version: $(go version)"
-          echo "Files before build:"
-          ls -la
+            if [[ "${{ matrix.goos }}" == "windows" ]]; then
+              OUTPUT_NAME="build/${BINARY_NAME}-v${{ needs.validate.outputs.version }}-${ARCH_SUFFIX}.exe"
+            else
+              OUTPUT_NAME="build/${BINARY_NAME}-v${{ needs.validate.outputs.version }}-${ARCH_SUFFIX}"
+            fi
 
-          # Debug: Show Go cache and module cache
-          echo "Go build cache location: $(go env GOCACHE)"
-          echo "Go module cache location: $(go env GOMODCACHE)"
-          echo "Go build cache contents:"
-          ls -la "$(go env GOCACHE)" 2>/dev/null || echo "Cache directory not accessible"
-          echo "Go module cache contents (top level):"
-          ls -la "$(go env GOMODCACHE)" 2>/dev/null || echo "Module cache directory not accessible"
+            echo "Building $BINARY_NAME: $OUTPUT_NAME"
 
-          # Ensure clean build environment
-          rm -f "$OUTPUT_NAME" "$OUTPUT_NAME.sha256" "$OUTPUT_NAME.sha512"
-          go clean -cache
+            # Ensure clean build environment for this binary
+            rm -f "$OUTPUT_NAME" "$OUTPUT_NAME.sha256" "$OUTPUT_NAME.sha512"
 
-          # Build with optimizations (using debug.BuildInfo for version info)
-          if ! go build \
-            -ldflags="-s -w" \
-            -o "$OUTPUT_NAME" \
-            ./cmd/soundtouch-cli; then
-            echo "❌ Build failed"
-            echo "Files after failed build:"
-            ls -la
-            exit 1
-          fi
+            if ! go build \
+              -trimpath \
+              -ldflags="-s -w" \
+              -o "$OUTPUT_NAME" \
+              "$CMD_PATH"; then
+              echo "❌ Build failed for $BINARY_NAME"
+              exit 1
+            fi
 
-          # Debug: Show post-build state
-          echo "Files after successful build:"
-          ls -la
+            # Verify binary was created
+            ls -la "$OUTPUT_NAME"
+            echo "$BINARY_NAME=$OUTPUT_NAME" >> $GITHUB_OUTPUT
+          }
 
-          # Verify binary was created and is executable
-          ls -la "$OUTPUT_NAME"
-          file "$OUTPUT_NAME"
+          # Build CLI
+          build_binary "soundtouch-cli" "./cmd/soundtouch-cli"
 
-          echo "binary_name=$OUTPUT_NAME" >> $GITHUB_OUTPUT
+          # Build Service
+          build_binary "soundtouch-service" "./cmd/soundtouch-service"
+
+          # Build Web
+          build_binary "soundtouch-web" "./cmd/soundtouch-web"
+
+          # Build Backup
+          build_binary "soundtouch-backup" "./cmd/soundtouch-backup"
         id: build
 
-      - name: Generate individual checksum
+      - name: Generate individual checksums
         run: |
-          OUTPUT_NAME="${{ steps.build.outputs.binary_name }}"
+          CLI_NAME="${{ steps.build.outputs.soundtouch-cli }}"
+          SVC_NAME="${{ steps.build.outputs.soundtouch-service }}"
+          WEB_NAME="${{ steps.build.outputs.soundtouch-web }}"
+          BCK_NAME="${{ steps.build.outputs.soundtouch-backup }}"
 
           # Use atomic operations to avoid conflicts
           TEMP_DIR=$(mktemp -d)
 
-          echo "Building checksums for: $OUTPUT_NAME"
-          echo "Matrix: ${{ matrix.goos }}-${{ matrix.goarch }}"
+          generate_checksums() {
+            local FILE=$1
+            echo "Building checksums for: $FILE"
+            sha256sum "$FILE" > "${TEMP_DIR}/$(basename "$FILE").sha256"
+            sha512sum "$FILE" > "${TEMP_DIR}/$(basename "$FILE").sha512"
+            mv "${TEMP_DIR}/$(basename "$FILE").sha256" "$FILE.sha256"
+            mv "${TEMP_DIR}/$(basename "$FILE").sha512" "$FILE.sha512"
+          }
 
-          # Generate checksums in temp directory first
-          sha256sum "$OUTPUT_NAME" > "${TEMP_DIR}/$(basename "$OUTPUT_NAME").sha256"
-          sha512sum "$OUTPUT_NAME" > "${TEMP_DIR}/$(basename "$OUTPUT_NAME").sha512"
-
-          # Move to final location atomically
-          mv "${TEMP_DIR}/$(basename "$OUTPUT_NAME").sha256" "$OUTPUT_NAME.sha256"
-          mv "${TEMP_DIR}/$(basename "$OUTPUT_NAME").sha512" "$OUTPUT_NAME.sha512"
+          generate_checksums "$CLI_NAME"
+          generate_checksums "$SVC_NAME"
+          generate_checksums "$WEB_NAME"
+          generate_checksums "$BCK_NAME"
 
           # Cleanup
           rm -rf "$TEMP_DIR"
-
           echo "✅ Checksums generated successfully"
 
       - name: Upload build artifact
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
-          name: ${{ steps.build.outputs.binary_name }}
+          name: binaries-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.goarm }}
           path: |
-            ${{ steps.build.outputs.binary_name }}
-            ${{ steps.build.outputs.binary_name }}.sha256
-            ${{ steps.build.outputs.binary_name }}.sha512
+            build/soundtouch-cli-v*
+            build/soundtouch-service-v*
+            build/soundtouch-web-v*
+            build/soundtouch-backup-v*
           retention-days: 1
 
   checksums:
@@ -215,9 +222,10 @@ jobs:
     needs: [validate, build]
 
     steps:
-      - name: Download all artifacts
-        uses: actions/download-artifact@v7
+      - name: Download binary artifacts
+        uses: actions/download-artifact@v8
         with:
+          pattern: binaries-*
           path: ./binaries
 
       - name: Generate checksums
@@ -226,13 +234,13 @@ jobs:
 
           # Debug: Show the downloaded structure
           echo "📁 Downloaded artifact structure:"
-          find . -type f -name "soundtouch-cli-*"
+          ls -R
 
           # Create a collection directory to avoid naming conflicts
           mkdir -p release-files
 
           # Move all files from subdirectories to the collection directory
-          find . -mindepth 2 -type f -name "soundtouch-cli-*" -exec mv {} release-files/ \;
+          find . -mindepth 2 -type f \( -name "soundtouch-cli-*" -o -name "soundtouch-service-*" -o -name "soundtouch-web-*" -o -name "soundtouch-backup-*" \) -exec mv {} release-files/ \;
 
           # Remove empty directories
           find . -type d -empty -delete
@@ -242,20 +250,20 @@ jobs:
 
           # Debug: Show flattened structure
           echo "📁 Flattened structure:"
-          ls -la soundtouch-cli-* || echo "No files found matching pattern"
+          ls -la soundtouch-* || echo "No files found matching pattern"
 
           # Generate combined checksums (exclude individual .sha256/.sha512 files)
-          if ls soundtouch-cli-v* 1> /dev/null 2>&1; then
+          if ls soundtouch-* 1> /dev/null 2>&1; then
             # Only checksum the actual binaries, not the .sha256/.sha512 files
-            ls soundtouch-cli-v* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha256sum > checksums.sha256
-            ls soundtouch-cli-v* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha512sum > checksums.sha512
+            ls soundtouch-cli-* soundtouch-service-* soundtouch-web-* soundtouch-backup-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha256sum > checksums.sha256
+            ls soundtouch-cli-* soundtouch-service-* soundtouch-web-* soundtouch-backup-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha512sum > checksums.sha512
 
             echo "📋 Generated combined checksums:"
             cat checksums.sha256
 
             # Verify all expected files are present (binaries only, not checksum files)
-            EXPECTED_COUNT=7  # Based on build matrix
-            ACTUAL_COUNT=$(ls soundtouch-cli-v* | grep -v '\.sha256$' | grep -v '\.sha512$' | wc -l)
+            EXPECTED_COUNT=28  # 7 platforms * 4 binaries
+            ACTUAL_COUNT=$(ls soundtouch-* | grep -v '\.sha256$' | grep -v '\.sha512$' | wc -l)
 
             if [[ $ACTUAL_COUNT -ne $EXPECTED_COUNT ]]; then
               echo "❌ Expected $EXPECTED_COUNT binaries, found $ACTUAL_COUNT"
@@ -272,7 +280,7 @@ jobs:
           fi
 
       - name: Upload checksums
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: checksums
           path: |
@@ -283,7 +291,7 @@ jobs:
           retention-days: 1
 
       - name: Upload all release assets
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: release-assets
           path: binaries/release-files/
@@ -302,7 +310,7 @@ jobs:
           fetch-depth: 0
 
       - name: Download release assets
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: release-assets
           path: ./release-assets
@@ -369,19 +377,32 @@ jobs:
           - [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Systematic issue resolution
           - [Deployment Guide](docs/DEPLOYMENT.md) - Production deployment examples (Docker, K8s, systemd)
 
-          ## 🔧 CLI Tool
+          ## 🔧 CLI & Service Tools
 
-          Download the CLI tool for your platform from the assets below:
+          Download the tools for your platform from the assets below:
 
+          ### CLI Tool
           \`\`\`bash
           # Quick device discovery
           ./soundtouch-cli -discover
+          \`\`\`
 
-          # Get device information
-          ./soundtouch-cli -host 192.168.1.100 -info
+          ### SoundTouch Service
+          \`\`\`bash
+          # Start the service
+          ./soundtouch-service
+          \`\`\`
 
-          # Monitor real-time events
-          ./soundtouch-cli -host 192.168.1.100 -nowplaying
+          ### SoundTouch Web
+          \`\`\`bash
+          # Start the web app
+          ./soundtouch-web
+          \`\`\`
+
+          ### SoundTouch Backup
+          \`\`\`bash
+          # Back up cloud account and all paired speakers in one go
+          ./soundtouch-backup all
           \`\`\`
 
           ## 🧪 Tested Hardware
@@ -402,6 +423,8 @@ jobs:
           - Windows (amd64)
           - FreeBSD (amd64)
 
+          `soundtouch-cli`, `soundtouch-service`, `soundtouch-web`, and `soundtouch-backup` are included.
+
           ## 🔐 Checksums
 
           Multiple checksum options are provided for download verification:
@@ -445,7 +468,7 @@ jobs:
           echo "release_notes_file=release_notes.md" >> $GITHUB_OUTPUT
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ github.event.inputs.tag }}
           name: "Bose SoundTouch Go Library ${{ github.event.inputs.tag }}"
@@ -454,6 +477,9 @@ jobs:
           prerelease: ${{ needs.validate.outputs.is_prerelease == 'true' }}
           files: |
             release-assets/soundtouch-cli-v*
+            release-assets/soundtouch-service-v*
+            release-assets/soundtouch-web-v*
+            release-assets/soundtouch-backup-v*
             release-assets/checksums.sha256
             release-assets/checksums.sha512
           fail_on_unmatched_files: true
@@ -468,34 +494,101 @@ jobs:
 
     steps:
       - name: Download release assets
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: release-assets
           path: ./release-assets
 
       - name: Upload additional assets to existing release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ github.event.release.tag_name }}
           files: |
             release-assets/soundtouch-cli-v*
+            release-assets/soundtouch-service-v*
+            release-assets/soundtouch-web-v*
+            release-assets/soundtouch-backup-v*
             release-assets/checksums.sha256
             release-assets/checksums.sha512
           fail_on_unmatched_files: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  docker:
+    name: Build and Push Docker Image
+    runs-on: ubuntu-latest
+    needs: validate
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for soundtouch-service
+        id: meta-service
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.validate.outputs.version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.validate.outputs.version }}
+            type=raw,value=latest,enable=${{ needs.validate.outputs.is_prerelease == 'false' }}
+
+      - name: Build and push soundtouch-service Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: soundtouch-service
+          platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
+          push: true
+          tags: ${{ steps.meta-service.outputs.tags }}
+          labels: ${{ steps.meta-service.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Extract metadata (tags, labels) for soundtouch-web
+        id: meta-web
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}-web
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.validate.outputs.version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.validate.outputs.version }}
+            type=raw,value=latest,enable=${{ needs.validate.outputs.is_prerelease == 'false' }}
+
+      - name: Build and push soundtouch-web Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: soundtouch-web
+          platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
+          push: true
+          tags: ${{ steps.meta-web.outputs.tags }}
+          labels: ${{ steps.meta-web.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
   notify:
     name: Post-Release Notifications
     runs-on: ubuntu-latest
-    needs: [validate, create_release, update_release]
-    if: always() && (needs.create_release.result == 'success' || needs.update_release.result == 'success')
+    needs: [validate, create_release, update_release, docker]
+    if: always() && (needs.create_release.result == 'success' || needs.update_release.result == 'success' || needs.docker.result == 'success')
 
     steps:
       - name: Notify success
         run: |
           echo "🎉 Release ${{ needs.validate.outputs.version }} completed successfully!"
-          echo "📦 Binaries built for 7 platforms"
+          echo "📦 Binaries built for 7 platforms (CLI, Service, Web, and Backup)"
+          echo "🐳 Docker image published to ghcr.io"
           echo "🔐 Checksums generated and verified"
           echo "📋 Release notes automatically generated"
           echo ""

.github/workflows/security.yml

@@ -14,6 +14,8 @@ jobs:
   vulnerability-scan:
     name: Vulnerability Scan
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
 
     steps:
       - name: Checkout code
@@ -24,6 +26,9 @@ jobs:
         with:
           go-version-file: "go.mod"
 
+      - name: Install libpcap
+        run: sudo apt-get install -y libpcap-dev
+
       - name: Install security scanning tools
         run: |
           go install golang.org/x/vuln/cmd/govulncheck@latest
@@ -43,7 +48,7 @@ jobs:
 
       - name: Upload vulnerability scan results
         if: failure()
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: vulnerability-scan-results
           path: |
@@ -53,6 +58,8 @@ jobs:
   static-analysis:
     name: Static Security Analysis
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
 
     steps:
       - name: Checkout code
@@ -63,6 +70,9 @@ jobs:
         with:
           go-version-file: "go.mod"
 
+      - name: Install libpcap
+        run: sudo apt-get install -y libpcap-dev
+
       - name: Install static analysis tools
         run: |
           go install honnef.co/go/tools/cmd/staticcheck@latest
@@ -102,6 +112,9 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v6
 
+      - name: Install libpcap
+        run: sudo apt-get install -y libpcap-dev
+
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v4
         with:
@@ -119,6 +132,8 @@ jobs:
   dependency-review:
     name: Dependency Review
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     if: github.event_name == 'pull_request'
 
     steps:
@@ -137,6 +152,8 @@ jobs:
     runs-on: ubuntu-latest
     needs: [vulnerability-scan, static-analysis, codeql-analysis]
     if: always()
+    permissions:
+      contents: read
 
     steps:
       - name: Security scan summary

.gitignore

@@ -12,20 +12,26 @@ dist/
 #example-upnp
 
 # Root-level binary executables (exclude built binaries in root)
+/soundtouch-backup
 /soundtouch-cli
+/soundtouch-service
+/soundtouch-web
 /example-mdns
 /example-upnp
 /example-unified
 /mdns-scanner
 /websocket-demo
+/main
 
 # Environment configuration
 .env
 .env.local
 .env.*.local
+docker-compose.override.yml
 
 # Test coverage reports
 coverage.out
+coverage*.out
 coverage.html
 *.prof
 
@@ -52,6 +58,15 @@ vendor/
 ehthumbs.db
 Thumbs.db
 
+# Android MITM setup — downloaded/generated artefacts, not committed
+scripts/android/bose.apk
+scripts/android/frida-server
+scripts/android/frida-server.xz
+scripts/android/frida/
+scripts/android/frida-venv/
+scripts/android/captures/
+scripts/android/mitm/
+
 # Temporary files
 *.tmp
 *.temp
@@ -59,6 +74,7 @@ Thumbs.db
 *.pid
 *.seed
 *.pid.lock
+.output.txt
 
 # Runtime data
 pids

.golangci.yml

@@ -50,7 +50,12 @@ linters:
         linters:
           - gocritic # Can be overly strict for test code
           - wsl # Whitespace less critical in tests
+          - wsl_v5 # Whitespace less critical in tests
           - gocyclo # Complexity less critical in tests
+          - govet # Avoid shadow warnings in tests
+          - revive # Avoid exported/package-comments in tests
+          - errcheck # Avoid mandatory error checks in tests
+          - unparam # Often parameters are fixed in test setups
 
       # Exclude specific rules for generated files
       - path: ".*\\.pb\\.go$"
@@ -62,6 +67,11 @@ linters:
           - staticcheck
         text: "SA9003:" # Empty branch
 
+      - linters:
+          - staticcheck
+        text: "SA1008: keys in http.Header are canonicalized"
+        path: pkg/service/handlers/handlers_etag_test.go
+
       # Allow main functions to not check errors in examples
       - path: cmd/.*\.go
         text: "Error return value of.*is not checked"
@@ -85,7 +95,7 @@ linters:
         - fieldalignment # Can be overly aggressive
 
     gocyclo:
-      min-complexity: 15
+      min-complexity: 20
 
     gocritic:
       enabled-checks:

CONTRIBUTING.md

@@ -76,7 +76,7 @@ When filing a bug report, include:
 Feature requests are welcome! Please:
 
 1. **Check if the feature already exists** in documentation
-2. **Verify it's supported by the SoundTouch API** (see [official API docs](docs/API-Endpoints-Overview.md))
+2. **Verify it's supported by the SoundTouch API** (see [official API docs](docs/reference/API-ENDPOINTS.md))
 3. **Explain the use case** and how it benefits users
 
 ### 🔧 Contributing Code
@@ -469,10 +469,10 @@ Contributors will be:
 
 - [Go Documentation](https://golang.org/doc/)
 - [Effective Go](https://golang.org/doc/effective_go.html)
-- [Bose SoundTouch API Documentation](docs/API-Endpoints-Overview.md)
+- [Bose SoundTouch API Documentation](docs/reference/API-ENDPOINTS.md)
 - [Project Architecture](docs/PROJECT-PATTERNS.md)
-- [Development Status](docs/STATUS.md)
+- [Development Status](docs/archive/STATUS.md)
 
 ---
 
-**Thank you for contributing!** Every contribution helps make this library better for the entire SoundTouch community.
+**Thank you for contributing!** Every contribution helps make this library better for the entire SoundTouch community.

Dockerfile

@@ -0,0 +1,70 @@
+# Build stage
+FROM --platform=$BUILDPLATFORM golang:1.26.3-alpine AS builder
+
+# Declare automatic platform ARGs to make them available in build stage
+# See https://docs.docker.com/reference/dockerfile#automatic-platform-args-in-the-global-scope
+# We should not set defaults here, but rely on BuildKit to set them matching the BUILDPLATFORM
+ARG TARGETARCH
+ARG TARGETOS
+ARG TARGETVARIANT
+
+WORKDIR /app
+
+# Copy go mod and sum files
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy the rest of the source code
+COPY . .
+
+# Build the soundtouch-service
+RUN if [ "${TARGETARCH}" = "arm" ] && [ -n "${TARGETVARIANT}" ]; then \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} GOARM=${TARGETVARIANT#v} go build -o /soundtouch-service ./cmd/soundtouch-service; \
+    else \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /soundtouch-service ./cmd/soundtouch-service; \
+    fi
+
+# Build the soundtouch-web
+RUN if [ "${TARGETARCH}" = "arm" ] && [ -n "${TARGETVARIANT}" ]; then \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} GOARM=${TARGETVARIANT#v} go build -o /soundtouch-web ./cmd/soundtouch-web; \
+    else \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /soundtouch-web ./cmd/soundtouch-web; \
+    fi
+
+# soundtouch-service image
+FROM alpine:3.23 AS soundtouch-service
+
+RUN apk add --no-cache ca-certificates tzdata
+
+WORKDIR /app
+
+COPY --from=builder /soundtouch-service /app/soundtouch-service
+
+# Verify the binary works on the target platform
+RUN /app/soundtouch-service version || echo "Binary verification complete"
+
+RUN mkdir -p /app/data
+
+ENV PORT=8000
+ENV DATA_DIR=/app/data
+ENV LOG_PROXY_BODY=false
+ENV REDACT_PROXY_LOGS=true
+
+EXPOSE 8000
+
+ENTRYPOINT ["/app/soundtouch-service"]
+
+# soundtouch-web image
+FROM alpine:3.23 AS soundtouch-web
+
+RUN apk add --no-cache ca-certificates tzdata
+
+WORKDIR /app
+
+COPY --from=builder /soundtouch-web /app/soundtouch-web
+
+ENV PORT=8080
+
+EXPOSE 8080
+
+ENTRYPOINT ["/app/soundtouch-web"]

Makefile

@@ -12,68 +12,111 @@ GOFMT=gofmt
 # Build parameters
 BINARY_NAME=soundtouch-cli
 BINARY_PATH=./cmd/$(BINARY_NAME)
+SERVICE_NAME=soundtouch-service
+SERVICE_PATH=./cmd/$(SERVICE_NAME)
+WEB_NAME=soundtouch-web
+WEB_PATH=./cmd/$(WEB_NAME)
 EXAMPLE_MDNS_NAME=example-mdns
 EXAMPLE_MDNS_PATH=./cmd/$(EXAMPLE_MDNS_NAME)
 EXAMPLE_UPNP_NAME=example-upnp
 EXAMPLE_UPNP_PATH=./cmd/$(EXAMPLE_UPNP_NAME)
 SCANNER_NAME=mdns-scanner
 SCANNER_PATH=./cmd/$(SCANNER_NAME)
+FAVICON_GEN_NAME=favicon-gen
+FAVICON_GEN_PATH=./cmd/$(FAVICON_GEN_NAME)
+BACKUP_NAME=soundtouch-backup
+BACKUP_PATH=./cmd/$(BACKUP_NAME)
 BUILD_DIR=./build
 
-# Version info
-# No ldflags needed - using debug.BuildInfo since Go 1.18
+# Build flags: strip debug info/DWARF for smaller binaries, remove local paths for reproducibility
+BUILDFLAGS=-trimpath -ldflags="-s -w"
 
 all: check build
 
-build: build-cli build-examples
+build: build-cli build-service build-web build-examples build-favicon-gen build-backup
 
 build-cli:
 	@echo "Building $(BINARY_NAME)..."
 	@mkdir -p $(BUILD_DIR)
-	$(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME) $(BINARY_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME) $(BINARY_PATH)
+
+build-service:
+	@echo "Building $(SERVICE_NAME)..."
+	@mkdir -p $(BUILD_DIR)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME) $(SERVICE_PATH)
+
+build-web:
+	@echo "Building $(WEB_NAME)..."
+	@mkdir -p $(BUILD_DIR)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(WEB_NAME) $(WEB_PATH)
 
 build-examples:
 	@echo "Building $(EXAMPLE_MDNS_NAME)..."
 	@mkdir -p $(BUILD_DIR)
-	$(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME) $(EXAMPLE_MDNS_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME) $(EXAMPLE_MDNS_PATH)
 	@echo "Building $(EXAMPLE_UPNP_NAME)..."
-	$(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME) $(EXAMPLE_UPNP_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME) $(EXAMPLE_UPNP_PATH)
 	@echo "Building $(SCANNER_NAME)..."
-	$(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME) $(SCANNER_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME) $(SCANNER_PATH)
 
-build-all: build-linux build-darwin build-windows build-examples-all
+build-favicon-gen:
+	@echo "Building $(FAVICON_GEN_NAME)..."
+	@mkdir -p $(BUILD_DIR)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(FAVICON_GEN_NAME) $(FAVICON_GEN_PATH)
+
+build-backup:
+	@echo "Building $(BACKUP_NAME)..."
+	@mkdir -p $(BUILD_DIR)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME) $(BACKUP_PATH)
+
+build-all: build-linux build-linux-armv7 build-darwin build-windows build-examples-all
 
 build-linux:
 	@echo "Building for Linux..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=linux GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 $(BINARY_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 $(BINARY_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-linux-amd64 $(SERVICE_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-linux-amd64 $(BACKUP_PATH)
+
+build-linux-armv7:
+	@echo "Building for Linux ARMv7 (CGO_ENABLED=0 for kernel 3.14+ compatibility)..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-linux-armv7 $(SERVICE_PATH)
+	GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-armv7 $(BINARY_PATH)
+	GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-linux-armv7 $(BACKUP_PATH)
 
 build-darwin:
 	@echo "Building for macOS..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=darwin GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-amd64 $(BINARY_PATH)
-	GOOS=darwin GOARCH=arm64 $(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 $(BINARY_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-amd64 $(BINARY_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 $(BINARY_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-darwin-amd64 $(SERVICE_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-darwin-arm64 $(SERVICE_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-darwin-amd64 $(BACKUP_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-darwin-arm64 $(BACKUP_PATH)
 
 build-windows:
 	@echo "Building for Windows..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=windows GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe $(BINARY_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe $(BINARY_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-windows-amd64.exe $(SERVICE_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-windows-amd64.exe $(BACKUP_PATH)
 
 build-examples-all:
 	@echo "Building examples for all platforms..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=linux GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-linux-amd64 $(EXAMPLE_MDNS_PATH)
-	GOOS=darwin GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-darwin-amd64 $(EXAMPLE_MDNS_PATH)
-	GOOS=darwin GOARCH=arm64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-darwin-arm64 $(EXAMPLE_MDNS_PATH)
-	GOOS=windows GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-windows-amd64.exe $(EXAMPLE_MDNS_PATH)
-	GOOS=linux GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-linux-amd64 $(EXAMPLE_UPNP_PATH)
-	GOOS=darwin GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-darwin-amd64 $(EXAMPLE_UPNP_PATH)
-	GOOS=darwin GOARCH=arm64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-darwin-arm64 $(EXAMPLE_UPNP_PATH)
-	GOOS=windows GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-windows-amd64.exe $(EXAMPLE_UPNP_PATH)
-	GOOS=linux GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME)-linux-amd64 $(SCANNER_PATH)
-	GOOS=darwin GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME)-darwin-amd64 $(SCANNER_PATH)
-	GOOS=darwin GOARCH=arm64 $(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME)-darwin-arm64 $(SCANNER_PATH)
-	GOOS=windows GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME)-windows-amd64.exe $(SCANNER_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-linux-amd64 $(EXAMPLE_MDNS_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-darwin-amd64 $(EXAMPLE_MDNS_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-darwin-arm64 $(EXAMPLE_MDNS_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-windows-amd64.exe $(EXAMPLE_MDNS_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-linux-amd64 $(EXAMPLE_UPNP_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-darwin-amd64 $(EXAMPLE_UPNP_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-darwin-arm64 $(EXAMPLE_UPNP_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-windows-amd64.exe $(EXAMPLE_UPNP_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME)-linux-amd64 $(SCANNER_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME)-darwin-amd64 $(SCANNER_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME)-darwin-arm64 $(SCANNER_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME)-windows-amd64.exe $(SCANNER_PATH)
 
 test:
 	@echo "Running tests..."
@@ -85,7 +128,56 @@ test-coverage:
 	$(GOCMD) tool cover -html=coverage.out -o coverage.html
 	@echo "Coverage report generated: coverage.html"
 
-check: fmt vet test
+check: fmt vet test test-http-client
+
+test-http-client:
+	@echo "Starting services with docker compose..."
+	@docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d --build
+	@echo "Waiting for services to start..."
+	@sleep 10
+	@echo "Running .http tests..."
+	@docker run --rm --network soundtouch-test-net \
+		-v "$(PWD)/tests/integration/http-client:/workdir" \
+		jetbrains/intellij-http-client:2026.1 \
+		--env-file /workdir/http-client.env.json \
+		--env ci \
+		/workdir/spotify_registration.http \
+		/workdir/amazon_registration.http \
+		/workdir/create_account.http \
+		/workdir/register_device.http \
+		/workdir/spotify_full_flow.http \
+		/workdir/customer_support.http \
+		/workdir/power_on.http \
+		/workdir/get_bmx_services.http \
+		/workdir/get_sourceproviders.http \
+		/workdir/get_software_update.http \
+		/workdir/get_soundtouch_updates.http \
+		/workdir/get_streaming_token.http \
+		/workdir/post_oauth_token.http \
+		/workdir/post_oauth_token_amazon.http \
+		/workdir/get_provider_settings.http \
+		/workdir/tunein_playback_station.http \
+		/workdir/set_preset_6.http \
+		/workdir/get_presets.http \
+		/workdir/delete_preset_6.http \
+		/workdir/set_preset_5.http \
+		/workdir/post_recent.http \
+		/workdir/get_recents.http \
+		/workdir/get_account_presets.http \
+		/workdir/get_account_devices.http \
+		/workdir/get_account_sources.http \
+		/workdir/get_api_versions.http \
+		/workdir/post_musicprovider_is_eligible.http \
+		/workdir/get_full_account.http \
+		/workdir/get_group.http \
+		/workdir/unregister_device.http \
+		--report; \
+	EXIT_CODE=$$?; \
+	docker compose -f docker-compose.yml -f docker-compose.ci.yml logs soundtouch-service; \
+	docker compose -f docker-compose.yml -f docker-compose.ci.yml logs spotify-mock; \
+	docker compose -f docker-compose.yml -f docker-compose.ci.yml logs amazon-mock; \
+	docker compose -f docker-compose.yml -f docker-compose.ci.yml down; \
+	exit $$EXIT_CODE
 
 fmt:
 	@echo "Formatting code..."
@@ -108,6 +200,18 @@ dev: build-cli
 	@echo "Starting development CLI..."
 	$(BUILD_DIR)/$(BINARY_NAME) -help
 
+dev-service: build-service
+	@echo "Starting development service..."
+	$(BUILD_DIR)/$(SERVICE_NAME)
+
+dev-service-proxy: build-service
+	@echo "Starting development service with proxy..."
+	@if [ -z "$(PROXY_URL)" ]; then \
+		echo "Usage: make dev-service-proxy PROXY_URL=http://localhost:8001"; \
+		exit 1; \
+	fi
+	PYTHON_BACKEND_URL=$(PROXY_URL) $(BUILD_DIR)/$(SERVICE_NAME)
+
 dev-discover: build-cli
 	@echo "Running device discovery..."
 	$(BUILD_DIR)/$(BINARY_NAME) -discover
@@ -164,9 +268,44 @@ dev-scan-http: build-examples
 	@echo "Scanning for HTTP mDNS services..."
 	$(BUILD_DIR)/$(SCANNER_NAME) -service _http._tcp -v
 
-install: build-cli
-	@echo "Installing $(BINARY_NAME) to $(GOPATH)/bin..."
+dev-web: build-web
+	@echo "Starting web UI (default port 8080)..."
+	cd cmd/soundtouch-web && ../../$(BUILD_DIR)/$(WEB_NAME)
+
+dev-web-port: build-web
+	@echo "Starting web UI on custom port..."
+	@if [ -z "$(PORT)" ]; then \
+		echo "Usage: make dev-web-port PORT=8888"; \
+		exit 1; \
+	fi
+	cd cmd/soundtouch-web && ../../$(BUILD_DIR)/$(WEB_NAME) -port $(PORT)
+
+dev-backup: build-backup
+	@echo "Running backup tool..."
+	$(BUILD_DIR)/$(BACKUP_NAME) --help
+
+dev-backup-cloud: build-backup
+	@echo "Running cloud backup..."
+	$(BUILD_DIR)/$(BACKUP_NAME) cloud
+
+dev-backup-local: build-backup
+	@echo "Running local backup (auto-discover)..."
+	$(BUILD_DIR)/$(BACKUP_NAME) local --discover
+
+dev-web-host: build-web
+	@echo "Starting web UI with specific host..."
+	@if [ -z "$(HOST)" ]; then \
+		echo "Usage: make dev-web-host HOST=192.168.1.10"; \
+		exit 1; \
+	fi
+	cd cmd/soundtouch-web && ../../$(BUILD_DIR)/$(WEB_NAME) -host $(HOST)
+
+install: build-cli build-service build-web build-backup
+	@echo "Installing binaries to $(GOPATH)/bin..."
 	cp $(BUILD_DIR)/$(BINARY_NAME) $(GOPATH)/bin/
+	cp $(BUILD_DIR)/$(SERVICE_NAME) $(GOPATH)/bin/
+	cp $(BUILD_DIR)/$(WEB_NAME) $(GOPATH)/bin/
+	cp $(BUILD_DIR)/$(BACKUP_NAME) $(GOPATH)/bin/
 
 clean:
 	@echo "Cleaning..."
@@ -177,7 +316,7 @@ clean:
 release: clean check build-all
 	@echo "Creating release archive..."
 	@mkdir -p $(BUILD_DIR)/release
-	@for binary in $(BUILD_DIR)/$(BINARY_NAME)-*; do \
+	@for binary in $(BUILD_DIR)/$(BINARY_NAME)-* $(BUILD_DIR)/$(SERVICE_NAME)-*; do \
 		if [ -f "$$binary" ]; then \
 			cp "$$binary" $(BUILD_DIR)/release/; \
 		fi \
@@ -186,18 +325,27 @@ release: clean check build-all
 
 docker-build:
 	@echo "Building Docker image..."
-	docker build -t soundtouch-go:$(VERSION) .
+	docker build --target soundtouch-service -t soundtouch-service .
 
-docker-dev: docker-build
-	@echo "Running development container..."
-	docker run --rm -it --network host soundtouch-go:$(VERSION)
+docker-run-host:
+	@echo "Running Docker container..."
+	@echo "Note: --network host is used for discovery (Linux only). For macOS/Windows use port mapping."
+	docker run --rm -it --network host -v $$(pwd)/data:/app/data soundtouch-service
+
+docker-run-ports:
+	@echo "Running Docker container with port mapping (discovery will be manual)..."
+	docker run --rm -it -p 8000:8000 -v $$(pwd)/data:/app/data soundtouch-service
 
 help:
 	@echo "Available targets:"
-	@echo "  build         - Build the CLI tool and examples"
+	@echo "  build         - Build the CLI tool, service, and examples"
 	@echo "  build-cli     - Build only the CLI tool"
+	@echo "  build-service - Build only the service"
+	@echo "  build-backup  - Build only the backup tool"
+	@echo "  build-favicon-gen - Build the favicon generator"
 	@echo "  build-examples - Build only the example programs"
 	@echo "  build-all     - Build for all platforms"
+	@echo "  build-linux-armv7 - Build for Linux ARMv7 (kernel 3.14+ compatible, CGO_ENABLED=0)"
 	@echo "  test          - Run tests"
 	@echo "  test-coverage - Run tests with coverage report"
 	@echo "  check         - Run fmt, vet, and tests"
@@ -206,6 +354,8 @@ help:
 	@echo "  lint          - Run golangci-lint"
 	@echo "  tidy          - Tidy dependencies"
 	@echo "  dev           - Build and show CLI help"
+	@echo "  dev-service   - Build and run service locally"
+	@echo "  dev-service-proxy - Build and run service with proxy (PROXY_URL=url required)"
 	@echo "  dev-discover  - Build and run device discovery"
 	@echo "  dev-info      - Build and get device info (HOST=ip required)"
 	@echo "  dev-mdns      - Build and run mDNS discovery example"
@@ -217,14 +367,23 @@ help:
 	@echo "  dev-scan-all     - Scan all mDNS services on network"
 	@echo "  dev-scan-soundtouch - Scan specifically for SoundTouch mDNS services"
 	@echo "  dev-scan-http    - Scan for HTTP mDNS services"
-	@echo "  install       - Install binary to GOPATH/bin"
+	@echo "  dev-backup       - Build and show backup tool help"
+	@echo "  dev-backup-cloud - Build and run cloud backup (prompts for credentials)"
+	@echo "  dev-backup-local - Build and run local backup (auto-discover speakers)"
+	@echo "  dev-web          - Build and run web UI (default port 8080)"
+	@echo "  dev-web-port     - Build and run web UI on custom port (PORT=8888)"
+	@echo "  dev-web-host     - Build and run web UI with specific device (HOST=ip)"
+	@echo "  install       - Install binaries to GOPATH/bin"
 	@echo "  clean         - Clean build artifacts"
 	@echo "  release       - Create release binaries"
 	@echo "  docker-build  - Build Docker image"
-	@echo "  docker-dev    - Run development container"
+	@echo "  docker-run-host  - Run container with host networking (Linux discovery)"
+	@echo "  docker-run-ports - Run container with port mapping (macOS/Windows/No discovery)"
 	@echo "  help          - Show this help message"
 	@echo ""
 	@echo "Examples:"
+	@echo "  make dev-service"
+	@echo "  make dev-service-proxy PROXY_URL=http://192.168.1.50:8001"
 	@echo "  make dev-discover"
 	@echo "  make dev-info HOST=192.168.1.10"
 	@echo "  make dev-mdns"
@@ -235,5 +394,8 @@ help:
 	@echo "  make dev-upnp-timeout TIMEOUT=10s"
 	@echo "  make dev-scan-all"
 	@echo "  make dev-scan-soundtouch"
+	@echo "  make dev-web"
+	@echo "  make dev-web-port PORT=8888"
+	@echo "  make dev-web-host HOST=192.168.1.10"
 	@echo "  make test"
 	@echo "  make build-all"

README.md

@@ -1,431 +1,127 @@
-# Bose SoundTouch API Client
-
-A comprehensive Go library and CLI tool for controlling Bose SoundTouch devices via their Web API.
+# Bose SoundTouch Toolkit
 
 [![Go Reference](https://pkg.go.dev/badge/github.com/gesellix/bose-soundtouch.svg)](https://pkg.go.dev/github.com/gesellix/bose-soundtouch)
 [![Go Report Card](https://goreportcard.com/badge/github.com/gesellix/bose-soundtouch)](https://goreportcard.com/report/github.com/gesellix/bose-soundtouch)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Note**: This is an independent project based on the [official Bose SoundTouch Web API documentation](https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf). Not affiliated with or endorsed by Bose Corporation.
+> Independent project. Not affiliated with or endorsed by Bose Corporation.
 
-## Features
+## Context: Cloud Shutdown
 
-- ✅ **Complete API Coverage**: All available SoundTouch Web API endpoints implemented
-- 🎵 **Media Control**: Play, pause, stop, volume, bass, balance, source selection
-- 🏠 **Multiroom Support**: Create and manage zones across multiple speakers
-- ⚡ **Real-time Events**: WebSocket connection for live device state monitoring
-- 🔍 **Device Discovery**: Automatic discovery via UPnP/SSDP and mDNS
-- 📻 **Content Navigation**: Browse and search TuneIn, Pandora, Spotify, local music
-- 🎙️ **Station Management**: Add and play radio stations without presets
-- 🖥️ **CLI Tool**: Comprehensive command-line interface
-- 🔒 **Production Ready**: Extensive testing with real SoundTouch hardware
-- 🌐 **Cross-Platform**: Windows, macOS, Linux support
+Bose is shutting down SoundTouch cloud services on **May 6, 2026**. After that, music service browsing, preset sync, and the official SoundTouch app stop working. This toolkit lets you keep your speakers fully functional.
 
-## Quick Start
-
-### Installation
-
-#### Install CLI Tool
-```bash
-go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-cli@latest
-```
-
-#### Add Library to Your Project
-```bash
-go get github.com/gesellix/bose-soundtouch
-```
-
-### CLI Usage
-
-#### Discover Devices
-```bash
-# Find SoundTouch devices on your network
-soundtouch-cli discover devices
-```
-
-# Control a Device
-```bash
-# Basic device information
-soundtouch-cli --host 192.168.1.100 info get
-
-# Media controls
-soundtouch-cli --host 192.168.1.100 play start
-soundtouch-cli --host 192.168.1.100 volume set --level 50
-soundtouch-cli --host 192.168.1.100 source select --source SPOTIFY
-
-# Preset management
-soundtouch-cli --host 192.168.1.100 preset list
-soundtouch-cli --host 192.168.1.100 preset store-current --slot 1
-soundtouch-cli --host 192.168.1.100 preset select --slot 1
-
-# Browse and discover content
-soundtouch-cli --host 192.168.1.100 browse tunein
-soundtouch-cli --host 192.168.1.100 station search-tunein --query "jazz"
-soundtouch-cli --host 192.168.1.100 station add --source TUNEIN --token <token> --name "Jazz Radio"
-
-# Real-time monitoring
-soundtouch-cli --host 192.168.1.100 events subscribe
-```
-
-### Library Usage
-
-#### Basic Control
-```go
-package main
-
-import (
-    "fmt"
-    "log"
-    
-    "github.com/gesellix/bose-soundtouch/pkg/client"
-)
-
-func main() {
-    // Connect to your SoundTouch device
-    c := client.NewClient(&client.Config{
-        Host: "192.168.1.100",
-        Port: 8090,
-    })
-    
-    // Get device information
-    info, err := c.GetDeviceInfo()
-    if err != nil {
-        log.Fatal(err)
-    }
-    fmt.Printf("Device: %s\n", info.Name)
-    
-    // Control playback
-    err = c.Play()
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    // Set volume
-    err = c.SetVolume(50)
-    if err != nil {
-        log.Fatal(err)
-    }
-}
-```
-
-#### Device Discovery
-```go
-package main
-
-import (
-    "context"
-    "fmt"
-    "log"
-    "time"
-    
-    "github.com/gesellix/bose-soundtouch/pkg/discovery"
-)
-
-func main() {
-    // Discover SoundTouch devices
-    service := discovery.NewService(5 * time.Second)
-    devices, err := service.DiscoverDevices(context.Background())
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    for _, device := range devices {
-        fmt.Printf("Found: %s at %s:%d\n", 
-            device.Name, device.Host, device.Port)
-    }
-}
-```
-
-#### Real-time Events
-```go
-package main
-
-import (
-    "context"
-    "fmt"
-    "log"
-    
-    "github.com/gesellix/bose-soundtouch/pkg/client"
-    "github.com/gesellix/bose-soundtouch/pkg/models"
-)
-
-func main() {
-    c := client.NewClient(&client.Config{
-        Host: "192.168.1.100",
-        Port: 8090,
-    })
-    
-    // Subscribe to device events
-    events, err := c.SubscribeToEvents(context.Background())
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    for event := range events {
-        switch e := event.(type) {
-        case *models.NowPlayingUpdated:
-            fmt.Printf("Now playing: %s by %s\n", e.Track, e.Artist)
-        case *models.VolumeUpdated:
-            fmt.Printf("Volume changed to: %d\n", e.ActualVolume)
-        case *models.ConnectionStateUpdated:
-            fmt.Printf("Connection state: %s\n", e.State)
-        }
-    }
-}
-```
-
-#### Preset Management
-```go
-package main
-
-import (
-    "fmt"
-    "log"
-    
-    "github.com/gesellix/bose-soundtouch/pkg/client"
-    "github.com/gesellix/bose-soundtouch/pkg/models"
-)
-
-func main() {
-    c := client.NewClient(&client.Config{
-        Host: "192.168.1.100",
-        Port: 8090,
-    })
-    
-    // Get current presets
-    presets, err := c.GetPresets()
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    fmt.Printf("Found %d presets\n", len(presets.Preset))
-    
-    // Store currently playing content as preset 1
-    err = c.StoreCurrentAsPreset(1)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    // Store Spotify playlist as preset 2
-    spotifyContent := &models.ContentItem{
-        Source:        "SPOTIFY",
-        Type:          "uri",
-        Location:      "spotify:playlist:37i9dQZF1DXcBWIGoYBM5M",
-        SourceAccount: "your_username",
-        IsPresetable:  true,
-        ItemName:      "Today's Top Hits",
-    }
-    err = c.StorePreset(2, spotifyContent)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    // Store radio station as preset 3
-    radioContent := &models.ContentItem{
-        Source:       "TUNEIN",
-        Type:         "stationurl",
-        Location:     "/v1/playbook/station/s33828",
-        IsPresetable: true,
-        ItemName:     "K-LOVE Radio",
-    }
-    err = c.StorePreset(3, radioContent)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    // Select preset 1
-    err = c.SelectPreset(1)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    fmt.Println("Preset management complete!")
-}
-```
-
-#### Multiroom Zones
-```go
-package main
-
-import (
-    "log"
-    
-    "github.com/gesellix/bose-soundtouch/pkg/client"
-    "github.com/gesellix/bose-soundtouch/pkg/models"
-)
-
-func main() {
-    master := client.NewClient(&client.Config{
-        Host: "192.168.1.100", // Master speaker
-        Port: 8090,
-    })
-    
-    // Create a multiroom zone
-    zone := &models.Zone{
-        Master: "192.168.1.100",
-        Members: []models.ZoneMember{
-            {IPAddress: "192.168.1.101"}, // Living room
-            {IPAddress: "192.168.1.102"}, // Kitchen
-        },
-    }
-    
-    err := master.SetZone(zone)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    fmt.Println("Multiroom zone created!")
-}
-```
-
-## Supported Devices
-
-This library supports all Bose SoundTouch-compatible devices, including:
-
-- SoundTouch 10, 20, 30 series
-- SoundTouch Portable  
-- Wave SoundTouch music system
-- SoundTouch-enabled Bose speakers
-
-**Tested Hardware**:
-- ✅ SoundTouch 10
-- ✅ SoundTouch 20
-
-## API Coverage
-
-| Feature | Status | Description |
-|---------|--------|-------------|
-| Device Info | ✅ Complete | Device details, name, capabilities |
-| Media Control | ✅ Complete | Play/pause/stop, track navigation |
-| Volume & Audio | ✅ Complete | Volume, bass, balance control |
-| Source Selection | ✅ Complete | Spotify, Bluetooth, AUX, etc. |
-| Content Navigation | ✅ Complete | Browse music libraries, radio stations |
-| Station Management | ✅ Complete | Search, add, remove stations |
-| Preset Management | ✅ Complete | Store, select, remove presets |
-| Real-time Events | ✅ Complete | WebSocket event streaming |
-| Multiroom Zones | ✅ Complete | Zone creation and management |
-| System Settings | ✅ Complete | Clock, display, network info |
-| Advanced Audio | ✅ Complete | DSP controls, tone controls |
-
-**API Limitations**: None - all documented SoundTouch Web API functionality is implemented, including endpoints discovered via the comprehensive [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API).
-
-## Documentation
-
-- 📖 [Contributing Guide](CONTRIBUTING.md) - How to contribute to the project
-- 📚 [API Reference](docs/API-Endpoints-Overview.md) - Complete endpoint documentation
-- 🔧 [CLI Reference](docs/CLI-REFERENCE.md) - Command-line tool guide
-- 🎯 [Getting Started](docs/GETTING-STARTED.md) - Detailed setup and usage
-- 📻 [Preset Quick Start](docs/PRESET-QUICKSTART.md) - Favorite content management
-- 🧭 [Navigation Guide](docs/NAVIGATION-GUIDE.md) - Content browsing and station management
-- 📋 [Navigation API Reference](docs/API-NAVIGATION-REFERENCE.md) - Navigation API documentation
-- ⚙️ [Advanced Features](docs/SYSTEM-ENDPOINTS.md) - Advanced functionality
-- 🏠 [Multiroom Setup](docs/zone-management.md) - Zone configuration guide
-- ⚡ [WebSocket Events](docs/websocket-events.md) - Real-time event handling
-- 🔍 [Device Discovery](docs/DISCOVERY.md) - Discovery configuration
-- 🛠️ [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
-
-## Development
-
-### Prerequisites
-- Go 1.25.6 or later
-- Optional: SoundTouch device for testing
-
-### Building from Source
-```bash
-# Clone the repository
-git clone https://github.com/gesellix/bose-soundtouch.git
-cd Bose-SoundTouch
-
-# Install dependencies
-go mod download
-
-# Build CLI tool
-make build
-
-# Run tests
-make test
-
-# Install CLI locally
-go install ./cmd/soundtouch-cli
-```
-
-### Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
-
-- Setting up your development environment
-- Coding guidelines and best practices
-- Testing with real devices
-- Submitting pull requests
-
-## Examples
-
-Check out the [examples/](examples/) directory for more usage patterns:
-
-- **Basic HTTP Client**: Simple device control
-- **Preset Management**: Store and manage favorite content
-- **Navigation & Stations**: Browse content and manage radio stations
-- **WebSocket Events**: Real-time monitoring
-- **Device Discovery**: Finding devices on your network
-- **Multiroom Management**: Zone operations
-- **Advanced Audio**: DSP and tone controls
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Disclaimer
-
-This is an independent project based on the official Bose SoundTouch Web API documentation provided by Bose Corporation. It is not affiliated with, endorsed by, or supported by Bose Corporation. Use at your own risk.
-
-SoundTouch is a trademark of Bose Corporation.
-
-## SoundTouch End of Life Notice
-
-**Important:** Bose has announced that [SoundTouch cloud support will end on May 6, 2026](https://www.bose.com/soundtouch-end-of-life).
-
-**What will continue to work:**
-- ✅ Local API control (this library's primary functionality)
-- ✅ Bluetooth, AirPlay, Spotify Connect, and AUX streaming
-- ✅ Remote control features (Play, Pause, Skip, Volume)
-- ✅ Multiroom grouping
-
-**What will stop working:**
-- ❌ Cloud-based preset sync between devices and SoundTouch app
-- ❌ Browsing music services directly from the SoundTouch app
-- ❌ Cloud-based features and updates
-
-**What continues to work:**
-- ✅ Local preset management via this API client (store, select, remove)
-- ✅ Direct content playback (stations, playlists, etc.)
-
-This Go library will continue to work as it uses the local Web API for direct device control, which is unaffected by the cloud service discontinuation. The local preset management functionality implemented in this library (discovered through the [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)) provides an alternative to the cloud-based preset features that will be discontinued.
-
-**Community Alternatives**: See the [Related Projects](#related-projects) section below for additional tools like SoundCork that provide cloud service alternatives and the SoundTouch Plus project that offers comprehensive Home Assistant integration.
-
-## Related Projects
-
-### SoundTouch Plus
-- **Project**: [SoundTouch Plus Home Assistant Component](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus)
-- **Wiki**: [SoundTouch WebServices API Documentation](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
-- **Description**: Comprehensive Home Assistant integration with extensive API documentation
-- **Contribution**: The SoundTouch Plus Wiki provided invaluable documentation of working endpoints beyond the official API, enabling the preset management and content navigation features in this library
-
-### SoundCork
-- **Project**: [SoundCork - SoundTouch API Intercept](https://github.com/deborahgu/soundcork)
-- **Description**: Intercept API for Bose SoundTouch devices after cloud service discontinuation
-- **Purpose**: Provides a local alternative to cloud-based SoundTouch services post-sunset
-- **Compatibility**: Complements this Go library by extending functionality beyond the local device API
-
-These projects form a comprehensive ecosystem for SoundTouch device management and provide alternatives to Bose's discontinued cloud services.
-
-## Support
-
-- 🐛 **Bug Reports**: [Create an issue](https://github.com/gesellix/bose-soundtouch/issues/new)
-- 💡 **Feature Requests**: [Start a discussion](https://github.com/gesellix/bose-soundtouch/discussions)
-- ❓ **Questions**: Check [existing discussions](https://github.com/gesellix/bose-soundtouch/discussions)
-- 📖 **Documentation**: Browse the [docs/](docs/) directory
+See the [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVIVAL-GUIDE.html) for the full picture.
 
 ---
 
-**Star this project** ⭐ if you find it useful!
+## Tools
+
+### soundtouch-service — AfterTouch
+
+A local server that replaces the Bose cloud ("AfterTouch"). Once your speaker is redirected to it, you have full control without any Bose cloud dependency. The built-in web UI at `http://localhost:8000` handles all setup — no config files needed to get started.
+
+**Two scenarios:**
+
+**Before shutdown — migrate your existing setup**
+While the Bose cloud is still running, use `soundtouch-backup` to save your account data. The local service web UI then helps with the migration so your speaker keeps its presets and credentials.
+
+**After shutdown or factory reset — start fresh**
+Create a local account, configure your speakers, and start using them immediately. No Bose infrastructure required.
+
+**Redirecting your speaker**
+
+The service needs a stable address on your local network (e.g. `soundtouch.fritz.box` or `soundtouch.local`). The speaker must then be redirected to resolve the Bose cloud hostnames to that address. Two supported methods:
+
+| Method       | How it works                        | Notes                                                        |
+|--------------|-------------------------------------|--------------------------------------------------------------|
+| XML redirect | Upload a config XML via the Web API | Surgical; covers only registered endpoints; best for testing |
+| DNS/DHCP     | Serve custom DNS on your network    | Covers all devices at once; requires port 53 and TLS         |
+
+The web UI walks you through each method. DNS redirect requires HTTPS — the service manages its own CA certificate and the web UI guides you through trusting it on each speaker.
+
+> **Note:** A hosts-file method (direct SSH edits to `/etc/hosts`) also exists in the codebase but is deprecated and not exposed in the web UI.
+
+**Enabling SSH via USB stick**
+
+Some setup steps require SSH access to the speaker. Enable it once per device: create a file named `remote_services` on a FAT-formatted USB drive (the drive may need its bootable flag set — see [SoundCork issue #172](https://github.com/deborahgu/soundcork/issues/172)), and insert it while the speaker is powered on. After reboot, root SSH is available with no password.
+
+See [Device Initial Setup](https://gesellix.github.io/Bose-SoundTouch/guides/DEVICE-INITIAL-SETUP.html) and [Migration Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-GUIDE.html) for step-by-step instructions.
+
+---
+
+### soundtouch-backup
+
+Backs up your Bose cloud account (presets, paired devices, music sources) and each speaker's local state before the shutdown. Run `soundtouch-backup all` to capture everything in one step; it authenticates with the Bose cloud, then polls each paired speaker over the local network.
+
+See the [soundtouch-backup README](cmd/soundtouch-backup/README.md) for usage.
+
+---
+
+### soundtouch-cli
+
+Command-line control of any SoundTouch device: play/pause/volume, presets, source selection, multiroom zones, device discovery, and more. Works entirely over the local network — no cloud dependency. Well-suited for scripting and home automation.
+
+See the [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html) for full usage.
+
+---
+
+### soundtouch-web
+
+A standalone web UI for device control — play, pause, volume, preset selection, real-time status — served from a local Go binary. Complements `soundtouch-service` when you want a dedicated device-control interface separate from the setup/admin UI.
+
+See the [soundtouch-web README](cmd/soundtouch-web/README.md) for usage.
+
+---
+
+### Go library
+
+`pkg/client` provides a Go API for all SoundTouch device endpoints: media control, volume, presets, sources, zones, real-time WebSocket events, and device discovery. Use it to build your own integrations.
+
+```
+go get github.com/gesellix/bose-soundtouch
+```
+
+See the [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API-ENDPOINTS.html) and [pkg.go.dev](https://pkg.go.dev/github.com/gesellix/bose-soundtouch) for documentation.
+
+---
+
+## Documentation
+
+- [Getting Started](https://gesellix.github.io/Bose-SoundTouch/guides/GETTING-STARTED.html)
+- [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVIVAL-GUIDE.html)
+- [Migration Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-GUIDE.html)
+- [Device Initial Setup](https://gesellix.github.io/Bose-SoundTouch/guides/DEVICE-INITIAL-SETUP.html)
+- [Migration & Safety Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-SAFETY.html)
+- [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html)
+- [SoundTouch Service Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SOUNDTOUCH-SERVICE.html)
+- [HTTPS & CA Setup](https://gesellix.github.io/Bose-SoundTouch/guides/HTTPS-SETUP.html)
+- [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API-ENDPOINTS.html)
+
+---
+
+## Related projects
+
+- **[SoundCork](https://github.com/deborahgu/soundcork)** (Deborah Kaplan et al.) — Python service interception; pioneered the cloud emulation approach this project builds on
+- **[SoundCork Stockholm App](https://github.com/krahl/soundcork-stockholm-app)** — Companion app for SoundCork
+- **[SoundTouch Plus](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus)** (Todd Lucas) — Home Assistant integration; extensive undocumented API documentation
+- **[ÜberBöse API](https://github.com/julius-d/ueberboese-api)** (Julius) — API research and advanced endpoint discovery
+- **[Bose SoundTouch Hook](https://github.com/CodeFinder2/bose-soundtouch-hook)** (Adrian Böckenkamp) — `LD_PRELOAD` hooking for reverse engineering device internals
+
+---
+
+## Support
+
+- Bug reports: [GitHub Issues](https://github.com/gesellix/bose-soundtouch/issues/new)
+- Questions & discussions: [GitHub Discussions](https://github.com/gesellix/bose-soundtouch/discussions)
+
+---
+
+**Star this project** ⭐ if you find it useful!
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+SoundTouch is a trademark of Bose Corporation.

cmd/debug-consolidation/main.go

@@ -0,0 +1,242 @@
+// Package main provides a debug tool for analyzing device consolidation and migration scenarios.
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Println("Usage: debug-consolidation <data-directory>")
+		fmt.Println("Example: debug-consolidation /var/lib/soundtouch-service")
+		os.Exit(1)
+	}
+
+	dataDir := os.Args[1]
+
+	fmt.Printf("🔍 Analyzing device consolidation in: %s\n", dataDir)
+
+	// Initialize datastore
+	ds := datastore.NewDataStore(dataDir)
+
+	// List all devices
+	devices, err := ds.ListAllDevices()
+	if err != nil {
+		log.Fatalf("Failed to list devices: %v", err)
+	}
+
+	fmt.Printf("📱 Found %d device entries:\n", len(devices))
+
+	for i := range devices {
+		device := &devices[i]
+		fmt.Printf("  %d. %s (Account: %s)\n", i+1, device.DeviceID, device.AccountID)
+		fmt.Printf("     Name: %s\n", device.Name)
+		fmt.Printf("     IP: %s, MAC: %s, Serial: %s\n",
+			device.IPAddress, device.MacAddress, device.DeviceSerialNumber)
+
+		// Check directory contents
+		deviceDir := ds.AccountDeviceDir(device.AccountID, device.DeviceID)
+		analyzeDeviceDirectory(deviceDir, device.DeviceID)
+		fmt.Println()
+	}
+
+	// Group devices by potential physical device
+	fmt.Println("🔄 Analyzing potential consolidation opportunities:")
+
+	deviceGroups := groupDevicesByIdentity(devices)
+
+	for i, group := range deviceGroups {
+		if len(group) <= 1 {
+			continue
+		}
+
+		fmt.Printf("  Group %d - %d entries for same physical device:\n", i+1, len(group))
+
+		for i := range group {
+			device := &group[i]
+			deviceDir := ds.AccountDeviceDir(device.AccountID, device.DeviceID)
+			fileCount := countFiles(deviceDir)
+			fmt.Printf("    - %s (%d files)\n", device.DeviceID, fileCount)
+		}
+
+		// Recommend consolidation target
+		macDevice := findMACBasedDevice(group)
+		if macDevice != nil {
+			fmt.Printf("    → Recommend keeping: %s (MAC-based)\n", macDevice.DeviceID)
+		} else {
+			fmt.Printf("    → No clear MAC-based target found\n")
+		}
+
+		fmt.Println()
+	}
+}
+
+func analyzeDeviceDirectory(dirPath, deviceID string) {
+	entries, err := os.ReadDir(dirPath)
+	if err != nil {
+		fmt.Printf("     Directory: %s (Error: %v)\n", dirPath, err)
+		return
+	}
+
+	fmt.Printf("     Directory: %s (%d files)\n", dirPath, len(entries))
+
+	// Check for important files
+	importantFiles := []string{"DeviceInfo.xml", "Presets.xml", "Recents.xml", "Sources.xml"}
+	for _, fileName := range importantFiles {
+		filePath := filepath.Join(dirPath, fileName)
+		if stat, err := os.Stat(filePath); err == nil {
+			status := "✓"
+			if stat.Size() == 0 {
+				status = "⚠️ (empty)"
+			} else if stat.Size() < 100 {
+				status = "⚠️ (very small)"
+			}
+
+			fmt.Printf("       %s %s (%d bytes)\n", status, fileName, stat.Size())
+		} else {
+			fmt.Printf("       ❌ %s (missing)\n", fileName)
+		}
+	}
+
+	// Check if deviceID looks like MAC address
+	if isLikelyMACAddress(deviceID) {
+		fmt.Printf("       📍 Device ID appears to be MAC address format\n")
+	} else {
+		fmt.Printf("       📍 Device ID appears to be %s format\n", guessIDType(deviceID))
+	}
+}
+
+func countFiles(dirPath string) int {
+	entries, err := os.ReadDir(dirPath)
+	if err != nil {
+		return 0
+	}
+
+	count := 0
+
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			count++
+		}
+	}
+
+	return count
+}
+
+func groupDevicesByIdentity(devices []models.ServiceDeviceInfo) [][]models.ServiceDeviceInfo {
+	var groups [][]models.ServiceDeviceInfo
+
+	// Simple grouping by MAC address and serial number
+	macGroups := make(map[string][]models.ServiceDeviceInfo)
+	serialGroups := make(map[string][]models.ServiceDeviceInfo)
+	ipGroups := make(map[string][]models.ServiceDeviceInfo)
+
+	for i := range devices {
+		device := &devices[i]
+		// Group by MAC address
+		if device.MacAddress != "" {
+			macGroups[device.MacAddress] = append(macGroups[device.MacAddress], *device)
+		}
+
+		// Group by serial number
+		if device.DeviceSerialNumber != "" {
+			serialGroups[device.DeviceSerialNumber] = append(serialGroups[device.DeviceSerialNumber], *device)
+		}
+
+		// Group by IP address
+		if device.IPAddress != "" {
+			ipGroups[device.IPAddress] = append(ipGroups[device.IPAddress], *device)
+		}
+	}
+
+	// Merge groups - prioritize MAC address grouping
+	processed := make(map[string]bool)
+
+	for _, macDevices := range macGroups {
+		if len(macDevices) > 1 {
+			groups = append(groups, macDevices)
+			for i := range macDevices {
+				processed[macDevices[i].DeviceID] = true
+			}
+		}
+	}
+
+	// Check for serial number groups not already processed
+	for _, serialDevices := range serialGroups {
+		if len(serialDevices) > 1 {
+			unprocessed := []models.ServiceDeviceInfo{}
+
+			for i := range serialDevices {
+				if !processed[serialDevices[i].DeviceID] {
+					unprocessed = append(unprocessed, serialDevices[i])
+				}
+			}
+
+			if len(unprocessed) > 1 {
+				groups = append(groups, unprocessed)
+				for i := range unprocessed {
+					processed[unprocessed[i].DeviceID] = true
+				}
+			}
+		}
+	}
+
+	return groups
+}
+
+func findMACBasedDevice(devices []models.ServiceDeviceInfo) *models.ServiceDeviceInfo {
+	for i := range devices {
+		if isLikelyMACAddress(devices[i].DeviceID) {
+			return &devices[i]
+		}
+	}
+
+	return nil
+}
+
+func isLikelyMACAddress(id string) bool {
+	// MAC addresses are typically 12 hex characters without separators
+	// or 17 characters with separators (XX:XX:XX:XX:XX:XX)
+	if len(id) == 12 {
+		for _, c := range id {
+			if (c < '0' || c > '9') && (c < 'A' || c > 'F') && (c < 'a' || c > 'f') {
+				return false
+			}
+		}
+
+		return true
+	}
+
+	return false
+}
+
+func guessIDType(id string) string {
+	if len(id) > 15 && (id[0] == 'I' || id[0] == 'K') {
+		return "serial number"
+	}
+
+	// Check if it looks like an IP address
+	if len(id) >= 7 && len(id) <= 15 {
+		dotCount := 0
+
+		for _, c := range id {
+			if c == '.' {
+				dotCount++
+			} else if c < '0' || c > '9' {
+				break
+			}
+		}
+
+		if dotCount == 3 {
+			return "IP address"
+		}
+	}
+
+	return "unknown"
+}

cmd/favicon-gen/main.go

@@ -0,0 +1,152 @@
+// Package main provides a utility to generate PNG and ICO favicons from SVG source files.
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/binary"
+	"fmt"
+	"image"
+	"image/png"
+	"log"
+	"os"
+	"path/filepath"
+
+	"github.com/srwiley/oksvg"
+	"github.com/srwiley/rasterx"
+)
+
+func main() {
+	mediaDir := "pkg/service/handlers/web/img"
+	files := []string{"favicon-braille", "favicon-morse"}
+
+	for _, name := range files {
+		svgPath := filepath.Join(mediaDir, name+".svg")
+		pngPath := filepath.Join(mediaDir, name+".png")
+		icoPath := filepath.Join(mediaDir, name+".ico")
+
+		fmt.Printf("Processing %s...\n", name)
+
+		// 1. Render SVG to PNG
+		img, err := renderSVG(svgPath, 32, 32)
+		if err != nil {
+			log.Fatalf("Failed to render %s: %v", svgPath, err)
+		}
+
+		f, err := os.Create(pngPath)
+		if err != nil {
+			log.Fatalf("Failed to create %s: %v", pngPath, err)
+		}
+
+		if err := png.Encode(f, img); err != nil {
+			f.Close()
+			log.Fatalf("Failed to encode PNG %s: %v", pngPath, err)
+		}
+
+		f.Close()
+		fmt.Printf("Created %s\n", pngPath)
+
+		// 2. Create ICO (containing multiple sizes)
+		sizes := []int{16, 32, 48}
+
+		var images []image.Image
+
+		for _, s := range sizes {
+			m, err := renderSVG(svgPath, s, s)
+			if err != nil {
+				log.Fatalf("Failed to render %s at size %d: %v", svgPath, s, err)
+			}
+
+			images = append(images, m)
+		}
+
+		if err := writeICO(icoPath, images); err != nil {
+			log.Fatalf("Failed to write ICO %s: %v", icoPath, err)
+		}
+
+		fmt.Printf("Created %s\n", icoPath)
+	}
+}
+
+func renderSVG(path string, w, h int) (image.Image, error) {
+	in, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer in.Close()
+
+	icon, err := oksvg.ReadIconStream(in)
+	if err != nil {
+		return nil, err
+	}
+
+	icon.SetTarget(0, 0, float64(w), float64(h))
+	rgba := image.NewRGBA(image.Rect(0, 0, w, h))
+	gv := rasterx.NewScannerGV(w, h, rgba, rgba.Bounds())
+	dasher := rasterx.NewDasher(w, h, gv)
+	icon.Draw(dasher, 1.0)
+
+	return rgba, nil
+}
+
+// Simple ICO encoder that wraps PNGs
+func writeICO(path string, images []image.Image) error {
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	bw := bufio.NewWriter(f)
+	defer bw.Flush()
+
+	// ICONDIR header
+	// Reserved (2), Type (2), Count (2)
+	binary.Write(bw, binary.LittleEndian, uint16(0))
+	binary.Write(bw, binary.LittleEndian, uint16(1)) // 1 = ICO
+	binary.Write(bw, binary.LittleEndian, uint16(len(images)))
+
+	var pngData [][]byte
+
+	for _, img := range images {
+		var buf bytes.Buffer
+		if err := png.Encode(&buf, img); err != nil {
+			return err
+		}
+
+		pngData = append(pngData, buf.Bytes())
+	}
+
+	offset := uint32(6 + len(images)*16)
+	for i, img := range images {
+		b := img.Bounds()
+
+		width := uint8(b.Dx())
+		if b.Dx() >= 256 {
+			width = 0
+		}
+
+		height := uint8(b.Dy())
+		if b.Dy() >= 256 {
+			height = 0
+		}
+
+		// ICONDIRENTRY
+		bw.WriteByte(width)
+		bw.WriteByte(height)
+		bw.WriteByte(0)                                   // Color count
+		bw.WriteByte(0)                                   // Reserved
+		binary.Write(bw, binary.LittleEndian, uint16(1))  // Planes (1)
+		binary.Write(bw, binary.LittleEndian, uint16(32)) // Bits per pixel (32)
+		binary.Write(bw, binary.LittleEndian, uint32(len(pngData[i])))
+		binary.Write(bw, binary.LittleEndian, offset)
+
+		offset += uint32(len(pngData[i]))
+	}
+
+	for _, data := range pngData {
+		bw.Write(data)
+	}
+
+	return nil
+}

cmd/mock-amazon/main.go

@@ -0,0 +1,23 @@
+// Package main provides a mock Amazon LWA server for testing purposes.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+
+	"github.com/gesellix/bose-soundtouch/pkg/testutils/amazon"
+)
+
+func main() {
+	port := flag.Int("port", 8080, "Port to listen on")
+
+	flag.Parse()
+
+	log.Printf("Starting mock Amazon LWA server on port %d", *port)
+
+	if err := http.ListenAndServe(fmt.Sprintf(":%d", *port), amazon.NewAmazonHandler()); err != nil {
+		log.Fatal(err)
+	}
+}

cmd/mock-spotify/main.go

@@ -0,0 +1,23 @@
+// Package main provides a mock Spotify server for testing purposes.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+
+	"github.com/gesellix/bose-soundtouch/pkg/testutils/spotify"
+)
+
+func main() {
+	port := flag.Int("port", 8080, "Port to listen on")
+
+	flag.Parse()
+
+	log.Printf("Starting mock Spotify server on port %d", *port)
+
+	if err := http.ListenAndServe(fmt.Sprintf(":%d", *port), spotify.NewSpotifyHandler()); err != nil {
+		log.Fatal(err)
+	}
+}

cmd/soundtouch-backup/README.md

@@ -0,0 +1,212 @@
+# soundtouch-backup
+
+A standalone tool for backing up Bose SoundTouch data — both your **cloud account** (presets, devices, sources) and the **local filesystem** of each speaker — before the Bose cloud services shut down on May 6, 2026.
+
+## Overview
+
+| Subcommand | What it backs up                                                                                   |
+|------------|----------------------------------------------------------------------------------------------------|
+| `all`      | Cloud account **and** all paired speakers in one step — the recommended starting point             |
+| `cloud`    | Bose account profile, paired devices, cloud presets, music service sources                         |
+| `local`    | Speaker HTTP API data (presets, sources, volume, …) and optionally device filesystem files via SSH |
+
+Output is a single `.tar.gz` archive (or `.zip`) with a dated root directory.
+
+## Building
+
+```bash
+make build-backup
+# binary: ./build/soundtouch-backup
+```
+
+Or install alongside the other tools:
+
+```bash
+make install
+```
+
+## Usage
+
+### Combined backup (recommended)
+
+The `all` command is the simplest way to capture everything: it authenticates with the Bose cloud, backs up your account data, then reads the IP addresses from `devices.xml` and backs up each reachable speaker over HTTP.
+
+```bash
+# Interactive — prompts for email and password
+soundtouch-backup all
+
+# Non-interactive
+soundtouch-backup all --email you@example.com --password secret
+
+# Include SSH filesystem backup for each speaker
+soundtouch-backup all --ssh
+
+# Environment variables
+BOSE_EMAIL=you@example.com BOSE_PASSWORD=secret soundtouch-backup all --ssh
+```
+
+**Flags**
+
+| Flag         | Short  | Default                               | Description                                            |
+|--------------|--------|---------------------------------------|--------------------------------------------------------|
+| `--email`    | `-e`   | —                                     | Bose account email (`$BOSE_EMAIL`)                     |
+| `--password` | `--pw` | —                                     | Bose account password (`$BOSE_PASSWORD`)               |
+| `--ssh`      |        | on                                    | Also capture filesystem files via SSH for each speaker |
+| `--output`   | `-o`   | `soundtouch-backup-YYYY-MM-DD.tar.gz` | Output archive path                                    |
+| `--format`   |        | `tar.gz`                              | Archive format: `tar.gz` or `zip`                      |
+
+Speakers that are offline or unreachable at the time of backup are skipped with a `✗` warning; the cloud data is still saved.
+
+---
+
+### Cloud backup
+
+Backs up data from your Bose account at `streaming.bose.com`. Credentials are prompted interactively if not supplied as flags.
+
+```bash
+# Interactive — prompts for email, masked password input
+soundtouch-backup cloud
+
+# Non-interactive
+soundtouch-backup cloud --email you@example.com --password secret
+
+# Environment variables (avoids secrets in shell history)
+BOSE_EMAIL=you@example.com BOSE_PASSWORD=secret soundtouch-backup cloud
+
+# Zip output
+soundtouch-backup cloud --format zip --output my-bose-cloud.zip
+```
+
+**Flags**
+
+| Flag         | Short  | Default                               | Description                                       |
+|--------------|--------|---------------------------------------|---------------------------------------------------|
+| `--email`    | `-e`   | —                                     | Bose account email (`$BOSE_EMAIL`)                |
+| `--password` | `--pw` | —                                     | Bose account password (`$BOSE_PASSWORD`)          |
+| `--output`   | `-o`   | `soundtouch-backup-YYYY-MM-DD.tar.gz` | Output archive path (`$SOUNDTOUCH_BACKUP_OUTPUT`) |
+| `--format`   |        | `tar.gz`                              | Archive format: `tar.gz` or `zip`                 |
+
+**What gets fetched**
+
+| File in archive          | Source endpoint                                                                 |
+|--------------------------|---------------------------------------------------------------------------------|
+| `cloud/emailaddress.xml` | `GET /streaming/account/{id}/emailaddress`                                      |
+| `cloud/devices.xml`      | `GET /streaming/account/{id}/devices`                                           |
+| `cloud/sources.xml`      | `GET /streaming/account/{id}/sources`                                           |
+| `cloud/presets.xml`      | `GET /streaming/account/{id}/presets/all`                                       |
+| `cloud/full.xml`         | `GET /streaming/account/{id}/full` (may overlap with the above; skipped if 4xx) |
+
+---
+
+### Local backup
+
+Backs up each speaker over its HTTP API on port 8090. With `--ssh`, also captures key filesystem files via SSH.
+
+```bash
+# Auto-discover all speakers on the local network
+soundtouch-backup local
+
+# Specific speaker
+soundtouch-backup local --host 192.168.178.28
+
+# Multiple speakers
+soundtouch-backup local --host 192.168.178.28 --host 192.168.178.35
+
+# Include SSH filesystem backup
+soundtouch-backup local --ssh
+
+# Longer discovery window on busy networks
+soundtouch-backup local --discover-timeout 10s
+```
+
+**Flags**
+
+| Flag                 | Short | Default                               | Description                                      |
+|----------------------|-------|---------------------------------------|--------------------------------------------------|
+| `--host`             | `-H`  | —                                     | Speaker host/IP, repeatable (`$SOUNDTOUCH_HOST`) |
+| `--port`             | `-p`  | `8090`                                | Speaker HTTP port (`$SOUNDTOUCH_PORT`)           |
+| `--discover`         | `-d`  | auto                                  | Force mDNS/UPnP discovery                        |
+| `--discover-timeout` |       | `5s`                                  | Discovery timeout                                |
+| `--ssh`              |       | on                                    | Also capture filesystem files via SSH            |
+| `--output`           | `-o`  | `soundtouch-backup-YYYY-MM-DD.tar.gz` | Output archive path                              |
+| `--format`           |       | `tar.gz`                              | Archive format: `tar.gz` or `zip`                |
+
+**What gets fetched via HTTP**
+
+| File                | Device endpoint |
+|---------------------|-----------------|
+| `info.xml`          | `/info`         |
+| `name.xml`          | `/name`         |
+| `presets.xml`       | `/presets`      |
+| `sources.xml`       | `/sources`      |
+| `now_playing.xml`   | `/now_playing`  |
+| `volume.xml`        | `/volume`       |
+| `bass.xml`          | `/bass`         |
+| `balance.xml`       | `/balance`      |
+| `capabilities.xml`  | `/capabilities` |
+| `network_info.xml`  | `/networkInfo`  |
+| `clock_display.xml` | `/clockDisplay` |
+| `zone.xml`          | `/getZone`      |
+
+Endpoints that return HTTP 4xx (not supported on the device model) are silently skipped.
+
+**What gets fetched via SSH** (`--ssh`)
+
+SSH connects as `root@<host>:22` with an empty password, which is the default for SoundTouch firmware.
+
+Individual files:
+
+| Remote path               | Notes                                      |
+|---------------------------|--------------------------------------------|
+| `/etc/hosts`              | DNS redirect state                         |
+| `/etc/resolv.conf`        | DNS resolver configuration                 |
+| `/etc/remote_services`    | Service registration (post-migration only) |
+| `/mnt/nv/remote_services` | Alternative location for remote services   |
+
+Directories (all regular files recursively):
+
+| Remote path                      | Contents                                                                   |
+|----------------------------------|----------------------------------------------------------------------------|
+| `/opt/Bose/etc/`                 | Full Bose configuration directory, including `SoundTouchSdkPrivateCfg.xml` |
+| `/mnt/nv/BoseApp-Persistence/1/` | Persisted app state                                                        |
+
+Missing files and directories are silently skipped with a `⚠` warning.
+
+---
+
+## Archive structure
+
+Both subcommands write into a single dated archive:
+
+```
+soundtouch-backup-2026-05-02/
+├── cloud/
+│   ├── emailaddress.xml
+│   ├── devices.xml
+│   ├── sources.xml
+│   └── presets.xml
+└── local/
+    ├── A_Sound_Machine/
+    │   ├── info.xml
+    │   ├── presets.xml
+    │   ├── sources.xml
+    │   ├── volume.xml
+    │   ├── …
+    │   └── ssh/
+    │       ├── etc/
+    │       │   ├── hosts
+    │       │   └── resolv.conf
+    │       ├── opt/Bose/etc/
+    │       │   └── SoundTouchSdkPrivateCfg.xml
+    │       └── mnt/nv/BoseApp-Persistence/1/
+    └── Sound_Machinechen/
+        └── …
+```
+
+Running `cloud` and `local` separately produces two archives. To combine them, use the same `--output` path for both invocations — each adds its own subdirectory so they won't collide (`.tar.gz` does not support appending; use `--format zip` if you need a single archive from two runs, or just keep them separate).
+
+## See also
+
+- [Cloud Shutdown Survival Guide](../../docs/guides/SURVIVAL-GUIDE.md) — full migration context
+- [`soundtouch-cli`](../soundtouch-cli/) — live device control
+- [`soundtouch-service`](../soundtouch-service/) — local cloud replacement

cmd/soundtouch-backup/cmd_all.go

@@ -0,0 +1,119 @@
+package main
+
+import (
+	"encoding/xml"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/urfave/cli/v2"
+)
+
+func allCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "all",
+		Usage: "Back up cloud account then all paired speakers in one go",
+		Description: "Authenticates with the Bose cloud, backs up account data, then reads" +
+			" the device IP addresses from the cloud device list and backs up each reachable" +
+			" speaker over HTTP (and optionally SSH).",
+		Flags: append(outputFlags,
+			&cli.StringFlag{
+				Name:    "email",
+				Aliases: []string{"e"},
+				Usage:   "Bose account email",
+				EnvVars: []string{"BOSE_EMAIL"},
+			},
+			&cli.StringFlag{
+				Name:    "password",
+				Aliases: []string{"pw"},
+				Usage:   "Bose account password",
+				EnvVars: []string{"BOSE_PASSWORD"},
+			},
+			&cli.BoolFlag{
+				Name:  "ssh",
+				Usage: "Also back up device filesystem files via SSH (root@host:22, no password required)",
+				Value: true,
+			},
+		),
+		Action: runAllBackup,
+	}
+}
+
+func runAllBackup(c *cli.Context) error {
+	doSSH := c.Bool("ssh")
+	output := resolveOutputPath(c.String("output"), c.String("format"))
+	format := c.String("format")
+
+	// 1. Cloud backup
+	client, err := setupCloudClient(c.String("email"), c.String("password"))
+	if err != nil {
+		return err
+	}
+
+	root := archiveRoot()
+	files := collectCloudFiles(client, root)
+
+	if len(files) == 0 {
+		return fmt.Errorf("no cloud data fetched")
+	}
+
+	// 2. Resolve speakers from devices.xml, then back each one up
+	devicesData := files[root+"/cloud/devices.xml"]
+	if devicesData == nil {
+		printWarn("devices.xml not available — skipping local backup")
+	} else {
+		targets := parseDevicesXML(devicesData)
+		if len(targets) == 0 {
+			printWarn("no device IP addresses found in devices.xml")
+		} else {
+			fmt.Printf("Found %d device(s) in cloud account, attempting local backup...\n", len(targets))
+		}
+
+		hc := &http.Client{Timeout: 10 * time.Second}
+
+		for k, v := range collectLocalFiles(hc, targets, root, doSSH) {
+			files[k] = v
+		}
+	}
+
+	if err := writeArchive(output, format, files); err != nil {
+		return fmt.Errorf("writing archive: %w", err)
+	}
+
+	fmt.Printf("Archive written: %s (%d files)\n", output, len(files))
+
+	return nil
+}
+
+type xmlDevice struct {
+	Name      string `xml:"name"`
+	IPAddress string `xml:"ipaddress"`
+}
+
+type xmlDevices struct {
+	XMLName xml.Name    `xml:"devices"`
+	Devices []xmlDevice `xml:"device"`
+}
+
+// parseDevicesXML extracts speaker targets from a devices.xml cloud response.
+func parseDevicesXML(data []byte) []speakerTarget {
+	var d xmlDevices
+
+	if err := xml.Unmarshal(data, &d); err != nil {
+		return nil
+	}
+
+	var targets []speakerTarget
+
+	for _, dev := range d.Devices {
+		if dev.IPAddress == "" {
+			continue
+		}
+
+		// Pass name as a hint for error messages; backupSpeakerHTTP re-fetches
+		// from /info to get the current name and include info.xml in the archive.
+		targets = append(targets, speakerTarget{host: dev.IPAddress, port: 8090, name: dev.Name})
+	}
+
+	return targets
+}

cmd/soundtouch-backup/cmd_cloud.go

@@ -0,0 +1,252 @@
+package main
+
+import (
+	"bytes"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+	"time"
+
+	"github.com/urfave/cli/v2"
+)
+
+const (
+	streamingBase  = "https://streaming.bose.com"
+	streamingCT    = "application/vnd.bose.streaming-v1.1+xml"
+	stockholmVer   = "27.0.13-4277+8963611.epdbuild.develop.hepdswbld04.2025-10-02T13:17:00"
+	nativeFrameVer = "27.0.2 -3353+4ae7c78.epdbuild.HEAD.ssgbld02.2023-10-12T15:10Z"
+	protocolVer    = "67"
+	appGUID        = "b94dedd1-a61b-492b-b86b-2bc32c9261f4"
+	appUserAgent   = "Mozilla/5.0 (Linux; Android 13; Android SDK built for arm64 Build/TE1A.220922.034; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/101.0.4951.61 Mobile Safari/537.36 Manufacturer/unknown DeviceModel/Android-SDK-built-for-arm64 SOUNDTOUCH_MOBILE_APP/" + appGUID
+)
+
+func cloudCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "cloud",
+		Usage: "Back up your Bose SoundTouch cloud account (devices, presets, sources)",
+		Flags: append(outputFlags,
+			&cli.StringFlag{
+				Name:    "email",
+				Aliases: []string{"e"},
+				Usage:   "Bose account email",
+				EnvVars: []string{"BOSE_EMAIL"},
+			},
+			&cli.StringFlag{
+				Name:    "password",
+				Aliases: []string{"pw"},
+				Usage:   "Bose account password",
+				EnvVars: []string{"BOSE_PASSWORD"},
+			},
+		),
+		Action: runCloudBackup,
+	}
+}
+
+func runCloudBackup(c *cli.Context) error {
+	output := resolveOutputPath(c.String("output"), c.String("format"))
+	format := c.String("format")
+
+	client, err := setupCloudClient(c.String("email"), c.String("password"))
+	if err != nil {
+		return err
+	}
+
+	root := archiveRoot()
+	files := collectCloudFiles(client, root)
+
+	if len(files) == 0 {
+		return fmt.Errorf("no data fetched")
+	}
+
+	if err := writeArchive(output, format, files); err != nil {
+		return fmt.Errorf("writing archive: %w", err)
+	}
+
+	fmt.Printf("Archive written: %s (%d files)\n", output, len(files))
+
+	return nil
+}
+
+// setupCloudClient prompts for missing credentials, then authenticates with the Bose cloud.
+func setupCloudClient(email, password string) (*cloudClient, error) {
+	if email == "" || password == "" {
+		var err error
+
+		email, password, err = promptCredentials(email)
+		if err != nil {
+			return nil, fmt.Errorf("credentials: %w", err)
+		}
+	}
+
+	if email == "" || password == "" {
+		return nil, fmt.Errorf("email and password are required")
+	}
+
+	fmt.Printf("Authenticating as %s...\n", email)
+
+	client, err := loginToCloud(email, password)
+	if err != nil {
+		return nil, fmt.Errorf("authentication failed: %w", err)
+	}
+
+	printOK(fmt.Sprintf("Authenticated (account ID: %s)", client.accountID))
+
+	return client, nil
+}
+
+// collectCloudFiles fetches all cloud account data and returns a files map ready for
+// archiving. Keys are prefixed with root (e.g. "soundtouch-backup-2026-05-02/cloud/").
+func collectCloudFiles(client *cloudClient, root string) map[string][]byte {
+	type cloudEndpoint struct {
+		label    string
+		filename string
+		fetch    func(*cloudClient) ([]byte, error)
+	}
+
+	endpoints := []cloudEndpoint{
+		{"email address", "emailaddress.xml", fetchEmailAddress},
+		{"devices", "devices.xml", fetchDevices},
+		{"sources", "sources.xml", fetchSources},
+		{"presets", "presets.xml", fetchPresets},
+		{"full account", "full.xml", fetchFull},
+	}
+
+	files := make(map[string][]byte)
+
+	for _, ep := range endpoints {
+		data, err := ep.fetch(client)
+		if err != nil {
+			printFail(fmt.Sprintf("%s: %v", ep.label, err))
+
+			continue
+		}
+
+		files[root+"/cloud/"+ep.filename] = data
+		printOK(fmt.Sprintf("%s (%d bytes)", ep.label, len(data)))
+	}
+
+	return files
+}
+
+type cloudClient struct {
+	http      *http.Client
+	accountID string
+	token     string
+}
+
+type loginXML struct {
+	XMLName  xml.Name `xml:"login"`
+	Username string   `xml:"username"`
+	Password string   `xml:"password"`
+}
+
+var accountIDRe = regexp.MustCompile(`<account\s+id="([^"]+)"`)
+
+func loginToCloud(email, password string) (*cloudClient, error) {
+	loginBody, err := xml.Marshal(loginXML{Username: email, Password: password})
+	if err != nil {
+		return nil, err
+	}
+
+	body := []byte(`<?xml version="1.0" encoding="UTF-8"?>`)
+	body = append(body, loginBody...)
+
+	req, err := http.NewRequest("POST", streamingBase+"/streaming/account/login", bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+
+	setStreamingHeaders(req, "")
+
+	hc := &http.Client{Timeout: 30 * time.Second}
+
+	resp, err := hc.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	token := resp.Header.Get("credentials")
+	if token == "" {
+		return nil, fmt.Errorf("no credentials in response — check your email and password")
+	}
+
+	data, err := io.ReadAll(io.LimitReader(resp.Body, 64*1024))
+	if err != nil {
+		return nil, err
+	}
+
+	m := accountIDRe.FindSubmatch(data)
+	if len(m) < 2 {
+		return nil, fmt.Errorf("could not extract account ID from login response")
+	}
+
+	return &cloudClient{http: hc, accountID: string(m[1]), token: token}, nil
+}
+
+func setStreamingHeaders(req *http.Request, token string) {
+	req.Header.Set("content-type", streamingCT)
+	req.Header.Set("accept", streamingCT)
+	req.Header.Set("clienttype", "SOUNDTOUCH_MOBILE_APP")
+	req.Header.Set("version_stockholmversion", stockholmVer)
+	req.Header.Set("version_nativeframeversion", nativeFrameVer)
+	req.Header.Set("version_protocolversion", protocolVer)
+	req.Header.Set("user-agent", appUserAgent)
+	req.Header.Set("guid", appGUID)
+	req.Header.Set("x-requested-with", "com.bose.soundtouch")
+	req.Header.Set("pragma", "no-cache")
+	req.Header.Set("cache-control", "no-cache")
+
+	if token != "" {
+		req.Header.Set("authorization", token)
+	}
+}
+
+func (c *cloudClient) get(path string) ([]byte, error) {
+	url := fmt.Sprintf("%s%s?_=%d", streamingBase, path, time.Now().UnixMilli())
+
+	req, err := http.NewRequest("GET", url, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	setStreamingHeaders(req, c.token)
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	return io.ReadAll(io.LimitReader(resp.Body, 2*1024*1024))
+}
+
+func fetchEmailAddress(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/emailaddress")
+}
+
+func fetchDevices(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/devices")
+}
+
+func fetchSources(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/sources")
+}
+
+func fetchPresets(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/presets/all")
+}
+
+func fetchFull(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/full")
+}

cmd/soundtouch-backup/cmd_local.go

@@ -0,0 +1,288 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/config"
+	"github.com/gesellix/bose-soundtouch/pkg/discovery"
+	"github.com/gesellix/bose-soundtouch/pkg/ssh"
+	"github.com/urfave/cli/v2"
+)
+
+var localEndpoints = []struct {
+	path string
+	file string
+}{
+	{"/info", "info.xml"},
+	{"/name", "name.xml"},
+	{"/presets", "presets.xml"},
+	{"/sources", "sources.xml"},
+	{"/now_playing", "now_playing.xml"},
+	{"/volume", "volume.xml"},
+	{"/bass", "bass.xml"},
+	{"/balance", "balance.xml"},
+	{"/capabilities", "capabilities.xml"},
+	{"/networkInfo", "network_info.xml"},
+	{"/clockDisplay", "clock_display.xml"},
+	{"/getZone", "zone.xml"},
+}
+
+// sshFiles lists individual device filesystem paths captured via SSH.
+// Paths that may not exist on all devices are silently skipped.
+var sshFiles = []string{
+	"/etc/hosts",
+	"/etc/resolv.conf",
+	"/etc/remote_services",
+	"/mnt/nv/remote_services",
+}
+
+// sshDirs lists device directories whose contents are recursively captured via SSH.
+var sshDirs = []string{
+	"/opt/Bose/etc",
+	"/mnt/nv/BoseApp-Persistence/1",
+}
+
+func localCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "local",
+		Usage: "Back up one or more SoundTouch speakers on your local network",
+		Flags: append(outputFlags,
+			&cli.StringSliceFlag{
+				Name:    "host",
+				Aliases: []string{"H"},
+				Usage:   "Speaker host/IP (repeatable for multiple speakers)",
+				EnvVars: []string{"SOUNDTOUCH_HOST"},
+			},
+			&cli.IntFlag{
+				Name:    "port",
+				Aliases: []string{"p"},
+				Usage:   "Speaker HTTP port",
+				Value:   8090,
+				EnvVars: []string{"SOUNDTOUCH_PORT"},
+			},
+			&cli.BoolFlag{
+				Name:    "discover",
+				Aliases: []string{"d"},
+				Usage:   "Auto-discover speakers on the local network",
+			},
+			&cli.DurationFlag{
+				Name:  "discover-timeout",
+				Usage: "Discovery timeout",
+				Value: 5 * time.Second,
+			},
+			&cli.BoolFlag{
+				Name:  "ssh",
+				Usage: "Also back up device filesystem files via SSH (root@host:22, no password required)",
+				Value: true,
+			},
+		),
+		Action: runLocalBackup,
+	}
+}
+
+type speakerTarget struct {
+	host string
+	port int
+	name string
+}
+
+func runLocalBackup(c *cli.Context) error {
+	hosts := c.StringSlice("host")
+	port := c.Int("port")
+	doDiscover := c.Bool("discover") || len(hosts) == 0
+	discoverTimeout := c.Duration("discover-timeout")
+	doSSH := c.Bool("ssh")
+	output := resolveOutputPath(c.String("output"), c.String("format"))
+	format := c.String("format")
+
+	var targets []speakerTarget
+
+	if doDiscover {
+		fmt.Printf("Discovering speakers (timeout: %s)...\n", discoverTimeout)
+
+		ctx, cancel := context.WithTimeout(c.Context, discoverTimeout)
+		defer cancel()
+
+		cfg, _ := config.LoadFromEnv()
+		svc := discovery.NewUnifiedDiscoveryService(cfg)
+
+		found, discErr := svc.DiscoverDevices(ctx)
+		if discErr != nil {
+			printWarn(fmt.Sprintf("Discovery failed: %v", discErr))
+		}
+
+		for _, d := range found {
+			targets = append(targets, speakerTarget{host: d.Host, port: d.Port, name: d.Name})
+			printOK(fmt.Sprintf("Found: %s (%s:%d)", d.Name, d.Host, d.Port))
+		}
+	}
+
+	for _, h := range hosts {
+		targets = append(targets, speakerTarget{host: h, port: port})
+	}
+
+	if len(targets) == 0 {
+		return fmt.Errorf("no speakers found — use --host <ip> or --discover")
+	}
+
+	hc := &http.Client{Timeout: 10 * time.Second}
+	root := archiveRoot()
+	files := collectLocalFiles(hc, targets, root, doSSH)
+
+	if len(files) == 0 {
+		return fmt.Errorf("no data collected")
+	}
+
+	if err := writeArchive(output, format, files); err != nil {
+		return fmt.Errorf("writing archive: %w", err)
+	}
+
+	fmt.Printf("Archive written: %s (%d files)\n", output, len(files))
+
+	return nil
+}
+
+// collectLocalFiles backs up all targets over HTTP (and optionally SSH) and returns
+// a files map ready for archiving. Keys are prefixed with root.
+func collectLocalFiles(hc *http.Client, targets []speakerTarget, root string, doSSH bool) map[string][]byte {
+	files := make(map[string][]byte)
+
+	for _, t := range targets {
+		name, entries, err := backupSpeakerHTTP(hc, t)
+		if err != nil {
+			printFail(fmt.Sprintf("%s:%d — %v", t.host, t.port, err))
+
+			continue
+		}
+
+		dir := root + "/local/" + sanitizeName(name) + "/"
+
+		for filename, data := range entries {
+			files[dir+filename] = data
+		}
+
+		printOK(fmt.Sprintf("%s: %d files via HTTP", name, len(entries)))
+
+		if doSSH {
+			sshEntries := backupSpeakerSSH(t.host, name)
+
+			for filename, data := range sshEntries {
+				files[dir+filename] = data
+			}
+
+			if len(sshEntries) > 0 {
+				printOK(fmt.Sprintf("%s: %d files via SSH", name, len(sshEntries)))
+			}
+		}
+	}
+
+	return files
+}
+
+func backupSpeakerHTTP(hc *http.Client, t speakerTarget) (name string, files map[string][]byte, err error) {
+	base := fmt.Sprintf("http://%s:%d", t.host, t.port)
+	files = make(map[string][]byte)
+	name = t.name
+	infoFetched := false
+
+	if name == "" {
+		data, ferr := fetchRaw(hc, base+"/info")
+		if ferr != nil {
+			return "", nil, fmt.Errorf("cannot reach %s: %w", base, ferr)
+		}
+
+		files["info.xml"] = data
+		infoFetched = true
+
+		if extracted := xmlFirst(data, "name"); extracted != "" {
+			name = extracted
+		} else {
+			name = t.host
+		}
+	}
+
+	for _, ep := range localEndpoints {
+		if ep.path == "/info" && infoFetched {
+			continue
+		}
+
+		data, ferr := fetchRaw(hc, base+ep.path)
+		if ferr != nil {
+			printWarn(fmt.Sprintf("%s: skipped %s (%v)", name, ep.file, ferr))
+			continue
+		}
+
+		files[ep.file] = data
+	}
+
+	return name, files, nil
+}
+
+// backupSpeakerSSH connects to the device via SSH and reads the key filesystem paths.
+// Files that don't exist on the device are silently skipped.
+// Returned map keys are relative paths within the device backup directory (e.g. "ssh/etc/hosts").
+func backupSpeakerSSH(host, deviceName string) map[string][]byte {
+	client := ssh.NewClient(host)
+	files := make(map[string][]byte)
+
+	for _, remotePath := range sshFiles {
+		data, err := client.ReadFile(remotePath)
+		if err != nil {
+			// Most missing files are expected (e.g. /etc/remote_services only exists post-migration)
+			printWarn(fmt.Sprintf("%s: SSH skipped %s (%v)", deviceName, remotePath, err))
+
+			continue
+		}
+
+		if len(data) == 0 {
+			printWarn(fmt.Sprintf("%s: SSH empty file %s", deviceName, remotePath))
+		}
+
+		files["ssh"+remotePath] = data
+	}
+
+	for _, remoteDir := range sshDirs {
+		dirFiles, err := client.ReadDir(remoteDir)
+		if err != nil {
+			printWarn(fmt.Sprintf("%s: SSH skipped dir %s (%v)", deviceName, remoteDir, err))
+			continue
+		}
+
+		for path, data := range dirFiles {
+			files["ssh"+path] = data
+		}
+	}
+
+	return files
+}
+
+func fetchRaw(hc *http.Client, url string) ([]byte, error) {
+	resp, err := hc.Get(url)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode >= 400 {
+		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	return io.ReadAll(io.LimitReader(resp.Body, 1024*1024))
+}
+
+func xmlFirst(data []byte, field string) string {
+	re := regexp.MustCompile(`<` + regexp.QuoteMeta(field) + `[^>]*>([^<]+)</` + regexp.QuoteMeta(field) + `>`)
+
+	m := re.FindSubmatch(data)
+	if len(m) >= 2 {
+		return strings.TrimSpace(string(m[1]))
+	}
+
+	return ""
+}

cmd/soundtouch-backup/common.go

@@ -0,0 +1,172 @@
+package main
+
+import (
+	"archive/tar"
+	"archive/zip"
+	"bufio"
+	"compress/gzip"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/urfave/cli/v2"
+	"golang.org/x/term"
+)
+
+const (
+	FormatTarGz = "tar.gz"
+	FormatZip   = "zip"
+)
+
+var outputFlags = []cli.Flag{
+	&cli.StringFlag{
+		Name:    "output",
+		Aliases: []string{"o"},
+		Usage:   "Output archive file (default: soundtouch-backup-YYYY-MM-DD.tar.gz)",
+		EnvVars: []string{"SOUNDTOUCH_BACKUP_OUTPUT"},
+	},
+	&cli.StringFlag{
+		Name:  "format",
+		Usage: "Archive format: tar.gz or zip",
+		Value: FormatTarGz,
+	},
+}
+
+func resolveOutputPath(output, format string) string {
+	date := time.Now().Format("2006-01-02")
+
+	ext := ".tar.gz"
+	if format == FormatZip {
+		ext = ".zip"
+	}
+
+	filename := "soundtouch-backup-" + date + ext
+
+	if output == "" {
+		return filename
+	}
+
+	if info, err := os.Stat(output); err == nil && info.IsDir() {
+		return output + string(os.PathSeparator) + filename
+	}
+
+	return output
+}
+
+func archiveRoot() string {
+	return "soundtouch-backup-" + time.Now().Format("2006-01-02")
+}
+
+func writeArchive(outputPath, format string, files map[string][]byte) error {
+	if format == FormatZip {
+		return writeZip(outputPath, files)
+	}
+
+	return writeTarGz(outputPath, files)
+}
+
+func writeTarGz(outputPath string, files map[string][]byte) error {
+	f, err := os.Create(outputPath)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	gz := gzip.NewWriter(f)
+	defer gz.Close()
+
+	tw := tar.NewWriter(gz)
+	defer tw.Close()
+
+	now := time.Now()
+	for name, data := range files {
+		hdr := &tar.Header{
+			Name:     name,
+			Mode:     0644,
+			Size:     int64(len(data)),
+			ModTime:  now,
+			Typeflag: tar.TypeReg,
+		}
+		if err := tw.WriteHeader(hdr); err != nil {
+			return fmt.Errorf("tar header %s: %w", name, err)
+		}
+
+		if _, err := tw.Write(data); err != nil {
+			return fmt.Errorf("tar write %s: %w", name, err)
+		}
+	}
+
+	return nil
+}
+
+func writeZip(outputPath string, files map[string][]byte) error {
+	f, err := os.Create(outputPath)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	zw := zip.NewWriter(f)
+	defer zw.Close()
+
+	for name, data := range files {
+		w, err := zw.Create(name)
+		if err != nil {
+			return fmt.Errorf("zip entry %s: %w", name, err)
+		}
+
+		if _, err := w.Write(data); err != nil {
+			return fmt.Errorf("zip write %s: %w", name, err)
+		}
+	}
+
+	return nil
+}
+
+func promptCredentials(emailHint string) (email, password string, err error) {
+	r := bufio.NewReader(os.Stdin)
+
+	if emailHint != "" {
+		email = emailHint
+	} else {
+		fmt.Print("Bose account email: ")
+
+		email, err = r.ReadString('\n')
+		if err != nil {
+			return
+		}
+
+		email = strings.TrimSpace(email)
+	}
+
+	fmt.Print("Password: ")
+
+	raw, termErr := term.ReadPassword(int(os.Stdin.Fd()))
+
+	fmt.Println()
+
+	if termErr != nil {
+		err = fmt.Errorf("reading password: %w (tip: use --password flag or BOSE_PASSWORD env var)", termErr)
+		return
+	}
+
+	password = string(raw)
+
+	return
+}
+
+func sanitizeName(name string) string {
+	r := strings.NewReplacer(
+		"/", "_", "\\", "_", ":", "_",
+		"*", "_", "?", "_", "\"", "_",
+		"<", "_", ">", "_", "|", "_",
+		" ", "_",
+	)
+
+	return r.Replace(name)
+}
+
+func printOK(msg string)   { fmt.Printf("  ✓ %s\n", msg) }
+func printFail(msg string) { fmt.Printf("  ✗ %s\n", msg) }
+func printWarn(msg string) { fmt.Printf("  ⚠ %s\n", msg) }

cmd/soundtouch-backup/main.go

@@ -0,0 +1,37 @@
+// Package main implements the soundtouch-backup tool for backing up Bose SoundTouch
+// cloud account data and local speaker filesystem files.
+package main
+
+import (
+	"log"
+	"os"
+	"runtime/debug"
+
+	"github.com/urfave/cli/v2"
+)
+
+var version = "dev"
+
+func init() {
+	if info, ok := debug.ReadBuildInfo(); ok {
+		if info.Main.Version != "" && info.Main.Version != "(devel)" {
+			version = info.Main.Version
+		}
+	}
+}
+
+func main() {
+	app := &cli.App{
+		Name:    "soundtouch-backup",
+		Usage:   "Back up Bose SoundTouch account and speaker data",
+		Version: version,
+		Commands: []*cli.Command{
+			allCommand(),
+			cloudCommand(),
+			localCommand(),
+		},
+	}
+	if err := app.Run(os.Args); err != nil {
+		log.Fatal(err)
+	}
+}

cmd/soundtouch-cli/cmd_account.go

@@ -0,0 +1,742 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/urfave/cli/v2"
+)
+
+// createCredentialsForSource creates credentials for the specified source type
+func createCredentialsForSource(source, user, password, displayName string) *models.MusicServiceCredentials {
+	switch source {
+	case "SPOTIFY":
+		return models.NewSpotifyCredentials(user, password)
+	case "PANDORA":
+		return models.NewPandoraCredentials(user, password)
+	case "AMAZON":
+		return models.NewAmazonMusicCredentials(user, password)
+	case "DEEZER":
+		return models.NewDeezerCredentials(user, password)
+	case "IHEART":
+		return models.NewIHeartRadioCredentials(user, password)
+	case "STORED_MUSIC":
+		if displayName == "" {
+			displayName = "Network Music Library"
+		}
+
+		return models.NewStoredMusicCredentials(user, displayName)
+	default:
+		// Generic credentials for other services
+		if displayName == "" {
+			displayName = source
+		}
+
+		return models.NewMusicServiceCredentials(source, displayName, user, password)
+	}
+}
+
+// validateAccountInput validates the input parameters for account management
+func validateAccountInput(source, user, password string) error {
+	if source == "" {
+		return fmt.Errorf("source is required (use --source)")
+	}
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	// STORED_MUSIC doesn't require a password
+	if source != "STORED_MUSIC" && password == "" {
+		return fmt.Errorf("password is required for %s (use --password)", source)
+	}
+
+	return nil
+}
+
+// addMusicServiceAccount handles adding a music service account
+func addMusicServiceAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	source := strings.ToUpper(c.String("source"))
+	user := c.String("user")
+	password := c.String("password")
+	displayName := c.String("name")
+
+	if validationErr := validateAccountInput(source, user, password); validationErr != nil {
+		return validationErr
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Adding %s account", source), clientConfig.Host, clientConfig.Port)
+
+	credentials := createCredentialsForSource(source, user, password, displayName)
+
+	// Override display name if provided
+	if c.IsSet("name") {
+		credentials.DisplayName = displayName
+	}
+
+	fmt.Printf("  Service: %s\n", credentials.GetDescription())
+	fmt.Printf("  User: %s\n", user)
+
+	if source == "STORED_MUSIC" {
+		fmt.Printf("  Type: Network Music Library\n")
+	} else {
+		fmt.Printf("  Type: Streaming Service\n")
+	}
+
+	err = client.SetMusicServiceAccount(credentials)
+	if err != nil {
+		return fmt.Errorf("failed to add music service account: %w", err)
+	}
+
+	PrintSuccess(fmt.Sprintf("%s account added successfully", source))
+
+	// Show next steps
+	fmt.Printf("\n💡 Next Steps:\n")
+	fmt.Printf("   • Check available sources: soundtouch-cli --host %s source list\n", clientConfig.Host)
+	fmt.Printf("   • Select this source: soundtouch-cli --host %s source select --source %s --account %s\n", clientConfig.Host, source, user)
+
+	return nil
+}
+
+// removeMusicServiceAccount handles removing a music service account
+func removeMusicServiceAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	source := strings.ToUpper(c.String("source"))
+	user := c.String("user")
+	displayName := c.String("name")
+
+	if source == "" {
+		return fmt.Errorf("source is required (use --source)")
+	}
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Removing %s account", source), clientConfig.Host, clientConfig.Port)
+
+	var credentials *models.MusicServiceCredentials
+
+	// Create credentials for removal (empty password)
+	switch source {
+	case "SPOTIFY":
+		credentials = models.NewSpotifyCredentials(user, "")
+	case "PANDORA":
+		credentials = models.NewPandoraCredentials(user, "")
+	case "AMAZON":
+		credentials = models.NewAmazonMusicCredentials(user, "")
+	case "DEEZER":
+		credentials = models.NewDeezerCredentials(user, "")
+	case "IHEART":
+		credentials = models.NewIHeartRadioCredentials(user, "")
+	case "STORED_MUSIC":
+		if displayName == "" {
+			displayName = "Network Music Library"
+		}
+
+		credentials = models.NewStoredMusicCredentials(user, displayName)
+	default:
+		// Generic credentials for other services
+		if displayName == "" {
+			displayName = source
+		}
+
+		credentials = models.NewMusicServiceCredentials(source, displayName, user, "")
+	}
+
+	// Override display name if provided
+	if c.IsSet("name") {
+		credentials.DisplayName = displayName
+	}
+
+	fmt.Printf("  Service: %s\n", credentials.GetDescription())
+	fmt.Printf("  User: %s\n", user)
+
+	err = client.RemoveMusicServiceAccount(credentials)
+	if err != nil {
+		return fmt.Errorf("failed to remove music service account: %w", err)
+	}
+
+	PrintSuccess(fmt.Sprintf("%s account removed successfully", source))
+
+	return nil
+}
+
+// addSpotifyAccount is a convenience command for adding Spotify accounts
+func addSpotifyAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+	password := c.String("password")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	if password == "" {
+		return fmt.Errorf("password is required (use --password)")
+	}
+
+	PrintDeviceHeader("Adding Spotify Premium account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+	fmt.Printf("  Service: Spotify Premium\n")
+
+	err = client.AddSpotifyAccount(user, password)
+	if err != nil {
+		return fmt.Errorf("failed to add Spotify account: %w", err)
+	}
+
+	PrintSuccess("Spotify account added successfully")
+
+	// Show next steps
+	fmt.Printf("\n💡 Next Steps:\n")
+	fmt.Printf("   • Check available sources: soundtouch-cli --host %s source list\n", clientConfig.Host)
+	fmt.Printf("   • Select Spotify: soundtouch-cli --host %s source spotify\n", clientConfig.Host)
+
+	return nil
+}
+
+// removeSpotifyAccount is a convenience command for removing Spotify accounts
+func removeSpotifyAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	PrintDeviceHeader("Removing Spotify account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+
+	err = client.RemoveSpotifyAccount(user)
+	if err != nil {
+		return fmt.Errorf("failed to remove Spotify account: %w", err)
+	}
+
+	PrintSuccess("Spotify account removed successfully")
+
+	return nil
+}
+
+// addPandoraAccount is a convenience command for adding Pandora accounts
+func addPandoraAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+	password := c.String("password")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	if password == "" {
+		return fmt.Errorf("password is required (use --password)")
+	}
+
+	PrintDeviceHeader("Adding Pandora account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+	fmt.Printf("  Service: Pandora Music Service\n")
+
+	err = client.AddPandoraAccount(user, password)
+	if err != nil {
+		return fmt.Errorf("failed to add Pandora account: %w", err)
+	}
+
+	PrintSuccess("Pandora account added successfully")
+
+	// Show next steps
+	fmt.Printf("\n💡 Next Steps:\n")
+	fmt.Printf("   • Check available sources: soundtouch-cli --host %s source list\n", clientConfig.Host)
+	fmt.Printf("   • Select Pandora: soundtouch-cli --host %s source select --source PANDORA --account %s\n", clientConfig.Host, user)
+
+	return nil
+}
+
+// removePandoraAccount is a convenience command for removing Pandora accounts
+func removePandoraAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	PrintDeviceHeader("Removing Pandora account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+
+	err = client.RemovePandoraAccount(user)
+	if err != nil {
+		return fmt.Errorf("failed to remove Pandora account: %w", err)
+	}
+
+	PrintSuccess("Pandora account removed successfully")
+
+	return nil
+}
+
+// addStoredMusicAccount is a convenience command for adding STORED_MUSIC accounts
+func addStoredMusicAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+	displayName := c.String("name")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user) - this should be the UPnP server GUID with /0 suffix")
+	}
+
+	if displayName == "" {
+		displayName = "Network Music Library"
+	}
+
+	PrintDeviceHeader("Adding network music library", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  Server ID: %s\n", user)
+	fmt.Printf("  Display Name: %s\n", displayName)
+	fmt.Printf("  Type: UPnP/DLNA Media Server\n")
+
+	err = client.AddStoredMusicAccount(user, displayName)
+	if err != nil {
+		return fmt.Errorf("failed to add network music library: %w", err)
+	}
+
+	PrintSuccess("Network music library added successfully")
+
+	// Show next steps
+	fmt.Printf("\n💡 Next Steps:\n")
+	fmt.Printf("   • Check available sources: soundtouch-cli --host %s source list\n", clientConfig.Host)
+	fmt.Printf("   • Browse library: soundtouch-cli --host %s browse stored-music --account %s\n", clientConfig.Host, user)
+
+	return nil
+}
+
+// addAmazonMusicAccount is a convenience command for adding Amazon Music accounts
+func addAmazonMusicAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+	password := c.String("password")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	if password == "" {
+		return fmt.Errorf("password is required (use --password)")
+	}
+
+	PrintDeviceHeader("Adding Amazon Music account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+	fmt.Printf("  Service: Amazon Music\n")
+
+	err = client.AddAmazonMusicAccount(user, password)
+	if err != nil {
+		return fmt.Errorf("failed to add Amazon Music account: %w", err)
+	}
+
+	PrintSuccess("Amazon Music account added successfully")
+
+	// Show next steps
+	fmt.Printf("\n💡 Next Steps:\n")
+	fmt.Printf("   • Check available sources: soundtouch-cli --host %s source list\n", clientConfig.Host)
+	fmt.Printf("   • Select Amazon Music: soundtouch-cli --host %s source select --source AMAZON --account %s\n", clientConfig.Host, user)
+
+	return nil
+}
+
+// removeAmazonMusicAccount is a convenience command for removing Amazon Music accounts
+func removeAmazonMusicAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	PrintDeviceHeader("Removing Amazon Music account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+
+	err = client.RemoveAmazonMusicAccount(user)
+	if err != nil {
+		return fmt.Errorf("failed to remove Amazon Music account: %w", err)
+	}
+
+	PrintSuccess("Amazon Music account removed successfully")
+
+	return nil
+}
+
+// addDeezerAccount is a convenience command for adding Deezer accounts
+func addDeezerAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+	password := c.String("password")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	if password == "" {
+		return fmt.Errorf("password is required (use --password)")
+	}
+
+	PrintDeviceHeader("Adding Deezer Premium account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+	fmt.Printf("  Service: Deezer Premium\n")
+
+	err = client.AddDeezerAccount(user, password)
+	if err != nil {
+		return fmt.Errorf("failed to add Deezer account: %w", err)
+	}
+
+	PrintSuccess("Deezer account added successfully")
+
+	// Show next steps
+	fmt.Printf("\n💡 Next Steps:\n")
+	fmt.Printf("   • Check available sources: soundtouch-cli --host %s source list\n", clientConfig.Host)
+	fmt.Printf("   • Select Deezer: soundtouch-cli --host %s source select --source DEEZER --account %s\n", clientConfig.Host, user)
+
+	return nil
+}
+
+// removeDeezerAccount is a convenience command for removing Deezer accounts
+func removeDeezerAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	PrintDeviceHeader("Removing Deezer account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+
+	err = client.RemoveDeezerAccount(user)
+	if err != nil {
+		return fmt.Errorf("failed to remove Deezer account: %w", err)
+	}
+
+	PrintSuccess("Deezer account removed successfully")
+
+	return nil
+}
+
+// addIHeartRadioAccount is a convenience command for adding iHeartRadio accounts
+func addIHeartRadioAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+	password := c.String("password")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	if password == "" {
+		return fmt.Errorf("password is required (use --password)")
+	}
+
+	PrintDeviceHeader("Adding iHeartRadio account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+	fmt.Printf("  Service: iHeartRadio\n")
+
+	err = client.AddIHeartRadioAccount(user, password)
+	if err != nil {
+		return fmt.Errorf("failed to add iHeartRadio account: %w", err)
+	}
+
+	PrintSuccess("iHeartRadio account added successfully")
+
+	// Show next steps
+	fmt.Printf("\n💡 Next Steps:\n")
+	fmt.Printf("   • Check available sources: soundtouch-cli --host %s source list\n", clientConfig.Host)
+	fmt.Printf("   • Select iHeartRadio: soundtouch-cli --host %s source select --source IHEART --account %s\n", clientConfig.Host, user)
+
+	return nil
+}
+
+// removeIHeartRadioAccount is a convenience command for removing iHeartRadio accounts
+func removeIHeartRadioAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	PrintDeviceHeader("Removing iHeartRadio account", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  User: %s\n", user)
+
+	err = client.RemoveIHeartRadioAccount(user)
+	if err != nil {
+		return fmt.Errorf("failed to remove iHeartRadio account: %w", err)
+	}
+
+	PrintSuccess("iHeartRadio account removed successfully")
+
+	return nil
+}
+
+// removeStoredMusicAccount is a convenience command for removing STORED_MUSIC accounts
+func removeStoredMusicAccount(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	user := c.String("user")
+	displayName := c.String("name")
+
+	if user == "" {
+		return fmt.Errorf("user is required (use --user)")
+	}
+
+	if displayName == "" {
+		displayName = "Network Music Library"
+	}
+
+	PrintDeviceHeader("Removing network music library", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  Server ID: %s\n", user)
+	fmt.Printf("  Display Name: %s\n", displayName)
+
+	err = client.RemoveStoredMusicAccount(user, displayName)
+	if err != nil {
+		return fmt.Errorf("failed to remove network music library: %w", err)
+	}
+
+	PrintSuccess("Network music library removed successfully")
+
+	return nil
+}
+
+// listMusicServiceAccounts shows configured music service accounts from sources
+func listMusicServiceAccounts(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	PrintDeviceHeader("Music service accounts", clientConfig.Host, clientConfig.Port)
+
+	sources, err := client.GetSources()
+	if err != nil {
+		return fmt.Errorf("failed to get sources: %w", err)
+	}
+
+	// Filter for streaming/music service sources
+	musicSources := []string{"SPOTIFY", "PANDORA", "AMAZON", "DEEZER", "IHEART", "STORED_MUSIC", "LOCAL_MUSIC"}
+
+	found := false
+
+	for _, musicSource := range musicSources {
+		sourcesOfType := sources.GetSourcesByType(musicSource)
+		if len(sourcesOfType) > 0 {
+			found = true
+
+			fmt.Printf("\n📱 %s:\n", getServiceDisplayName(musicSource))
+
+			for _, source := range sourcesOfType {
+				status := "🔴 Unavailable"
+				if source.Status == models.SourceStatusReady {
+					status = "🟢 Ready"
+				}
+
+				accountInfo := ""
+				if source.SourceAccount != "" && source.SourceAccount != source.Source {
+					accountInfo = fmt.Sprintf(" (%s)", source.SourceAccount)
+				}
+
+				fmt.Printf("    %s %s%s\n", status, source.GetDisplayName(), accountInfo)
+			}
+		}
+	}
+
+	if !found {
+		fmt.Printf("  📭 No music service accounts configured\n")
+		fmt.Printf("\n💡 Add accounts with:\n")
+		fmt.Printf("   • soundtouch-cli --host %s account add-spotify --user <email> --password <pass>\n", clientConfig.Host)
+		fmt.Printf("   • soundtouch-cli --host %s account add-pandora --user <user> --password <pass>\n", clientConfig.Host)
+		fmt.Printf("   • soundtouch-cli --host %s account add --source AMAZON --user <user> --password <pass>\n", clientConfig.Host)
+	}
+
+	return nil
+}
+
+// pairDevice triggers the Stockholm registration flow via WebSocket
+func pairDevice(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	accountID := c.String("id")
+	token := c.String("token")
+
+	PrintDeviceHeader("Pairing device with Marge account", clientConfig.Host, clientConfig.Port)
+	fmt.Printf("  Account ID: %s\n", accountID)
+
+	// We need a WebSocket client for this
+	ws := client.NewWebSocketClient(nil)
+
+	err = ws.Connect()
+	if err != nil {
+		return fmt.Errorf("failed to connect to device WebSocket: %w", err)
+	}
+
+	defer func() { _ = ws.Disconnect() }()
+
+	err = ws.PairWithAccount(accountID, token)
+	if err != nil {
+		return fmt.Errorf("failed to send pairing request: %w", err)
+	}
+
+	PrintSuccess("Pairing request sent successfully")
+	fmt.Println("💡 The device will now register itself with the cloud service.")
+
+	return nil
+}
+
+// unpairDevice triggers the Stockholm unregistration flow via WebSocket
+func unpairDevice(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	PrintDeviceHeader("Unpairing device from Marge account", clientConfig.Host, clientConfig.Port)
+
+	// We need a WebSocket client for this
+	ws := client.NewWebSocketClient(nil)
+
+	err = ws.Connect()
+	if err != nil {
+		return fmt.Errorf("failed to connect to device WebSocket: %w", err)
+	}
+
+	defer func() { _ = ws.Disconnect() }()
+
+	err = ws.UnPairFromAccount()
+	if err != nil {
+		return fmt.Errorf("failed to send unpairing request: %w", err)
+	}
+
+	PrintSuccess("Unpairing request sent successfully")
+
+	return nil
+}
+
+// getServiceDisplayName returns a user-friendly display name for a service
+func getServiceDisplayName(source string) string {
+	switch source {
+	case "SPOTIFY":
+		return "Spotify"
+	case "PANDORA":
+		return "Pandora"
+	case "AMAZON":
+		return "Amazon Music"
+	case "DEEZER":
+		return "Deezer"
+	case "IHEART":
+		return "iHeartRadio"
+	case "STORED_MUSIC":
+		return "Network Libraries"
+	case "LOCAL_MUSIC":
+		return "Local Music Servers"
+	default:
+		return source
+	}
+}

cmd/soundtouch-cli/cmd_events.go

@@ -0,0 +1,464 @@
+// Package main provides the soundtouch-cli events command for WebSocket event monitoring.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/client"
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/urfave/cli/v2"
+)
+
+// eventSubscribe handles the events subscribe command
+func eventSubscribe(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	// Parse filters
+	filterStr := c.String("filter")
+	filters := parseEventFilters(filterStr)
+
+	// Parse duration
+	duration := c.Duration("duration")
+	verbose := c.Bool("verbose")
+	reconnect := !c.Bool("no-reconnect")
+
+	PrintDeviceHeader("Starting WebSocket event monitoring", clientConfig.Host, clientConfig.Port)
+
+	// Create SoundTouch client
+	soundTouchClient, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	// Test basic connectivity
+	fmt.Println("Testing device connectivity...")
+
+	deviceInfo, err := soundTouchClient.GetDeviceInfo()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to connect to device: %v", err))
+		return err
+	}
+
+	macAddress := ""
+	if len(deviceInfo.NetworkInfo) > 0 {
+		macAddress = deviceInfo.NetworkInfo[0].MacAddress
+	}
+
+	fmt.Printf("✅ Connected to: %s (Type: %s, MAC: %s)\n",
+		deviceInfo.Name, deviceInfo.Type, macAddress)
+
+	// Create WebSocket client
+	wsClient := setupWebSocketClient(soundTouchClient, reconnect, verbose)
+
+	// Set up event handlers
+	setupEventHandlers(wsClient, filters, verbose)
+
+	// Connect to WebSocket
+	fmt.Println("🔌 Connecting to WebSocket...")
+
+	err = wsClient.Connect()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to connect to WebSocket: %v", err))
+		return err
+	}
+
+	fmt.Println("✅ Connected! Listening for events...")
+
+	if len(filters) > 0 {
+		fmt.Printf("📋 Filtering events: %s\n", strings.Join(getFilterKeys(filters), ", "))
+	}
+
+	if duration > 0 {
+		fmt.Printf("⏰ Will listen for %v\n", duration)
+	} else {
+		fmt.Println("⏸️  Press Ctrl+C to stop")
+	}
+
+	// Set up graceful shutdown
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	// Handle duration limit
+	if duration > 0 {
+		go func() {
+			select {
+			case <-time.After(duration):
+				fmt.Println("\n⏰ Duration limit reached, shutting down...")
+				cancel()
+			case <-ctx.Done():
+				return
+			}
+		}()
+	}
+
+	// Handle interrupt signals
+	sigChan := make(chan os.Signal, 1)
+	signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
+
+	go func() {
+		select {
+		case sig := <-sigChan:
+			fmt.Printf("\n🛑 Received signal %v, shutting down...\n", sig)
+			cancel()
+		case <-ctx.Done():
+			return
+		}
+	}()
+
+	// Wait for shutdown
+	<-ctx.Done()
+
+	// Disconnect WebSocket
+	fmt.Println("🔌 Disconnecting...")
+
+	if err := wsClient.Disconnect(); err != nil {
+		PrintError(fmt.Sprintf("Error during disconnect: %v", err))
+	}
+
+	fmt.Println("✅ Disconnected successfully")
+
+	return nil
+}
+
+// parseEventFilters validates and parses the filter string
+func parseEventFilters(eventFilter string) map[string]bool {
+	validFilters := map[string]bool{
+		"nowPlaying": true, "volume": true, "connection": true,
+		"preset": true, "zone": true, "bass": true,
+		"sdkInfo": true, "userActivity": true,
+	}
+
+	if eventFilter == "" {
+		return nil
+	}
+
+	filters := make(map[string]bool)
+	filterList := strings.Split(eventFilter, ",")
+
+	for _, f := range filterList {
+		f = strings.TrimSpace(f)
+		if !validFilters[f] {
+			PrintError(fmt.Sprintf("Invalid filter '%s'. Valid filters: %s",
+				f, strings.Join(getFilterKeys(validFilters), ", ")))
+			os.Exit(1)
+		}
+
+		filters[f] = true
+	}
+
+	return filters
+}
+
+// setupWebSocketClient creates and configures the WebSocket client
+func setupWebSocketClient(soundTouchClient *client.Client, reconnect, verbose bool) *client.WebSocketClient {
+	wsConfig := &client.WebSocketConfig{
+		ReconnectInterval:    5 * time.Second,
+		MaxReconnectAttempts: 0, // Unlimited if reconnect enabled
+		PingInterval:         30 * time.Second,
+		PongTimeout:          10 * time.Second,
+		ReadBufferSize:       2048,
+		WriteBufferSize:      2048,
+	}
+
+	if verbose {
+		wsConfig.Logger = &VerboseLogger{}
+	} else {
+		wsConfig.Logger = &SilentLogger{}
+	}
+
+	if !reconnect {
+		wsConfig.MaxReconnectAttempts = 1
+	}
+
+	return soundTouchClient.NewWebSocketClient(wsConfig)
+}
+
+// setupEventHandlers configures all event handlers
+func setupEventHandlers(wsClient *client.WebSocketClient, filters map[string]bool, verbose bool) {
+	// Now Playing events
+	if filters == nil || filters["nowPlaying"] {
+		wsClient.OnNowPlaying(func(event *models.NowPlayingUpdatedEvent) {
+			handleNowPlayingEvent(event, verbose)
+		})
+	}
+
+	// Volume events
+	if filters == nil || filters["volume"] {
+		wsClient.OnVolumeUpdated(func(event *models.VolumeUpdatedEvent) {
+			handleVolumeEvent(event, verbose)
+		})
+	}
+
+	// Connection state events
+	if filters == nil || filters["connection"] {
+		wsClient.OnConnectionState(func(event *models.ConnectionStateUpdatedEvent) {
+			handleConnectionEvent(event)
+		})
+	}
+
+	// Preset events
+	if filters == nil || filters["preset"] {
+		wsClient.OnPresetUpdated(func(event *models.PresetUpdatedEvent) {
+			handlePresetEvent(event, verbose)
+		})
+	}
+
+	// Zone/Multiroom events
+	if filters == nil || filters["zone"] {
+		wsClient.OnZoneUpdated(func(event *models.ZoneUpdatedEvent) {
+			handleZoneEvent(event)
+		})
+	}
+
+	// Bass events
+	if filters == nil || filters["bass"] {
+		wsClient.OnBassUpdated(func(event *models.BassUpdatedEvent) {
+			handleBassEvent(event)
+		})
+	}
+
+	// Special message handler
+	wsClient.OnSpecialMessage(func(message *models.SpecialMessage) {
+		handleSpecialMessage(message, filters, verbose)
+	})
+
+	// Unknown events (always enabled for debugging)
+	wsClient.OnUnknownEvent(func(event *models.WebSocketEvent) {
+		handleUnknownEvent(event, verbose)
+	})
+}
+
+// Event handlers
+func handleNowPlayingEvent(event *models.NowPlayingUpdatedEvent, verbose bool) {
+	fmt.Printf("\n🎵 Now Playing Update [%s]:\n", event.DeviceID)
+	np := &event.NowPlaying
+
+	if np.IsEmpty() {
+		fmt.Println("  ⏹️  Nothing playing")
+		return
+	}
+
+	fmt.Printf("  🎵 %s\n", np.GetDisplayTitle())
+
+	if artist := np.GetDisplayArtist(); artist != "" {
+		fmt.Printf("  👤 %s\n", artist)
+	}
+
+	if np.Album != "" {
+		fmt.Printf("  💿 %s\n", np.Album)
+	}
+
+	fmt.Printf("  📻 Source: %s\n", np.Source)
+	fmt.Printf("  ▶️  Status: %s\n", np.PlayStatus.String())
+
+	if np.HasTimeInfo() {
+		fmt.Printf("  ⏱️  Duration: %s\n", np.FormatDuration())
+	}
+
+	if np.ShuffleSetting != "" {
+		fmt.Printf("  🔀 Shuffle: %s\n", np.ShuffleSetting.String())
+	}
+
+	if np.RepeatSetting != "" {
+		fmt.Printf("  🔁 Repeat: %s\n", np.RepeatSetting.String())
+	}
+
+	if verbose {
+		fmt.Printf("  📱 Raw Source: %s, Account: %s\n", np.Source, np.SourceAccount)
+
+		if np.Art != nil && np.Art.URL != "" {
+			fmt.Printf("  🖼️  Artwork: %s\n", np.Art.URL)
+		}
+	}
+}
+
+func handleVolumeEvent(event *models.VolumeUpdatedEvent, verbose bool) {
+	vol := &event.Volume
+	fmt.Printf("\n🔊 Volume Update [%s]:\n", event.DeviceID)
+
+	if vol.IsMuted() {
+		fmt.Println("  🔇 Muted")
+	} else {
+		fmt.Printf("  🔊 Level: %d\n", vol.ActualVolume)
+
+		if vol.TargetVolume != vol.ActualVolume {
+			fmt.Printf("  🎯 Target: %d\n", vol.TargetVolume)
+		}
+
+		fmt.Printf("  📊 %s\n", models.GetVolumeLevelName(vol.ActualVolume))
+	}
+
+	if verbose {
+		fmt.Printf("  📱 Sync: %v\n", vol.IsVolumeSync())
+	}
+}
+
+func handleConnectionEvent(event *models.ConnectionStateUpdatedEvent) {
+	cs := &event.ConnectionState
+	fmt.Printf("\n🌐 Connection Update [%s]:\n", event.DeviceID)
+
+	if cs.IsConnected() {
+		fmt.Println("  ✅ Connected")
+	} else {
+		fmt.Printf("  ❌ State: %s\n", cs.State)
+	}
+
+	if cs.Signal != "" {
+		fmt.Printf("  📶 Signal: %s\n", cs.GetSignalStrength())
+	}
+}
+
+func handlePresetEvent(event *models.PresetUpdatedEvent, verbose bool) {
+	presets := &event.Presets
+
+	deviceHeader := "\n📻 Presets Update"
+	if event.DeviceID != "" {
+		deviceHeader += fmt.Sprintf(" [%s]", event.DeviceID)
+	}
+
+	fmt.Printf("%s:\n", deviceHeader)
+	fmt.Printf("  📻 Total presets: %d\n", len(presets.Preset))
+
+	for _, preset := range presets.Preset {
+		fmt.Printf("  📻 Preset %d:", preset.ID)
+
+		if preset.ContentItem != nil {
+			fmt.Printf(" %s", preset.ContentItem.ItemName)
+			fmt.Printf(" (%s)", preset.ContentItem.Source)
+		}
+
+		fmt.Println()
+	}
+
+	if verbose {
+		fmt.Printf("  📱 Raw presets data: %d total presets\n", len(presets.Preset))
+	}
+}
+
+func handleZoneEvent(event *models.ZoneUpdatedEvent) {
+	zone := &event.Zone
+	fmt.Printf("\n🏠 Zone Update [%s]:\n", event.DeviceID)
+	fmt.Printf("  👑 Master: %s\n", zone.Master)
+
+	if len(zone.Members) > 0 {
+		fmt.Printf("  👥 Members (%d):\n", len(zone.Members))
+
+		for i, member := range zone.Members {
+			fmt.Printf("    %d. %s (%s)\n", i+1, member.DeviceID, member.IP)
+		}
+	} else {
+		fmt.Println("  👤 Single device (no zone)")
+	}
+}
+
+func handleBassEvent(event *models.BassUpdatedEvent) {
+	bass := &event.Bass
+	fmt.Printf("\n🎵 Bass Update [%s]:\n", event.DeviceID)
+	fmt.Printf("  🎚️  Level: %d\n", bass.ActualBass)
+
+	if bass.TargetBass != bass.ActualBass {
+		fmt.Printf("  🎯 Target: %d\n", bass.TargetBass)
+	}
+
+	levelDesc := "Neutral"
+	if bass.ActualBass > 0 {
+		levelDesc = "Boosted"
+	} else if bass.ActualBass < 0 {
+		levelDesc = "Reduced"
+	}
+
+	fmt.Printf("  📊 %s\n", levelDesc)
+}
+
+func handleSpecialMessage(message *models.SpecialMessage, filters map[string]bool, verbose bool) {
+	// Check if we should filter this message type
+	if filters != nil {
+		switch message.Type {
+		case models.MessageTypeSdkInfo:
+			if !filters["sdkInfo"] {
+				return
+			}
+		case models.MessageTypeUserActivity:
+			if !filters["userActivity"] {
+				return
+			}
+		case models.MessageTypeUserInactivity:
+			if !filters["userInactivity"] {
+				return
+			}
+		}
+	}
+
+	switch message.Type {
+	case models.MessageTypeSdkInfo:
+		if sdkInfo := message.GetSdkInfo(); sdkInfo != nil {
+			fmt.Printf("\n📡 SDK Info:\n")
+			fmt.Printf("  📋 Server Version: %s\n", sdkInfo.ServerVersion)
+			fmt.Printf("  🔧 Server Build: %s\n", sdkInfo.ServerBuild)
+		}
+	case models.MessageTypeUserActivity:
+		fmt.Printf("\n👤 User Activity [%s]\n", message.DeviceID)
+
+		if verbose {
+			fmt.Printf("  ⏰ Timestamp: %s\n", message.Timestamp.Format("15:04:05"))
+		}
+	case models.MessageTypeUserInactivity:
+		fmt.Printf("\n💤 User Inactivity [%s]\n", message.DeviceID)
+
+		if verbose {
+			fmt.Printf("  ⏰ Timestamp: %s\n", message.Timestamp.Format("15:04:05"))
+		}
+	default:
+		fmt.Printf("\n❓ Unknown Special Message: %s\n", message.String())
+
+		if verbose {
+			fmt.Printf("  📱 Raw data: %s\n", string(message.RawData))
+		}
+	}
+}
+
+func handleUnknownEvent(event *models.WebSocketEvent, verbose bool) {
+	fmt.Printf("\n❓ Unknown Event [%s]:\n", event.DeviceID)
+	types := event.GetEventTypes()
+
+	for _, eventType := range types {
+		fmt.Printf("  📝 Type: %s\n", eventType)
+	}
+
+	if verbose {
+		events := event.GetEvents()
+		fmt.Printf("  📱 Event count: %d\n", len(events))
+		fmt.Printf("  ⏰ Timestamp: %s\n", event.Timestamp.Format(time.RFC3339))
+	}
+}
+
+// getFilterKeys extracts keys from filter map
+func getFilterKeys(filters map[string]bool) []string {
+	var keys []string
+	for k := range filters {
+		keys = append(keys, k)
+	}
+
+	return keys
+}
+
+// Logger implementations
+type VerboseLogger struct{}
+
+func (v *VerboseLogger) Printf(format string, args ...interface{}) {
+	timestamp := time.Now().Format("15:04:05")
+	fmt.Printf("[%s] [WebSocket] %s\n", timestamp, fmt.Sprintf(format, args...))
+}
+
+type SilentLogger struct{}
+
+func (s *SilentLogger) Printf(_ string, _ ...interface{}) {
+	// Do nothing - silent logging
+}

cmd/soundtouch-cli/cmd_events_test.go

@@ -0,0 +1,338 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestParseEventFilters(t *testing.T) {
+	tests := []struct {
+		name        string
+		eventFilter string
+		want        map[string]bool
+		expectExit  bool
+	}{
+		{
+			name:        "empty filter",
+			eventFilter: "",
+			want:        nil,
+			expectExit:  false,
+		},
+		{
+			name:        "single valid filter",
+			eventFilter: "nowPlaying",
+			want:        map[string]bool{"nowPlaying": true},
+			expectExit:  false,
+		},
+		{
+			name:        "multiple valid filters",
+			eventFilter: "nowPlaying,volume,bass",
+			want:        map[string]bool{"nowPlaying": true, "volume": true, "bass": true},
+			expectExit:  false,
+		},
+		{
+			name:        "filters with spaces",
+			eventFilter: "nowPlaying, volume , bass",
+			want:        map[string]bool{"nowPlaying": true, "volume": true, "bass": true},
+			expectExit:  false,
+		},
+		{
+			name:        "all valid filters",
+			eventFilter: "nowPlaying,volume,connection,preset,zone,bass,sdkInfo,userActivity",
+			want: map[string]bool{
+				"nowPlaying":   true,
+				"volume":       true,
+				"connection":   true,
+				"preset":       true,
+				"zone":         true,
+				"bass":         true,
+				"sdkInfo":      true,
+				"userActivity": true,
+			},
+			expectExit: false,
+		},
+		{
+			name:        "duplicate filters",
+			eventFilter: "volume,volume,bass",
+			want:        map[string]bool{"volume": true, "bass": true},
+			expectExit:  false,
+		},
+		{
+			name:        "single invalid filter - should exit",
+			eventFilter: "invalidFilter",
+			want:        nil,
+			expectExit:  true,
+		},
+		{
+			name:        "mixed valid and invalid - should exit",
+			eventFilter: "nowPlaying,invalidFilter,volume",
+			want:        nil,
+			expectExit:  true,
+		},
+		{
+			name:        "comma only",
+			eventFilter: ",",
+			want:        nil,
+			expectExit:  true,
+		},
+		{
+			name:        "trailing comma",
+			eventFilter: "nowPlaying,volume,",
+			want:        nil,
+			expectExit:  true,
+		},
+		{
+			name:        "leading comma",
+			eventFilter: ",nowPlaying,volume",
+			want:        nil,
+			expectExit:  true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.expectExit {
+				// For test cases that should exit, we can't easily test the os.Exit call
+				// So we'll just test that invalid filters exist in the input
+				if tt.eventFilter == "" {
+					return // Empty filter is valid
+				}
+
+				// Check if the filter contains any invalid values
+				hasInvalid := false
+
+				if tt.eventFilter != "" {
+					if strings.Contains(tt.eventFilter, "invalidFilter") ||
+						strings.Contains(tt.eventFilter, ",,") ||
+						strings.HasPrefix(tt.eventFilter, ",") ||
+						strings.HasSuffix(tt.eventFilter, ",") ||
+						tt.eventFilter == "," {
+						hasInvalid = true
+					}
+				}
+
+				if !hasInvalid && tt.expectExit {
+					t.Errorf("Expected invalid filter but didn't find one in: %s", tt.eventFilter)
+				}
+			} else {
+				// We can't easily test the actual function since it calls os.Exit on invalid input
+				// Instead, we'll test the logic manually
+				if tt.eventFilter == "" {
+					if tt.want != nil {
+						t.Errorf("parseEventFilters() = %v, want %v", nil, tt.want)
+					}
+
+					return
+				}
+
+				// Simulate the parsing logic
+				filters := make(map[string]bool)
+				validFilters := map[string]bool{
+					"nowPlaying": true, "volume": true, "connection": true,
+					"preset": true, "zone": true, "bass": true,
+					"sdkInfo": true, "userActivity": true,
+				}
+
+				parts := []string{}
+
+				for _, part := range []string{tt.eventFilter} {
+					// Simple split simulation
+					switch part {
+					case "nowPlaying,volume,bass":
+						parts = []string{"nowPlaying", "volume", "bass"}
+					case "nowPlaying, volume , bass":
+						parts = []string{"nowPlaying", " volume ", " bass"}
+					case "nowPlaying,volume,connection,preset,zone,bass,sdkInfo,userActivity":
+						parts = []string{"nowPlaying", "volume", "connection", "preset", "zone", "bass", "sdkInfo", "userActivity"}
+					case "volume,volume,bass":
+						parts = []string{"volume", "volume", "bass"}
+					default:
+						parts = []string{part}
+					}
+				}
+
+				allValid := true
+
+				for _, f := range parts {
+					f = strings.TrimSpace(f)
+					if f == "" {
+						allValid = false
+						break
+					}
+
+					if !validFilters[f] {
+						allValid = false
+						break
+					}
+
+					filters[f] = true
+				}
+
+				if allValid && !reflect.DeepEqual(filters, tt.want) {
+					t.Errorf("parseEventFilters() = %v, want %v", filters, tt.want)
+				}
+			}
+		})
+	}
+}
+
+func TestGetFilterKeys(t *testing.T) {
+	tests := []struct {
+		name    string
+		filters map[string]bool
+		want    []string
+	}{
+		{
+			name:    "nil map",
+			filters: nil,
+			want:    []string{},
+		},
+		{
+			name:    "empty map",
+			filters: map[string]bool{},
+			want:    []string{},
+		},
+		{
+			name:    "single filter",
+			filters: map[string]bool{"nowPlaying": true},
+			want:    []string{"nowPlaying"},
+		},
+		{
+			name:    "multiple filters",
+			filters: map[string]bool{"nowPlaying": true, "volume": true, "bass": true},
+			want:    []string{"nowPlaying", "volume", "bass"},
+		},
+		{
+			name: "all filters",
+			filters: map[string]bool{
+				"nowPlaying":   true,
+				"volume":       true,
+				"connection":   true,
+				"preset":       true,
+				"zone":         true,
+				"bass":         true,
+				"sdkInfo":      true,
+				"userActivity": true,
+			},
+			want: []string{"nowPlaying", "volume", "connection", "preset", "zone", "bass", "sdkInfo", "userActivity"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := getFilterKeys(tt.filters)
+
+			if len(got) != len(tt.want) {
+				t.Errorf("getFilterKeys() returned %d keys, want %d", len(got), len(tt.want))
+			}
+
+			// Convert to map for easier comparison since order doesn't matter
+			gotMap := make(map[string]bool)
+			for _, key := range got {
+				gotMap[key] = true
+			}
+
+			wantMap := make(map[string]bool)
+			for _, key := range tt.want {
+				wantMap[key] = true
+			}
+
+			if !reflect.DeepEqual(gotMap, wantMap) {
+				t.Errorf("getFilterKeys() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+// Test event handler setup logic
+func TestEventHandlerTypes(t *testing.T) {
+	// Test that we have all the expected event types defined
+	validEventTypes := []string{
+		"nowPlaying",
+		"volume",
+		"connection",
+		"preset",
+		"zone",
+		"bass",
+		"sdkInfo",
+		"userActivity",
+	}
+
+	// Verify all event types are accounted for
+	eventTypeMap := map[string]bool{
+		"nowPlaying": true, "volume": true, "connection": true,
+		"preset": true, "zone": true, "bass": true,
+		"sdkInfo": true, "userActivity": true,
+	}
+
+	for _, eventType := range validEventTypes {
+		if !eventTypeMap[eventType] {
+			t.Errorf("Event type %s is not in the valid event types map", eventType)
+		}
+	}
+
+	// Verify we have exactly 8 event types
+	if len(validEventTypes) != 8 {
+		t.Errorf("Expected 8 event types, got %d", len(validEventTypes))
+	}
+}
+
+// Benchmark filter parsing performance
+func BenchmarkParseEventFilters(b *testing.B) {
+	testCases := []struct {
+		name   string
+		filter string
+	}{
+		{"empty", ""},
+		{"single", "nowPlaying"},
+		{"multiple", "nowPlaying,volume,bass"},
+		{"all_filters", "nowPlaying,volume,connection,preset,zone,bass,sdkInfo,userActivity"},
+		{"with_spaces", "nowPlaying, volume , bass"},
+	}
+
+	for _, tc := range testCases {
+		b.Run(tc.name, func(b *testing.B) {
+			for i := 0; i < b.N; i++ {
+				// We can't benchmark the actual function due to os.Exit calls
+				// So we benchmark the core logic
+				if tc.filter == "" {
+					continue
+				}
+
+				filters := make(map[string]bool)
+				// Simulate string splitting and processing
+				for _, f := range []string{"nowPlaying", "volume", "bass"} {
+					filters[f] = true
+				}
+			}
+		})
+	}
+}
+
+// Test WebSocket configuration defaults
+func TestWebSocketConfigDefaults(t *testing.T) {
+	// This tests the configuration values used in setupWebSocketClient
+	// We can't easily unit test the actual function without mocking the client
+	// But we can test that our expected defaults are reasonable
+	defaultReconnectInterval := 5000000000 // 5 seconds in nanoseconds
+	defaultPingInterval := 30000000000     // 30 seconds in nanoseconds
+	defaultPongTimeout := 10000000000      // 10 seconds in nanoseconds
+	defaultBufferSize := 2048
+
+	if defaultReconnectInterval < 1000000000 { // Less than 1 second
+		t.Error("Reconnect interval should be at least 1 second")
+	}
+
+	if defaultPingInterval < 10000000000 { // Less than 10 seconds
+		t.Error("Ping interval should be at least 10 seconds")
+	}
+
+	if defaultPongTimeout < 1000000000 { // Less than 1 second
+		t.Error("Pong timeout should be at least 1 second")
+	}
+
+	if defaultBufferSize < 1024 {
+		t.Error("Buffer size should be at least 1024 bytes")
+	}
+}

cmd/soundtouch-cli/cmd_introspect.go

@@ -0,0 +1,357 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/urfave/cli/v2"
+)
+
+// introspectService handles getting introspect data for a specific service
+func introspectService(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	source := strings.ToUpper(c.String("source"))
+	sourceAccount := c.String("account")
+
+	// Check service availability first
+	checker := NewServiceAvailabilityChecker(client)
+	if !checker.CheckSourceAvailable(source, fmt.Sprintf("get introspect data for %s", strings.ToLower(source))) {
+		PrintWarning(fmt.Sprintf("Service %s may not be available, but continuing with introspect request...", source))
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Getting introspect data for %s", source), clientConfig.Host, clientConfig.Port)
+
+	if sourceAccount != "" {
+		fmt.Printf("Source Account: %s\n", sourceAccount)
+	}
+
+	fmt.Println()
+
+	response, err := client.Introspect(source, sourceAccount)
+	if err != nil {
+		return fmt.Errorf("failed to get introspect data: %w", err)
+	}
+
+	// Print basic information
+	fmt.Printf("=== %s Service Introspect Data ===\n", source)
+	printIntrospectBasicInfo(response)
+
+	// Print service state
+	fmt.Printf("\n=== Service State ===\n")
+	printIntrospectServiceState(response)
+
+	// Print capabilities
+	fmt.Printf("\n=== Service Capabilities ===\n")
+	printIntrospectCapabilities(response)
+
+	// Print history information
+	if response.GetMaxHistorySize() > 0 {
+		fmt.Printf("\n=== Content History ===\n")
+		printIntrospectHistory(response)
+	}
+
+	// Print technical details
+	if response.TokenLastChangedTimeSeconds > 0 || response.PlayStatusState != "" {
+		fmt.Printf("\n=== Technical Details ===\n")
+		printIntrospectTechnicalDetails(response)
+	}
+
+	return nil
+}
+
+// introspectSpotify handles getting Spotify introspect data using convenience method
+func introspectSpotify(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	sourceAccount := c.String("account")
+
+	// Check Spotify availability
+	checker := NewServiceAvailabilityChecker(client)
+	if !checker.ValidateSpotifyAvailable("get Spotify introspect data") {
+		PrintWarning("Spotify may not be available, but continuing with introspect request...")
+	}
+
+	PrintDeviceHeader("Getting Spotify introspect data", clientConfig.Host, clientConfig.Port)
+
+	if sourceAccount != "" {
+		fmt.Printf("Spotify Account: %s\n", sourceAccount)
+	}
+
+	fmt.Println()
+
+	response, err := client.IntrospectSpotify(sourceAccount)
+	if err != nil {
+		return fmt.Errorf("failed to get Spotify introspect data: %w", err)
+	}
+
+	// Print Spotify-specific information
+	fmt.Printf("=== Spotify Service Introspect Data ===\n")
+	printIntrospectBasicInfo(response)
+
+	// Print service state with Spotify context
+	fmt.Printf("\n=== Spotify Service State ===\n")
+	printIntrospectServiceState(response)
+
+	// Print Spotify capabilities
+	fmt.Printf("\n=== Spotify Service Capabilities ===\n")
+	printIntrospectCapabilities(response)
+
+	// Show Spotify-specific recommendations
+	if response.IsInactive() {
+		fmt.Printf("\n💡 Spotify Setup Recommendations:\n")
+
+		if !response.HasUser() {
+			fmt.Printf("   • Sign in to your Spotify account on the device\n")
+		}
+
+		fmt.Printf("   • Use 'soundtouch-cli source select --source SPOTIFY' to activate Spotify\n")
+		fmt.Printf("   • Ensure you have Spotify Premium for full functionality\n")
+	}
+
+	// Print history information
+	if response.GetMaxHistorySize() > 0 {
+		fmt.Printf("\n=== Spotify Content History ===\n")
+		printIntrospectHistory(response)
+	}
+
+	// Print technical details
+	if response.TokenLastChangedTimeSeconds > 0 || response.PlayStatusState != "" {
+		fmt.Printf("\n=== Technical Details ===\n")
+		printIntrospectTechnicalDetails(response)
+	}
+
+	return nil
+}
+
+// introspectAllServices handles getting introspect data for all available services
+func introspectAllServices(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	PrintDeviceHeader("Getting introspect data for all services", clientConfig.Host, clientConfig.Port)
+
+	// Get service availability to know which services to check
+	serviceAvailability, err := client.GetServiceAvailability()
+	if err != nil {
+		return fmt.Errorf("failed to get service availability: %w", err)
+	}
+
+	// Services to introspect (only streaming services that support introspect)
+	servicesToCheck := []string{"SPOTIFY", "PANDORA", "TUNEIN", "AMAZON", "DEEZER"}
+
+	successCount := 0
+	failCount := 0
+
+	for i, source := range servicesToCheck {
+		if i > 0 {
+			fmt.Println("\n" + strings.Repeat("─", 50))
+		}
+
+		// Check if service is available
+		serviceType := sourceToServiceType(source)
+		if serviceType != "" && !serviceAvailability.IsServiceAvailable(serviceType) {
+			fmt.Printf("\n❌ %s: Service not available on this device\n", source)
+			continue
+		}
+
+		fmt.Printf("\n🔍 Getting introspect data for %s...\n", source)
+
+		response, err := client.Introspect(source, "")
+		if err != nil {
+			fmt.Printf("❌ %s: Failed to get introspect data - %v\n", source, err)
+
+			failCount++
+
+			continue
+		}
+
+		fmt.Printf("✅ %s: Successfully retrieved introspect data\n", source)
+		printIntrospectSummary(source, response)
+
+		successCount++
+	}
+
+	// Print summary
+	fmt.Print("\n" + strings.Repeat("═", 50) + "\n")
+	fmt.Printf("📊 Introspect Summary:\n")
+	fmt.Printf("   ✅ Successful: %d services\n", successCount)
+	fmt.Printf("   ❌ Failed: %d services\n", failCount)
+	fmt.Printf("   📡 Total checked: %d services\n", len(servicesToCheck))
+
+	if successCount > 0 {
+		PrintSuccess(fmt.Sprintf("Successfully retrieved introspect data for %d services", successCount))
+	}
+
+	return nil
+}
+
+// printIntrospectBasicInfo prints basic introspect information
+func printIntrospectBasicInfo(response *models.IntrospectResponse) {
+	fmt.Printf("State: %s\n", response.State)
+
+	if response.HasUser() {
+		fmt.Printf("User: %s\n", response.User)
+	}
+
+	fmt.Printf("Currently Playing: %s\n", formatBooleanStatus(response.IsPlaying))
+
+	if response.HasCurrentContent() {
+		fmt.Printf("Current Content: %s\n", response.CurrentURI)
+	}
+
+	fmt.Printf("Shuffle Mode: %s\n", response.ShuffleMode)
+
+	if response.HasSubscription() {
+		fmt.Printf("Subscription Type: %s\n", response.SubscriptionType)
+	}
+}
+
+// printIntrospectServiceState prints service state information
+func printIntrospectServiceState(response *models.IntrospectResponse) {
+	if response.IsActive() {
+		fmt.Printf("✅ Service is ACTIVE\n")
+	} else if response.IsInactive() {
+		fmt.Printf("❌ Service is INACTIVE")
+
+		if response.GetState() == models.IntrospectStateInactiveUnselected {
+			fmt.Printf(" (Never been used)")
+		}
+
+		fmt.Println()
+	}
+
+	// Additional state information
+	if response.IsPlaying {
+		fmt.Printf("🎵 Currently playing content\n")
+	} else {
+		fmt.Printf("⏸️  Not currently playing\n")
+	}
+
+	if response.IsShuffleEnabled() {
+		fmt.Printf("🔀 Shuffle mode is ON\n")
+	} else {
+		fmt.Printf("➡️  Shuffle mode is OFF\n")
+	}
+}
+
+// printIntrospectCapabilities prints service capabilities
+func printIntrospectCapabilities(response *models.IntrospectResponse) {
+	capabilities := []struct {
+		supported bool
+		feature   string
+		icon      string
+	}{
+		{response.SupportsSkipPrevious(), "Skip Previous", "⏮️"},
+		{response.SupportsSeek(), "Seek within tracks", "🎯"},
+		{response.SupportsResume(), "Resume playback", "▶️"},
+	}
+
+	for _, cap := range capabilities {
+		status := "❌"
+		if cap.supported {
+			status = "✅"
+		}
+
+		fmt.Printf("%s %s %s\n", status, cap.icon, cap.feature)
+	}
+
+	// Data collection status
+	if response.CollectsData() {
+		fmt.Printf("📊 Data collection: ENABLED\n")
+	} else {
+		fmt.Printf("🚫 Data collection: DISABLED\n")
+	}
+}
+
+// printIntrospectHistory prints content history information
+func printIntrospectHistory(response *models.IntrospectResponse) {
+	fmt.Printf("Max History Size: %d items\n", response.GetMaxHistorySize())
+}
+
+// printIntrospectTechnicalDetails prints technical details
+func printIntrospectTechnicalDetails(response *models.IntrospectResponse) {
+	if response.TokenLastChangedTimeSeconds > 0 {
+		// Convert timestamp to readable format
+		tokenTime := time.Unix(response.TokenLastChangedTimeSeconds, 0)
+		fmt.Printf("Token Last Changed: %s\n", tokenTime.Format("2006-01-02 15:04:05 MST"))
+		fmt.Printf("Token Timestamp: %d seconds since Unix epoch\n", response.TokenLastChangedTimeSeconds)
+
+		if response.TokenLastChangedTimeMicroseconds > 0 {
+			fmt.Printf("Token Microseconds: %d\n", response.TokenLastChangedTimeMicroseconds)
+		}
+	}
+
+	if response.PlayStatusState != "" {
+		fmt.Printf("Play Status State: %s\n", response.PlayStatusState)
+	}
+
+	fmt.Printf("Received Playback Request: %s\n", formatBooleanStatus(response.ReceivedPlaybackRequest))
+}
+
+// printIntrospectSummary prints a brief summary for the "all" command
+func printIntrospectSummary(_ string, response *models.IntrospectResponse) {
+	fmt.Printf("   State: %s", response.State)
+
+	if response.HasUser() {
+		fmt.Printf(" (User: %s)", response.User)
+	}
+
+	fmt.Println()
+
+	fmt.Printf("   Playing: %s", formatBooleanStatus(response.IsPlaying))
+
+	if response.HasCurrentContent() {
+		fmt.Printf(" | Content: %.50s", response.CurrentURI)
+
+		if len(response.CurrentURI) > 50 {
+			fmt.Printf("...")
+		}
+	}
+
+	fmt.Println()
+
+	var capabilities []string
+	if response.SupportsSkipPrevious() {
+		capabilities = append(capabilities, "Skip")
+	}
+
+	if response.SupportsSeek() {
+		capabilities = append(capabilities, "Seek")
+	}
+
+	if response.SupportsResume() {
+		capabilities = append(capabilities, "Resume")
+	}
+
+	if len(capabilities) > 0 {
+		fmt.Printf("   Capabilities: %s\n", strings.Join(capabilities, ", "))
+	} else {
+		fmt.Printf("   Capabilities: None\n")
+	}
+}
+
+// formatBooleanStatus formats boolean values for display
+func formatBooleanStatus(value bool) string {
+	if value {
+		return "✅ Yes"
+	}
+
+	return "❌ No"
+}

cmd/soundtouch-cli/cmd_introspect_test.go

@@ -0,0 +1,482 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+)
+
+func TestIntrospectCommands(t *testing.T) {
+	tests := []struct {
+		name           string
+		args           []string
+		expectedOutput []string
+		expectError    bool
+	}{
+		{
+			name: "introspect service with source flag",
+			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "source", "introspect", "--source", "SPOTIFY"},
+			expectedOutput: []string{
+				"Getting introspect data for SPOTIFY",
+				"=== SPOTIFY Service Introspect Data ===",
+				"State: Active",
+				"User: test_user",
+				"Currently Playing: ✅ Yes",
+				"Current Content: spotify://track/123",
+				"Shuffle Mode: ON",
+				"Subscription Type: Premium",
+				"=== Service State ===",
+				"✅ Service is ACTIVE",
+				"🎵 Currently playing content",
+				"🔀 Shuffle mode is ON",
+				"=== Service Capabilities ===",
+				"✅ ⏮️ Skip Previous",
+				"✅ 🎯 Seek within tracks",
+				"✅ ▶️ Resume playback",
+				"🚫 Data collection: DISABLED",
+				"=== Spotify Content History ===",
+				"Max History Size: 15 items",
+				"=== Technical Details ===",
+				"Token Last Changed:",
+				"Token Timestamp: 1702566495",
+				"Play Status State: 2",
+				"Received Playback Request: ❌ No",
+			},
+		},
+		{
+			name: "introspect spotify convenience command",
+			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "source", "introspect-spotify"},
+			expectedOutput: []string{
+				"Getting Spotify introspect data",
+				"=== Spotify Service Introspect Data ===",
+				"State: Active",
+				"User: test_user",
+				"=== Spotify Service State ===",
+				"✅ Service is ACTIVE",
+				"=== Spotify Service Capabilities ===",
+			},
+		},
+		{
+			name: "introspect with account parameter",
+			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "source", "introspect", "--source", "SPOTIFY", "--account", "my_spotify_account"},
+			expectedOutput: []string{
+				"Getting introspect data for SPOTIFY",
+				"Source Account: my_spotify_account",
+			},
+		},
+		{
+			name:        "introspect missing source flag",
+			args:        []string{"soundtouch-cli", "--host", "192.168.1.100", "source", "introspect"},
+			expectError: true,
+		},
+		{
+			name:        "introspect missing host",
+			args:        []string{"soundtouch-cli", "source", "introspect", "--source", "SPOTIFY"},
+			expectError: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Skip actual execution for now - these would need mock HTTP servers
+			// This test structure shows how the CLI commands would be tested
+			t.Skip("Integration test - requires mock HTTP server setup")
+
+			// Example of how you would set up the test:
+			// app := createTestApp()
+			//
+			// var buf bytes.Buffer
+			// app.Writer = &buf
+			// app.ErrWriter = &buf
+			//
+			// err := app.Run(tt.args)
+			//
+			// if tt.expectError {
+			//     if err == nil {
+			//         t.Error("expected error, got nil")
+			//     }
+			//     return
+			// }
+			//
+			// if err != nil {
+			//     t.Fatalf("unexpected error: %v", err)
+			// }
+			//
+			// output := buf.String()
+			// for _, expected := range tt.expectedOutput {
+			//     if !strings.Contains(output, expected) {
+			//         t.Errorf("expected output to contain %q, got:\n%s", expected, output)
+			//     }
+			// }
+		})
+	}
+}
+
+func TestPrintIntrospectBasicInfo(t *testing.T) {
+	tests := []struct {
+		name     string
+		response *models.IntrospectResponse
+		expected []string
+	}{
+		{
+			name: "active spotify response",
+			response: &models.IntrospectResponse{
+				State:            "Active",
+				User:             "test_user",
+				IsPlaying:        true,
+				ShuffleMode:      "ON",
+				CurrentURI:       "spotify://track/123",
+				SubscriptionType: "Premium",
+			},
+			expected: []string{
+				"State: Active",
+				"User: test_user",
+				"Currently Playing: ✅ Yes",
+				"Current Content: spotify://track/123",
+				"Shuffle Mode: ON",
+				"Subscription Type: Premium",
+			},
+		},
+		{
+			name: "inactive response",
+			response: &models.IntrospectResponse{
+				State:       "InactiveUnselected",
+				User:        "",
+				IsPlaying:   false,
+				ShuffleMode: "OFF",
+				CurrentURI:  "",
+			},
+			expected: []string{
+				"State: InactiveUnselected",
+				"Currently Playing: ❌ No",
+				"Shuffle Mode: OFF",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Capture stdout
+			oldStdout := os.Stdout
+			r, w, _ := os.Pipe()
+			os.Stdout = w
+
+			// Call the function
+			printIntrospectBasicInfo(tt.response)
+
+			// Restore stdout and read output
+			w.Close()
+
+			os.Stdout = oldStdout
+
+			var buf bytes.Buffer
+
+			_, err := buf.ReadFrom(r)
+			if err != nil {
+				t.Fatalf("failed to read output: %v", err)
+			}
+
+			output := buf.String()
+
+			// Check expected strings are present
+			for _, expected := range tt.expected {
+				if !containsSubstring(output, expected) {
+					t.Errorf("expected output to contain %q, got:\n%s", expected, output)
+				}
+			}
+
+			// Check unwanted strings are not present
+			if tt.response.User == "" && containsSubstring(output, "User:") {
+				t.Error("expected no user information when user is empty")
+			}
+
+			if tt.response.CurrentURI == "" && containsSubstring(output, "Current Content:") {
+				t.Error("expected no current content when URI is empty")
+			}
+
+			if tt.response.SubscriptionType == "" && containsSubstring(output, "Subscription Type:") {
+				t.Error("expected no subscription information when type is empty")
+			}
+		})
+	}
+}
+
+func TestPrintIntrospectServiceState(t *testing.T) {
+	tests := []struct {
+		name     string
+		response *models.IntrospectResponse
+		expected []string
+	}{
+		{
+			name: "active playing with shuffle",
+			response: &models.IntrospectResponse{
+				State:       "Active",
+				IsPlaying:   true,
+				ShuffleMode: "ON",
+			},
+			expected: []string{
+				"✅ Service is ACTIVE",
+				"🎵 Currently playing content",
+				"🔀 Shuffle mode is ON",
+			},
+		},
+		{
+			name: "inactive unselected",
+			response: &models.IntrospectResponse{
+				State:       "InactiveUnselected",
+				IsPlaying:   false,
+				ShuffleMode: "OFF",
+			},
+			expected: []string{
+				"❌ Service is INACTIVE (Never been used)",
+				"⏸️  Not currently playing",
+				"➡️  Shuffle mode is OFF",
+			},
+		},
+		{
+			name: "inactive but configured",
+			response: &models.IntrospectResponse{
+				State:       "Inactive",
+				IsPlaying:   false,
+				ShuffleMode: "OFF",
+			},
+			expected: []string{
+				"❌ Service is INACTIVE",
+				"⏸️  Not currently playing",
+				"➡️  Shuffle mode is OFF",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Capture stdout
+			oldStdout := os.Stdout
+			r, w, _ := os.Pipe()
+			os.Stdout = w
+
+			// Call the function
+			printIntrospectServiceState(tt.response)
+
+			// Restore stdout and read output
+			w.Close()
+
+			os.Stdout = oldStdout
+
+			var buf bytes.Buffer
+
+			_, err := buf.ReadFrom(r)
+			if err != nil {
+				t.Fatalf("failed to read output: %v", err)
+			}
+
+			output := buf.String()
+
+			// Check expected strings are present
+			for _, expected := range tt.expected {
+				if !containsSubstring(output, expected) {
+					t.Errorf("expected output to contain %q, got:\n%s", expected, output)
+				}
+			}
+		})
+	}
+}
+
+func TestPrintIntrospectCapabilities(t *testing.T) {
+	tests := []struct {
+		name     string
+		response *models.IntrospectResponse
+		expected []string
+	}{
+		{
+			name: "full capabilities enabled",
+			response: &models.IntrospectResponse{
+				NowPlaying: &models.IntrospectNowPlaying{
+					SkipPreviousSupported: true,
+					SeekSupported:         true,
+					ResumeSupported:       true,
+					CollectData:           true,
+				},
+			},
+			expected: []string{
+				"✅ ⏮️ Skip Previous",
+				"✅ 🎯 Seek within tracks",
+				"✅ ▶️ Resume playback",
+				"📊 Data collection: ENABLED",
+			},
+		},
+		{
+			name: "limited capabilities",
+			response: &models.IntrospectResponse{
+				NowPlaying: &models.IntrospectNowPlaying{
+					SkipPreviousSupported: false,
+					SeekSupported:         false,
+					ResumeSupported:       true,
+					CollectData:           false,
+				},
+			},
+			expected: []string{
+				"❌ ⏮️ Skip Previous",
+				"❌ 🎯 Seek within tracks",
+				"✅ ▶️ Resume playback",
+				"🚫 Data collection: DISABLED",
+			},
+		},
+		{
+			name: "no capabilities info",
+			response: &models.IntrospectResponse{
+				NowPlaying: nil,
+			},
+			expected: []string{
+				"❌ ⏮️ Skip Previous",
+				"❌ 🎯 Seek within tracks",
+				"❌ ▶️ Resume playback",
+				"🚫 Data collection: DISABLED",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Capture stdout
+			oldStdout := os.Stdout
+			r, w, _ := os.Pipe()
+			os.Stdout = w
+
+			// Call the function
+			printIntrospectCapabilities(tt.response)
+
+			// Restore stdout and read output
+			w.Close()
+
+			os.Stdout = oldStdout
+
+			var buf bytes.Buffer
+
+			_, err := buf.ReadFrom(r)
+			if err != nil {
+				t.Fatalf("failed to read output: %v", err)
+			}
+
+			output := buf.String()
+
+			// Check expected strings are present
+			for _, expected := range tt.expected {
+				if !containsSubstring(output, expected) {
+					t.Errorf("expected output to contain %q, got:\n%s", expected, output)
+				}
+			}
+		})
+	}
+}
+
+func TestPrintIntrospectSummary(t *testing.T) {
+	tests := []struct {
+		name     string
+		source   string
+		response *models.IntrospectResponse
+		expected []string
+	}{
+		{
+			name:   "full spotify summary",
+			source: "SPOTIFY",
+			response: &models.IntrospectResponse{
+				State:      "Active",
+				User:       "spotify_user",
+				IsPlaying:  true,
+				CurrentURI: "spotify://track/very_long_track_uri_that_should_be_truncated_because_its_too_long_for_display",
+				NowPlaying: &models.IntrospectNowPlaying{
+					SkipPreviousSupported: true,
+					SeekSupported:         true,
+					ResumeSupported:       true,
+				},
+			},
+			expected: []string{
+				"State: Active (User: spotify_user)",
+				"Playing: ✅ Yes | Content: spotify://track/very_long_track_uri_that_should_be...",
+				"Capabilities: Skip, Seek, Resume",
+			},
+		},
+		{
+			name:   "minimal summary",
+			source: "PANDORA",
+			response: &models.IntrospectResponse{
+				State:     "Inactive",
+				IsPlaying: false,
+			},
+			expected: []string{
+				"State: Inactive",
+				"Playing: ❌ No",
+				"Capabilities: None",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Capture stdout
+			oldStdout := os.Stdout
+			r, w, _ := os.Pipe()
+			os.Stdout = w
+
+			// Call the function
+			printIntrospectSummary(tt.source, tt.response)
+
+			// Restore stdout and read output
+			w.Close()
+
+			os.Stdout = oldStdout
+
+			var buf bytes.Buffer
+
+			_, err := buf.ReadFrom(r)
+			if err != nil {
+				t.Fatalf("failed to read output: %v", err)
+			}
+
+			output := buf.String()
+
+			// Check expected strings are present
+			for _, expected := range tt.expected {
+				if !containsSubstring(output, expected) {
+					t.Errorf("expected output to contain %q, got:\n%s", expected, output)
+				}
+			}
+		})
+	}
+}
+
+func TestFormatBooleanStatus(t *testing.T) {
+	tests := []struct {
+		name     string
+		value    bool
+		expected string
+	}{
+		{
+			name:     "true value",
+			value:    true,
+			expected: "✅ Yes",
+		},
+		{
+			name:     "false value",
+			value:    false,
+			expected: "❌ No",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := formatBooleanStatus(tt.value)
+			if result != tt.expected {
+				t.Errorf("expected %q, got %q", tt.expected, result)
+			}
+		})
+	}
+}
+
+// Helper function to check if output contains a substring
+func containsSubstring(output, substring string) bool {
+	return bytes.Contains([]byte(output), []byte(substring))
+}

cmd/soundtouch-cli/cmd_playback.go

@@ -102,6 +102,10 @@ func printContentDetails(nowPlaying *models.NowPlaying, verbose bool) {
 	fmt.Printf("\nContent Details:\n")
 	printContentLocation(nowPlaying.ContentItem)
 	printVerboseContentInfo(nowPlaying, verbose)
+
+	if verbose {
+		printVerbosePlaybackDetails(nowPlaying)
+	}
 }
 
 // printContentLocation prints the content location
@@ -125,9 +129,48 @@ func printVerboseContentInfo(nowPlaying *models.NowPlaying, verbose bool) {
 		fmt.Printf("  Item Name: %s\n", nowPlaying.ContentItem.ItemName)
 	}
 
+	if nowPlaying.ContentItem.ContainerArt != "" {
+		fmt.Printf("  Container Art: %s\n", nowPlaying.ContentItem.ContainerArt)
+	}
+
 	fmt.Printf("  Presetable: %t\n", nowPlaying.ContentItem.IsPresetable)
 }
 
+// printVerbosePlaybackDetails prints detailed playback information in verbose mode
+func printVerbosePlaybackDetails(nowPlaying *models.NowPlaying) {
+	fmt.Printf("\nPlayback Details:\n")
+
+	// Shuffle and repeat settings
+	if nowPlaying.ShuffleSetting != "" {
+		fmt.Printf("  Shuffle: %s\n", nowPlaying.ShuffleSetting.String())
+	}
+
+	if nowPlaying.RepeatSetting != "" {
+		fmt.Printf("  Repeat: %s\n", nowPlaying.RepeatSetting.String())
+	}
+
+	// Track ID
+	if nowPlaying.TrackID != "" {
+		fmt.Printf("  Track ID: %s\n", nowPlaying.TrackID)
+	}
+
+	// Art details
+	if nowPlaying.Art != nil {
+		fmt.Printf("  Art Image Status: %s\n", nowPlaying.Art.ArtImageStatus)
+
+		if nowPlaying.Art.URL != "" {
+			fmt.Printf("  Art URL: %s\n", nowPlaying.Art.URL)
+		}
+	}
+
+	// Capabilities
+	fmt.Printf("\nCapabilities:\n")
+	fmt.Printf("  Skip Enabled: %t\n", nowPlaying.CanSkip())
+	fmt.Printf("  Skip Previous Enabled: %t\n", nowPlaying.CanSkipPrevious())
+	fmt.Printf("  Favorite Enabled: %t\n", nowPlaying.CanFavorite())
+	fmt.Printf("  Seek Supported: %t\n", nowPlaying.IsSeekSupported())
+}
+
 // printPlaybackStatus prints special status messages
 func printPlaybackStatus(nowPlaying *models.NowPlaying) {
 	if nowPlaying.PlayStatus == models.PlayStatusBuffering {

cmd/soundtouch-cli/cmd_preset.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/gesellix/bose-soundtouch/pkg/models"
 	"github.com/urfave/cli/v2"
@@ -101,26 +102,36 @@ func extractPresetParams(c *cli.Context) *presetParams {
 
 // resolveLocationAndMetadata resolves location and fetches metadata if needed
 func resolveLocationAndMetadata(params *presetParams) error {
+	originalLocation := params.location
 	resolvedSource, resolvedLocation := resolveLocation(params.source, params.location)
-	if resolvedLocation != params.location && (params.source == "" || params.source == "TUNEIN") {
-		// If location was a TuneIn URL, fetch metadata if name or artwork is missing
-		if params.name == "" || params.artwork == "" {
-			metadata, err := fetchTuneInMetadata(params.location)
-			if err == nil && metadata != nil {
-				if params.name == "" {
-					params.name = metadata.Name
-				}
-
-				if params.artwork == "" {
-					params.artwork = metadata.Artwork
-				}
-			}
-		}
-	}
 
 	params.source = resolvedSource
 	params.location = resolvedLocation
 
+	// If metadata (name or artwork) is missing, try to fetch it
+	if params.name == "" || params.artwork == "" {
+		var (
+			metadata *Metadata
+			err      error
+		)
+
+		if params.source == "TUNEIN" && strings.Contains(originalLocation, "tunein.com/radio/") {
+			metadata, err = fetchTuneInMetadata(originalLocation)
+		} else if params.source == "SPOTIFY" && strings.Contains(originalLocation, "open.spotify.com/") {
+			metadata, err = fetchSpotifyMetadata(originalLocation)
+		}
+
+		if err == nil && metadata != nil {
+			if params.name == "" {
+				params.name = metadata.Name
+			}
+
+			if params.artwork == "" {
+				params.artwork = metadata.Artwork
+			}
+		}
+	}
+
 	return nil
 }
 

cmd/soundtouch-cli/cmd_recents.go

@@ -0,0 +1,524 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/urfave/cli/v2"
+)
+
+// getRecents handles getting recently played content
+func getRecents(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	PrintDeviceHeader("Getting recently played content", clientConfig.Host, clientConfig.Port)
+
+	response, err := client.GetRecents()
+	if err != nil {
+		return fmt.Errorf("failed to get recent items: %w", err)
+	}
+
+	if response.IsEmpty() {
+		fmt.Printf("📭 No recent items found\n")
+		fmt.Printf("💡 Play some content to populate the recent items list\n")
+
+		return nil
+	}
+
+	// Display summary
+	fmt.Printf("📊 Recent Items Summary:\n")
+	fmt.Printf("   Total Items: %d\n", response.GetItemCount())
+
+	// Show source breakdown
+	sources := map[string]int{
+		"Spotify":      len(response.GetSpotifyItems()),
+		"Local Music":  len(response.GetLocalMusicItems()),
+		"Stored Music": len(response.GetStoredMusicItems()),
+		"TuneIn":       len(response.GetTuneInItems()),
+		"Pandora":      len(response.GetPandoraItems()),
+	}
+
+	fmt.Printf("   By Source:\n")
+
+	for source, count := range sources {
+		if count > 0 {
+			fmt.Printf("     • %s: %d items\n", source, count)
+		}
+	}
+
+	// Show type breakdown
+	tracks := len(response.GetTracks())
+	stations := len(response.GetStations())
+	playlists := len(response.GetPlaylistsAndAlbums())
+	presetable := len(response.GetPresetableItems())
+
+	fmt.Printf("   By Type:\n")
+
+	if tracks > 0 {
+		fmt.Printf("     • 🎵 Tracks: %d\n", tracks)
+	}
+
+	if stations > 0 {
+		fmt.Printf("     • 📻 Stations: %d\n", stations)
+	}
+
+	if playlists > 0 {
+		fmt.Printf("     • 📋 Playlists/Albums: %d\n", playlists)
+	}
+
+	if presetable > 0 {
+		fmt.Printf("     • ⭐ Presetable: %d\n", presetable)
+	}
+
+	fmt.Printf("\n=== Recent Items ===\n")
+
+	// Display items with details
+	maxItems := c.Int("limit")
+	if maxItems <= 0 || maxItems > len(response.Items) {
+		maxItems = len(response.Items)
+	}
+
+	for i, item := range response.Items[:maxItems] {
+		printRecentItem(i+1, &item, c.Bool("detailed"))
+	}
+
+	if len(response.Items) > maxItems {
+		fmt.Printf("\n... and %d more items (use --limit to show more)\n", len(response.Items)-maxItems)
+	}
+
+	return nil
+}
+
+// getRecentsFiltered handles getting filtered recent content
+// buildFilterDescription creates a description string for the applied filters
+func buildFilterDescription(source, contentType string) string {
+	switch {
+	case source != "" && contentType != "":
+		return fmt.Sprintf(" (filtered by source: %s, type: %s)", source, contentType)
+	case source != "":
+		return fmt.Sprintf(" (filtered by source: %s)", source)
+	case contentType != "":
+		return fmt.Sprintf(" (filtered by type: %s)", contentType)
+	default:
+		return ""
+	}
+}
+
+// applyContentTypeFilter filters items by content type
+func applyContentTypeFilter(items []models.RecentsResponseItem, contentType string) []models.RecentsResponseItem {
+	if contentType == "" {
+		return items
+	}
+
+	var typeFiltered []models.RecentsResponseItem
+
+	for _, item := range items {
+		if shouldIncludeItemByType(item, contentType) {
+			typeFiltered = append(typeFiltered, item)
+		}
+	}
+
+	return typeFiltered
+}
+
+// shouldIncludeItemByType checks if an item matches the specified content type
+func shouldIncludeItemByType(item models.RecentsResponseItem, contentType string) bool {
+	switch contentType {
+	case "track", "tracks":
+		return item.IsTrack()
+	case "station", "stations":
+		return item.IsStation()
+	case "playlist", "playlists":
+		return item.IsPlaylist()
+	case "album", "albums":
+		return item.IsAlbum()
+	case "container", "containers":
+		return item.IsContainer()
+	case "presetable":
+		return item.IsPresetable()
+	default:
+		return false
+	}
+}
+
+// displayFilteredResults prints the filtered recent items
+func displayFilteredResults(filteredItems []models.RecentsResponseItem, c *cli.Context) {
+	maxItems := c.Int("limit")
+	if maxItems <= 0 || maxItems > len(filteredItems) {
+		maxItems = len(filteredItems)
+	}
+
+	for i, item := range filteredItems[:maxItems] {
+		printRecentItem(i+1, &item, c.Bool("detailed"))
+	}
+
+	if len(filteredItems) > maxItems {
+		fmt.Printf("\n... and %d more items (use --limit to show more)\n", len(filteredItems)-maxItems)
+	}
+}
+
+func getRecentsFiltered(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	source := strings.ToUpper(c.String("source"))
+	contentType := strings.ToLower(c.String("type"))
+	filterDesc := buildFilterDescription(source, contentType)
+
+	PrintDeviceHeader("Getting filtered recent content"+filterDesc, clientConfig.Host, clientConfig.Port)
+
+	response, err := client.GetRecents()
+	if err != nil {
+		return fmt.Errorf("failed to get recent items: %w", err)
+	}
+
+	if response.IsEmpty() {
+		fmt.Printf("📭 No recent items found\n")
+		return nil
+	}
+
+	// Apply source filter
+	var filteredItems []models.RecentsResponseItem
+	if source != "" {
+		filteredItems = response.GetItemsBySource(source)
+	} else {
+		filteredItems = response.Items
+	}
+
+	// Apply type filter
+	filteredItems = applyContentTypeFilter(filteredItems, contentType)
+
+	if len(filteredItems) == 0 {
+		fmt.Printf("📭 No items match the specified filters\n")
+		fmt.Printf("💡 Try different filter criteria or check available content\n")
+
+		return nil
+	}
+
+	fmt.Printf("📊 Filtered Results: %d items\n\n", len(filteredItems))
+	displayFilteredResults(filteredItems, c)
+
+	return nil
+}
+
+// getRecentsMostRecent shows only the most recent item
+func getRecentsMostRecent(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	PrintDeviceHeader("Getting most recent item", clientConfig.Host, clientConfig.Port)
+
+	response, err := client.GetRecents()
+	if err != nil {
+		return fmt.Errorf("failed to get recent items: %w", err)
+	}
+
+	mostRecent := response.GetMostRecent()
+	if mostRecent == nil {
+		fmt.Printf("📭 No recent items found\n")
+		return nil
+	}
+
+	fmt.Printf("🕒 Most Recent Item:\n\n")
+	printRecentItem(1, mostRecent, true)
+
+	return nil
+}
+
+// printRecentItem prints details about a recent item
+func printRecentItem(index int, item *models.RecentsResponseItem, detailed bool) {
+	// Basic information
+	displayName := item.GetDisplayName()
+	source := item.GetSource()
+	contentType := item.GetContentType()
+
+	// Format source display
+	sourceDisplay := formatSourceForDisplay(source)
+
+	// Content type icon
+	typeIcon := getContentTypeIcon(item)
+
+	fmt.Printf("%d. %s %s\n", index, typeIcon, displayName)
+	fmt.Printf("   Source: %s", sourceDisplay)
+
+	if contentType != "" {
+		fmt.Printf(" | Type: %s", contentType)
+	}
+
+	fmt.Printf("\n")
+
+	// Time information
+	if item.GetUTCTime() > 0 {
+		playTime := time.Unix(item.GetUTCTime(), 0)
+		fmt.Printf("   Played: %s\n", playTime.Format("2006-01-02 15:04:05"))
+	}
+
+	// Additional details if requested
+	if detailed {
+		if item.HasID() {
+			fmt.Printf("   ID: %s\n", item.GetID())
+		}
+
+		if item.IsPresetable() {
+			fmt.Printf("   ⭐ Can be saved as preset\n")
+		}
+
+		if item.HasArtwork() {
+			fmt.Printf("   🎨 Has artwork: %s\n", truncateString(item.GetArtwork(), 50))
+		}
+
+		location := item.GetLocation()
+		if location != "" {
+			fmt.Printf("   📍 Location: %s\n", truncateString(location, 50))
+		}
+
+		sourceAccount := item.GetSourceAccount()
+		if sourceAccount != "" && sourceAccount != source {
+			fmt.Printf("   👤 Account: %s\n", truncateString(sourceAccount, 30))
+		}
+
+		// Content classification
+		var classifications []string
+		if item.IsStreamingContent() {
+			classifications = append(classifications, "Streaming")
+		}
+
+		if item.IsLocalContent() {
+			classifications = append(classifications, "Local")
+		}
+
+		if len(classifications) > 0 {
+			fmt.Printf("   🏷️  Classification: %s\n", strings.Join(classifications, ", "))
+		}
+	}
+
+	fmt.Println()
+}
+
+// getContentTypeIcon returns an emoji icon for the content type
+func getContentTypeIcon(item *models.RecentsResponseItem) string {
+	switch {
+	case item.IsTrack():
+		return "🎵"
+	case item.IsStation():
+		return "📻"
+	case item.IsPlaylist():
+		return "📋"
+	case item.IsAlbum():
+		return "💿"
+	case item.IsContainer():
+		return "📁"
+	default:
+		return "🎶"
+	}
+}
+
+// formatSourceForDisplay formats source names for user-friendly display
+func formatSourceForDisplay(source string) string {
+	switch source {
+	case "SPOTIFY":
+		return "Spotify"
+	case "LOCAL_MUSIC":
+		return "Local Music"
+	case "STORED_MUSIC":
+		return "Stored Music"
+	case "TUNEIN":
+		return "TuneIn Radio"
+	case "PANDORA":
+		return "Pandora"
+	case "AMAZON":
+		return "Amazon Music"
+	case "DEEZER":
+		return "Deezer"
+	case "IHEART":
+		return "iHeartRadio"
+	case "BLUETOOTH":
+		return "Bluetooth"
+	case "AUX":
+		return "AUX Input"
+	case "AIRPLAY":
+		return "AirPlay"
+	default:
+		return source
+	}
+}
+
+// truncateString truncates a string to the specified length with ellipsis
+func truncateString(s string, maxLength int) string {
+	if len(s) <= maxLength {
+		return s
+	}
+
+	if maxLength <= 3 {
+		return "..."
+	}
+
+	return s[:maxLength-3] + "..."
+}
+
+// printBasicStats prints overall statistics about recent items
+func printBasicStats(response *models.RecentsResponse) {
+	fmt.Printf("Overall Statistics:\n")
+	fmt.Printf("  Total Items: %d\n", response.GetItemCount())
+
+	if !response.IsEmpty() {
+		mostRecent := response.GetMostRecent()
+		if mostRecent != nil {
+			lastPlayTime := time.Unix(mostRecent.GetUTCTime(), 0)
+			fmt.Printf("  Last Played: %s\n", lastPlayTime.Format("2006-01-02 15:04:05"))
+		}
+	}
+}
+
+// printSourceStats prints statistics broken down by source
+func printSourceStats(response *models.RecentsResponse) {
+	fmt.Printf("\nBy Source:\n")
+
+	sourceStats := map[string]int{
+		"Spotify":      len(response.GetSpotifyItems()),
+		"Pandora":      len(response.GetPandoraItems()),
+		"TuneIn":       len(response.GetTuneInItems()),
+		"Local Music":  len(response.GetLocalMusicItems()),
+		"Stored Music": len(response.GetStoredMusicItems()),
+	}
+
+	// Add other sources if they exist
+	otherSources := make(map[string]int)
+
+	for _, item := range response.Items {
+		source := item.GetSource()
+		found := false
+
+		for knownSource := range sourceStats {
+			if strings.Contains(strings.ToLower(knownSource), strings.ToLower(source)) ||
+				strings.Contains(strings.ToLower(source), strings.ToLower(knownSource)) {
+				found = true
+				break
+			}
+		}
+
+		if !found && source != "" {
+			otherSources[formatSourceForDisplay(source)]++
+		}
+	}
+
+	// Merge other sources
+	for source, count := range otherSources {
+		sourceStats[source] = count
+	}
+
+	for source, count := range sourceStats {
+		if count > 0 {
+			percentage := float64(count) / float64(response.GetItemCount()) * 100
+			fmt.Printf("  %-15s %3d items (%5.1f%%)\n", source+":", count, percentage)
+		}
+	}
+}
+
+// printContentTypeStats prints statistics broken down by content type
+func printContentTypeStats(response *models.RecentsResponse) {
+	fmt.Printf("\nBy Content Type:\n")
+
+	tracks := len(response.GetTracks())
+	stations := len(response.GetStations())
+	playlists := len(response.GetPlaylistsAndAlbums())
+
+	if tracks > 0 {
+		percentage := float64(tracks) / float64(response.GetItemCount()) * 100
+		fmt.Printf("  %-15s %3d items (%5.1f%%)\n", "Tracks:", tracks, percentage)
+	}
+
+	if stations > 0 {
+		percentage := float64(stations) / float64(response.GetItemCount()) * 100
+		fmt.Printf("  %-15s %3d items (%5.1f%%)\n", "Stations:", stations, percentage)
+	}
+
+	if playlists > 0 {
+		percentage := float64(playlists) / float64(response.GetItemCount()) * 100
+		fmt.Printf("  %-15s %3d items (%5.1f%%)\n", "Playlists/Albums:", playlists, percentage)
+	}
+}
+
+// printSpecialCategoryStats prints statistics for special content categories
+func printSpecialCategoryStats(response *models.RecentsResponse) {
+	presetable := len(response.GetPresetableItems())
+	if presetable > 0 {
+		fmt.Printf("\nSpecial Categories:\n")
+
+		percentage := float64(presetable) / float64(response.GetItemCount()) * 100
+		fmt.Printf("  %-15s %3d items (%5.1f%%)\n", "Presetable:", presetable, percentage)
+	}
+}
+
+// printSourceAnalysisStats prints streaming vs local content analysis
+func printSourceAnalysisStats(response *models.RecentsResponse) {
+	streamingCount := 0
+	localCount := 0
+
+	for _, item := range response.Items {
+		if item.IsStreamingContent() {
+			streamingCount++
+		} else if item.IsLocalContent() {
+			localCount++
+		}
+	}
+
+	fmt.Printf("\nSource Analysis:\n")
+
+	if streamingCount > 0 {
+		percentage := float64(streamingCount) / float64(response.GetItemCount()) * 100
+		fmt.Printf("  %-15s %3d items (%5.1f%%)\n", "Streaming:", streamingCount, percentage)
+	}
+
+	if localCount > 0 {
+		percentage := float64(localCount) / float64(response.GetItemCount()) * 100
+		fmt.Printf("  %-15s %3d items (%5.1f%%)\n", "Local:", localCount, percentage)
+	}
+}
+
+// recentsStats shows statistics about recent items
+func recentsStats(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	PrintDeviceHeader("Getting recent items statistics", clientConfig.Host, clientConfig.Port)
+
+	response, err := client.GetRecents()
+	if err != nil {
+		return fmt.Errorf("failed to get recent items: %w", err)
+	}
+
+	if response.IsEmpty() {
+		fmt.Printf("📊 Statistics: No recent items found\n")
+		return nil
+	}
+
+	fmt.Printf("📊 Recent Items Statistics\n\n")
+
+	printBasicStats(response)
+	printSourceStats(response)
+	printContentTypeStats(response)
+	printSpecialCategoryStats(response)
+	printSourceAnalysisStats(response)
+
+	return nil
+}

cmd/soundtouch-cli/cmd_recents_test.go

@@ -0,0 +1,411 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+)
+
+func TestRecentsCommands(t *testing.T) {
+	tests := []struct {
+		name           string
+		args           []string
+		expectedOutput []string
+		expectError    bool
+	}{
+		{
+			name: "recents list command",
+			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "recents", "list"},
+			expectedOutput: []string{
+				"Getting recently played content",
+				"Recent Items Summary:",
+				"Recent Items",
+			},
+		},
+		{
+			name: "recents filter by source",
+			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "recents", "filter", "--source", "SPOTIFY"},
+			expectedOutput: []string{
+				"Getting filtered recent content",
+				"filtered by source: SPOTIFY",
+			},
+		},
+		{
+			name: "recents latest command",
+			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "recents", "latest"},
+			expectedOutput: []string{
+				"Getting most recent item",
+				"Most Recent Item:",
+			},
+		},
+		{
+			name: "recents stats command",
+			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "recents", "stats"},
+			expectedOutput: []string{
+				"Getting recent items statistics",
+				"Recent Items Statistics",
+			},
+		},
+		{
+			name:        "recents missing host",
+			args:        []string{"soundtouch-cli", "recents", "list"},
+			expectError: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Skip actual execution for now - these would need mock HTTP servers
+			// This test structure shows how the CLI commands would be tested
+			t.Skip("Integration test - requires mock HTTP server setup")
+
+			// Example of how you would set up the test:
+			// app := createTestApp()
+			//
+			// var buf bytes.Buffer
+			// app.Writer = &buf
+			// app.ErrWriter = &buf
+			//
+			// err := app.Run(tt.args)
+			//
+			// if tt.expectError {
+			//     if err == nil {
+			//         t.Error("expected error, got nil")
+			//     }
+			//     return
+			// }
+			//
+			// if err != nil {
+			//     t.Fatalf("unexpected error: %v", err)
+			// }
+			//
+			// output := buf.String()
+			// for _, expected := range tt.expectedOutput {
+			//     if !strings.Contains(output, expected) {
+			//         t.Errorf("expected output to contain %q, got:\n%s", expected, output)
+			//     }
+			// }
+		})
+	}
+}
+
+func TestPrintRecentItem(t *testing.T) {
+	tests := []struct {
+		name     string
+		item     *models.RecentsResponseItem
+		detailed bool
+		expected []string
+	}{
+		{
+			name: "basic track item",
+			item: &models.RecentsResponseItem{
+				DeviceID: "device1",
+				UTCTime:  1701200000,
+				ContentItem: &models.ContentItem{
+					Source:   "SPOTIFY",
+					Type:     "track",
+					ItemName: "Test Song",
+				},
+			},
+			detailed: false,
+			expected: []string{
+				"🎵 Test Song",
+				"Source: Spotify",
+				"Type: track",
+			},
+		},
+		{
+			name: "detailed station item",
+			item: &models.RecentsResponseItem{
+				DeviceID: "device1",
+				UTCTime:  1701200000,
+				ID:       "station123",
+				ContentItem: &models.ContentItem{
+					Source:        "TUNEIN",
+					Type:          "stationurl",
+					ItemName:      "Rock FM",
+					Location:      "tunein:station:s12345",
+					SourceAccount: "tunein_account",
+					IsPresetable:  true,
+				},
+			},
+			detailed: true,
+			expected: []string{
+				"📻 Rock FM",
+				"Source: TuneIn Radio",
+				"ID: station123",
+				"Can be saved as preset",
+				"Location: tunein:station:s12345",
+				"Classification: Streaming",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Capture stdout
+			oldStdout := os.Stdout
+			r, w, _ := os.Pipe()
+			os.Stdout = w
+
+			// Call the function
+			printRecentItem(1, tt.item, tt.detailed)
+
+			// Restore stdout and read output
+			w.Close()
+
+			os.Stdout = oldStdout
+
+			var buf bytes.Buffer
+
+			_, err := buf.ReadFrom(r)
+			if err != nil {
+				t.Fatalf("failed to read output: %v", err)
+			}
+
+			output := buf.String()
+
+			// Check expected strings are present
+			for _, expected := range tt.expected {
+				if !bytes.Contains(buf.Bytes(), []byte(expected)) {
+					t.Errorf("expected output to contain %q, got:\n%s", expected, output)
+				}
+			}
+		})
+	}
+}
+
+func TestGetContentTypeIcon(t *testing.T) {
+	tests := []struct {
+		name     string
+		item     *models.RecentsResponseItem
+		expected string
+	}{
+		{
+			name: "track item",
+			item: &models.RecentsResponseItem{
+				ContentItem: &models.ContentItem{Type: "track"},
+			},
+			expected: "🎵",
+		},
+		{
+			name: "station item",
+			item: &models.RecentsResponseItem{
+				ContentItem: &models.ContentItem{Type: "stationurl"},
+			},
+			expected: "📻",
+		},
+		{
+			name: "playlist item",
+			item: &models.RecentsResponseItem{
+				ContentItem: &models.ContentItem{Type: "playlist"},
+			},
+			expected: "📋",
+		},
+		{
+			name: "album item",
+			item: &models.RecentsResponseItem{
+				ContentItem: &models.ContentItem{Type: "album"},
+			},
+			expected: "💿",
+		},
+		{
+			name: "container item",
+			item: &models.RecentsResponseItem{
+				ContentItem: &models.ContentItem{Type: "container"},
+			},
+			expected: "📁",
+		},
+		{
+			name: "unknown type",
+			item: &models.RecentsResponseItem{
+				ContentItem: &models.ContentItem{Type: "unknown"},
+			},
+			expected: "🎶",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := getContentTypeIcon(tt.item)
+			if result != tt.expected {
+				t.Errorf("expected %q, got %q", tt.expected, result)
+			}
+		})
+	}
+}
+
+func TestFormatSourceForDisplay(t *testing.T) {
+	tests := []struct {
+		name     string
+		source   string
+		expected string
+	}{
+		{"Spotify", "SPOTIFY", "Spotify"},
+		{"Local Music", "LOCAL_MUSIC", "Local Music"},
+		{"Stored Music", "STORED_MUSIC", "Stored Music"},
+		{"TuneIn", "TUNEIN", "TuneIn Radio"},
+		{"Pandora", "PANDORA", "Pandora"},
+		{"Amazon", "AMAZON", "Amazon Music"},
+		{"Deezer", "DEEZER", "Deezer"},
+		{"iHeart", "IHEART", "iHeartRadio"},
+		{"Bluetooth", "BLUETOOTH", "Bluetooth"},
+		{"AUX", "AUX", "AUX Input"},
+		{"AirPlay", "AIRPLAY", "AirPlay"},
+		{"Unknown", "UNKNOWN_SOURCE", "UNKNOWN_SOURCE"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := formatSourceForDisplay(tt.source)
+			if result != tt.expected {
+				t.Errorf("expected %q, got %q", tt.expected, result)
+			}
+		})
+	}
+}
+
+func TestTruncateString(t *testing.T) {
+	tests := []struct {
+		name      string
+		input     string
+		maxLength int
+		expected  string
+	}{
+		{
+			name:      "short string",
+			input:     "hello",
+			maxLength: 10,
+			expected:  "hello",
+		},
+		{
+			name:      "exact length",
+			input:     "hello",
+			maxLength: 5,
+			expected:  "hello",
+		},
+		{
+			name:      "long string",
+			input:     "this is a very long string that needs truncation",
+			maxLength: 20,
+			expected:  "this is a very lo...",
+		},
+		{
+			name:      "very short max length",
+			input:     "hello world",
+			maxLength: 3,
+			expected:  "...",
+		},
+		{
+			name:      "zero length",
+			input:     "hello",
+			maxLength: 0,
+			expected:  "...",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := truncateString(tt.input, tt.maxLength)
+			if result != tt.expected {
+				t.Errorf("expected %q, got %q", tt.expected, result)
+			}
+		})
+	}
+}
+
+// Test helper functions that would be used in full integration tests
+func createTestRecentsResponse() *models.RecentsResponse {
+	return &models.RecentsResponse{
+		Items: []models.RecentsResponseItem{
+			{
+				DeviceID: "1004567890AA",
+				UTCTime:  1701300000,
+				ID:       "spotify1",
+				ContentItem: &models.ContentItem{
+					Source:        "SPOTIFY",
+					Type:          "track",
+					Location:      "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
+					SourceAccount: "spotify_user",
+					IsPresetable:  true,
+					ItemName:      "Shape of You - Ed Sheeran",
+					ContainerArt:  "https://i.scdn.co/image/ab67616d0000b273ba5db46f4b838ef6027e6f96",
+				},
+			},
+			{
+				DeviceID: "1004567890AA",
+				UTCTime:  1701200000,
+				ID:       "local1",
+				ContentItem: &models.ContentItem{
+					Source:       "LOCAL_MUSIC",
+					Type:         "track",
+					Location:     "/music/local_song.mp3",
+					IsPresetable: false,
+					ItemName:     "Local Song - Local Artist",
+				},
+			},
+			{
+				DeviceID: "1004567890AA",
+				UTCTime:  1701100000,
+				ID:       "tunein1",
+				ContentItem: &models.ContentItem{
+					Source:        "TUNEIN",
+					Type:          "stationurl",
+					Location:      "tunein:station:s24939",
+					SourceAccount: "tunein",
+					IsPresetable:  true,
+					ItemName:      "BBC Radio 1",
+				},
+			},
+		},
+	}
+}
+
+func TestCreateTestRecentsResponse(t *testing.T) {
+	response := createTestRecentsResponse()
+
+	if response == nil {
+		t.Fatal("expected response, got nil")
+	}
+
+	if response.GetItemCount() != 3 {
+		t.Errorf("expected 3 items, got %d", response.GetItemCount())
+	}
+
+	if response.IsEmpty() {
+		t.Error("expected response not to be empty")
+	}
+
+	// Test filtering
+	spotifyItems := response.GetSpotifyItems()
+	if len(spotifyItems) != 1 {
+		t.Errorf("expected 1 Spotify item, got %d", len(spotifyItems))
+	}
+
+	localItems := response.GetLocalMusicItems()
+	if len(localItems) != 1 {
+		t.Errorf("expected 1 local music item, got %d", len(localItems))
+	}
+
+	tuneInItems := response.GetTuneInItems()
+	if len(tuneInItems) != 1 {
+		t.Errorf("expected 1 TuneIn item, got %d", len(tuneInItems))
+	}
+
+	tracks := response.GetTracks()
+	if len(tracks) != 2 {
+		t.Errorf("expected 2 tracks, got %d", len(tracks))
+	}
+
+	stations := response.GetStations()
+	if len(stations) != 1 {
+		t.Errorf("expected 1 station, got %d", len(stations))
+	}
+
+	presetableItems := response.GetPresetableItems()
+	if len(presetableItems) != 2 {
+		t.Errorf("expected 2 presetable items, got %d", len(presetableItems))
+	}
+}

cmd/soundtouch-cli/cmd_source.go

@@ -1,7 +1,9 @@
 package main
 
 import (
+	"encoding/base64"
 	"fmt"
+	"net/url"
 	"strings"
 
 	"github.com/gesellix/bose-soundtouch/pkg/models"
@@ -209,6 +211,279 @@ func selectAux(c *cli.Context) error {
 	return nil
 }
 
+// selectLocalInternetRadio handles selecting LOCAL_INTERNET_RADIO source
+func selectLocalInternetRadio(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	location := c.String("location")
+	if location == "" {
+		return fmt.Errorf("location is required (use --location)")
+	}
+
+	sourceAccount := c.String("account")
+	itemName := c.String("name")
+	containerArt := c.String("artwork")
+
+	// Check LOCAL_INTERNET_RADIO availability
+	checker := NewServiceAvailabilityChecker(client)
+	if !checker.CheckSourceAvailable("LOCAL_INTERNET_RADIO", "select internet radio") {
+		return fmt.Errorf("LOCAL_INTERNET_RADIO is not available")
+	}
+
+	PrintDeviceHeader("Selecting internet radio stream", clientConfig.Host, clientConfig.Port)
+
+	if itemName != "" {
+		fmt.Printf("  Station: %s\n", itemName)
+	}
+
+	fmt.Printf("  Location: %s\n", location)
+
+	err = client.SelectLocalInternetRadio(location, sourceAccount, itemName, containerArt)
+	if err != nil {
+		return fmt.Errorf("failed to select internet radio: %w", err)
+	}
+
+	PrintSuccess("Internet radio stream selected")
+
+	return nil
+}
+
+// selectCustomRadio handles selecting custom radio stream via soundtouch-service
+func selectCustomRadio(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	streamURL := c.String("url")
+	itemName := c.String("name")
+	containerArt := c.String("artwork")
+	serviceURL := c.String("service-url")
+
+	encodedURL := base64.URLEncoding.EncodeToString([]byte(streamURL))
+	location := fmt.Sprintf("%s/custom/v1/playback/%s", serviceURL, encodedURL)
+
+	params := url.Values{}
+	if itemName != "" {
+		params.Add("name", itemName)
+	}
+
+	if containerArt != "" {
+		params.Add("imageUrl", containerArt)
+	}
+
+	if len(params) > 0 {
+		location += "?" + params.Encode()
+	}
+
+	// Check LOCAL_INTERNET_RADIO availability
+	checker := NewServiceAvailabilityChecker(client)
+	if !checker.CheckSourceAvailable("LOCAL_INTERNET_RADIO", "select custom radio") {
+		return fmt.Errorf("LOCAL_INTERNET_RADIO is not available")
+	}
+
+	PrintDeviceHeader("Selecting custom radio stream", clientConfig.Host, clientConfig.Port)
+
+	if itemName != "" {
+		fmt.Printf("  Station: %s\n", itemName)
+	}
+
+	fmt.Printf("  URL: %s\n", streamURL)
+	fmt.Printf("  Proxy: %s\n", location)
+
+	err = client.SelectLocalInternetRadio(location, "", itemName, containerArt)
+	if err != nil {
+		return fmt.Errorf("failed to select custom radio: %w", err)
+	}
+
+	PrintSuccess("Custom radio stream selected")
+
+	return nil
+}
+
+// selectLocalMusic handles selecting LOCAL_MUSIC source
+func selectLocalMusic(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	location := c.String("location")
+	if location == "" {
+		return fmt.Errorf("location is required (use --location)")
+	}
+
+	sourceAccount := c.String("account")
+	if sourceAccount == "" {
+		return fmt.Errorf("account is required for LOCAL_MUSIC (use --account)")
+	}
+
+	itemName := c.String("name")
+	containerArt := c.String("artwork")
+
+	// Check LOCAL_MUSIC availability
+	checker := NewServiceAvailabilityChecker(client)
+	if !checker.CheckSourceAvailable("LOCAL_MUSIC", "select local music") {
+		return fmt.Errorf("LOCAL_MUSIC is not available")
+	}
+
+	PrintDeviceHeader("Selecting local music content", clientConfig.Host, clientConfig.Port)
+
+	if itemName != "" {
+		fmt.Printf("  Content: %s\n", itemName)
+	}
+
+	fmt.Printf("  Location: %s\n", location)
+	fmt.Printf("  Account: %s\n", sourceAccount)
+
+	err = client.SelectLocalMusic(location, sourceAccount, itemName, containerArt)
+	if err != nil {
+		return fmt.Errorf("failed to select local music: %w", err)
+	}
+
+	PrintSuccess("Local music content selected")
+
+	return nil
+}
+
+// selectStoredMusic handles selecting STORED_MUSIC source
+func selectStoredMusic(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	location := c.String("location")
+	if location == "" {
+		return fmt.Errorf("location is required (use --location)")
+	}
+
+	sourceAccount := c.String("account")
+	if sourceAccount == "" {
+		return fmt.Errorf("account is required for STORED_MUSIC (use --account)")
+	}
+
+	itemName := c.String("name")
+	containerArt := c.String("artwork")
+
+	// Check STORED_MUSIC availability
+	checker := NewServiceAvailabilityChecker(client)
+	if !checker.CheckSourceAvailable("STORED_MUSIC", "select stored music") {
+		return fmt.Errorf("STORED_MUSIC is not available")
+	}
+
+	PrintDeviceHeader("Selecting stored music content", clientConfig.Host, clientConfig.Port)
+
+	if itemName != "" {
+		fmt.Printf("  Content: %s\n", itemName)
+	}
+
+	fmt.Printf("  Location: %s\n", location)
+	fmt.Printf("  Account: %s\n", sourceAccount)
+
+	err = client.SelectStoredMusic(location, sourceAccount, itemName, containerArt)
+	if err != nil {
+		return fmt.Errorf("failed to select stored music: %w", err)
+	}
+
+	PrintSuccess("Stored music content selected")
+
+	return nil
+}
+
+// selectContent handles selecting content using a ContentItem directly
+func selectContent(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	// Required parameters
+	source := strings.ToUpper(c.String("source"))
+	if source == "" {
+		return fmt.Errorf("source is required (use --source)")
+	}
+
+	location := c.String("location")
+	if location == "" {
+		return fmt.Errorf("location is required (use --location)")
+	}
+
+	// Optional parameters
+	sourceAccount := c.String("account")
+	itemName := c.String("name")
+	containerArt := c.String("artwork")
+	itemType := c.String("type")
+	isPresetable := c.Bool("presetable")
+
+	// Create ContentItem
+	contentItem := &models.ContentItem{
+		Source:        source,
+		Type:          itemType,
+		Location:      location,
+		SourceAccount: sourceAccount,
+		IsPresetable:  isPresetable,
+		ItemName:      itemName,
+		ContainerArt:  containerArt,
+	}
+
+	// Set default type if not specified
+	if itemType == "" {
+		switch source {
+		case "SPOTIFY":
+			contentItem.Type = "uri"
+		case "TUNEIN", "LOCAL_INTERNET_RADIO":
+			contentItem.Type = "stationurl"
+		case "LOCAL_MUSIC":
+			contentItem.Type = "album" // default, could be track, artist, etc.
+		}
+	}
+
+	// Set default item name if not specified
+	if itemName == "" {
+		contentItem.ItemName = source
+	}
+
+	PrintDeviceHeader("Selecting content", clientConfig.Host, clientConfig.Port)
+
+	fmt.Printf("  Source: %s\n", source)
+	fmt.Printf("  Location: %s\n", location)
+
+	if sourceAccount != "" {
+		fmt.Printf("  Account: %s\n", sourceAccount)
+	}
+
+	if itemName != "" {
+		fmt.Printf("  Name: %s\n", itemName)
+	}
+
+	if itemType != "" {
+		fmt.Printf("  Type: %s\n", itemType)
+	}
+
+	err = client.SelectContentItem(contentItem)
+	if err != nil {
+		return fmt.Errorf("failed to select content: %w", err)
+	}
+
+	PrintSuccess("Content selected")
+
+	return nil
+}
+
 // getServiceAvailability handles displaying service availability information
 func getServiceAvailability(c *cli.Context) error {
 	clientConfig := GetClientConfig(c)

cmd/soundtouch-cli/cmd_speaker.go

@@ -0,0 +1,217 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/urfave/cli/v2"
+)
+
+// playTTS plays a Text-To-Speech message on the speaker
+func playTTS(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	text := c.String("text")
+	appKey := c.String("app-key")
+	volume := c.Int("volume")
+	language := c.String("language")
+
+	if text == "" {
+		PrintError("Text message is required")
+		return fmt.Errorf("text message cannot be empty")
+	}
+
+	if appKey == "" {
+		PrintError("App key is required")
+		return fmt.Errorf("app key cannot be empty")
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Playing TTS message: \"%s\"", text), clientConfig.Host, clientConfig.Port)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	// Create PlayInfo for TTS
+	var playInfo *models.PlayInfo
+	if volume > 0 {
+		playInfo = models.NewTTSPlayInfo(text, appKey, language, volume)
+	} else {
+		playInfo = models.NewTTSPlayInfo(text, appKey, language)
+	}
+
+	err = client.PlayCustom(playInfo)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to play TTS message: %v", err))
+		return err
+	}
+
+	fmt.Printf("✅ TTS message sent successfully\n")
+
+	if volume > 0 {
+		fmt.Printf("   Volume: %d\n", volume)
+	} else {
+		fmt.Printf("   Volume: current level\n")
+	}
+
+	fmt.Printf("   Language: %s\n", strings.ToUpper(language))
+	fmt.Printf("   Message: \"%s\"\n", text)
+
+	return nil
+}
+
+// playURL plays audio content from a URL on the speaker
+func playURL(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	urlStr := c.String("url")
+	appKey := c.String("app-key")
+	service := c.String("service")
+	message := c.String("message")
+	reason := c.String("reason")
+	volume := c.Int("volume")
+
+	if urlStr == "" {
+		PrintError("URL is required")
+		return fmt.Errorf("URL cannot be empty")
+	}
+
+	if appKey == "" {
+		PrintError("App key is required")
+		return fmt.Errorf("app key cannot be empty")
+	}
+
+	// Set defaults if not provided
+	if service == "" {
+		service = "URL Playback"
+	}
+
+	if message == "" {
+		message = "Audio Content"
+	}
+
+	if reason == "" {
+		// Extract filename or use URL as reason
+		if idx := strings.LastIndex(urlStr, "/"); idx != -1 && idx < len(urlStr)-1 {
+			reason = urlStr[idx+1:]
+		} else {
+			reason = urlStr
+		}
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Playing URL: %s", urlStr), clientConfig.Host, clientConfig.Port)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	// Create PlayInfo for URL content
+	var playInfo *models.PlayInfo
+	if volume > 0 {
+		playInfo = models.NewURLPlayInfo(urlStr, appKey, service, message, reason, volume)
+	} else {
+		playInfo = models.NewURLPlayInfo(urlStr, appKey, service, message, reason)
+	}
+
+	err = client.PlayCustom(playInfo)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to play URL content: %v", err))
+		return err
+	}
+
+	fmt.Printf("✅ URL playback started successfully\n")
+	fmt.Printf("   URL: %s\n", urlStr)
+	fmt.Printf("   Service: %s\n", service)
+	fmt.Printf("   Message: %s\n", message)
+
+	if volume > 0 {
+		fmt.Printf("   Volume: %d\n", volume)
+	} else {
+		fmt.Printf("   Volume: current level\n")
+	}
+
+	return nil
+}
+
+// playNotification plays a notification sound or a local file on the speaker
+func playNotification(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	path := c.String("path")
+
+	if path != "" {
+		PrintDeviceHeader(fmt.Sprintf("Playing notification file: %s", path), clientConfig.Host, clientConfig.Port)
+	} else {
+		PrintDeviceHeader("Playing notification beep", clientConfig.Host, clientConfig.Port)
+	}
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	err = client.PlayNotification(path)
+	if err != nil {
+		if path != "" {
+			PrintError(fmt.Sprintf("Failed to play notification file: %v", err))
+		} else {
+			PrintError(fmt.Sprintf("Failed to play notification beep: %v", err))
+		}
+
+		return err
+	}
+
+	if path != "" {
+		fmt.Printf("✅ Notification file sent successfully: %s\n", path)
+	} else {
+		fmt.Printf("✅ Notification beep played successfully\n")
+	}
+
+	return nil
+}
+
+// playNotificationBeep plays a notification beep on the speaker (uses existing endpoint)
+func playNotificationBeep(c *cli.Context) error {
+	return playNotification(c)
+}
+
+// showSpeakerHelp displays help information about speaker functionality
+func showSpeakerHelp(_ *cli.Context) error {
+	fmt.Println("SoundTouch Speaker Playback Commands")
+	fmt.Println("=====================================")
+	fmt.Println()
+	fmt.Println("The /speaker endpoint supports playing notifications and URL content:")
+	fmt.Println()
+	fmt.Println("• Text-to-Speech (TTS) Messages:")
+	fmt.Println("  Play spoken messages using Google TTS")
+	fmt.Println("  Example: soundtouch-cli speaker tts --text \"Hello World\" --app-key YOUR_KEY")
+	fmt.Println()
+	fmt.Println("• URL Content Playback:")
+	fmt.Println("  Play audio files from HTTP/HTTPS URLs")
+	fmt.Println("  Example: soundtouch-cli speaker url --url \"https://example.com/audio.mp3\" --app-key YOUR_KEY")
+	fmt.Println()
+	fmt.Println("• Notification Beep:")
+	fmt.Println("  Play a simple notification sound")
+	fmt.Println("  Example: soundtouch-cli speaker beep")
+	fmt.Println()
+	fmt.Println("• Custom Notification:")
+	fmt.Println("  Play a device-local PCM file as notification")
+	fmt.Println("  Example: soundtouch-cli speaker notify --path \"/opt/Bose/chimes/grouped.pcm\"")
+	fmt.Println()
+	fmt.Println("Notes:")
+	fmt.Println("• Only ST-10 (Series III) speakers support the /speaker endpoint")
+	fmt.Println("• ST-300 and other models may not support this functionality")
+	fmt.Println("• You need to provide your own app_key for TTS and URL playback")
+	fmt.Println("• Currently playing content is paused during playback and resumed after")
+	fmt.Println("• If device is a zone master, content plays on all zone members")
+	fmt.Println("• Volume is automatically restored after playback completes")
+	fmt.Println()
+	fmt.Println("Supported Languages for TTS:")
+	fmt.Println("EN (English), DE (German), ES (Spanish), FR (French), IT (Italian),")
+	fmt.Println("NL (Dutch), PT (Portuguese), RU (Russian), ZH (Chinese), JA (Japanese)")
+
+	return nil
+}

cmd/soundtouch-cli/common.go

@@ -1,10 +1,14 @@
 package main
 
 import (
+	"encoding/base64"
 	"fmt"
+	"html"
 	"io"
 	"net"
 	"net/http"
+	"os"
+	"regexp"
 	"runtime"
 	"strconv"
 	"strings"
@@ -163,10 +167,26 @@ func resolveLocation(source, location string) (string, string) {
 		}
 	}
 
+	// Spotify URL conversion
+	// Example: https://open.spotify.com/album/7F50uh7oGitmAEScRKV6pD?si=YhDPWL9LRGO5whz1wLsteA
+	if strings.Contains(location, "open.spotify.com/") {
+		re := regexp.MustCompile(`https://open\.spotify\.com/([^/]+)/([^?]+)`)
+
+		matches := re.FindStringSubmatch(location)
+		if len(matches) >= 3 {
+			contentType := matches[1]
+			contentID := matches[2]
+			uri := fmt.Sprintf("spotify:%s:%s", contentType, contentID)
+			encodedURI := base64.StdEncoding.EncodeToString([]byte(uri))
+
+			return "SPOTIFY", "/playback/container/" + encodedURI
+		}
+	}
+
 	return source, location
 }
 
-type TuneInMetadata struct {
+type Metadata struct {
 	Name    string
 	Artwork string
 }
@@ -175,8 +195,8 @@ var httpClient = &http.Client{
 	Timeout: 5 * time.Second,
 }
 
-func fetchTuneInMetadata(url string) (*TuneInMetadata, error) {
-	if !strings.Contains(url, "tunein.com/radio/") {
+func fetchTuneInMetadata(url string) (*Metadata, error) {
+	if !strings.Contains(url, "tunein.com/radio/") && !strings.Contains(url, "127.0.0.1") && !strings.Contains(url, "localhost") {
 		return nil, fmt.Errorf("url is not a TuneIn radio URL")
 	}
 
@@ -195,20 +215,20 @@ func fetchTuneInMetadata(url string) (*TuneInMetadata, error) {
 		return nil, err
 	}
 
-	html := string(body)
-	metadata := &TuneInMetadata{}
+	rawHTML := string(body)
+	metadata := &Metadata{}
 
 	// Simple extraction of og:title and og:image
 	// Example: <meta data-react-helmet="true" property="og:title" content="WDR 2 Rheinland, 100.4 FM, Köln | Free Internet Radio | TuneIn"/>
 	// Example: <meta data-react-helmet="true" property="og:image" content="https://cdn-radiotime-logos.tunein.com/s213886g.png"/>
 
 	titlePrefix := `property="og:title" content="`
-	if idx := strings.Index(html, titlePrefix); idx != -1 {
+	if idx := strings.Index(rawHTML, titlePrefix); idx != -1 {
 		start := idx + len(titlePrefix)
 
-		end := strings.Index(html[start:], `"`)
+		end := strings.Index(rawHTML[start:], `"`)
 		if end != -1 {
-			title := html[start : start+end]
+			title := html.UnescapeString(rawHTML[start : start+end])
 			// Clean up title (remove ", 100.4 FM, Köln | Free Internet Radio | TuneIn")
 			if pipeIdx := strings.Index(title, " | "); pipeIdx != -1 {
 				title = title[:pipeIdx]
@@ -223,12 +243,72 @@ func fetchTuneInMetadata(url string) (*TuneInMetadata, error) {
 	}
 
 	imagePrefix := `property="og:image" content="`
-	if idx := strings.Index(html, imagePrefix); idx != -1 {
+	if idx := strings.Index(rawHTML, imagePrefix); idx != -1 {
 		start := idx + len(imagePrefix)
 
-		end := strings.Index(html[start:], `"`)
+		end := strings.Index(rawHTML[start:], `"`)
 		if end != -1 {
-			metadata.Artwork = html[start : start+end]
+			metadata.Artwork = rawHTML[start : start+end]
+		}
+	}
+
+	return metadata, nil
+}
+
+func fetchSpotifyMetadata(url string) (*Metadata, error) {
+	if !strings.Contains(url, "open.spotify.com/") && !strings.Contains(url, "127.0.0.1") && !strings.Contains(url, "localhost") {
+		return nil, fmt.Errorf("url is not a Spotify URL")
+	}
+
+	resp, err := httpClient.Get(url)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("unexpected status code: %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1024*200)) // Spotify pages can be larger
+	if err != nil {
+		return nil, err
+	}
+
+	rawHTML := string(body)
+	metadata := &Metadata{}
+
+	// Simple extraction of og:title and og:image
+	// Example: <meta property="og:title" content="Terminal Caribe - Album by Santi &amp; Tuğçe | Spotify"
+
+	titlePrefix := `property="og:title" content="`
+	if idx := strings.Index(rawHTML, titlePrefix); idx != -1 {
+		start := idx + len(titlePrefix)
+
+		end := strings.Index(rawHTML[start:], `"`)
+		if end != -1 {
+			title := html.UnescapeString(rawHTML[start : start+end])
+			// Clean up title (remove " | Spotify")
+			if pipeIdx := strings.Index(title, " | "); pipeIdx != -1 {
+				title = title[:pipeIdx]
+			}
+
+			// Spotify often has "- Album by ..." or "- Playlist by ..."
+			// We might want to keep it or clean it up.
+			// User's TuneIn example cleaned it up.
+			// For now let's just keep what Spotify provides as title minus the " | Spotify" part.
+
+			metadata.Name = title
+		}
+	}
+
+	imagePrefix := `property="og:image" content="`
+	if idx := strings.Index(rawHTML, imagePrefix); idx != -1 {
+		start := idx + len(imagePrefix)
+
+		end := strings.Index(rawHTML[start:], `"`)
+		if end != -1 {
+			metadata.Artwork = rawHTML[start : start+end]
 		}
 	}
 
@@ -252,7 +332,7 @@ func PrintWarning(message string) {
 
 // showVersionInfo displays detailed version information including build details
 func showVersionInfo(_ *cli.Context) error {
-	fmt.Printf("soundtouch-cli version %s\n", version)
+	fmt.Printf("%s version %s\n", os.Args[0], version)
 	fmt.Printf("Build commit: %s\n", commit)
 	fmt.Printf("Build date: %s\n", date)
 	fmt.Printf("Go version: %s\n", runtime.Version())

cmd/soundtouch-cli/common_test.go

@@ -7,7 +7,7 @@ import (
 )
 
 func TestFetchTuneInMetadata(t *testing.T) {
-	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		html := `
 <!doctype html>
 <html>
@@ -30,23 +30,23 @@ func TestFetchTuneInMetadata(t *testing.T) {
 
 	defer func() { httpClient = oldClient }()
 
-	metadata, err := fetchTuneInMetadata("https://tunein.com/radio/WDR-2-Rheinland-1004-s213886/")
+	metadata, err := fetchTuneInMetadata(ts.URL + "/radio/WDR-2-Rheinland-1004-s213886/")
 	if err != nil {
 		t.Fatalf("fetchTuneInMetadata() error = %v", err)
 	}
 
 	if metadata == nil {
 		t.Fatal("fetchTuneInMetadata() returned nil metadata")
-	}
+	} else {
+		expectedName := "WDR 2 Rheinland"
+		if metadata.Name != expectedName {
+			t.Errorf("metadata.Name = %v, want %v", metadata.Name, expectedName)
+		}
 
-	expectedName := "WDR 2 Rheinland"
-	if metadata.Name != expectedName {
-		t.Errorf("metadata.Name = %v, want %v", metadata.Name, expectedName)
-	}
-
-	expectedArtwork := "https://cdn-radiotime-logos.tunein.com/s213886g.png"
-	if metadata.Artwork != expectedArtwork {
-		t.Errorf("metadata.Artwork = %v, want %v", metadata.Artwork, expectedArtwork)
+		expectedArtwork := "https://cdn-radiotime-logos.tunein.com/s213886g.png"
+		if metadata.Artwork != expectedArtwork {
+			t.Errorf("metadata.Artwork = %v, want %v", metadata.Artwork, expectedArtwork)
+		}
 	}
 }
 
@@ -115,3 +115,92 @@ func TestResolveLocation(t *testing.T) {
 		})
 	}
 }
+
+func TestResolveLocationSpotify(t *testing.T) {
+	tests := []struct {
+		name             string
+		source           string
+		location         string
+		expectedSource   string
+		expectedLocation string
+	}{
+		{
+			name:             "Spotify album URL",
+			source:           "",
+			location:         "https://open.spotify.com/album/6rT8yer84xoh0t17poLsmn?si=XqxdZazpTLC1ceoC8EeCuA",
+			expectedSource:   "SPOTIFY",
+			expectedLocation: "/playback/container/c3BvdGlmeTphbGJ1bTo2clQ4eWVyODR4b2gwdDE3cG9Mc21u",
+		},
+		{
+			name:             "Spotify playlist URL",
+			source:           "",
+			location:         "https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd",
+			expectedSource:   "SPOTIFY",
+			expectedLocation: "/playback/container/c3BvdGlmeTpwbGF5bGlzdDozN2k5ZFFaRjFEWDBYVXN1eFdIUlFk",
+		},
+		{
+			name:             "Spotify track URL",
+			source:           "",
+			location:         "https://open.spotify.com/track/17GmwQ9Q3MTAz05OokmNNB?si=123",
+			expectedSource:   "SPOTIFY",
+			expectedLocation: "/playback/container/c3BvdGlmeTp0cmFjazoxN0dtd1E5UTNNVEF6MDVPb2ttTk5C",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotSource, gotLocation := resolveLocation(tt.source, tt.location)
+			if gotSource != tt.expectedSource {
+				t.Errorf("resolveLocation() gotSource = %v, want %v", gotSource, tt.expectedSource)
+			}
+
+			if gotLocation != tt.expectedLocation {
+				t.Errorf("resolveLocation() gotLocation = %v, want %v", gotLocation, tt.expectedLocation)
+			}
+		})
+	}
+}
+
+func TestFetchSpotifyMetadata(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		html := `
+<!doctype html>
+<html>
+<head>
+    <meta property="og:title" content="Terminal Caribe - Album by Santi &amp; Tuğçe | Spotify"/>
+    <meta property="og:image" content="https://i.scdn.co/image/ab67616d0000b273f0e55478f4a15182405bcb47"/>
+</head>
+<body></body>
+</html>
+`
+
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(html))
+	}))
+	defer ts.Close()
+
+	// Temporarily override httpClient to use test server
+	oldClient := httpClient
+	httpClient = ts.Client()
+
+	defer func() { httpClient = oldClient }()
+
+	metadata, err := fetchSpotifyMetadata(ts.URL + "/album/7F50uh7oGitmAEScRKV6pD")
+	if err != nil {
+		t.Fatalf("fetchSpotifyMetadata() error = %v", err)
+	}
+
+	if metadata == nil {
+		t.Fatal("fetchSpotifyMetadata() returned nil metadata")
+	} else {
+		expectedName := "Terminal Caribe - Album by Santi & Tuğçe"
+		if metadata.Name != expectedName {
+			t.Errorf("metadata.Name = %v, want %v", metadata.Name, expectedName)
+		}
+
+		expectedArtwork := "https://i.scdn.co/image/ab67616d0000b273f0e55478f4a15182405bcb47"
+		if metadata.Artwork != expectedArtwork {
+			t.Errorf("metadata.Artwork = %v, want %v", metadata.Artwork, expectedArtwork)
+		}
+	}
+}

cmd/soundtouch-cli/main.go

@@ -104,7 +104,7 @@ func main() {
 		Version: version,
 		Authors: []*cli.Author{
 			{
-				Name: "Tobias Gesellchen, and the SoundTouch CLI Contributors",
+				Name: "Tobias Gesellchen, and the Bose-SoundTouch Contributors",
 			},
 		},
 		Flags: CommonFlags,
@@ -209,6 +209,72 @@ func main() {
 				Action: getPresets,
 				Before: RequireHost,
 			},
+			// Recent content commands
+			{
+				Name:    "recents",
+				Aliases: []string{"recent"},
+				Usage:   "Recently played content commands",
+				Subcommands: []*cli.Command{
+					{
+						Name:   "list",
+						Usage:  "List recently played content",
+						Action: getRecents,
+						Flags: []cli.Flag{
+							&cli.IntFlag{
+								Name:  "limit",
+								Usage: "Maximum number of items to display (0 for all)",
+								Value: 10,
+							},
+							&cli.BoolFlag{
+								Name:    "detailed",
+								Aliases: []string{"d"},
+								Usage:   "Show detailed information for each item",
+							},
+						},
+						Before: RequireHost,
+					},
+					{
+						Name:   "filter",
+						Usage:  "List recently played content with filters",
+						Action: getRecentsFiltered,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:    "source",
+								Aliases: []string{"s"},
+								Usage:   "Filter by source (SPOTIFY, LOCAL_MUSIC, TUNEIN, etc.)",
+							},
+							&cli.StringFlag{
+								Name:    "type",
+								Aliases: []string{"t"},
+								Usage:   "Filter by content type (track, station, playlist, album, presetable)",
+							},
+							&cli.IntFlag{
+								Name:  "limit",
+								Usage: "Maximum number of items to display (0 for all)",
+								Value: 10,
+							},
+							&cli.BoolFlag{
+								Name:    "detailed",
+								Aliases: []string{"d"},
+								Usage:   "Show detailed information for each item",
+							},
+						},
+						Before: RequireHost,
+					},
+					{
+						Name:   "latest",
+						Usage:  "Show only the most recent item",
+						Action: getRecentsMostRecent,
+						Before: RequireHost,
+					},
+					{
+						Name:   "stats",
+						Usage:  "Show statistics about recent content",
+						Action: recentsStats,
+						Before: RequireHost,
+					},
+				},
+			},
 			// Playback commands
 			{
 				Name:    "play",
@@ -830,6 +896,164 @@ func main() {
 						Action: selectAux,
 						Before: RequireHost,
 					},
+					{
+						Name:   "internet-radio",
+						Usage:  "Select internet radio stream (LOCAL_INTERNET_RADIO)",
+						Action: selectLocalInternetRadio,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "location",
+								Aliases:  []string{"l"},
+								Usage:    "Stream location URL (direct stream or streamUrl format)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "account",
+								Aliases: []string{"a"},
+								Usage:   "Source account (optional)",
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Station name",
+							},
+							&cli.StringFlag{
+								Name:  "artwork",
+								Usage: "Station artwork URL",
+							},
+						},
+					},
+					{
+						Name:   "custom-radio",
+						Usage:  "Select custom radio stream via soundtouch-service",
+						Action: selectCustomRadio,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "url",
+								Aliases:  []string{"u"},
+								Usage:    "Stream URL",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Station name",
+							},
+							&cli.StringFlag{
+								Name:  "artwork",
+								Usage: "Station artwork URL",
+							},
+							&cli.StringFlag{
+								Name:  "service-url",
+								Usage: "URL of the soundtouch-service (default: http://localhost:8080)",
+								Value: "http://localhost:8080",
+							},
+						},
+					},
+					{
+						Name:   "local-music",
+						Usage:  "Select local music content (LOCAL_MUSIC)",
+						Action: selectLocalMusic,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "location",
+								Aliases:  []string{"l"},
+								Usage:    "Content location (e.g., album:983, track:2579)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "account",
+								Aliases:  []string{"a"},
+								Usage:    "Source account GUID (required)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Content name",
+							},
+							&cli.StringFlag{
+								Name:  "artwork",
+								Usage: "Content artwork URL",
+							},
+						},
+					},
+					{
+						Name:   "stored-music",
+						Usage:  "Select stored music content (STORED_MUSIC)",
+						Action: selectStoredMusic,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "location",
+								Aliases:  []string{"l"},
+								Usage:    "Content location ID (e.g., 6_a2874b5d_4f83d999)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "account",
+								Aliases:  []string{"a"},
+								Usage:    "Source account GUID (required)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Content name",
+							},
+							&cli.StringFlag{
+								Name:  "artwork",
+								Usage: "Content artwork URL",
+							},
+						},
+					},
+					{
+						Name:   "content",
+						Usage:  "Select content using ContentItem (advanced)",
+						Action: selectContent,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "source",
+								Aliases:  []string{"s"},
+								Usage:    "Content source (SPOTIFY, TUNEIN, LOCAL_INTERNET_RADIO, etc.)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "location",
+								Aliases:  []string{"l"},
+								Usage:    "Content location",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "account",
+								Aliases: []string{"a"},
+								Usage:   "Source account",
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Content name",
+							},
+							&cli.StringFlag{
+								Name:    "type",
+								Aliases: []string{"t"},
+								Usage:   "Content type (uri, stationurl, album, track, etc.)",
+							},
+							&cli.StringFlag{
+								Name:  "artwork",
+								Usage: "Content artwork URL",
+							},
+							&cli.BoolFlag{
+								Name:  "presetable",
+								Usage: "Mark content as presetable",
+								Value: true,
+							},
+						},
+					},
 					{
 						Name:   "availability",
 						Usage:  "Show service availability",
@@ -842,6 +1066,44 @@ func main() {
 						Action: compareSourcesAndAvailability,
 						Before: RequireHost,
 					},
+					{
+						Name:   "introspect",
+						Usage:  "Get introspect data for a music service",
+						Action: introspectService,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "source",
+								Aliases:  []string{"s"},
+								Usage:    "Music service source (SPOTIFY, PANDORA, TUNEIN, etc.)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "account",
+								Aliases: []string{"a"},
+								Usage:   "Source account name (optional)",
+							},
+						},
+						Before: RequireHost,
+					},
+					{
+						Name:   "introspect-spotify",
+						Usage:  "Get Spotify introspect data (convenience command)",
+						Action: introspectSpotify,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:    "account",
+								Aliases: []string{"a"},
+								Usage:   "Spotify account name (optional)",
+							},
+						},
+						Before: RequireHost,
+					},
+					{
+						Name:   "introspect-all",
+						Usage:  "Get introspect data for all available services",
+						Action: introspectAllServices,
+						Before: RequireHost,
+					},
 				},
 			},
 			// Bass commands
@@ -1392,6 +1654,416 @@ func main() {
 					},
 				},
 			},
+			// Speaker commands (TTS and URL playback)
+			{
+				Name:    "speaker",
+				Aliases: []string{"sp"},
+				Usage:   "Speaker notification and content playback commands",
+				Subcommands: []*cli.Command{
+					{
+						Name:   "tts",
+						Usage:  "Play a Text-To-Speech message",
+						Action: playTTS,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "text",
+								Aliases:  []string{"t"},
+								Usage:    "Text message to speak",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "app-key",
+								Aliases:  []string{"k"},
+								Usage:    "Application key for the request",
+								Required: true,
+							},
+							&cli.IntFlag{
+								Name:    "volume",
+								Aliases: []string{"v"},
+								Usage:   "Volume level (0-100, 0 = current volume)",
+								Value:   0,
+							},
+							&cli.StringFlag{
+								Name:    "language",
+								Aliases: []string{"l"},
+								Usage:   "Language code (EN, DE, ES, FR, etc.)",
+								Value:   "EN",
+							},
+						},
+					},
+					{
+						Name:   "url",
+						Usage:  "Play audio content from a URL",
+						Action: playURL,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "url",
+								Aliases:  []string{"u"},
+								Usage:    "URL of the audio content to play",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "app-key",
+								Aliases:  []string{"k"},
+								Usage:    "Application key for the request",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "service",
+								Aliases: []string{"s"},
+								Usage:   "Service name (appears in NowPlaying artist field)",
+								Value:   "URL Playback",
+							},
+							&cli.StringFlag{
+								Name:    "message",
+								Aliases: []string{"m"},
+								Usage:   "Message description (appears in NowPlaying album field)",
+								Value:   "Audio Content",
+							},
+							&cli.StringFlag{
+								Name:    "reason",
+								Aliases: []string{"r"},
+								Usage:   "Reason or filename (appears in NowPlaying track field)",
+							},
+							&cli.IntFlag{
+								Name:    "volume",
+								Aliases: []string{"v"},
+								Usage:   "Volume level (0-100, 0 = current volume)",
+								Value:   0,
+							},
+						},
+					},
+					{
+						Name:   "notify",
+						Usage:  "Play a notification sound or local file",
+						Action: playNotification,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:    "path",
+								Aliases: []string{"p"},
+								Usage:   "Device-local path to a PCM file (e.g. /opt/Bose/chimes/grouped.pcm)",
+							},
+						},
+					},
+					{
+						Name:   "beep",
+						Usage:  "Play a notification beep sound",
+						Action: playNotificationBeep,
+						Before: RequireHost,
+					},
+					{
+						Name:   "help",
+						Usage:  "Show detailed help about speaker functionality",
+						Action: showSpeakerHelp,
+					},
+				},
+			},
+			// Account management commands
+			{
+				Name:    "account",
+				Aliases: []string{"acc"},
+				Usage:   "Music service account management commands",
+				Subcommands: []*cli.Command{
+					{
+						Name:   "list",
+						Usage:  "List configured music service accounts",
+						Action: listMusicServiceAccounts,
+						Before: RequireHost,
+					},
+					{
+						Name:   "add",
+						Usage:  "Add a music service account",
+						Action: addMusicServiceAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "source",
+								Aliases:  []string{"s"},
+								Usage:    "Music service source (SPOTIFY, PANDORA, AMAZON, DEEZER, IHEART, STORED_MUSIC)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Username or account identifier",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "password",
+								Aliases: []string{"p"},
+								Usage:   "Account password (not required for STORED_MUSIC)",
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Display name for the service",
+							},
+						},
+					},
+					{
+						Name:   "remove",
+						Usage:  "Remove a music service account",
+						Action: removeMusicServiceAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "source",
+								Aliases:  []string{"s"},
+								Usage:    "Music service source (SPOTIFY, PANDORA, AMAZON, DEEZER, IHEART, STORED_MUSIC)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Username or account identifier",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Display name for the service",
+							},
+						},
+					},
+					{
+						Name:   "add-spotify",
+						Usage:  "Add a Spotify Premium account",
+						Action: addSpotifyAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Spotify username/email",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "password",
+								Aliases:  []string{"p"},
+								Usage:    "Spotify password",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "remove-spotify",
+						Usage:  "Remove a Spotify account",
+						Action: removeSpotifyAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Spotify username/email to remove",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "add-pandora",
+						Usage:  "Add a Pandora account",
+						Action: addPandoraAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Pandora username",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "password",
+								Aliases:  []string{"p"},
+								Usage:    "Pandora password",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "remove-pandora",
+						Usage:  "Remove a Pandora account",
+						Action: removePandoraAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Pandora username to remove",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "add-nas",
+						Usage:  "Add a network music library (NAS/UPnP)",
+						Action: addStoredMusicAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "UPnP server GUID with /0 suffix (e.g., d09708a1-5953-44bc-a413-123456789012/0)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Display name for the music library",
+								Value:   "Network Music Library",
+							},
+						},
+					},
+					{
+						Name:   "remove-nas",
+						Usage:  "Remove a network music library",
+						Action: removeStoredMusicAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "UPnP server GUID with /0 suffix to remove",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Display name for the music library",
+								Value:   "Network Music Library",
+							},
+						},
+					},
+					{
+						Name:   "add-amazon",
+						Usage:  "Add an Amazon Music account",
+						Action: addAmazonMusicAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Amazon Music username",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "password",
+								Aliases:  []string{"p"},
+								Usage:    "Amazon Music password",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "remove-amazon",
+						Usage:  "Remove an Amazon Music account",
+						Action: removeAmazonMusicAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Amazon Music username to remove",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "add-deezer",
+						Usage:  "Add a Deezer Premium account",
+						Action: addDeezerAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Deezer username",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "password",
+								Aliases:  []string{"p"},
+								Usage:    "Deezer password",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "remove-deezer",
+						Usage:  "Remove a Deezer account",
+						Action: removeDeezerAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "Deezer username to remove",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "add-iheart",
+						Usage:  "Add an iHeartRadio account",
+						Action: addIHeartRadioAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "iHeartRadio username",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "password",
+								Aliases:  []string{"p"},
+								Usage:    "iHeartRadio password",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "remove-iheart",
+						Usage:  "Remove an iHeartRadio account",
+						Action: removeIHeartRadioAccount,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "user",
+								Aliases:  []string{"u"},
+								Usage:    "iHeartRadio username to remove",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "pair",
+						Usage:  "Pair the device with a Marge cloud account (Stockholm registration)",
+						Action: pairDevice,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "id",
+								Usage:    "Marge account ID (e.g., 1234567)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "token",
+								Usage:    "User authorization token",
+								Required: true,
+							},
+						},
+					},
+					{
+						Name:   "unpair",
+						Usage:  "Unpair the device from its Marge cloud account",
+						Action: unpairDevice,
+						Before: RequireHost,
+					},
+				},
+			},
 			// Token commands
 			{
 				Name:    "token",
@@ -1406,6 +2078,42 @@ func main() {
 					},
 				},
 			},
+			// Events commands
+			{
+				Name:    "events",
+				Aliases: []string{"e"},
+				Usage:   "WebSocket event monitoring commands",
+				Subcommands: []*cli.Command{
+					{
+						Name:   "subscribe",
+						Usage:  "Subscribe to real-time device events via WebSocket",
+						Action: eventSubscribe,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:    "filter",
+								Aliases: []string{"f"},
+								Usage:   "Filter events by type (comma-separated): nowPlaying,volume,connection,preset,zone,bass,sdkInfo,userActivity",
+							},
+							&cli.DurationFlag{
+								Name:    "duration",
+								Aliases: []string{"d"},
+								Usage:   "How long to listen for events (0 = infinite)",
+								Value:   0,
+							},
+							&cli.BoolFlag{
+								Name:  "no-reconnect",
+								Usage: "Disable automatic reconnection on connection loss",
+							},
+							&cli.BoolFlag{
+								Name:    "verbose",
+								Aliases: []string{"v"},
+								Usage:   "Enable verbose logging and detailed event information",
+							},
+						},
+					},
+				},
+			},
 		},
 	}
 

cmd/soundtouch-service/main_test.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"os"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+)
+
+func TestApplyPersistedSettings(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "main-test")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	ds := datastore.NewDataStore(tmpDir)
+
+	t.Run("overrides true with false", func(t *testing.T) {
+		config := &serviceConfig{
+			redact:  true,
+			logBody: true,
+			record:  true,
+		}
+
+		// Simulate the bug by using the old bitwise OR logic in the test,
+		// which should fail if we expect false.
+		// config.redact = config.redact || false -> stays true
+
+		settings := datastore.Settings{
+			RedactLogs:         false,
+			LogBodies:          false,
+			RecordInteractions: false,
+		}
+		err := ds.SaveSettings(settings)
+		if err != nil {
+			t.Fatalf("Failed to save settings: %v", err)
+		}
+
+		applyPersistedSettings(ds, config)
+
+		if config.redact != false {
+			t.Errorf("Expected redact to be false, got true")
+		}
+		if config.logBody != false {
+			t.Errorf("Expected logBody to be false, got true")
+		}
+		if config.record != false {
+			t.Errorf("Expected record to be false, got true")
+		}
+	})
+
+	t.Run("retains false when settings are false", func(t *testing.T) {
+		settings := datastore.Settings{
+			RedactLogs: false,
+		}
+		err := ds.SaveSettings(settings)
+		if err != nil {
+			t.Fatalf("Failed to save settings: %v", err)
+		}
+
+		config := &serviceConfig{
+			redact: false,
+		}
+
+		applyPersistedSettings(ds, config)
+
+		if config.redact != false {
+			t.Errorf("Expected redact to be false, got true")
+		}
+	})
+
+	t.Run("overrides false with true", func(t *testing.T) {
+		settings := datastore.Settings{
+			RedactLogs: true,
+		}
+		err := ds.SaveSettings(settings)
+		if err != nil {
+			t.Fatalf("Failed to save settings: %v", err)
+		}
+
+		config := &serviceConfig{
+			redact: false,
+		}
+
+		applyPersistedSettings(ds, config)
+
+		if config.redact != true {
+			t.Errorf("Expected redact to be true, got false")
+		}
+	})
+}

cmd/soundtouch-service/router_test.go

@@ -0,0 +1,104 @@
+package main
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"reflect"
+	"runtime"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/handlers"
+	"github.com/go-chi/chi/v5"
+)
+
+func TestPrintRoutes(t *testing.T) {
+	// Initialize a minimal server to get the router
+	server := handlers.NewServer(nil, nil, "http://localhost:8000", true, true, true)
+	r := setupRouter(server)
+
+	var routes []string
+	walkFunc := func(method string, route string, handler http.Handler, middlewares ...func(http.Handler) http.Handler) error {
+		route = strings.ReplaceAll(route, "/*/", "/")
+		handlerName := runtime.FuncForPC(reflect.ValueOf(handler).Pointer()).Name()
+		// Clean up the handler name (remove package path)
+		// For example, "github.com/gesellix/bose-soundtouch/cmd/soundtouch-service.setupRouter.func1"
+		// or "command-line-arguments.setupRouter.func1"
+		// or "main.setupRouter.func1"
+		parts := strings.Split(handlerName, "/")
+		if len(parts) > 0 {
+			handlerName = parts[len(parts)-1]
+		}
+		// Now we might have "soundtouch-service.setupRouter.func1"
+		// or "command-line-arguments.setupRouter.func1"
+		// or "main.setupRouter.func1"
+		// Let's remove the first part if it's a known varying package name
+		if idx := strings.Index(handlerName, "setupRouter"); idx != -1 {
+			handlerName = handlerName[idx:]
+		}
+		// In case it's not setupRouter but still has a package prefix
+		for {
+			dotIdx := strings.Index(handlerName, ".")
+			if dotIdx == -1 {
+				break
+			}
+			prefix := handlerName[:dotIdx]
+			if prefix == "main" || prefix == "command-line-arguments" || strings.Contains(prefix, "soundtouch-service") {
+				handlerName = handlerName[dotIdx+1:]
+			} else {
+				break
+			}
+		}
+
+		// Also remove any ".funcN" suffix if it's an anonymous function
+		if idx := strings.Index(handlerName, ".func"); idx != -1 {
+			handlerName = handlerName[:idx]
+		}
+
+		routes = append(routes, fmt.Sprintf("%-8s %-60s %s", method, route, handlerName))
+		return nil
+	}
+
+	if err := chi.Walk(r, walkFunc); err != nil {
+		t.Fatalf("Failed to walk routes: %v", err)
+	}
+
+	sort.Strings(routes)
+
+	output := strings.Join(routes, "\n") + "\n"
+
+	// Define snapshot path
+	snapshotPath := "testdata/router_routes.txt"
+	actualPath := "testdata/router_routes.actual.txt"
+
+	// Always write the current (actual) routes to a file
+	if err := os.WriteFile(actualPath, []byte(output), 0644); err != nil {
+		t.Fatalf("Failed to write actual routes: %v", err)
+	}
+
+	// Check if snapshot exists
+	if _, err := os.Stat(snapshotPath); os.IsNotExist(err) {
+		// Create testdata directory if it doesn't exist
+		if err := os.MkdirAll("testdata", 0755); err != nil {
+			t.Fatalf("Failed to create testdata directory: %v", err)
+		}
+		// Initial snapshot creation
+		if err := os.WriteFile(snapshotPath, []byte(output), 0644); err != nil {
+			t.Fatalf("Failed to write snapshot: %v", err)
+		}
+		t.Logf("Initial snapshot created at %s", snapshotPath)
+		return
+	}
+
+	// Read existing snapshot
+	existingOutput, err := os.ReadFile(snapshotPath)
+	if err != nil {
+		t.Fatalf("Failed to read snapshot: %v", err)
+	}
+
+	if string(existingOutput) != output {
+		t.Errorf("Router routes changed! Diff the snapshot at %s with %s", snapshotPath, actualPath)
+	}
+}

cmd/soundtouch-service/testdata/.gitignore

@@ -0,0 +1 @@
+*.actual.txt

cmd/soundtouch-service/testdata/router_routes.txt

@@ -0,0 +1,154 @@
+CONNECT  /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+DELETE   /accounts/{account}/devices/{device}                         handlers.(*Server).HandleMargeRemoveDevice-fm
+DELETE   /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleMargeDeleteGroup-fm
+DELETE   /bmx/tunein/v1/favorite/{stationID}                          handlers.(*Server).HandleTuneInDeleteFavorite-fm
+DELETE   /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+DELETE   /setup/devices/{deviceId}                                    handlers.(*Server).HandleRemoveDevice-fm
+DELETE   /setup/dns-discoveries                                       handlers.(*Server).HandleClearDNSDiscoveries-fm
+DELETE   /setup/interactions/sessions                                 handlers.(*Server).HandleCleanupSessions-fm
+DELETE   /setup/interactions/sessions/{session}                       handlers.(*Server).HandleDeleteSession-fm
+DELETE   /setup/parity-mismatches                                     handlers.(*Server).HandleClearParityMismatches-fm
+DELETE   /streaming/account/{account}/device/{device}/preset/{presetNumber} handlers.(*Server).HandleMargeRemovePreset-fm
+DELETE   /streaming/account/{account}/group/{groupId}                 handlers.(*Server).HandleMargeDeleteGroup-fm
+GET      /                                                            handlers.(*Server).HandleRoot-fm
+GET      /accounts/{account}/devices                                  handlers.(*Server).HandleMargeAccountDevices-fm
+GET      /accounts/{account}/devices/{device}/group                   handlers.(*Server).HandleMargeDeviceGroup-fm
+GET      /accounts/{account}/devices/{device}/group/                  handlers.(*Server).HandleMargeDeviceGroup-fm
+GET      /accounts/{account}/devices/{device}/group/member            handlers.(*Server).HandleMargeDeviceGroupMember-fm
+GET      /accounts/{account}/devices/{device}/group/server            handlers.(*Server).HandleMargeDeviceGroupServer-fm
+GET      /accounts/{account}/devices/{device}/presets                 handlers.(*Server).HandleMargePresets-fm
+GET      /accounts/{account}/devices/{device}/recents                 handlers.(*Server).HandleMargeRecents-fm
+GET      /accounts/{account}/full                                     handlers.(*Server).HandleMargeAccountFull-fm
+GET      /accounts/{account}/sources                                  handlers.(*Server).HandleMargeAccountSources-fm
+GET      /bmx-icons/*                                                 handlers.(*Server).HandleBmxIcons
+GET      /bmx/registry/v1/services                                    handlers.(*Server).HandleBMXRegistry-fm
+GET      /bmx/registry/v1/servicesAvailability                        handlers.(*Server).HandleBMXServicesAvailability-fm
+GET      /bmx/tunein/v1/navigate                                      handlers.(*Server).HandleTuneInNavigate-fm
+GET      /bmx/tunein/v1/navigate/*                                    handlers.(*Server).HandleTuneInNavigate-fm
+GET      /bmx/tunein/v1/playback/episode/{podcastID}                  handlers.(*Server).HandleTuneInPlaybackPodcast-fm
+GET      /bmx/tunein/v1/playback/episodes/{podcastID}                 handlers.(*Server).HandleTuneInPodcastInfo-fm
+GET      /bmx/tunein/v1/playback/station/{stationID}                  handlers.(*Server).HandleTuneInPlayback-fm
+GET      /bmx/tunein/v1/search                                        handlers.(*Server).HandleTuneInSearch-fm
+GET      /ced/*                                                       handlers.(*Server).HandleCedStatic
+GET      /custom/v1/playback/{encodedURL}                             handlers.(*Server).HandleCustomPlayback-fm
+GET      /customer/account/{account}                                  handlers.(*Server).HandleMargeAccountProfile-fm
+GET      /docs/*                                                      handlers.(*Server).HandleDocs-fm
+GET      /favicon.ico                                                 setupRouter
+GET      /health                                                      handlers.(*Server).HandleHealth-fm
+GET      /media/*                                                     handlers.(*Server).HandleMedia
+GET      /mgmt/accounts/                                              handlers.(*Server).HandleMgmtListAccounts-fm
+GET      /mgmt/accounts/{accountId}                                   handlers.(*Server).HandleMgmtAccountDetails-fm
+GET      /mgmt/accounts/{accountId}/speakers                          handlers.(*Server).HandleMgmtListSpeakers-fm
+GET      /mgmt/amazon/accounts                                        handlers.(*Server).HandleMgmtAmazonAccounts-fm
+GET      /mgmt/amazon/callback                                        handlers.(*Server).HandleMgmtAmazonCallback-fm
+GET      /mgmt/amazon/token                                           handlers.(*Server).HandleMgmtAmazonToken-fm
+GET      /mgmt/devices/{deviceId}/events                              handlers.(*Server).HandleMgmtDeviceEvents-fm
+GET      /mgmt/spotify/accounts                                       handlers.(*Server).HandleMgmtSpotifyAccounts-fm
+GET      /mgmt/spotify/callback                                       handlers.(*Server).HandleMgmtSpotifyCallback-fm
+GET      /mgmt/spotify/token                                          handlers.(*Server).HandleMgmtSpotifyToken-fm
+GET      /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+GET      /proxy/*                                                     handlers.(*Server).HandleProxyRequest-fm
+GET      /setup/ca.crt                                                handlers.(*Server).HandleGetCACert-fm
+GET      /setup/devices                                               handlers.(*Server).HandleListDiscoveredDevices-fm
+GET      /setup/devices/{deviceId}/events                             handlers.(*Server).HandleGetDeviceEvents-fm
+GET      /setup/discovery-status                                      handlers.(*Server).HandleGetDiscoveryStatus-fm
+GET      /setup/dns-discoveries                                       handlers.(*Server).HandleGetDNSDiscoveries-fm
+GET      /setup/dns-discoveries/download                              handlers.(*Server).HandleDownloadDNSDiscoveries-fm
+GET      /setup/info/{deviceId}                                       handlers.(*Server).HandleGetDeviceInfo-fm
+GET      /setup/interaction-content                                   handlers.(*Server).HandleGetInteractionContent-fm
+GET      /setup/interaction-stats                                     handlers.(*Server).HandleGetInteractionStats-fm
+GET      /setup/interactions                                          handlers.(*Server).HandleListInteractions-fm
+GET      /setup/interactions/sessions/{session}/download              handlers.(*Server).HandleDownloadSession-fm
+GET      /setup/parity-mismatches                                     handlers.(*Server).HandleListParityMismatches-fm
+GET      /setup/proxy-settings                                        handlers.(*Server).HandleGetProxySettings-fm
+GET      /setup/settings                                              handlers.(*Server).HandleGetSettings-fm
+GET      /setup/summary/{deviceId}                                    handlers.(*Server).HandleGetMigrationSummary-fm
+GET      /setup/version                                               handlers.(*Server).HandleGetVersionInfo-fm
+GET      /streaming/account/{account}/device/{device}/group           handlers.(*Server).HandleMargeDeviceGroup-fm
+GET      /streaming/account/{account}/device/{device}/group/          handlers.(*Server).HandleMargeDeviceGroup-fm
+GET      /streaming/account/{account}/device/{device}/group/member    handlers.(*Server).HandleMargeDeviceGroupMember-fm
+GET      /streaming/account/{account}/device/{device}/group/server    handlers.(*Server).HandleMargeDeviceGroupServer-fm
+GET      /streaming/account/{account}/device/{device}/presets         handlers.(*Server).HandleMargePresets-fm
+GET      /streaming/account/{account}/device/{device}/recent          handlers.(*Server).HandleMargeRecents-fm
+GET      /streaming/account/{account}/device/{device}/recents         handlers.(*Server).HandleMargeRecents-fm
+GET      /streaming/account/{account}/devices                         handlers.(*Server).HandleMargeAccountDevices-fm
+GET      /streaming/account/{account}/emailaddress                    handlers.(*Server).HandleMargeGetEmailAddress-fm
+GET      /streaming/account/{account}/full                            handlers.(*Server).HandleMargeAccountFull-fm
+GET      /streaming/account/{account}/presets                         handlers.(*Server).HandleMargeAccountPresets-fm
+GET      /streaming/account/{account}/presets/all                     handlers.(*Server).HandleMargeAccountPresets-fm
+GET      /streaming/account/{account}/provider_settings               handlers.(*Server).HandleMargeProviderSettings-fm
+GET      /streaming/account/{account}/sources                         handlers.(*Server).HandleMargeAccountSources-fm
+GET      /streaming/device/{device}/streaming_token                   handlers.(*Server).HandleMargeStreamingToken-fm
+GET      /streaming/device_setting/account/{account}/device/{device}/device_settings handlers.(*Server).HandleMargeGetDeviceSettings-fm
+GET      /streaming/resources/api_versions.xml                        handlers.(*Server).HandleMargeAPIVersions-fm
+GET      /streaming/software/update/account/{account}                 handlers.(*Server).HandleMargeSoftwareUpdate-fm
+GET      /streaming/sourceproviders                                   handlers.(*Server).HandleMargeSourceProviders-fm
+GET      /updates/soundtouch                                          handlers.(*Server).HandleMargeSoftwareUpdate-fm
+GET      /v1/blacklist/{deviceId}                                     setupRouter
+GET      /web/*                                                       setupRouter.(*Server).HandleWeb
+HEAD     /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+OPTIONS  /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+PATCH    /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+POST     /accounts/{account}/devices                                  handlers.(*Server).HandleMargeAddDevice-fm
+POST     /accounts/{account}/devices/{device}/presets/{presetNumber}  handlers.(*Server).HandleMargeUpdatePreset-fm
+POST     /accounts/{account}/devices/{device}/recents                 handlers.(*Server).HandleMargeAddRecent-fm
+POST     /accounts/{account}/group                                    handlers.(*Server).HandleMargeAddGroup-fm
+POST     /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleMargeModifyGroup-fm
+POST     /alexa/certificate                                           handlers.(*Server).HandleAlexaCertificate-fm
+POST     /bmx/core02/svc-bmx-adapter-orion/prod/orion/token           handlers.(*Server).HandleOrionToken-fm
+POST     /bmx/orion/v1/playback/station/{data}                        handlers.(*Server).HandleOrionPlayback-fm
+POST     /bmx/tunein/v1/favorite/{stationID}                          handlers.(*Server).HandleTuneInFavorite-fm
+POST     /bmx/tunein/v1/report                                        handlers.(*Server).HandleTuneInReport-fm
+POST     /bmx/tunein/v1/token                                         handlers.(*Server).HandleTuneInToken-fm
+POST     /customer/account/{account}                                  handlers.(*Server).HandleMargeUpdateAccountProfile-fm
+POST     /customer/account/{account}/password                         handlers.(*Server).HandleMargeChangePassword-fm
+POST     /mgmt/accounts/{accountId}/language                          handlers.(*Server).HandleMgmtUpdateAccountLanguage-fm
+POST     /mgmt/accounts/{accountId}/provider-settings                 handlers.(*Server).HandleMgmtUpdateAccountProviderSetting-fm
+POST     /mgmt/amazon/confirm                                         handlers.(*Server).HandleMgmtAmazonConfirm-fm
+POST     /mgmt/amazon/init                                            handlers.(*Server).HandleMgmtAmazonInit-fm
+POST     /mgmt/amazon/prime                                           handlers.(*Server).HandleMgmtPrimeDeviceAmazon-fm
+POST     /mgmt/spotify/confirm                                        handlers.(*Server).HandleMgmtSpotifyConfirm-fm
+POST     /mgmt/spotify/entity                                         handlers.(*Server).HandleMgmtSpotifyEntity-fm
+POST     /mgmt/spotify/init                                           handlers.(*Server).HandleMgmtSpotifyInit-fm
+POST     /mgmt/spotify/prime                                          handlers.(*Server).HandleMgmtPrimeDevice-fm
+POST     /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+POST     /oauth/account/{account}/music/musicprovider/{sourceID}/token/cs handlers.(*Server).HandleBoseAccountToken-fm
+POST     /oauth/device/{deviceID}/music/musicprovider/{sourceID}/token handlers.(*Server).HandleBoseLegacyToken-fm
+POST     /oauth/device/{deviceID}/music/musicprovider/{sourceID}/token/cs1 handlers.(*Server).HandleBoseToken-fm
+POST     /oauth/device/{deviceID}/music/musicprovider/{sourceID}/token/cs3 handlers.(*Server).HandleBoseToken-fm
+POST     /setup/backup/{deviceId}                                     handlers.(*Server).HandleBackupConfig-fm
+POST     /setup/devices                                               handlers.(*Server).HandleAddManualDevice-fm
+POST     /setup/discover                                              handlers.(*Server).HandleTriggerDiscovery-fm
+POST     /setup/ensure-remote-services/{deviceId}                     handlers.(*Server).HandleEnsureRemoteServices-fm
+POST     /setup/migrate/{deviceId}                                    handlers.(*Server).HandleMigrateDevice-fm
+POST     /setup/proxy-settings                                        handlers.(*Server).HandleUpdateProxySettings-fm
+POST     /setup/reboot/{deviceId}                                     handlers.(*Server).HandleRebootDevice-fm
+POST     /setup/remove-remote-services/{deviceId}                     handlers.(*Server).HandleRemoveRemoteServices-fm
+POST     /setup/revert/{deviceId}                                     handlers.(*Server).HandleRevertMigration-fm
+POST     /setup/settings                                              handlers.(*Server).HandleUpdateSettings-fm
+POST     /setup/sync/{deviceId}                                       handlers.(*Server).HandleInitialSync-fm
+POST     /setup/test-connection/{deviceId}                            handlers.(*Server).HandleTestConnection-fm
+POST     /setup/test-dns/{deviceId}                                   handlers.(*Server).HandleTestDNSRedirection-fm
+POST     /setup/test-hosts/{deviceId}                                 handlers.(*Server).HandleTestHostsRedirection-fm
+POST     /setup/trust-ca/{deviceId}                                   handlers.(*Server).HandleTrustCACert-fm
+POST     /streaming/account                                           handlers.(*Server).HandleMargeCreateAccount-fm
+POST     /streaming/account/login                                     handlers.(*Server).HandleMargeLogin-fm
+POST     /streaming/account/{account}/device/                         handlers.(*Server).HandleMargeAddDevice-fm
+POST     /streaming/account/{account}/device/{device}                 handlers.(*Server).HandleMargeAddDevice-fm
+POST     /streaming/account/{account}/device/{device}/presets/{presetNumber} handlers.(*Server).HandleMargeUpdatePreset-fm
+POST     /streaming/account/{account}/device/{device}/recent          handlers.(*Server).HandleMargeAddRecent-fm
+POST     /streaming/account/{account}/group                           handlers.(*Server).HandleMargeAddGroup-fm
+POST     /streaming/account/{account}/group/{groupId}                 handlers.(*Server).HandleMargeModifyGroup-fm
+POST     /streaming/account/{account}/source                          handlers.(*Server).HandleMargeAddSource-fm
+POST     /streaming/device_setting/account/{account}/device/{device}/device_settings handlers.(*Server).HandleMargeUpdateDeviceSettings-fm
+POST     /streaming/music/musicprovider/{providerID}/is_eligible      handlers.(*Server).HandleMusicProviderIsEligible-fm
+POST     /streaming/music/musicprovider/{providerID}/trial/is_eligible handlers.(*Server).HandleMusicProviderIsEligible-fm
+POST     /streaming/stats/error                                       handlers.(*Server).HandleErrorStats-fm
+POST     /streaming/stats/usage                                       handlers.(*Server).HandleUsageStats-fm
+POST     /streaming/support/customersupport                           handlers.(*Server).HandleMargeCustomerSupport-fm
+POST     /streaming/support/power_on                                  handlers.(*Server).HandleMargePowerOn-fm
+POST     /v1/scmudc/{deviceId}                                        handlers.(*Server).HandleAppEvents-fm
+POST     /v1/stapp/{deviceId}                                         handlers.(*Server).HandleAppEvents-fm
+PUT      /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+PUT      /streaming/account/{account}/device/{device}/preset/{presetNumber} handlers.(*Server).HandleMargeUpdatePreset-fm
+TRACE    /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm

cmd/soundtouch-web/.gitignore

@@ -0,0 +1,2 @@
+soundtouch-web
+soundtouch-web-test

cmd/soundtouch-web/IMPLEMENTATION.md

@@ -0,0 +1,276 @@
+# SoundTouch Web Implementation
+
+## Overview
+
+The `soundtouch-web` tool provides a modern single-page application (SPA) for controlling Bose SoundTouch devices. Built with a JSON API backend and client-side JavaScript rendering, it offers superior performance and eliminates template rendering issues.
+
+## Architecture
+
+### Single-Page Application Design
+
+The architecture eliminates Go template dependencies and provides:
+- **JSON API Backend**: Pure Go server returning only JSON responses
+- **Client-Side Rendering**: JavaScript handles all HTML generation
+- **WebSocket Real-time**: Bi-directional communication for live updates
+- **Better Performance**: No server-side template processing
+- **Easier Development**: Clear separation of frontend/backend concerns
+
+### Core Components
+
+#### 1. Main Application (`main.go`)
+- **Entry Point**: Handles command-line arguments and application initialization
+- **SPA Routing**: Serves static HTML file for all non-API routes
+- **Device Discovery**: Automatic discovery of SoundTouch devices using unified discovery service
+- **JSON API Server**: Configures API routes and serves the SPA
+- **Context Management**: Proper context handling for timeouts and cancellation
+
+#### 2. HTTP Handlers (`handlers/handlers.go`)
+- **WebApp Structure**: Central application state management
+- **JSON API Endpoints**: RESTful API returning only JSON responses
+- **Device Control**: Device control with proper validation and error handling
+- **Modular Design**: Separated control actions into focused functions
+
+#### 3. WebSocket Support (`handlers/websocket.go`)
+- **Real-time Updates**: Live device status streaming to web clients
+- **Device WebSocket Connections**: Maintains persistent connections to SoundTouch devices
+- **Event Handling**: Processes nowPlaying, volume, and connection state updates
+- **Status Synchronization**: Keeps device status current across all connected clients
+
+#### 4. Type Definitions (`webtypes/types.go`)
+- **Device Management**: Structures for device connections and status
+- **API Responses**: Standardized JSON response format
+- **WebSocket Messages**: Real-time message types
+- **Template Data**: HTML template data structures
+
+### Key Features Implemented
+
+#### Device Discovery & Management
+- **Auto-discovery**: Finds SoundTouch devices on local network using mDNS/UPnP
+- **Multi-device Support**: Manages multiple devices simultaneously
+- **Connection Tracking**: Monitors device availability and connection status
+- **Device Information**: Displays device details (name, type, IP address)
+
+#### Real-time Control Interface
+- **Now Playing**: Live track information with artwork display
+- **Playback Controls**: Play/pause/stop/next/previous with visual feedback
+- **Volume Control**: Real-time volume slider with mute functionality
+- **Bass Adjustment**: Bass level control for supported devices
+- **Preset Management**: Quick access to saved presets (1-6)
+- **Source Selection**: Input switching (Spotify, TuneIn, Bluetooth, AUX, etc.)
+
+#### Web Interface
+- **Single-Page Application**: Self-contained HTML file with embedded CSS and JavaScript
+- **Responsive Design**: Bootstrap 5-based UI optimized for desktop and mobile
+- **Client-Side Routing**: JavaScript handles page navigation without page reloads
+- **Dynamic Rendering**: All HTML generated client-side from JSON data
+- **Real-time Updates**: WebSocket-powered live status updates
+- **Performance Optimized**: Fast loading and no template rendering delays
+
+#### API Endpoints
+```
+GET  /                          # SPA - serves static/index.html
+GET  /api/devices              # List all devices (JSON)
+GET  /api/device/{id}          # Get device info (JSON)
+POST /api/discover             # Trigger device discovery
+GET  /api/control/{id}/play    # Playback control
+GET  /api/control/{id}/pause   # Pause playback
+GET  /api/control/{id}/stop    # Stop playback
+GET  /api/control/{id}/next    # Next track
+GET  /api/control/{id}/previous # Previous track
+POST /api/control/{id}/volume  # Set volume (JSON body)
+GET  /api/control/{id}/mute    # Toggle mute
+POST /api/control/{id}/bass    # Set bass level (JSON body)
+GET  /api/control/{id}/preset?id=N # Select preset
+GET  /api/control/{id}/source?name=X # Select source
+```
+
+#### WebSocket Events
+- **Connection**: `ws://localhost:8080/ws`
+- **Device Updates**: Real-time device list changes
+- **Status Updates**: Live playback and volume changes
+- **Connection Monitoring**: Device availability status
+
+## Technical Implementation
+
+### Frontend Architecture
+- **Single HTML File**: Complete application in `static/index.html`
+- **Embedded CSS**: Bootstrap 5 with custom Bose-inspired styling
+- **Vanilla JavaScript**: No framework dependencies, fast performance
+- **Client-Side Routing**: JavaScript manages page state without reloads
+- **Dynamic Components**: HTML elements generated from JSON API responses
+
+### Error Handling & Validation
+- **Input Validation**: Proper bounds checking for volume (0-100) and bass (-9 to 9)
+- **HTTP Status Codes**: Appropriate response codes for different error conditions
+- **JSON Error Responses**: Structured error messages for API consumers
+- **Client-Side Error Display**: JavaScript toast notifications for user feedback
+
+### Code Quality
+- **golangci-lint Compliance**: Passes all configured lint checks
+- **Context Handling**: Proper context propagation and timeout management
+- **Error Checking**: All JSON encoding/decoding operations checked
+- **Type Safety**: Strong typing with dedicated type package
+- **Test Coverage**: Comprehensive unit tests for handlers and types
+
+### WebSocket Integration
+- **Gabbo Protocol**: Native SoundTouch WebSocket protocol implementation
+- **Event Processing**: Handles all documented SoundTouch WebSocket events
+- **Connection Management**: Automatic reconnection and health monitoring
+- **Bi-directional Communication**: Both status monitoring and device control
+
+## Dependencies
+
+### Core Libraries
+- **chi v5**: HTTP router (inherited from existing codebase)
+- **gorilla/websocket**: WebSocket implementation
+- **Go standard library**: html/template, net/http, encoding/json
+
+### Project Dependencies
+- **pkg/client**: SoundTouch HTTP and WebSocket client library
+- **pkg/discovery**: Device discovery service (mDNS/UPnP)
+- **pkg/models**: XML/JSON data structures for SoundTouch API
+- **pkg/config**: Configuration management
+
+### Frontend Dependencies
+- **Bootstrap 5**: CSS framework for responsive design
+- **Bootstrap Icons**: Icon library for UI elements
+- **Vanilla JavaScript**: No external JS frameworks, pure WebSocket implementation
+
+## Build & Testing
+
+### Build Commands
+```bash
+# Build the web application
+cd cmd/soundtouch-web
+go build -o soundtouch-web
+
+# Build all project components (includes soundtouch-web)
+make build
+
+# Cross-platform builds
+make build-all
+```
+
+### Testing
+```bash
+# Run unit tests
+go test ./cmd/soundtouch-web/...
+
+# Run with coverage
+go test -cover ./cmd/soundtouch-web/...
+
+# Lint checking
+golangci-lint run cmd/soundtouch-web/...
+```
+
+### Development Server
+```bash
+# Run development server
+cd cmd/soundtouch-web
+go run main.go -port 8080
+
+# Access the web interface
+open http://localhost:8080
+```
+
+## Configuration
+
+### Command Line Options
+```bash
+soundtouch-web [options]
+
+Options:
+  -port string    Web server port (default "8080")
+  -host string    Specific device host for single-device mode (optional)
+```
+
+### File Structure
+```
+cmd/soundtouch-web/
+├── main.go                    # Application entry point
+├── soundtouch-web            # Built binary
+├── handlers/
+│   ├── handlers.go           # HTTP request handlers
+│   ├── handlers_test.go      # Handler tests
+│   └── websocket.go          # WebSocket functionality
+├── webtypes/
+│   ├── types.go              # Type definitions
+│   └── types_test.go         # Type tests
+├── templates/
+│   ├── layout.html           # Base HTML layout
+│   ├── index.html            # Device list page
+│   └── device.html           # Device control page
+├── static/
+│   └── style.css             # Additional CSS styles
+└── README.md                 # User documentation
+```
+
+## Browser Compatibility
+
+### Supported Browsers
+- **Chrome 80+** (recommended)
+- **Firefox 75+**
+- **Safari 13+**
+- **Edge 80+**
+
+### Required Features
+- WebSocket support
+- CSS Grid and Flexbox
+- ES6 JavaScript features
+- JSON API support
+
+## Security Considerations
+
+### Design Principles
+- **Local Network Only**: Designed for trusted local network environments
+- **No Authentication**: Assumes local network security
+- **CORS Policy**: Restricted to same-origin requests
+- **Input Validation**: All user inputs validated on server side
+
+### Network Security
+- **Port Usage**: Uses standard HTTP port (configurable)
+- **WebSocket Security**: Same-origin WebSocket connections only
+- **No External Dependencies**: All resources served locally
+
+## Performance Characteristics
+
+### Resource Usage
+- **Memory**: Minimal footprint, scales with number of discovered devices
+- **CPU**: Low usage, event-driven architecture
+- **Network**: Efficient WebSocket connections, HTTP REST for control
+
+### Scalability
+- **Device Limits**: Designed for typical home networks (5-20 devices)
+- **Concurrent Users**: Multiple browser sessions supported
+- **Update Frequency**: Real-time updates without polling
+
+## Future Enhancements
+
+### Potential Features
+- **Zone Management**: Multi-room audio control
+- **Preset Programming**: Advanced preset configuration
+- **Mobile PWA**: Progressive Web App for mobile installation
+- **Theme Support**: Additional UI themes
+- **Device Grouping**: Logical device organization
+
+### Technical Improvements
+- **Caching**: Enhanced device status caching
+- **Compression**: WebSocket message compression
+- **Persistence**: Device settings persistence
+- **Metrics**: Usage analytics and performance monitoring
+
+## Integration with Main Project
+
+### Project Alignment
+- **Consistent Architecture**: Follows established project patterns
+- **Shared Libraries**: Leverages existing pkg/ modules
+- **Build Integration**: Included in main Makefile targets
+- **Documentation**: Consistent with project documentation standards
+
+### Migration Path
+- **Cloud Replacement**: Serves as local alternative to Bose cloud services
+- **API Compatibility**: Maintains compatibility with existing SoundTouch APIs
+- **User Experience**: Familiar interface for existing SoundTouch app users
+- **Long-term Support**: Designed for continued operation post-2026
+
+This implementation provides a robust, feature-complete web interface for SoundTouch device control, ensuring continued functionality beyond the official app's lifecycle while maintaining high code quality and user experience standards.

cmd/soundtouch-web/README.md

@@ -0,0 +1,330 @@
+# SoundTouch Web UI
+
+A modern single-page web application (SPA) for controlling Bose SoundTouch devices. Built with a JSON API backend and client-side JavaScript rendering for superior performance and maintainability.
+
+## Architecture
+
+```
+Browser → Static HTML → JavaScript → JSON API → Go Server
+                     ↓
+               Client-Side Rendering
+```
+
+### Key Benefits
+- **Better Performance**: No server-side template processing overhead
+- **Improved Maintainability**: Clear separation between frontend (JavaScript) and backend (Go)
+- **Real-time Experience**: Smooth client-side updates without page reloads
+- **Mobile Ready**: The JSON API can power both this web interface and mobile applications
+
+## Features
+
+Based on captured WebSocket interactions and device API capabilities, this web UI provides:
+
+### Device Management
+- **Auto-discovery** of SoundTouch devices on the network
+- **Real-time status monitoring** via WebSocket connections
+- **Multi-device support** with centralized control
+- **Connection status** indicators and health monitoring
+
+### Playback Control
+- **Play/Pause/Stop/Next/Previous** controls
+- **Now playing information** with artwork, track details, and progress
+- **Real-time updates** of playback state changes
+- **Source selection** from available inputs (Spotify, TuneIn, Bluetooth, AUX, etc.)
+
+### Audio Controls
+- **Volume control** with real-time slider updates
+- **Mute/Unmute** functionality
+- **Bass adjustment** (on supported models)
+- **Audio level monitoring** and statistics
+
+### Preset Management
+- **6 preset buttons** with visual feedback
+- **Preset content display** showing station/playlist names
+- **One-click preset selection**
+
+### Advanced Features
+- **WebSocket real-time updates** for instant state synchronization
+- **Responsive design** optimized for desktop and mobile
+- **Dark mode support** (auto-detects system preference)
+- **Accessibility features** (keyboard navigation, screen reader support)
+- **Network statistics** and device health monitoring
+
+## Screenshots
+
+### Main Device Overview
+The main page shows all discovered devices with their current status, now-playing information, and quick controls.
+
+### Detailed Device Control
+Individual device pages provide full control over:
+- Detailed now-playing information with artwork
+- Comprehensive audio controls (volume, bass)
+- Full preset and source selection
+- Real-time status updates
+
+## Installation
+
+### Prerequisites
+- Go 1.21 or later
+- Access to SoundTouch devices on the same network
+- Modern web browser with WebSocket support
+
+### Building
+```bash
+# From project root
+make build
+
+# Or manually
+cd cmd/soundtouch-web
+go build -o soundtouch-web
+```
+
+### Running
+```bash
+# Run with default settings (port 8080)
+./soundtouch-web
+
+# Specify custom port
+./soundtouch-web -port 8888
+
+# Connect to specific device
+./soundtouch-web -host 192.168.1.100
+```
+
+### Command Line Options
+```
+-port string    Web server port (default "8080")
+-host string    Specific SoundTouch device host (optional, enables single-device mode)
+-help          Show help information
+```
+
+## Usage
+
+### Accessing the Interface
+1. Start the application
+2. Open your web browser and navigate to `http://localhost:8080`
+3. Click "Discover Devices" to find SoundTouch devices on your network
+4. Click on any device for detailed control, or use quick controls from the main page
+
+### Device Discovery
+The application automatically discovers SoundTouch devices using:
+- **mDNS discovery** for local network devices
+- **UPnP/SSDP discovery** as fallback
+- **Manual device addition** via IP address
+
+### Real-time Updates
+The interface maintains WebSocket connections to each device for instant updates of:
+- Now playing information and artwork
+- Volume and audio settings changes
+- Playback status (play/pause/stop)
+- Connection status and device health
+
+### Responsive Design
+- **Desktop**: Full-featured interface with side-by-side panels
+- **Tablet**: Optimized layout with touch-friendly controls
+- **Mobile**: Stacked interface with gesture support
+
+## API Endpoints
+
+The web UI exposes a REST API for programmatic control:
+
+### Device Management
+```
+GET  /api/devices           # List all discovered devices
+GET  /api/device/{id}       # Get specific device info
+POST /api/discover          # Trigger device discovery
+```
+
+### Device Control
+```
+GET  /api/control/{id}/play        # Start playback
+GET  /api/control/{id}/pause       # Pause playback
+GET  /api/control/{id}/stop        # Stop playback
+GET  /api/control/{id}/next        # Next track
+GET  /api/control/{id}/previous    # Previous track
+POST /api/control/{id}/volume      # Set volume (body: {"level": 50})
+GET  /api/control/{id}/mute        # Mute audio
+GET  /api/control/{id}/unmute      # Unmute audio
+POST /api/control/{id}/bass        # Set bass (body: {"level": 0})
+GET  /api/control/{id}/preset?id=1 # Select preset
+GET  /api/control/{id}/source?name=SPOTIFY # Select source
+```
+
+### WebSocket Events
+Connect to `/ws` for real-time updates:
+```javascript
+const ws = new WebSocket('ws://localhost:8080/ws');
+ws.onmessage = function(event) {
+    const data = JSON.parse(event.data);
+    // Handle device updates, status changes, etc.
+};
+```
+
+## Architecture
+
+### Single-Page Application Architecture
+- **JSON API Backend**: Go server providing RESTful endpoints
+- **Client-Side Rendering**: JavaScript handles all UI rendering
+- **WebSocket Real-time**: Bi-directional real-time communication
+- **No Template Dependencies**: Eliminates server-side template issues
+
+### Backend Components
+- **Discovery Service**: Finds and manages SoundTouch devices
+- **WebSocket Manager**: Maintains real-time connections to devices
+- **JSON API Server**: RESTful interface returning only JSON
+- **Device Manager**: Tracks device state and health
+
+### Frontend Components
+- **Bootstrap 5**: Modern responsive UI framework
+- **Vanilla JavaScript**: No framework dependencies, fast loading
+- **WebSocket Client**: Real-time bidirectional communication
+- **Dynamic Rendering**: Client-side HTML generation from JSON
+
+### Communication Flow
+1. **SPA Loading**: Single HTML file with embedded CSS and JavaScript
+2. **JSON API**: Device discovery and control via REST endpoints
+3. **WebSocket (Device)**: Real-time status updates from SoundTouch devices
+4. **WebSocket (Browser)**: Real-time UI updates to web clients
+5. **Client Rendering**: JavaScript dynamically creates all UI elements
+
+## Development
+
+### Project Structure
+```
+cmd/soundtouch-web/
+├── main.go              # Application entry point and SPA routing
+├── handlers/            # HTTP and WebSocket handlers
+│   ├── handlers.go     # JSON API endpoints
+│   └── websocket.go    # WebSocket management
+├── webtypes/           # Type definitions
+│   └── types.go        # Request/response types
+├── static/             # Static assets
+│   ├── index.html      # Single-page application
+│   └── js/             # Legacy JS files (reference)
+├── templates/          # Legacy templates (unused in SPA)
+└── README.md          # This file
+```
+
+### Adding New Features
+1. **API Endpoints**: Add new JSON routes in `setupRoutes()` and `handlers.go`
+2. **WebSocket Events**: Extend event handlers in WebSocket client
+3. **UI Components**: Add JavaScript rendering functions in `static/index.html`
+4. **Device Controls**: Implement new control commands and update client-side handlers
+
+### Testing
+```bash
+# Unit tests
+go test ./...
+
+# Manual testing with multiple devices
+./soundtouch-web -port 8080
+
+# API testing
+curl http://localhost:8080/api/devices
+```
+
+## WebSocket Protocol Analysis
+
+This UI is based on extensive analysis of captured SoundTouch WebSocket interactions, including:
+
+### Message Types Implemented
+- **SoundTouchSdkInfo**: Initial handshake and version info
+- **nowPlayingUpdated**: Real-time track information
+- **volumeUpdated**: Audio level changes
+- **recentsUpdated**: Recently played items
+- **userActivityUpdate**: User interaction notifications
+
+### Request/Response Patterns
+- **Device Information**: System details and capabilities
+- **Audio Controls**: Volume, bass, mute controls
+- **Playback Control**: Play/pause/stop/skip commands
+- **Source Selection**: Input switching (Spotify, TuneIn, etc.)
+- **Preset Management**: Saved station/playlist access
+
+### Gabbo Protocol Features
+- **Persistent Connections**: Maintains long-lived WebSocket connections
+- **Request Correlation**: Uses request IDs for response matching
+- **Real-time Events**: Instant updates for all device state changes
+- **Bi-directional Control**: Both status monitoring and device control
+
+## Browser Compatibility
+
+### Supported Browsers
+- **Chrome 80+** (recommended)
+- **Firefox 75+**
+- **Safari 13+**
+- **Edge 80+**
+
+### Required Features
+- WebSocket support
+- CSS Grid and Flexbox
+- ES6 JavaScript features
+- Responsive CSS media queries
+
+## Security Considerations
+
+- **Local Network Only**: Designed for local network device control
+- **No Authentication**: Assumes trusted local network environment
+- **CORS Policy**: Restricted to same-origin requests
+- **WebSocket Security**: Uses same-origin WebSocket connections
+
+## Troubleshooting
+
+### Common Issues
+
+**Devices Not Found**
+- Ensure devices are on the same network
+- Check firewall settings (ports 8090, 8080)
+- Click "Discover Devices" button to trigger discovery
+
+**WebSocket Connection Failed**
+- Verify device supports WebSocket connections
+- Check browser console for connection errors
+- Refresh the page to reconnect WebSocket
+
+**Control Commands Not Working**
+- Check device is powered on and connected
+- Verify device is not in exclusive mode (e.g., Spotify Connect active)
+- Look for error notifications in the UI
+
+**Page Shows Template Errors**
+- This has been fixed in the SPA implementation
+- Ensure you're accessing the correct URL (localhost:8080)
+- Clear browser cache if you see old template-based content
+
+### Debug Mode
+Add verbose logging by setting environment variable:
+```bash
+export DEBUG=true
+./soundtouch-web
+```
+
+## Contributing
+
+This web UI is part of the larger SoundTouch Go library project. See the main project README for contribution guidelines.
+
+### Architecture Benefits
+The new SPA approach provides:
+- **Better Performance**: No server-side template rendering
+- **Easier Development**: Clear separation of frontend/backend
+- **Mobile Ready**: Same JSON API can power mobile apps
+- **Scalable**: Single-page app architecture
+
+### Feature Requests
+Based on WebSocket interaction analysis, potential future features:
+- Zone/multi-room management
+- Clock display control
+- Software update management
+- Advanced preset programming
+- Progressive Web App (PWA) features
+
+## License
+
+Same as the parent project - see main repository LICENSE file.
+
+## Acknowledgments
+
+- Built on the comprehensive SoundTouch Go library
+- UI design inspired by modern audio control interfaces
+- WebSocket protocol reverse-engineered from captured device interactions
+- Bootstrap and Bootstrap Icons for responsive design components

cmd/soundtouch-web/main.go

@@ -0,0 +1,55 @@
+// Package main provides a web UI for controlling Bose SoundTouch devices.
+package main
+
+import (
+	"log"
+	"net/http"
+	"os"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb"
+	"github.com/go-chi/chi/v5"
+	"github.com/urfave/cli/v2"
+)
+
+func main() {
+	app := &cli.App{
+		Name:  "soundtouch-web",
+		Usage: "Web UI for controlling Bose SoundTouch devices",
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:    "port",
+				Aliases: []string{"p"},
+				Usage:   "HTTP port to listen on",
+				Value:   "8080",
+				EnvVars: []string{"PORT"},
+			},
+			&cli.StringFlag{
+				Name:    "bind",
+				Usage:   "Network interface to bind to",
+				EnvVars: []string{"BIND_ADDR"},
+			},
+		},
+		Action: func(c *cli.Context) error {
+			port := c.String("port")
+			bindAddr := c.String("bind")
+
+			addr := ":" + port
+			if bindAddr != "" {
+				addr = bindAddr + ":" + port
+			}
+
+			webApp := soundtouchweb.New()
+
+			r := chi.NewRouter()
+			webApp.Mount(r)
+
+			log.Printf("SoundTouch Web UI starting on http://%s", addr)
+
+			return http.ListenAndServe(addr, r)
+		},
+	}
+
+	if err := app.Run(os.Args); err != nil {
+		log.Fatal(err)
+	}
+}

cmd/soundtouch-web/spa_test.go

@@ -0,0 +1,351 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb"
+	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb/webtypes"
+	"github.com/go-chi/chi/v5"
+)
+
+func withChiParams(r *http.Request, params map[string]string) *http.Request {
+	rctx := chi.NewRouteContext()
+	for k, v := range params {
+		rctx.URLParams.Add(k, v)
+	}
+	return r.WithContext(context.WithValue(r.Context(), chi.RouteCtxKey, rctx))
+}
+
+func TestSPARouting(t *testing.T) {
+	tests := []struct {
+		name           string
+		path           string
+		expectedStatus int
+		expectedHTML   bool
+	}{
+		{
+			name:           "root path serves HTML",
+			path:           "/",
+			expectedStatus: http.StatusOK,
+			expectedHTML:   true,
+		},
+		{
+			name:           "device path serves HTML",
+			path:           "/device/test-device",
+			expectedStatus: http.StatusOK,
+			expectedHTML:   true,
+		},
+		{
+			name:           "arbitrary path serves HTML",
+			path:           "/some/random/path",
+			expectedStatus: http.StatusOK,
+			expectedHTML:   true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest("GET", tt.path, nil)
+			w := httptest.NewRecorder()
+
+			spaHandler := func(w http.ResponseWriter, r *http.Request) {
+				if strings.HasPrefix(r.URL.Path, "/api/") || strings.HasPrefix(r.URL.Path, "/static/") || strings.HasPrefix(r.URL.Path, "/ws") {
+					http.NotFound(w, r)
+					return
+				}
+
+				w.Header().Set("Content-Type", "text/html")
+				w.WriteHeader(http.StatusOK)
+				w.Write([]byte(`<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <title>SoundTouch Web</title>
+</head>
+<body>
+    <div id="app">SPA Content</div>
+</body>
+</html>`))
+			}
+
+			spaHandler(w, req)
+
+			if w.Code != tt.expectedStatus {
+				t.Errorf("Expected status %d, got %d", tt.expectedStatus, w.Code)
+			}
+
+			if tt.expectedHTML {
+				contentType := w.Header().Get("Content-Type")
+				if !strings.Contains(contentType, "text/html") {
+					t.Errorf("Expected HTML content type, got %s", contentType)
+				}
+
+				body := w.Body.String()
+				if !strings.Contains(body, "<!doctype html>") {
+					t.Errorf("Expected HTML content, got: %s", body)
+				}
+			}
+		})
+	}
+}
+
+func TestAPIEndpoints(t *testing.T) {
+	app := soundtouchweb.NewWebApp()
+
+	tests := []struct {
+		name           string
+		path           string
+		method         string
+		expectedStatus int
+		expectedJSON   bool
+	}{
+		{
+			name:           "devices API returns JSON",
+			path:           "/api/devices",
+			method:         "GET",
+			expectedStatus: http.StatusOK,
+			expectedJSON:   true,
+		},
+		{
+			name:           "discover API accepts POST",
+			path:           "/api/discover",
+			method:         "POST",
+			expectedStatus: http.StatusOK,
+			expectedJSON:   true,
+		},
+		{
+			name:           "device API with ID",
+			path:           "/api/device/test-device",
+			method:         "GET",
+			expectedStatus: http.StatusNotFound,
+			expectedJSON:   true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest(tt.method, tt.path, nil)
+			w := httptest.NewRecorder()
+
+			switch tt.path {
+			case "/api/devices":
+				app.HandleAPIDevices(w, req)
+			case "/api/discover":
+				app.HandleAPIDiscover(w, req)
+			default:
+				if strings.HasPrefix(tt.path, "/api/device/") {
+					deviceID := strings.TrimPrefix(tt.path, "/api/device/")
+					req = withChiParams(req, map[string]string{"id": deviceID})
+					app.HandleAPIDevice(w, req)
+				}
+			}
+
+			if w.Code != tt.expectedStatus {
+				t.Errorf("Expected status %d, got %d", tt.expectedStatus, w.Code)
+			}
+
+			if tt.expectedJSON {
+				contentType := w.Header().Get("Content-Type")
+				if !strings.Contains(contentType, "application/json") {
+					t.Errorf("Expected JSON content type, got %s", contentType)
+				}
+
+				var response webtypes.APIResponse
+				if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+					t.Errorf("Invalid JSON response: %v", err)
+				}
+			}
+		})
+	}
+}
+
+func TestAPIResponseFormat(t *testing.T) {
+	app := soundtouchweb.NewWebApp()
+
+	req := httptest.NewRequest("GET", "/api/devices", nil)
+	w := httptest.NewRecorder()
+
+	app.HandleAPIDevices(w, req)
+
+	var response webtypes.APIResponse
+	if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+		t.Fatalf("Failed to decode JSON response: %v", err)
+	}
+
+	if !response.Success {
+		t.Errorf("Expected success=true, got success=%v", response.Success)
+	}
+
+	if response.Data == nil {
+		t.Errorf("Expected data field to be present")
+	}
+
+	dataMap, ok := response.Data.(map[string]interface{})
+	if !ok {
+		t.Errorf("Expected data to be a map, got %T", response.Data)
+	}
+
+	if len(dataMap) != 0 {
+		t.Errorf("Expected empty device map, got %d devices", len(dataMap))
+	}
+}
+
+func TestControlAPIValidation(t *testing.T) {
+	app := soundtouchweb.NewWebApp()
+
+	tests := []struct {
+		name           string
+		path           string
+		method         string
+		body           string
+		expectedStatus int
+		chiParams      map[string]string
+	}{
+		{
+			name:           "missing device ID",
+			path:           "/api/control//play",
+			method:         "GET",
+			expectedStatus: http.StatusBadRequest,
+		},
+		{
+			name:           "invalid control path",
+			path:           "/api/control/device",
+			method:         "GET",
+			expectedStatus: http.StatusBadRequest,
+		},
+		{
+			name:           "unknown action",
+			path:           "/api/control/nonexistent/invalid",
+			method:         "GET",
+			expectedStatus: http.StatusNotFound,
+			chiParams:      map[string]string{"id": "nonexistent", "action": "invalid"},
+		},
+		{
+			name:           "nonexistent device",
+			path:           "/api/control/nonexistent/play",
+			method:         "GET",
+			expectedStatus: http.StatusNotFound,
+			chiParams:      map[string]string{"id": "nonexistent", "action": "play"},
+		},
+		{
+			name:           "unknown action with valid device",
+			path:           "/api/control/testdevice/unknownaction",
+			method:         "GET",
+			expectedStatus: http.StatusBadRequest,
+			chiParams:      map[string]string{"id": "testdevice", "action": "unknownaction"},
+		},
+	}
+
+	mockDevice := &webtypes.DeviceConnection{
+		Client:     nil,
+		DeviceInfo: &models.DeviceInfo{Name: "Test Device"},
+		LastSeen:   time.Now(),
+		Status:     webtypes.DeviceStatus{IsConnected: true},
+	}
+	app.Devices["testdevice"] = mockDevice
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var req *http.Request
+			if tt.body != "" {
+				req = httptest.NewRequest(tt.method, tt.path, strings.NewReader(tt.body))
+				req.Header.Set("Content-Type", "application/json")
+			} else {
+				req = httptest.NewRequest(tt.method, tt.path, nil)
+			}
+			if tt.chiParams != nil {
+				req = withChiParams(req, tt.chiParams)
+			}
+
+			w := httptest.NewRecorder()
+			app.HandleAPIControl(w, req)
+
+			if w.Code != tt.expectedStatus {
+				t.Errorf("Test %s: Expected status %d, got %d. Response: %s", tt.name, tt.expectedStatus, w.Code, w.Body.String())
+			}
+
+			contentType := w.Header().Get("Content-Type")
+			if !strings.Contains(contentType, "application/json") {
+				t.Errorf("Expected JSON content type, got %s", contentType)
+			}
+
+			var response webtypes.APIResponse
+			if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+				t.Errorf("Invalid JSON response: %v", err)
+			}
+
+			if response.Success {
+				t.Errorf("Expected success=false for error case, got success=true")
+			}
+
+			if response.Error == "" {
+				t.Errorf("Expected error message, got empty string")
+			}
+		})
+	}
+}
+
+func TestWebSocketUpgrade(t *testing.T) {
+	app := soundtouchweb.NewWebApp()
+
+	req := httptest.NewRequest("GET", "/ws", nil)
+	req.Header.Set("Connection", "upgrade")
+	req.Header.Set("Upgrade", "websocket")
+	req.Header.Set("Sec-WebSocket-Key", "dGhlIHNhbXBsZSBub25jZQ==")
+	req.Header.Set("Sec-WebSocket-Version", "13")
+
+	w := httptest.NewRecorder()
+
+	app.HandleWebSocket(w, req)
+}
+
+func TestJSONAPIConsistency(t *testing.T) {
+	app := soundtouchweb.NewWebApp()
+
+	endpoints := []string{
+		"/api/devices",
+		"/api/device/test",
+	}
+
+	for _, endpoint := range endpoints {
+		t.Run("JSON consistency for "+endpoint, func(t *testing.T) {
+			req := httptest.NewRequest("GET", endpoint, nil)
+			w := httptest.NewRecorder()
+
+			switch endpoint {
+			case "/api/devices":
+				app.HandleAPIDevices(w, req)
+			default:
+				if strings.HasPrefix(endpoint, "/api/device/") {
+					deviceID := strings.TrimPrefix(endpoint, "/api/device/")
+					req = withChiParams(req, map[string]string{"id": deviceID})
+					app.HandleAPIDevice(w, req)
+				}
+			}
+
+			contentType := w.Header().Get("Content-Type")
+			if !strings.Contains(contentType, "application/json") {
+				t.Errorf("Endpoint %s should return JSON, got %s", endpoint, contentType)
+			}
+
+			var response webtypes.APIResponse
+			if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+				t.Errorf("Endpoint %s returned invalid JSON: %v", endpoint, err)
+			}
+
+			if response.Success && response.Data == nil {
+				t.Errorf("Endpoint %s: success response should have data", endpoint)
+			}
+			if !response.Success && response.Error == "" {
+				t.Errorf("Endpoint %s: error response should have error message", endpoint)
+			}
+		})
+	}
+}

data/.gitignore

@@ -0,0 +1,9 @@
+accounts/
+backend/
+certs/
+default/
+dns/
+interactions/
+parity_mismatches/
+patterns.json
+settings.json

doc.go

@@ -1,8 +1,11 @@
-// Package soundtouch provides a comprehensive Go library and CLI tool for controlling Bose SoundTouch devices.
+// Package soundtouch provides a comprehensive Go library, CLI tool, and local service for controlling and emulating Bose SoundTouch devices.
 //
-// This library implements the complete Bose SoundTouch Web API, enabling programmatic control
+// This project implements the complete Bose SoundTouch Web API, enabling programmatic control
 // of SoundTouch speakers including playback control, volume management, source selection,
-// multiroom zone management, and real-time event monitoring via WebSocket connections.
+// multiroom zone management, and real-time event monitoring.
+//
+// It also provides a local service (`soundtouch-service`) that can emulate the Bose Cloud,
+// allowing for offline control and enhanced debugging through HTTP interaction recording.
 //
 // # Quick Start
 //
@@ -41,63 +44,20 @@
 //		if err != nil {
 //			log.Fatal(err)
 //		}
-//
-//		// Set volume
-//		err = client.SetVolume(50)
-//		if err != nil {
-//			log.Fatal(err)
-//		}
 //	}
 //
-// # Device Discovery
+// # SoundTouch Service
 //
-// Automatically discover SoundTouch devices on your network:
+// The `soundtouch-service` provides several advanced features:
 //
-//	import "github.com/gesellix/bose-soundtouch/pkg/discovery"
+//   - Bose Cloud Emulation: Allows speakers to work without an internet connection.
+//   - HTTP Interaction Recording: Captures all traffic as IntelliJ-compatible .http files.
+//   - Speaker Migration: Automated tools to redirect speakers to the local service.
+//   - Web Interface: A management dashboard for proxy settings and speaker setup.
 //
-//	// Discover devices using UPnP/SSDP
-//	service := discovery.NewService(5*time.Second)
-//	devices, err := service.DiscoverDevices(ctx)
-//	if err != nil {
-//		log.Fatal(err)
-//	}
+// Install the service:
 //
-//	for _, device := range devices {
-//		fmt.Printf("Found device: %s at %s\n", device.Name, device.Host)
-//	}
-//
-// # Real-time Events
-//
-// Monitor device state changes in real-time using WebSocket connections:
-//
-//	// Subscribe to device events
-//	events, err := client.SubscribeToEvents(ctx)
-//	if err != nil {
-//		log.Fatal(err)
-//	}
-//
-//	for event := range events {
-//		switch e := event.(type) {
-//		case *models.NowPlayingUpdated:
-//			fmt.Printf("Now playing: %s by %s\n", e.Track, e.Artist)
-//		case *models.VolumeUpdated:
-//			fmt.Printf("Volume changed to: %d\n", e.ActualVolume)
-//		}
-//	}
-//
-// # Multiroom Zone Management
-//
-// Create and manage multiroom zones:
-//
-//	// Create a zone with multiple speakers
-//	zone := &models.Zone{
-//		Master: "192.168.1.100",
-//		Members: []models.ZoneMember{
-//			{IPAddress: "192.168.1.101"},
-//			{IPAddress: "192.168.1.102"},
-//		},
-//	}
-//	err = client.SetZone(zone)
+//	go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
 //
 // # CLI Tool
 //
@@ -111,45 +71,33 @@
 //
 //	# Control a device
 //	soundtouch-cli --host 192.168.1.100 play start
-//	soundtouch-cli --host 192.168.1.100 volume set --level 50
-//	soundtouch-cli --host 192.168.1.100 source select --source SPOTIFY
 //
 // # Supported Features
 //
 //   - ✅ Device Information & Capabilities
-//   - ✅ Playback Control (Play/Pause/Stop/Next/Previous)
-//   - ✅ Volume, Bass, and Balance Control
-//   - ✅ Source Selection (Spotify, Bluetooth, AUX, etc.)
-//   - ✅ Preset Management
-//   - ✅ Clock/Time Management
-//   - ✅ Network Information
+//   - ✅ Playback, Volume, Bass, and Balance Control
+//   - ✅ Source Selection & Preset Management
 //   - ✅ Real-time WebSocket Events
 //   - ✅ Multiroom Zone Management
 //   - ✅ Device Discovery (UPnP/SSDP and mDNS)
-//   - ✅ Cross-platform Support (Windows, macOS, Linux)
+//   - ✅ Local Cloud Emulation (soundtouch-service)
+//   - ✅ HTTP Traffic Recording & Sanitization
+//   - ✅ Automated Speaker Migration & Revert
 //
 // # Package Structure
 //
 //   - client: HTTP client for SoundTouch Web API
 //   - discovery: Device discovery using UPnP/SSDP and mDNS
 //   - models: Data structures for API requests/responses
-//   - config: Configuration management
+//   - service: Core logic for the soundtouch-service (proxy, recording, setup)
 //   - cmd/soundtouch-cli: Command-line interface tool
-//
-// # Hardware Compatibility
-//
-// This library has been tested with real Bose SoundTouch hardware and supports
-// all SoundTouch-compatible devices including:
-//   - SoundTouch 10, 20, 30 series
-//   - SoundTouch Portable
-//   - Wave SoundTouch music system
-//   - And other SoundTouch-enabled Bose speakers
+//   - cmd/soundtouch-service: Local cloud emulation service
 //
 // # Implementation Notes
 //
-// This implementation is based on the official Bose SoundTouch Web API documentation
-// and provides 90% coverage of all available endpoints. It is an independent project
-// and is not affiliated with or endorsed by Bose Corporation.
+// This project is an independent effort to preserve the functionality of Bose SoundTouch
+// devices and provide enhanced debugging and control capabilities. It is not
+// affiliated with or endorsed by Bose Corporation.
 //
 // For detailed API documentation, examples, and advanced usage patterns, visit:
 // https://pkg.go.dev/github.com/gesellix/bose-soundtouch

docker-compose.ci.yml

@@ -0,0 +1,46 @@
+services:
+  soundtouch-service:
+    build:
+      context: .
+      target: soundtouch-service
+    networks:
+      - soundtouch-test-net
+    volumes:
+      - ./tests/integration/testdata:/app/data
+    environment:
+      - SPOTIFY_CLIENT_ID=mock-id
+      - SPOTIFY_CLIENT_SECRET=mock-secret
+      - SPOTIFY_TOKEN_URL=http://spotify-mock:8080/api/token
+      - SPOTIFY_API_BASE=http://spotify-mock:8080
+      - AMAZON_CLIENT_ID=mock-amazon-id
+      - AMAZON_CLIENT_SECRET=mock-amazon-secret
+      - AMAZON_TOKEN_URL=http://amazon-mock:8080/auth/o2/token
+      - AMAZON_PROFILE_URL=http://amazon-mock:8080/user/profile
+
+  spotify-mock:
+    image: golang:1.26.3-alpine
+    container_name: spotify-mock
+    working_dir: /app
+    volumes:
+      - .:/app
+    command: go run ./cmd/mock-spotify/main.go -port 8080
+    ports:
+      - "8081:8080"
+    networks:
+      - soundtouch-test-net
+
+  amazon-mock:
+    image: golang:1.26.3-alpine
+    container_name: amazon-mock
+    working_dir: /app
+    volumes:
+      - .:/app
+    command: go run ./cmd/mock-amazon/main.go -port 8080
+    ports:
+      - "8082:8080"
+    networks:
+      - soundtouch-test-net
+
+networks:
+  soundtouch-test-net:
+    name: soundtouch-test-net

docker-compose.yml

@@ -0,0 +1,41 @@
+services:
+  soundtouch-service:
+    image: ghcr.io/gesellix/bose-soundtouch:${SOUNDTOUCH_VERSION:-latest}
+    # build: .
+    container_name: soundtouch-service
+    # Linux only, required for discovery. Swarm requires host network at the task level.
+    # network_mode: host
+    ports:
+      - "8000:8000"
+      - "8443:8443"
+    environment:
+      - PORT=8000
+      - HTTPS_PORT=8443
+      - DATA_DIR=/app/data
+      - LOG_PROXY_BODY=false
+      - REDACT_PROXY_LOGS=true
+      - RECORD_INTERACTIONS=true
+      - DISCOVERY_INTERVAL=5m
+      - SERVER_URL=http://${SOUNDTOUCH_HOSTNAME:-soundtouch.local}:8000
+      - HTTPS_SERVER_URL=https://${SOUNDTOUCH_HOSTNAME:-soundtouch.local}:8443
+    volumes:
+      - soundtouch-data:/app/data
+      # Use host volume for local development if preferred:
+      # - ./data:/app/data
+    restart: unless-stopped
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+      resources:
+        limits:
+          cpus: '0.50'
+          memory: 512M
+        reservations:
+          cpus: '0.25'
+          memory: 128M
+
+volumes:
+  soundtouch-data:
+    # Named volumes are preferred in Swarm. For multi-node persistence,
+    # consider using a volume driver like NFS or GlusterFS.

docs/CLAUDE.md

@@ -4,9 +4,9 @@
 
 This document contains important development guidelines for working on the Bose SoundTouch project. Please also read the following documentation:
 
-- **[PLAN.md](PLAN.md)** - Project planning and roadmap
+- **[PLAN.md](archive/PLAN.md)** - Project planning and roadmap
 - **[PROJECT-PATTERNS.md](PROJECT-PATTERNS.md)** - Project structure and design patterns
-- **[API-Endpoints-Overview.md](API-Endpoints-Overview.md)** - API endpoints overview
+- **[API-ENDPOINTS.md](reference/API-ENDPOINTS.md)** - API endpoints overview
 - **[SoundTouch Web API.pdf](2025.12.18%20SoundTouch%20Web%20API.pdf)** - Official API documentation
 
 ## Development Guidelines
@@ -95,4 +95,3 @@ When creating test data for API endpoints, prefer real device responses over hyp
 - **Documentation**: Completely in English for international accessibility
 - Conduct regular code reviews
 - Consider performance from the beginning
-

docs/CONTENT-SELECTION-IMPLEMENTATION.md

@@ -0,0 +1,229 @@
+# Content Selection Implementation Summary
+
+This document summarizes the implementation of advanced content selection features for the Bose SoundTouch Go client, including full support for the LOCAL_INTERNET_RADIO streamUrl format and LOCAL_MUSIC/STORED_MUSIC content selection.
+
+## ✅ Implementation Status: COMPLETE
+
+All content selection features from the [SoundTouch WebServices API Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) are now fully implemented with comprehensive API methods, CLI commands, tests, and documentation.
+
+## 🎯 Features Implemented
+
+### 1. Core API Methods
+
+#### `SelectContentItem(contentItem *models.ContentItem) error`
+- **Purpose**: Generic method for selecting any content using a ContentItem directly
+- **Use Case**: Maximum flexibility for complex content selection scenarios
+- **Validation**: Ensures ContentItem is not nil and has a valid source
+
+#### `SelectLocalInternetRadio(location, sourceAccount, itemName, containerArt string) error`
+- **Purpose**: Select LOCAL_INTERNET_RADIO content with streamUrl format support
+- **Features**:
+  - Direct stream URLs (e.g., `https://stream.example.com/radio`)
+  - streamUrl proxy format (e.g., `http://contentapi.gmuth.de/station.php?name=Station&streamUrl=ActualStream`)
+  - Automatic defaults for missing parameters
+- **Use Cases**: Internet radio streams, proxy-based radio services
+
+#### `SelectLocalInternetRadio(location, ...)` via `soundtouch-service`
+- **Purpose**: Select custom radio stream via local `soundtouch-service` proxy
+- **Features**:
+  - Flexible stream URL encoding (Base64 or URL-escaped)
+  - Dynamic generation of Bose-compatible playback JSON
+  - Seamless integration with existing `LOCAL_INTERNET_RADIO` source
+- **Use Case**: Playing any internet radio URL without external proxy dependencies
+
+#### `SelectLocalMusic(location, sourceAccount, itemName, containerArt string) error`
+- **Purpose**: Select LOCAL_MUSIC content from SoundTouch App Media Server
+- **Requirements**: SoundTouch App Media Server running on a computer
+- **Content Types**: Albums, tracks, artists, playlists
+- **Validation**: Requires both location and sourceAccount
+
+#### `SelectStoredMusic(location, sourceAccount, itemName, containerArt string) error`
+- **Purpose**: Select STORED_MUSIC content from UPnP/DLNA media servers
+- **Requirements**: UPnP/DLNA media server (Windows Media Player, NAS, etc.)
+- **Content Types**: NAS libraries, network music collections
+- **Validation**: Requires both location and sourceAccount
+
+### 2. CLI Commands
+
+All API methods are exposed through comprehensive CLI commands:
+
+#### `soundtouch-cli source internet-radio`
+```bash
+soundtouch-cli --host <device> source internet-radio \
+  --location "http://contentapi.gmuth.de/station.php?name=MyStation&streamUrl=https://stream.example.com/radio" \
+  --name "My Station" \
+  --artwork "https://example.com/art.png"
+```
+
+#### `soundtouch-cli source custom-radio`
+```bash
+soundtouch-cli --host <device> source custom-radio \
+  --url "https://stream.example.com/radio" \
+  --name "My Station" \
+  --artwork "https://example.com/art.png" \
+  --service-url "http://localhost:8080"
+```
+
+#### `soundtouch-cli source local-music`
+```bash
+soundtouch-cli --host <device> source local-music \
+  --location "album:983" \
+  --account "3f205110-4a57-4e91-810a-123456789012" \
+  --name "Welcome to the New"
+```
+
+#### `soundtouch-cli source stored-music`
+```bash
+soundtouch-cli --host <device> source stored-music \
+  --location "6_a2874b5d_4f83d999" \
+  --account "d09708a1-5953-44bc-a413-123456789012/0" \
+  --name "Christmas Album"
+```
+
+#### `soundtouch-cli source content` (Advanced)
+```bash
+soundtouch-cli --host <device> source content \
+  --source LOCAL_INTERNET_RADIO \
+  --location "https://stream.example.com/radio" \
+  --name "My Stream" \
+  --type stationurl \
+  --presetable
+```
+
+## 🧪 Test Coverage
+
+Comprehensive test suites implemented for all new functionality:
+
+### Unit Tests
+- **TestClient_SelectContentItem**: 5 test cases covering valid/invalid inputs
+- **TestClient_SelectLocalInternetRadio**: 4 test cases including streamUrl format
+- **TestClient_SelectLocalMusic**: 4 test cases with validation
+- **TestClient_SelectStoredMusic**: 4 test cases with error handling
+
+### Test Coverage Summary
+- ✅ Valid content selection scenarios
+- ✅ streamUrl format validation
+- ✅ Parameter validation and error handling
+- ✅ Default value assignment
+- ✅ HTTP request formatting verification
+
+## 📚 Documentation
+
+### Updated Documentation
+1. **CLI-REFERENCE.md**: Added comprehensive CLI command examples
+2. **Content Selection Example**: New `/examples/content-selection/` with working code
+3. **README Updates**: Added streamUrl format examples
+4. **API Documentation**: Inline Go documentation for all methods
+
+### Example Code
+Complete working example demonstrating:
+- LOCAL_INTERNET_RADIO with streamUrl proxy format
+- LOCAL_INTERNET_RADIO with direct streams
+- LOCAL_MUSIC content selection
+- STORED_MUSIC content selection
+- Generic ContentItem usage
+
+## 🔍 streamUrl Format Support
+
+### What is the streamUrl Format?
+The streamUrl format uses a proxy server that accepts the actual stream URL as a parameter:
+
+```
+http://contentapi.gmuth.de/station.php?name=StationName&streamUrl=ActualStreamURL
+```
+
+### Implementation Details
+- **Full Support**: All streamUrl format URLs work seamlessly
+- **Example from Wiki**: Exact implementation matches the wiki specification
+- **ContentItem Structure**:
+  ```go
+  contentItem := &models.ContentItem{
+      Source:       "LOCAL_INTERNET_RADIO",
+      Type:         "stationurl",
+      Location:     "http://contentapi.gmuth.de/station.php?name=Antenne%20Chillout&streamUrl=https://stream.antenne.de/chillout/stream/aacp",
+      IsPresetable: false,
+      ItemName:     "Antenne Chillout",
+      ContainerArt: "https://www.radio.net/300/antennechillout.png",
+  }
+  ```
+
+## 🏗️ Architecture
+
+### Design Principles
+1. **Consistency**: All methods follow the same parameter patterns
+2. **Flexibility**: `SelectContentItem()` allows maximum control
+3. **Convenience**: Specific methods (`SelectLocalInternetRadio()`, etc.) provide simpler interfaces
+4. **Validation**: Comprehensive input validation with clear error messages
+5. **Defaults**: Sensible defaults when optional parameters are empty
+
+### ContentItem Construction
+All convenience methods create properly structured `ContentItem` objects:
+- Automatic `Type` assignment based on source
+- `IsPresetable` defaults to `true`
+- Default `ItemName` when not provided
+- Proper source-specific validation
+
+## 🎵 Related Features
+
+### Sibling Features (Also Implemented)
+Based on the wiki structure, these related features are also supported:
+
+1. **LOCAL_MUSIC**: ✅ Fully implemented
+2. **STORED_MUSIC**: ✅ Fully implemented
+3. **SPOTIFY**: ✅ Previously implemented
+4. **TUNEIN**: ✅ Previously implemented
+5. **BLUETOOTH**: ✅ Previously implemented
+6. **AIRPLAY**: ✅ Previously implemented
+
+## 📋 Usage Examples
+
+### API Usage
+```go
+// streamUrl format
+location := "http://contentapi.gmuth.de/station.php?name=MyStation&streamUrl=https://stream.example.com/radio"
+err := client.SelectLocalInternetRadio(location, "", "My Station", "")
+
+// Direct ContentItem
+contentItem := &models.ContentItem{
+    Source:       "LOCAL_INTERNET_RADIO",
+    Type:         "stationurl",
+    Location:     location,
+    ItemName:     "My Station",
+    IsPresetable: true,
+}
+err := client.SelectContentItem(contentItem)
+```
+
+### CLI Usage
+```bash
+# streamUrl format
+soundtouch-cli --host 192.168.1.100 source internet-radio \
+  --location "http://contentapi.gmuth.de/station.php?name=MyStation&streamUrl=https://stream.example.com/radio" \
+  --name "My Station"
+
+# Direct stream
+soundtouch-cli --host 192.168.1.100 source internet-radio \
+  --location "https://stream.example.com/radio" \
+  --name "Direct Stream"
+```
+
+## 🔗 References
+
+- [SoundTouch WebServices API Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
+- [LOCAL_INTERNET_RADIO - streamUrl format](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API#select-local_internet_radio---streamurl-format)
+- [LOCAL_MUSIC](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API#select-local_music)
+- [Content Selection Example](../examples/content-selection/README.md)
+- [CLI Reference](guides/CLI-REFERENCE.md)
+- [Content Selection Example (Direct)](../examples/content-selection/)
+
+## ✅ Verification
+
+This implementation has been verified to:
+1. ✅ Support exact wiki specification for streamUrl format
+2. ✅ Handle all LOCAL_INTERNET_RADIO, LOCAL_MUSIC, and STORED_MUSIC scenarios
+3. ✅ Pass comprehensive test suite
+4. ✅ Work with CLI commands
+5. ✅ Include complete documentation and examples
+6. ✅ Maintain backward compatibility
+
+**Status**: 🎉 **COMPLETE** - All requested content selection features are fully implemented and ready for use!

docs/DEVICE-LOGGING.md

@@ -0,0 +1,107 @@
+# Device Logging & Troubleshooting
+
+Accessing logs from SoundTouch devices is critical for debugging custom service integrations and understanding internal device behavior. This document outlines the methods for collecting logs, as discovered by the **SoundCork** and **ÜberBöse API** communities.
+
+## Log Types
+
+1.  **System Logs**: Internal OS logs (Linux-based) including `dmesg`, `syslog`, and process-specific logs.
+2.  **Traffic Logs**: Real-time HTTP/HTTPS requests sent by the device to cloud or local services.
+3.  **Proxy Logs**: Logs generated by the `soundtouch-service` when it acts as a man-in-the-middle.
+
+---
+
+## 1. Accessing System Logs (Requires Root)
+
+Most SoundTouch devices run a modified Linux distribution. Accessing these logs requires root SSH or Telnet access.
+
+### Enabling Root Access (Remote Services)
+
+Community research (SoundCork Issue #112) has identified a "backdoor" to enable developer services:
+
+1.  **USB Method**:
+    -   Format a USB stick to **FAT32**.
+    -   Create an empty file named `remote_services` (no extension) in the root of the USB stick.
+    -   Insert the stick into the SoundTouch device.
+    -   Reboot the device (power cycle).
+    -   On some models, you may need to hold **4** and **Volume -** on the device while powering on to force a USB check.
+2.  **TAP Command (Legacy)**:
+    -   On older firmware versions, you can connect to port 17000 via Telnet and issue the command: `remote_services on`.
+
+### Making Root Access Persistent
+Once you have logged in as `root` (usually no password or a well-known community password), you can make the access survive reboots without the USB stick:
+```bash
+touch /mnt/nv/remote_services
+/etc/init.d/sshd start
+```
+
+### Viewing Logs
+Once inside via SSH:
+-   **Kernel Logs**: `dmesg`
+-   **System Logs**: `cat /var/log/messages` or `tail -f /tmp/soundtouch.log` (paths vary by firmware).
+-   **Real-time Monitoring**: `logread -f`
+-   **Process List**: `ps w`
+
+#### Pro-Tip: Filtered Real-time Monitoring
+To focus on cloud service and preset interactions (Marge), use the following command on the device:
+```bash
+logread -f | grep -Ei '(marge|preset)'
+```
+This is particularly useful for debugging preset synchronization and service redirection issues.
+
+---
+
+## 2. Traffic Logging & Interception
+
+If you cannot or do not want to root the device, you can monitor its outbound traffic by redirecting it to a proxy.
+
+### Via `soundtouch-service`
+The `soundtouch-service` included in this repository includes a built-in proxy. When a device is migrated to use this service, all of its cloud-bound traffic is logged to the service console.
+
+**Key Traffic to Monitor**:
+-   `POST /v1/scmudc/{deviceId}`: Real-time telemetry events.
+-   `GET /marge/...`: Account and streaming configuration requests.
+-   `POST /streaming/support/power_on`: Boot-time diagnostics.
+
+### Via Packet Sniffing (Advanced)
+If you have a managed switch or a router capable of port mirroring, you can use **Wireshark** or `tcpdump` to capture traffic.
+-   **Filter**: `tcp port 80 or tcp port 443`
+-   **Target**: The IP address of your SoundTouch device.
+
+---
+
+## 3. Troubleshooting Common Issues
+
+### "IsItBose" Validation Failures
+If the device fails to connect to your custom service despite correct configuration, it may be failing the internal `IsItBose` regex check.
+-   **Evidence**: Look for SSL handshake failures or "Unauthorized" errors in your service logs.
+-   **Solution**: See the [Binary Patching section in DEVICE-REDIRECT-METHODS.md](analysis/DEVICE-REDIRECT-METHODS.md#method-3-binary-patching).
+
+### Disappearing Sources (TuneIn/Local Radio)
+If `TUNEIN` or `LOCAL_INTERNET_RADIO` sources disappear after a reboot in an offline environment.
+-   **Cause**: These sources are validated against the cloud only during the initial boot sequence.
+-   **Solution**: Ensure your emulated service is reachable and responding correctly to `/streaming/support/power_on` and `/streaming/sourceproviders` during the device's boot-up.
+
+---
+
+## 4. HTTP Protocol Quirks
+
+### ETag Case-Sensitivity
+Research in **SoundCork Issue #129** revealed a significant bug in the SoundTouch device firmware regarding HTTP `ETag` headers.
+
+- **The Issue**: The device firmware expects the `ETag` header to be exactly title-cased (`ETag`). Many modern web servers or frameworks (like FastAPI/Uvicorn) return headers in all lowercase (`etag`) per HTTP/2 or standard case-insensitive conventions.
+- **The Symptom**: If the server returns a lowercase `etag`, the device fails to recognize it. Consequently, the device will never send an `If-None-Match` header in subsequent requests, breaking preset synchronization and efficient caching.
+- **The Workaround**: If you are using a custom service, you may need to use a reverse proxy (like **Nginx**) or a middleware to force the header casing to `ETag`.
+
+**Example Nginx Fix**:
+```nginx
+proxy_hide_header etag;
+add_header ETag $upstream_http_etag;
+```
+
+---
+
+## References
+- [SoundCork Issue #112: Enabling Remote Services](https://github.com/deborahgu/soundcork/issues/112)
+- [SoundCork Issue #149: Debugging with Systemd/Gunicorn](https://github.com/deborahgu/soundcork/issues/149)
+- [ÜberBöse API: Telemetry Documentation](https://github.com/julius-d/ueberboese-api)
+- [SoundCork Issue #129: ETag Case-Sensitivity & Preset Sync](https://github.com/deborahgu/soundcork/issues/129)

docs/DEVICE-SETUP.md

@@ -0,0 +1,114 @@
+# Bose SoundTouch Device Setup Flow
+
+This document details the multi-step process required to fully set up a Bose SoundTouch device, as derived from the Stockholm firmware (`setup/js/`) analysis.
+
+A complete setup flow involves a sequence of local (WebSocket) and cloud (HTTP) actions that move the device from a factory-reset state to a fully registered, functional system.
+
+## 1. Local Coordination Stage (WebSocket)
+
+Before a device can be controlled, it must be configured on the local network and named. These actions occur via a WebSocket connection to the device on port 8080.
+
+### 1.1 Language Configuration (Optional)
+If the device is in a factory-reset state, the UI typically ensures the device language matches the user's choice.
+- **WebSocket Action**: `set_language`
+- **Internal Logic**: `SetupWizard.js` handles this via `set_device_language`.
+
+### 1.2 Network Configuration (WiFi)
+Configures the device to connect to a specific wireless access point.
+- **File Reference**: `setup/js/workflow_wifi_setup.js`
+- **Logic**: Triggers a site survey, then sends SSID and credentials.
+- **WebSocket Command**: `set_WIFI_OLED` or similar internal method calls to configure the network profile.
+
+### 1.3 Device Naming (Rename Step)
+Assigns a user-friendly name (e.g., "Living Room") to the device.
+- **File Reference**: `setup/js/workflow_rename.js`
+- **WebSocket Action**: `name`
+- **XML Payload**:
+    ```xml
+    <name>Living Room</name>
+    ```
+- **Implementation**: The `RenameDevices.do_rename_devices()` function sends this to the device. The device then updates its local name and mDNS/SSDP broadcasts.
+
+## 2. Cloud Interaction Stage (HTTP)
+
+The device needs to be linked to a Bose "Marge" account to enable cloud-based features and music services.
+
+### 2.1 Account Creation (Registration)
+If a user doesn't have an account, the setup client creates one.
+- **File Reference**: `setup/js/workflow_marge.js`
+- **Cloud Endpoint**: `POST https://streaming.bose.com/streaming/account`
+- **Payload**: XML containing name, email, password, and country.
+- **Content-Type**: `application/vnd.bose.customer-v1.0+xml`
+
+### 2.2 Cloud Authentication (Login)
+The setup client must obtain a valid `accountId` and `userAuthToken` to pair the device.
+- **File Reference**: `setup/js/workflow_marge.js`
+- **Cloud Endpoint**: `POST https://streaming.bose.com/streaming/account/login`
+- **Payload**: XML containing username and password.
+- **Content-Type**: `application/vnd.bose.streaming-v1.2+xml`
+- **Result**: Returns a session token in the `Credentials` response header and the user's `account ID` in the XML body.
+
+## 3. Registration Bridge (WebSocket to Cloud)
+
+This is the final "pairing" step where the client tells the device which account it belongs to.
+
+### 3.1 Device Registration (The "Pair" Step)
+The client sends the user's credentials to the device, which then registers itself with the cloud.
+- **File Reference**: `setup/js/workflow_add_devices.js`
+- **WebSocket Action**: `setMargeAccount`
+- **XML Payload**:
+    ```xml
+    <PairDeviceWithAccount>
+        <accountId>12345</accountId>
+        <userAuthToken>jGwE... (truncated)</userAuthToken>
+    </PairDeviceWithAccount>
+    ```
+- **Device Reaction**: Upon receiving this, the device makes its own outbound HTTP POST to the Marge service:
+    `POST https://streaming.bose.com/{accountId}/devices`
+
+## 4. Finalization
+
+Once the registration is complete, the setup application (Stockholm) performs final cleanup. It's important to distinguish between **App State** (the Stockholm UI's persistent settings) and **Device State** (the physical speaker's configuration).
+
+### 4.1 Exiting Setup Mode (App Settings)
+The Stockholm app communicates with its "native container" (the WebView bridge on iOS/Android/Windows/macOS) using a `setData` command in **JSON format**. This is an internal message to the application's persistent storage, **not a network command sent to the physical speaker**.
+
+This command tells the Stockholm app which page to load on startup, effectively marking the setup as complete in the UI.
+
+- **Internal Command**: `setData`
+- **Parameter**: `startupPage`
+- **Normal Value**: `index.html` (Normal mode)
+- **Setup Value**: `setup/index.html` (Setup mode)
+
+**JSON Payload (Internal to Stockholm App)**:
+```json
+{
+    "method": "setData",
+    "params": {
+        "name": "startupPage",
+        "value": "index.html"
+    }
+}
+```
+
+**Other Common Internal Parameters**:
+- `changeStartupPage`: Set to `false` after a successful setup or update.
+- `tipsEnabled`: Set to `false` to suppress the "Getting Started" tutorials.
+- `promptUpdate`: Set to `true` if a firmware update was deferred during setup.
+
+### 4.2 Device Finalization
+The physical speaker considers the setup "done" once it successfully processes the `<PairDeviceWithAccount>` XML message and completes its own handshake with the Marge cloud. There is no specific "Finalize" XML command sent to the speaker; the successful registration is the signal.
+
+The `SetupWizard.js` calls `single_device_setup_done()` to trigger the internal `setData` updates described above. If these are not saved in the app's local storage, the Stockholm UI may return to the setup flow on next launch, even if the speaker is already paired.
+
+---
+
+## Summary of Scriptable Requirements
+
+To automate a device setup using a custom tool (like `soundtouch-cli`), you must perform the following:
+1.  **Configure WiFi**: (Assumed if device is reachable over IP).
+2.  **Set Name**: Send the `<name>` WebSocket message (XML) to update the device identity.
+3.  **Obtain Token**: Authenticate against the cloud service (Marge) via HTTP.
+4.  **Pair Device**: Send the `<PairDeviceWithAccount>` WebSocket message (XML) with the account ID and token.
+
+**Note**: The JSON `setData` commands are only necessary if you are building/controlling a version of the Stockholm UI itself. They are not required to configure the physical hardware.

docs/EXTERNAL-SERVICES-ABSTRACTION.md

@@ -0,0 +1,66 @@
+# Technical Proposal: External Service Provider Abstraction
+
+This document outlines a strategy to refactor the SoundTouch Service's content handling into a modular provider-based system.
+
+## 1. Problem Statement
+Currently, content handling for BMX (Bose Media Exchange) services like TuneIn or RadioBrowser is deeply intertwined with the HTTP handlers and XML models. Adding a new content provider (e.g., Local Media, Podcast RSS) requires modifying several files and duplicating boilerplate code for HTTP requests and error handling.
+
+## 2. Proposed Architecture
+
+### 2.1 The Provider Interface
+We define a generic `ContentProvider` interface that abstracts away the source-specific logic (API calls, data parsing).
+
+```go
+package provider
+
+import "github.com/gesellix/bose-soundtouch/pkg/models"
+
+type ContentProvider interface {
+    // ID returns the unique identifier for this provider (e.g. "RADIO_BROWSER")
+    ID() string
+
+    // Resolve returns playback details for a given content identifier
+    Resolve(id string) (*models.BmxPlaybackResponse, error)
+
+    // Search allows finding content within this provider
+    Search(query string) ([]models.ContentItem, error)
+}
+```
+
+### 2.2 Provider Registry
+A central registry in `soundtouch-service` manages the lifecycle and selection of providers.
+
+```go
+type Registry struct {
+    providers map[string]ContentProvider
+}
+
+func (r *Registry) Register(p ContentProvider) { ... }
+func (r *Registry) Get(id string) ContentProvider { ... }
+```
+
+## 3. Implementation Plan
+
+### 3.1 Phase 1: Modularize RadioBrowser
+1.  **Extract Logic**: Move current RadioBrowser logic from `bmx.go` into a new package `pkg/service/providers/radiobrowser`.
+2.  **Add Failover**: Implement the **API Failover** logic inspired by OpenCloudTouch.
+    -   Maintain a list of active RadioBrowser mirrors (e.g., `de1.api.radio-browser.info`, `nl1.api.radio-browser.info`).
+    -   Implement a round-robin or health-based selection strategy.
+3.  **Implements Interface**: Ensure the new package satisfies the `ContentProvider` interface.
+
+### 3.2 Phase 2: Refactor BMX Handlers
+-   Update `HandleTuneInPlayback` and `HandleOrionPlayback` to use the registry.
+-   The handlers will look up the provider based on the request context or URL parameters and delegate the resolution.
+
+### 3.3 Phase 3: Dynamic Service Advertising
+-   Modify `HandleBMXRegistry` to dynamically generate the `bmx_services.json` content based on the currently registered and enabled providers.
+
+## 4. Benefits
+-   **Resilience**: Centralized error handling and failover strategies for all external APIs.
+-   **Extensibility**: New services can be added by simply implementing the interface and registering them at startup.
+-   **Testability**: Providers can be unit-tested in isolation without mocking the entire HTTP server stack.
+-   **Unified UI**: A future Web UI can query the registry to show available content sources and their statuses.
+
+## 5. Next Steps
+1.  Refine the `ContentProvider` interface to include metadata (icons, user-friendly names).
+2.  Create a prototype for the `radiobrowser` provider with failover support.

docs/FEATURE_HISTORY.md

@@ -188,6 +188,63 @@ This document tracks the detailed evolution of features and capabilities in the
 - **Conditional Feature Availability**: Features only available on compatible devices
 - **Graceful Degradation**: Fallback to basic controls when advanced features unavailable
 
+### Phase 8: Speaker Notification System (February 2025)
+
+#### Notification Features
+- **Text-to-Speech (TTS)**: `/speaker` POST endpoint for TTS messages
+  - Multi-language support (EN, DE, ES, FR, IT, NL, PT, RU, ZH, JA, etc.)
+  - Google TTS integration with URL encoding
+  - Custom volume control with automatic restoration
+  - Configurable service metadata for NowPlaying display
+- **URL Audio Playback**: `/speaker` POST endpoint for URL content
+  - HTTP/HTTPS audio content playback
+  - Custom metadata support (service, message, reason fields)
+  - Volume control with automatic restoration
+  - Content interruption and resume functionality
+- **Notification Beep**: `/playNotification` GET endpoint
+  - Simple double beep notification sound
+  - Content pause/resume during notification
+  - Quick connectivity testing
+
+#### Smart Home Integration
+- **Home Automation Support**: Perfect for smart home notifications
+  - Doorbell alerts with custom TTS messages
+  - Security system integration with audio alerts
+  - IoT device status announcements
+- **Emergency Notifications**: High-priority alert system
+  - Volume override for critical alerts
+  - Custom audio content for specific scenarios
+  - Zone-wide notifications for multiroom setups
+
+#### Device Compatibility
+- **ST-10 Series Support**: Primary compatibility with ST-10 (Series III) speakers
+- **Device Detection**: Automatic capability checking
+- **Error Handling**: Graceful degradation for unsupported devices
+- **Volume Management**: Intelligent volume restoration
+
+#### CLI Integration
+- **Comprehensive Commands**: Full CLI support for all notification types
+  - `speaker tts` - Text-to-speech with language options
+  - `speaker url` - URL content playback with metadata
+  - `speaker beep` - Simple notification beep
+  - `speaker help` - Detailed functionality guide
+- **Parameter Validation**: Complete input validation and error handling
+- **Usage Examples**: Extensive real-world usage examples
+
+### Phase 9: Bug Fixes and Stability (February 2025)
+
+#### Critical Bug Fixes
+- **PlayNotificationBeep HTTP Method Fix**: Corrected `/playNotification` endpoint to use GET instead of POST
+  - **Issue**: `go run ./cmd/soundtouch-cli --host <device> sp beep` was failing with HTTP 400 status
+  - **Root Cause**: Go client was sending POST requests while SoundTouch devices expect GET requests
+  - **Fix**: Updated `PlayNotificationBeep()` method to use the existing `c.get()` method with `StationResponse` model
+  - **Verification**: Tested with SoundTouch 20, confirmed compatibility with curl equivalent (`curl http://<device>:8090/playNotification`)
+
+#### Code Quality Improvements
+- **Consistent HTTP Method Usage**: Leveraged existing client patterns instead of manual HTTP handling
+- **Model Reuse**: Used existing `StationResponse` struct for `/playNotification` XML response parsing
+- **Documentation Updates**: Added troubleshooting guide for speaker notification issues
+
 ## Feature Implementation Statistics
 
 ### API Endpoint Coverage Evolution
@@ -200,7 +257,9 @@ This document tracks the detailed evolution of features and capabilities in the
 | Phase 4 | 3 | 21 | 81% |
 | Phase 5 | 1 | 22 | 85% |
 | Phase 6 | 2 | 24 | 92% |
-| Phase 7 | 3 | 27 | 100% |
+| Phase 7 | 3 | 27 | 96% |
+| Phase 8 | 2 | 29 | 100% |
+| Phase 9 | 0 | 29 | 100% (Bug fixes) |
 
 ### Testing Evolution
 
@@ -212,6 +271,8 @@ This document tracks the detailed evolution of features and capabilities in the
 - **Phase 5**: WebSocket event tests (200 tests)
 - **Phase 6**: Zone management tests (250 tests)
 - **Phase 7**: Advanced audio tests (300+ tests)
+- **Phase 8**: Speaker notification tests (330+ tests)
+- **Phase 9**: Bug fix verification tests (335+ tests)
 
 #### Integration Test Coverage
 - **Real Device Testing**: SoundTouch 10 and SoundTouch 20
@@ -229,6 +290,8 @@ This document tracks the detailed evolution of features and capabilities in the
 - **Phase 5**: `events`
 - **Phase 6**: `zone`
 - **Phase 7**: Advanced audio commands
+- **Phase 8**: `speaker` (TTS, URL, beep notifications)
+- **Phase 9**: Bug fixes (speaker beep reliability)
 
 #### CLI Feature Enhancements
 - **Host:Port Parsing**: Support for `192.168.1.100:8090` format

docs/NAVIGATION-GUIDE.md

@@ -895,4 +895,4 @@ For additional help:
 
 ---
 
-*This guide covers the complete navigation and station management functionality. For preset management, see [PRESET-MANAGEMENT.md](PRESET-MANAGEMENT.md).*
+*This guide covers the complete navigation and station management functionality. For preset management, see [PRESET-MANAGEMENT.md](reference/PRESET-MANAGEMENT.md).*

docs/PARITY-IMPROVEMENTS.md

@@ -0,0 +1,88 @@
+### Overview of Recent Improvements and Next Steps
+
+This document summarizes the improvements made to the **Marge service** to improve parity with the upstream Bose SoundTouch service, along with open issues and proposed next steps.
+
+#### ✅ Completed Improvements (Marge Service)
+*   **Mapped Preset `buttonNumber`**: Correctly mapped the internal `ServicePreset.ID` or `ButtonNumber` to the `buttonNumber` XML attribute in the `/full` response and ensured it is persisted in the local datastore.
+*   **High-Fidelity Device Metadata**: Improved the datastore to correctly extract, persist, and report detailed device `<components>` (e.g., `LIGHTSWITCH`, `SMSC`) and their firmware versions from upstream responses.
+*   **Standardized Preferred Language**: Updated the default `preferredLanguage` to `de` in the `/full` response and added synchronization to persist it from upstream responses.
+*   **Persisted Provider Settings**: Added support for persisting and echoing back `providerSettings` (e.g., `STREAMING_QUALITY`, `ELIGIBLE_FOR_TRIAL`) from the `/full` response.
+*   **Populated `contentItemType`**: The `contentItemType` (e.g., `tracklisturl`) is now correctly synchronized from upstream, persisted in the local datastore, and returned in the `/full` response for both presets and recents.
+*   **Standardized Credential Types**: Adjusted the logic for Spotify to use the correct `token_version_3` type when a token is present in the `/full` response, improving parity with the upstream service. The service now respects existing `credential_type` values from `Sources.xml` (e.g., `token_version_3` for Spotify) while providing sensible defaults for new or incomplete sources.
+*   **Structured Sources (Sources.xml)**: Refactored `Sources.xml` to use an attribute-based structure (`sourceid`, `source`, `status`, `sourceAccount`, etc.) matching the real device's output. Removed redundant nested tags like `<sourcename>`, `<username>`, and `<name>`.
+*   **Nested Recents (Recents.xml)**: Implemented a nested `<contentItem>` structure within `<recent>` entries in `Recents.xml`, maintaining exact parity with the device's persistence format while supporting legacy flat formats for backward compatibility.
+*   **Inconsistent `serialNumber` Casing**: Fixed the casing mismatch in the `/full` response where the upstream uses camelCase `<serialNumber>` in the top-level `<device>` and lowercase `<serialnumber>` in the nested `<attachedProduct>`. Local responses now correctly mirror this inconsistency.
+*   **Attribute-level Parity**:
+    *   Ensured `sourceAccount=""` is preserved in XML even when empty, matching device behavior for sources like TUNEIN.
+    *   Fixed casing for attributes like `deviceID` and `utcTime` in `Recents.xml`.
+    *   Correctly mapped and persisted preset and recent `id` attributes during "Initial Data Sync".
+*   **Device Name Consistency**: Fixed an issue where the device `<name>` was empty in some local `/full` responses by ensuring it is correctly populated from the datastore and synchronized from upstream.
+*   **Improved XML Parity**: Empty `<name>` tags in the `/full` response are now self-closing (`<name/>`), matching upstream behavior.
+*   **Timestamp-based ID Generation**: Implemented a 9-digit ID schema (`YYMMDD` + 3-digit counter) for `recent` items, ensuring IDs are large, unique, and stay within the 32-bit integer range.
+*   **Automatic Source Learning**: The service now extracts and persists full metadata (credentials, provider IDs, and custom names) from incoming `POST /recent` requests. This improves parity for subsequent `GET /recents` calls.
+*   **Source Provider Mapping**: Synchronized local source provider IDs and timestamps with upstream data. The `RADIO_BROWSER` provider is included in the public `/streaming/sourceproviders` list to maintain internal functionality while acknowledging it as a parity gap.
+*   **Credential Preservation**: Improved `AddRecent` to correctly extract and echo back base64 tokens/credentials provided in the incoming request, improving source learning.
+*   **XML Formatting Parity**:
+    *   Added `standalone="yes"` to the XML declaration for all Marge responses, including `recent`, `presets`, `full account`, `software update`, and `sourceproviders`.
+    *   Enforced self-closing `<sourceSettings/>` tags for parity.
+    *   Standardized date formatting to UTC with milliseconds (`.000+00:00`).
+    *   Fixed casing for `/streaming/sourceproviders`: Root element is `<sourceProviders>`, but child elements are `<sourceprovider>` (all lowercase), matching upstream behavior.
+    *   Implemented structured XML marshaling with consistent 2-space indentation for recents and source providers.
+*   **Improved TuneIn Parity**: Fixed TuneIn source mapping to use ID `25` and ensuring `sourcename` is empty in responses, matching upstream behavior for station playback.
+*   **High-Fidelity Full Account Sync**: Refactored the `/streaming/account/{accountId}/full` response to match the upstream structure. This includes:
+    *   **Mapped Preset `buttonNumber`**: Correctly mapped the internal `ServicePreset.ID` to the `buttonNumber` XML attribute in the `/full` response.
+    *   **Structured XML Marshaling**: Replaced manual string concatenation with structured Go models and `xml.Marshal` for the entire response.
+    *   **Specific Response Models**: Introduced `FullResponseSource`, `FullResponsePreset`, and `FullResponseRecent` to accurately reflect the upstream structure where `<source>` is a child element, rather than a set of attributes.
+    *   **Correct Nesting**: Ensured that `<presets>` and `<recents>` correctly nest their associated `<source>` details, resolving previous data omissions.
+    *   **Device Identity**: Added `<serialNumber>` and `<updatedOn>` to both the top-level `<device>` and its `<attachedProduct>`, ensuring consistent device identification.
+    *   **Field-Level Parity**: Mapped missing fields like `<contentItemType>` and `<productlabel>` to match upstream expectations.
+    *   **Improved Source Matching**: Enhanced internal logic to correctly link presets and recents to their configured sources based on multiple identifiers (ID, Key, or Type).
+*   **Verified Parity Mismatch Fixes**: Comprehensive reproduction tests (`TestParityMismatchReproduction_V2` and `TestParityMismatchReproduction_V3`) now confirm parity for identified mismatches in `POST /recent` and `GET /recents`, including credentials and source-specific metadata.
+*   **Unified Response Logic**: Refactored the code so that both `POST /recent` and `GET /recents` use the same formatting functions, guaranteeing consistency.
+*   **Robust Parity Detection**: Updated the local parity checker to be whitespace-insensitive for XML bodies, significantly reducing noise from minor indentation or newline differences.
+*   **Maintainable XML Generation**: Reduced cyclomatic complexity and code duplication in `marge.go` by extracting focused helper functions for mapping internal data to response-specific XML models.
+
+---
+
+#### 🛠️ Open Issues and Next Steps
+
+Based on the latest `parity_mismatches` and the high-fidelity `/full` account response comparison (diff14), here are the recommended areas for further work:
+
+#### 1. BMX / TuneIn Playback Parity (Medium)
+Current mismatches in `/bmx/tunein/v1/playback/station/...` show differences in reporting URLs and missing links:
+*   **Mismatched Parameters**: Local reporting URLs use `listen_id=1234567890`, while upstream uses a different session-based ID.
+*   **Missing Links**: Some upstream responses include additional `_links` or metadata that are currently omitted in local responses.
+*   **Action**: Improve the `HandleTuneInPlayback` logic to better mirror the upstream response structure and parameter generation.
+
+#### 2. `/full` Account Response Data Gaps (Medium)
+While structural parity for the `/full` response is high, several value-level gaps remain as shown in `diff14`:
+*   **Timestamp Formats**: Upstream uses ISO-8601 with milliseconds (e.g., `2024-06-23T07:40:36.000+00:00`), whereas some local fields still use Unix epoch integers (e.g., `1234567890`).
+*   **Provider Settings**: The `providerSettings` block in the local response currently lacks crucial values like `keyName`, `providerId`, and `boseId` (appearing as empty tags).
+*   **Component Metadata**: Local component types are sometimes empty (`type=""`) compared to upstream values like `LIGHTSWITCH` or `SMSC`.
+*   **Source/Preset Identifiers**: Local IDs (e.g., `100004`) differ from upstream IDs (e.g., `1234567`), though this may be expected due to different account/device environments.
+*   **Action**: Update the mapping logic in `marge.go` and `setup.go` to ensure all fields in the `/full` response are correctly populated with high-fidelity values and standard ISO-8601 timestamps.
+
+#### 3. OAuth / Spotify Token Noise (Low/Medium)
+The `/oauth/device/.../token` endpoint frequently reports mismatches because tokens are naturally different between local and upstream.
+*   **The Issue**: This creates "noise" in your parity reports that isn't actually a bug.
+*   **Action**: Update the parity detection logic (or the handler) to selectively ignore the `access_token` field while still verifying that the rest of the JSON structure (expires_in, scope, token_type) matches.
+
+#### 4. Large IDs for Other Models (Medium)
+While we fixed IDs for `recents`, other models like `presets` or `sources` might still use small auto-incrementing integers.
+*   **Action**: Evaluate if other endpoints should also transition to the timestamp-based ID schema to further reduce diff noise.
+
+#### 5. Improved Data Persistence (Continuous)
+Continue the "learning" approach for other services. For example, if we see a new `sourceproviderid` in a Spotify or TuneIn request, we should ensure it is stored and reused.
+
+#### 6. Local Reboot & Device State Management (Continuous)
+Analysis of device reboot logs revealed several data requirements:
+*   **Power-On Details Tracking**: Implemented extraction and persistence of detailed device information (serial numbers, firmware version, product details, and MAC addresses) from the `POST /streaming/support/power_on` request. This data is now stored in the local datastore, improving our ability to respond accurately to subsequent management requests.
+*   **Source Provider Mapping**: Synchronized local source provider IDs and timestamps with upstream data. The `RADIO_BROWSER` provider is included in the public `/streaming/sourceproviders` list to maintain internal functionality while acknowledging it as a parity gap.
+
+#### 7. Account Full Response (/full) Structural & Value Parity (Completed)
+Structural and value gaps in the `/full` account response have been addressed:
+
+**Key Fixes:**
+*   **Structural**:
+    *   **Nested Source Association**: Improved the matching logic in `mapRecentsToFullResponse` to correctly link recents to their specific `ConfiguredSource` (e.g., by matching `sourceid` attribute).
+    *   **XML Tag Formatting**: Standardized self-closing tags and element formatting to match upstream's multi-line or empty-element formatting in various contexts.

docs/PARITY-OPENCLOUDTOUCH.md

@@ -0,0 +1,45 @@
+# Parity Analysis: Bose-SoundTouch (Go) vs. OpenCloudTouch (Python)
+
+This document provides a comparative analysis of the current Go implementation and the `scheilch/opencloudtouch` project, identifying functional gaps and potential improvements.
+
+## 1. Core Architecture and Language
+- **Bose-SoundTouch (Go)**: A high-performance, strongly typed backend with a CLI and background service. Focuses on full API coverage, parity testing, and robust hardware control (DSP, zones).
+- **OpenCloudTouch (OCT)**: A modern full-stack application (FastAPI + React/TypeScript). Prioritizes user experience with a web-based setup wizard and a clean abstraction for internet radio.
+
+## 2. Functional Comparison
+
+| Feature                 | Bose-SoundTouch (Go)                                       | OpenCloudTouch (Python)                                                 |
+|:------------------------|:-----------------------------------------------------------|:------------------------------------------------------------------------|
+| **Setup Experience**    | CLI-driven or manual API calls for migration (SSH, XML).   | Web-based **Setup Wizard** guides through SSH, backup, and redirection. |
+| **Radio Support**       | Static integration of **RadioBrowser** and TuneIn.         | Dynamic **RadioBrowserAdapter** with automatic **API Failover**.        |
+| **Commercial Services** | Deep integration (Spotify priming, Pandora, Deezer, etc.). | Basic support, focus is on local content and radio.                     |
+| **Hardware Control**    | Extensive (Bass, Treble, Soundbar levels, Clock display).  | Basic playback and zone controls.                                       |
+| **Cloud Emulation**     | High-fidelity parity (mirroring, discrepancy logging).     | Functional emulation for local preset/recent persistence.               |
+| **Notifications**       | Built-in **TTS** and custom URL audio alerts.              | Not a primary focus.                                                    |
+
+## 3. Key Strengths of OpenCloudTouch
+- **Guided Onboarding**: The setup wizard reduces the entry barrier for non-technical users significantly.
+- **Resilient Radio**: The API failover for RadioBrowser ensures continuous service even if specific community-hosted API instances go offline.
+- **Modern API Stack**: Uses OpenAPI and generated TypeScript types for a seamless frontend integration.
+- **Provider Abstraction**: A cleaner internal separation between the "Bose World" (XML/BMX) and external content providers (RadioBrowser).
+
+## 4. Suggested Improvements for Bose-SoundTouch
+
+### A. Web-based Setup Wizard (High Priority)
+- Implement a state-driven wizard in the `soundtouch-service` to handle:
+  - SSH activation (checking `/remote_services` via USB).
+  - Automated backup of speaker configuration.
+  - Verification of DNS/Hosts redirection.
+- Expose this via a simple embedded Web UI (using Go's `embed` package).
+
+### B. RadioBrowser Failover (Medium Priority)
+- Adapt the failover logic from OCT:
+  - Periodically refresh the list of available RadioBrowser API servers.
+  - Implement a retry mechanism that switches servers on 5xx errors or timeouts.
+
+### C. External Service Abstraction (Medium Priority)
+- Refactor the hardcoded BMX logic into a more modular **Provider System** (see `EXTERNAL-SERVICES-ABSTRACTION.md`).
+- This will allow easier addition of new sources (e.g., local DLNA, generic M3U playlists) without touching the core BMX handlers.
+
+## 5. Summary
+While our Go project provides the most complete technical coverage of SoundTouch hardware and commercial services, OpenCloudTouch sets a higher standard for **user onboarding** and **service resilience** for community-driven content. Integrating a setup wizard and a more robust radio backend would make our project significantly more accessible and reliable.

docs/PARITY-SOUNDCORK.md

@@ -0,0 +1,57 @@
+# Parity Analysis: Bose-SoundTouch (Go) vs. SoundCork (Python)
+
+This document provides a comparative analysis of the current Go implementation and the `deborahgu/soundcork` project, identifying functional gaps and potential improvements.
+
+## 1. Core Architecture and Language
+- **Bose-SoundTouch (Go)**: Uses `chi` for routing and `encoding/xml` for data. High performance, strong typing, and precise MIME type handling (`application/vnd.bose.streaming-v1.2+xml`).
+- **SoundCork (Python)**: Uses `FastAPI` and `xml.etree.ElementTree`. Prioritizes flexibility and rapid prototyping of streaming service mocks.
+
+## 2. Functional Comparison
+
+| Feature              | Bose-SoundTouch (Go)                                                                                                  | SoundCork (Python)                                                                      |
+|:---------------------|:----------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------|
+| **Group Management** | Full CRUD: `POST /group`, `POST /group/{id}`, `DELETE /group/{id}` with XML datastore persistence (`Group_{id}.xml`). | Active group management (`groups.py`), supporting `/addGroup` and stereo pairing logic. |
+| **ZeroConf Priming** | Full DH key exchange + encrypted blob; fallback to `tokenType=accesstoken` for older firmware.                        | Simple `tokenType=accesstoken` push only; token expires after ~60 minutes.              |
+| **BMX Services**     | Supports TuneIn, Orion, and custom streams.                                                                           | More modular `bmx_services.json` registry with broader mock support.                    |
+| **Persistence**      | Mixed JSON/XML datastore.                                                                                             | Pure XML-based persistence per device/account.                                          |
+| **Admin UI**         | CLI-based (`soundtouch-cli`) or API-driven.                                                                           | Draft Web UI for device discovery and account management (`admin.py`).                  |
+| **Discovery**        | Integrated setup tools and SSDP/MDNS awareness.                                                                       | Leverages `bosesoundtouchapi` Python library for active discovery.                      |
+
+## 3. Key Strengths of SoundCork
+- **Group Pairing Logic**: Includes logic to manage master/slave relationships for SoundTouch 10 stereo pairs.
+- **Service Extensibility**: JSON-based registry for BMX services makes it easier to mock multiple providers (SiriusXM, Spotify) without code changes.
+- ~~**Mock Coverage**: Better coverage of "dummy" endpoints that respond with plausible XML (e.g., `customerSupport`).~~ **Addressed**: AfterTouch's `HandleNotFound` (registered via `r.NotFound`) logs every unimplemented endpoint as `[UNHANDLED]` and forwards the request to the Bose upstream via `HandleBoseProxy`. This provides at least the same coverage as static dummy responses, while also aiding discovery of new endpoints.
+
+## 4. Suggested Implementation Steps for Bose-SoundTouch
+
+### ✅ A. Implement Full Group Support (Completed)
+- `POST /group`, `POST /group/{id}`, `DELETE /group/{id}` implemented in `pkg/service/handlers/handlers_marge.go`.
+- Group CRUD persisted in XML datastore (`Group_{id}.xml`) via `pkg/service/datastore/datastore.go`.
+- `GET /group` on device registration reads the group the device belongs to.
+
+### ✅ B. Proper ZeroConf Spotify Blob (Completed)
+- Full Spotify Connect ZeroConf protocol implemented in `pkg/service/spotify/zeroconf.go`.
+- Flow: `getInfo` (fetch speaker DH public key) → 768-bit DH key exchange → AES-128-CTR encrypted `LoginCredentials` protobuf blob → `addUser`.
+- Speaker can self-refresh credentials independently; no periodic re-priming needed for token expiry.
+- Automatic fallback to `tokenType=accesstoken` if `getInfo` fails (older firmware without DH support).
+- See `docs/concepts/spotify-priming-strategy.md` for full protocol details.
+- **Remaining gap**: Background watchdog to re-prime devices that lose their session (reboot / power loss). Not required for token expiry on modern firmware; only needed for the "speaker rebooted and lost state" recovery path and for older firmware on the fallback path (~45 min token expiry).
+
+### C. Modularize BMX Registry (Medium Priority)
+- Extract the hardcoded service list in `HandleBMXRegistry` into an external `bmx-services.json` file.
+- Allow users to customize which mocked services are advertised to the speaker.
+
+### D. Enhanced Source Management (Medium Priority)
+- Refine source learning logic to ensure all `sourceAccount` and `sourceName` metadata is correctly captured during synchronization, using patterns from `soundcork`'s `learnSource`.
+
+### E. Basic Admin Web UI (Low Priority)
+- Develop a minimal internal status page to list active accounts and connected devices, improving usability over raw API calls.
+
+## 5. Summary
+
+Group support and ZeroConf Spotify priming are now feature-complete in AfterTouch. The Go implementation is structurally more consistent with recent reference recordings (e.g., `buttonNumber`, detailed `components`). SoundCork's remaining functional advantages are:
+
+- **BMX service extensibility**: the `bmx_services.json` registry makes it trivial to add or mock new streaming providers without code changes (step C above).
+- **Group pairing logic**: master/slave relationship management for SoundTouch 10 stereo pairs goes beyond the CRUD AfterTouch implements.
+
+For the broader ecosystem context (feature matrix across all community projects, AfterTouch open tasks, and cross-project observations) see [docs/analysis/bose-soundtouch-community-tools.md](analysis/bose-soundtouch-community-tools.md).

docs/PRESET-QUICKSTART.md

@@ -332,14 +332,14 @@ soundtouch-cli --host 192.168.1.100 info
 
 ## Next Steps
 
-- 📖 [Complete CLI Reference](CLI-REFERENCE.md)
-- 🔧 [Full Implementation Guide](preset-store.md)
-- 📡 [WebSocket Events Documentation](websocket-events.md)
+- 📖 [Complete CLI Reference](guides/CLI-REFERENCE.md)
+- 🔧 [Full Implementation Guide](reference/PRESET-MANAGEMENT.md)
+- 📡 [WebSocket Events Documentation](reference/WEBSOCKET-EVENTS.md)
 - 💻 [Preset Management Example](../examples/preset-management/)
-- 📚 [API Endpoints Overview](API-Endpoints-Overview.md)
+- 📚 [API Endpoints Overview](reference/API-ENDPOINTS.md)
 
 ## Need Help?
 
 - 🐛 **Bug Reports**: [Create an issue](https://github.com/gesellix/bose-soundtouch/issues)
 - 💡 **Feature Requests**: [Start a discussion](https://github.com/gesellix/bose-soundtouch/discussions)
-- ❓ **Questions**: [Browse discussions](https://github.com/gesellix/bose-soundtouch/discussions)
+- ❓ **Questions**: [Browse discussions](https://github.com/gesellix/bose-soundtouch/discussions)

docs/PROJECT-PATTERNS.md

@@ -21,7 +21,7 @@ This document describes the most important patterns for the Bose SoundTouch API
 
 **Key Aspects:**
 - **Native Builds**: Full API functionality for CLI and server
-- **WASM Builds**: Browser-compatible subset functionality  
+- **WASM Builds**: Browser-compatible subset functionality
 - **Cross-Platform**: Linux, macOS, Windows support
 - **Embedded Assets**: Web UI directly embedded in binary
 
@@ -66,7 +66,7 @@ func (c *Client) GetNowPlaying() (*models.NowPlaying, error) {
         return nil, err
     }
     defer resp.Body.Close()
-    
+
     var nowPlaying models.NowPlaying
     err = xml.NewDecoder(resp.Body).Decode(&nowPlaying)
     return &nowPlaying, err
@@ -77,7 +77,7 @@ func (c *Client) GetNowPlaying() (*models.NowPlaying, error) {
 ```go
 func (c *Client) SendKey(key models.Key) error {
     keyXML := fmt.Sprintf(`<key state="press" sender="GoClient">%s</key>`, key)
-    
+
     resp, err := c.httpClient.Post(
         c.baseURL+"/key",
         "application/xml",
@@ -117,14 +117,14 @@ func (d *DiscoveryService) DiscoverDevices() ([]Device, error) {
         return nil, err
     }
     defer conn.Close()
-    
+
     // Send M-SEARCH request
     searchRequest := "M-SEARCH * HTTP/1.1\r\n" +
         "HOST: 239.255.255.250:1900\r\n" +
         "MAN: \"ssdp:discover\"\r\n" +
         "ST: urn:schemas-upnp-org:device:MediaRenderer:1\r\n" +
         "MX: 3\r\n\r\n"
-    
+
     // Implementation details...
     return devices, nil
 }
@@ -158,13 +158,13 @@ func (e *EventClient) Subscribe(eventType string, handler EventHandler) {
 
 func (e *EventClient) Start() error {
     u := url.URL{Scheme: "ws", Host: e.client.host + ":8090", Path: "/"}
-    
+
     conn, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
     if err != nil {
         return err
     }
     e.conn = conn
-    
+
     go e.eventLoop()
     return nil
 }
@@ -184,7 +184,7 @@ func (e *EventClient) eventLoop() {
                 }
                 return
             }
-            
+
             if handler, exists := e.handlers[event.Type]; exists {
                 go handler(event)
             }
@@ -220,7 +220,7 @@ func wasmDiscoverDevices(this js.Value, args []js.Value) interface{} {
     handler := js.FuncOf(func(this js.Value, args []js.Value) interface{} {
         go func() {
             devices, err := discovery.NewDiscoveryService(5*time.Second).DiscoverDevices()
-            
+
             result := make(map[string]interface{})
             if err != nil {
                 result["error"] = err.Error()
@@ -228,13 +228,13 @@ func wasmDiscoverDevices(this js.Value, args []js.Value) interface{} {
                 devicesJSON, _ := json.Marshal(devices)
                 result["devices"] = string(devicesJSON)
             }
-            
+
             // Call JavaScript callback
             args[0].Invoke(js.ValueOf(result))
         }()
         return nil
     })
-    
+
     return handler
 }
 ```
@@ -280,7 +280,7 @@ func main() {
                     if err != nil {
                         return err
                     }
-                    
+
                     for i, device := range devices {
                         fmt.Printf("%d: %s (%s)\n", i+1, device.Name, device.Host)
                     }
@@ -300,7 +300,7 @@ func main() {
             },
         },
     }
-    
+
     app.Run(os.Args)
 }
 
@@ -311,7 +311,7 @@ func getClientFromContext(c *cli.Context) *client.Client {
         devices, _ := discovery.DiscoverDevices()
         deviceHost = selectDeviceInteractive(devices)
     }
-    
+
     return client.NewClient(deviceHost, 8090)
 }
 ```
@@ -327,34 +327,34 @@ var webAssets embed.FS
 
 func main() {
     mux := http.NewServeMux()
-    
+
     // Embedded web assets
     webFS, err := fs.Sub(webAssets, "web")
     if err != nil {
         log.Fatal(err)
     }
-    
+
     // SPA routing
     mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
         if r.URL.Path != "/" {
             http.FileServer(http.FS(webFS)).ServeHTTP(w, r)
             return
         }
-        
+
         data, err := webAssets.ReadFile("web/index.html")
         if err != nil {
             http.Error(w, "Not found", http.StatusNotFound)
             return
         }
-        
+
         w.Header().Set("Content-Type", "text/html")
         w.Write(data)
     })
-    
+
     // API endpoints
     mux.HandleFunc("/api/devices", handleDeviceDiscovery)
     mux.HandleFunc("/api/client/", handleClientProxy)
-    
+
     log.Println("SoundTouch Web UI starting on :8080")
     log.Fatal(http.ListenAndServe(":8080", mux))
 }
@@ -370,36 +370,36 @@ func handleClientProxy(w http.ResponseWriter, r *http.Request) {
         http.Error(w, "Invalid path", http.StatusBadRequest)
         return
     }
-    
+
     deviceIP := pathParts[3]
     apiPath := "/" + strings.Join(pathParts[4:], "/")
-    
+
     // Proxy request to SoundTouch device
     targetURL := fmt.Sprintf("http://%s:8090%s", deviceIP, apiPath)
-    
+
     proxyReq, err := http.NewRequest(r.Method, targetURL, r.Body)
     if err != nil {
         http.Error(w, err.Error(), http.StatusInternalServerError)
         return
     }
-    
+
     // Copy headers
     for k, v := range r.Header {
         proxyReq.Header[k] = v
     }
-    
+
     resp, err := http.DefaultClient.Do(proxyReq)
     if err != nil {
         http.Error(w, err.Error(), http.StatusInternalServerError)
         return
     }
     defer resp.Body.Close()
-    
+
     // Enable CORS
     w.Header().Set("Access-Control-Allow-Origin", "*")
     w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
     w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
-    
+
     // Copy response
     w.WriteHeader(resp.StatusCode)
     io.Copy(w, resp.Body)
@@ -448,7 +448,7 @@ func (p *PlayStatus) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
     if err := d.DecodeElement(&s, &start); err != nil {
         return err
     }
-    
+
     switch s {
     case string(PlayStatusPlaying), string(PlayStatusPaused), string(PlayStatusStopped):
         *p = PlayStatus(s)
@@ -469,41 +469,41 @@ type Config struct {
     // Server configuration
     WebPort      int           `env:"WEB_PORT" default:"8080"`
     APITimeout   time.Duration `env:"API_TIMEOUT" default:"10s"`
-    
+
     // Discovery configuration
     DiscoveryTimeout time.Duration `env:"DISCOVERY_TIMEOUT" default:"5s"`
     CacheDevices     bool          `env:"CACHE_DEVICES" default:"true"`
-    
+
     // CORS configuration (for web proxy)
     CORSOrigins []string `env:"CORS_ORIGINS" default:"*"`
-    
+
     // Logging
     LogLevel string `env:"LOG_LEVEL" default:"info"`
 }
 
 func Load() Config {
     var cfg Config
-    
+
     // Load from .env file
     loadDotEnv()
-    
+
     // Parse environment variables with reflection
     parseEnvVars(&cfg)
-    
+
     return cfg
 }
 
 func parseEnvVars(cfg interface{}) {
     v := reflect.ValueOf(cfg).Elem()
     t := v.Type()
-    
+
     for i := 0; i < v.NumField(); i++ {
         field := v.Field(i)
         fieldType := t.Field(i)
-        
+
         envTag := fieldType.Tag.Get("env")
         defaultTag := fieldType.Tag.Get("default")
-        
+
         if envTag != "" {
             if envValue := os.Getenv(envTag); envValue != "" {
                 setFieldValue(field, envValue)
@@ -545,11 +545,11 @@ func (m *MockClient) GetNowPlaying() (*models.NowPlaying, error) {
     if err, exists := m.errors["now_playing"]; exists {
         return nil, err
     }
-    
+
     if resp, exists := m.responses["now_playing"]; exists {
         return resp.(*models.NowPlaying), nil
     }
-    
+
     return &models.NowPlaying{
         Track:  "Mock Track",
         Artist: "Mock Artist",
@@ -577,8 +577,8 @@ CMD ["go", "test", "-v", "./..."]
 ```bash
 # Makefile test target
 test-integration:
-	docker-compose -f test/docker-compose.yml up --build --abort-on-container-exit
-	docker-compose -f test/docker-compose.yml down
+	docker compose -f test/docker-compose.yml up --build --abort-on-container-exit
+	docker compose -f test/docker-compose.yml down
 ```
 
 ## Recommended Project Structure
@@ -741,7 +741,7 @@ type APIError struct {
     Message string `xml:",innerxml"`
 }
 
-// pkg/models/device.go  
+// pkg/models/device.go
 type DeviceInfo struct {
     XMLResponse
     Name     string `xml:"name"`
@@ -773,7 +773,7 @@ func main() {
             },
         },
     }
-    
+
     app.Run(os.Args)
 }
 ```
@@ -802,4 +802,4 @@ func main() {
 
 ## Conclusion
 
-This pattern collection enables the development of robust API clients for hardware devices that function both as native tools and as web applications. The combination of Go's type safety, WASM support, and a structured build system makes it possible to use a single codebase for various deployment scenarios.
+This pattern collection enables the development of robust API clients for hardware devices that function both as native tools and as web applications. The combination of Go's type safety, WASM support, and a structured build system makes it possible to use a single codebase for various deployment scenarios.

docs/README.md

@@ -0,0 +1,92 @@
+# Bose SoundTouch Toolkit Documentation
+
+Welcome to the documentation for the Bose SoundTouch Toolkit. This comprehensive toolkit helps you keep your Bose SoundTouch speakers functional even after the Bose Cloud shutdown in May 2026, with enhanced local management and monitoring capabilities.
+
+## 🚀 Start Here
+
+### For New Users
+- **[Complete Migration Guide](guides/MIGRATION-GUIDE.md)** - Step-by-step guide from Bose Cloud to local control
+- **[Getting Started](guides/GETTING-STARTED.md)** - Quick introduction to the toolkit
+
+### For Existing Users
+- **[Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)** - Prepare for the May 2026 shutdown
+- **[Backup Tool](../cmd/soundtouch-backup/README.md)** - Back up your cloud account and speaker data before shutdown
+- **[SoundTouch Service Guide](guides/SOUNDTOUCH-SERVICE.md)** - Advanced service configuration
+
+## 📋 Essential Documentation
+
+The documentation is organized into three main categories:
+
+### 1. **User Guides** - For everyday users migrating and managing devices
+### 2. **Technical Reference** - For developers and advanced configuration
+### 3. **Concept Documentation** - For contributors and system architects
+
+## 🗂 Documentation Structure
+
+## 🗂 User Guides
+
+### Migration & Setup
+- **[Complete Migration Guide](guides/MIGRATION-GUIDE.md)** - 📖 **Main guide** for migrating from Bose Cloud
+- [Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md) - Prepare for service shutdown
+- [Migration & Safety Guide](guides/MIGRATION-SAFETY.md) - Advanced migration strategies
+- [Initial Device Setup](guides/DEVICE-INITIAL-SETUP.md) - First-time device configuration
+- [Raspberry Pi Setup](guides/RASPBERRY-PI.md) - Installing on Raspberry Pi
+
+### Daily Management
+- [SoundTouch Service Guide](guides/SOUNDTOUCH-SERVICE.md) - Service operation and maintenance
+- [Troubleshooting](guides/TROUBLESHOOTING.md) - Common issues and solutions
+- [HTTPS Setup](guides/HTTPS-SETUP.md) - Secure connections
+- [Deployment Guide](guides/DEPLOYMENT.md) - Production deployments
+
+### Advanced Features
+- [MAC Address Mapping](guides/MAC-ADDRESS-MAPPING.md) - Device identification
+- [CLI Reference](guides/CLI-REFERENCE.md) - Command-line tools
+- [Backup Tool](../cmd/soundtouch-backup/README.md) - Cloud account and speaker data backup
+- [IoT Implementation Guide](guides/IOT-IMPLEMENTATION-GUIDE.md) - IoT integrations
+- [MQTT Integration Design](guides/MQTT-INTEGRATION-DESIGN.md) - MQTT setup
+
+## 📚 Technical Reference
+
+### API Documentation
+- [API Endpoints](reference/API-ENDPOINTS.md) - REST API reference
+- [Spotify Account Addition](reference/spotify-account-addition.md) - Technical requests for Spotify
+- [WebSocket Events](reference/WEBSOCKET-EVENTS.md) - Real-time events
+- [Zone Management](reference/ZONE-MANAGEMENT.md) - Multi-room control
+- [Preset Management](reference/PRESET-MANAGEMENT.md) - Preset operations
+
+### Analysis & Research
+- [Upstream URLs](analysis/UPSTREAM-URLS.md) - Bose service endpoints
+- [Device Redirect Methods](analysis/DEVICE-REDIRECT-METHODS.md) - Migration techniques
+- [IoT Configuration Analysis](analysis/IOT-CONFIGURATION-ANALYSIS.md) - Device configurations
+- [IoT Config Summary](analysis/IOT-CONFIG-SUMMARY.md) - Configuration summaries
+
+### Device Lifecycle & Network Independence
+- **[Device Lifecycle and /power_on Enhancement](device-lifecycle-and-power-on-enhancement.md)** - Complete analysis of device registration and network independence improvements
+- [/power_on Implementation Guide](power-on-implementation-guide.md) - Technical implementation details for enhanced device management
+
+## 🏗 Concept Documentation
+
+### Enhanced Service Architecture
+- **[Concept Overview](concepts/README.md)** - High-level architecture vision
+- [Upstream Service Simulation](concepts/upstream-service-simulation.md) - Complete concept design
+- [Implementation Plan](concepts/implementation-plan.md) - Development roadmap
+- [Technical Specification](concepts/technical-specification.md) - Detailed specifications
+
+### Development Planning
+- [Implementation Roadmap](concepts/implementation-roadmap.md) - Project phases and milestones
+
+## 💡 Quick Reference
+
+### Common Tasks
+- **Migrate first device**: Follow [Migration Guide Step 5](guides/MIGRATION-GUIDE.md#step-5-migrate-individual-devices)
+- **Check device health**: Dashboard → Devices → [Device Name] → Health Status
+- **Backup configuration**: Dashboard → Settings → Backup → Create Backup
+- **Add new device**: Dashboard → Devices → Discover Devices → Register
+
+### Getting Help
+- **Issues & Bugs**: [GitHub Issues](https://github.com/gesellix/Bose-SoundTouch/issues)
+- **Questions & Discussion**: [GitHub Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions)
+- **Documentation**: Check troubleshooting guides first
+- **Community**: Share experiences and help others
+
+For a complete list of all documents, see the [Summary](SUMMARY.md).

docs/REQUEST_RECORDING_CONCEPT.md

@@ -0,0 +1,345 @@
+# Request Recording Concept
+
+## Problem Statement
+
+The current request recording system has fundamental issues when dealing with request cloning, body consumption, and multiple response scenarios. Specifically:
+
+1. **Body Consumption**: HTTP request bodies can only be read once, leading to missing bodies in recordings
+2. **Request Cloning**: A single original request may be cloned multiple times for different purposes (local handling, mirroring, recording)
+3. **Multiple Responses**: The same logical request may generate different responses (local vs upstream mirror)
+4. **Data Integrity**: No guarantee that recorded requests are identical across different execution paths
+
+## Current Issues (Examples)
+
+### Issue 1: Missing Request Bodies in Mirror Recordings
+
+**Local Recording** (complete):
+```http
+### POST /v1/scmudc/A81B6A536A98
+POST /v1/scmudc/A81B6A536A98
+Host: events.api.bosecm.com
+Content-Type: text/json; charset=utf-8
+Content-Length: 587
+Authorization: Bearer jGwEmFWr...
+
+{"envelope":{"monoTime":234906,"payloadProtocolVersion":"3.1","payloadType":"scmudc","protocolVersion":"1.0","time":"2026-02-25T23:03:14.976349+00:00","uniqueId":"A81B6A536A98"},"payload":{"deviceInfo":{"boseID":"3230304","deviceID":"A81B6A536A98","deviceType":"SoundTouch 10","serialNumber":"I6332527703739342000020","softwareVersion":"27.0.6.46330.5043500 epdbuild.trunk.hepdswbld04.2022-08-04T11:20:29","systemSerialNumber":"069231P63364828AE"},"events":[{"data":{"play-state":"PAUSE_STATE"},"monoTime":234904,"time":"2026-02-25T23:03:14.973466+00:00","type":"play-state-changed"}]}}
+
+{% raw %}
+> {%
+    // Response: 200 OK
+%}
+{% endraw %}
+```
+
+**Mirror Recording** (missing body):
+```http
+### POST /v1/scmudc/A81B6A536A98
+POST /v1/scmudc/A81B6A536A98
+Host: events.api.bosecm.com
+Content-Type: text/json; charset=utf-8
+Content-Length: 587
+Authorization: Bearer jGwEmFWr...
+
+
+
+{% raw %}
+> {%
+    // Response: 200 OK
+    // Headers:
+    // X-Proxy-Origin: upstream-mirror
+%}
+{% endraw %}
+```
+
+### Issue 2: Request Flow Complexity
+
+Current middleware execution order:
+```
+1. MirrorMiddleware    - Buffers body, creates clones
+2. RecordMiddleware    - Also buffers body
+3. Application Handler - Processes request
+4. Mirror Execution    - Async/sync mirror to upstream
+5. Recording           - Multiple recording points
+```
+
+Problems:
+- Multiple body reads across middleware chain
+- Inconsistent request state between clones
+- Race conditions in async scenarios
+- No guarantee of request equivalence
+
+## Proposed Solution: Context-Bound Request Snapshots
+
+### Core Concept
+
+Create **immutable request snapshots** early in the request lifecycle and propagate them through the **Request Context**. This ensures all downstream consumers (Mirroring, Recording, Parity Check) use identical data without re-reading the request body.
+
+### Architecture (Context-Only)
+
+```
+┌─────────────────┐
+│ Original Request│
+└─────────┬───────┘
+          │
+          ▼
+┌─────────────────┐    ┌──────────────────┐
+│ Snapshot Creator│───▶│ Request Context  │
+│  (Middleware)   │    │ (Pointer-based)  │
+└─────────┬───────┘    └──────────────────┘
+          │                      │
+          ▼                      │ (Safe for async)
+┌─────────────────┐              │
+│   Middleware    │◀─────────────┘
+│     Chain       │
+└─────────┬───────┘
+          │
+      ┌───▼────┐ ┌─────────┐ ┌──────────────┐
+      │ Local  │ │ Mirror  │ │ Recording    │
+      │Handler │ │Execution│ │  System      │
+      └────────┘ └─────────┘ └──────────────┘
+```
+
+### Request Snapshot Structure
+
+```go
+type RequestSnapshot struct {
+    Method    string
+    URL       *url.URL
+    Headers   http.Header
+    Body      []byte
+    Host      string
+    Timestamp time.Time
+}
+
+// Typed key for context safety
+type contextKey struct{ name string }
+var SnapshotKey = &contextKey{"request_snapshot"}
+```
+
+### Implementation Strategy
+
+#### Phase 1: Snapshot Middleware
+
+```go
+func (s *Server) SnapshotMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        // 1. Capture body once with size limit (e.g. 2MB)
+        body, _ := io.ReadAll(io.LimitReader(r.Body, 2*1024*1024))
+        r.Body.Close()
+
+        // 2. Create snapshot
+        snapshot := &RequestSnapshot{
+            Method:    r.Method,
+            URL:       cloneURL(r.URL),
+            Headers:   r.Header.Clone(),
+            Body:      body,
+            Host:      r.Host,
+            Timestamp: time.Now(),
+        }
+
+        // 3. Inject pointer into context
+        ctx := context.WithValue(r.Context(), SnapshotKey, snapshot)
+
+        // 4. Restore r.Body for downstream compatibility
+        r = r.WithContext(ctx)
+        r.Body = io.NopCloser(bytes.NewReader(snapshot.Body))
+
+        next.ServeHTTP(w, r)
+    })
+}
+```
+
+#### Phase 2: Downstream Consumption
+
+Consumers (Mirror/Record) retrieve the snapshot directly from context:
+
+```go
+snapshot, ok := r.Context().Value(SnapshotKey).(*RequestSnapshot)
+if ok {
+    // Use snapshot.Body directly instead of io.ReadAll(r.Body)
+}
+```
+
+## Hardware Considerations (Raspberry Pi Zero 2W)
+
+To protect MicroSD health and optimize for limited memory:
+
+1. **No Intermediate Disk Storage**: Snapshots exist only in memory; they are never written to disk until the final `.http` recording is generated.
+2. **Memory Management**: Use `sync.Pool` for temporary buffers to reduce GC churn on the single-core/low-memory SoC.
+3. **Automatic Cleanup**: Snapshots are naturally garbage collected once the Request Context and all child goroutines (detached mirrors/recordings) finish.
+4. **Body Capping**: Strict limits on snapshot size prevent OOM (Out-of-Memory) conditions.
+
+#### Phase 2: Response Capture System
+
+```go
+type ResponseRecorder struct {
+    http.ResponseWriter
+    snapshot     *ResponseSnapshot
+    snapshotID   string
+    source       string
+    startTime    time.Time
+}
+
+func (r *ResponseRecorder) WriteHeader(statusCode int) {
+    r.snapshot.StatusCode = statusCode
+    r.snapshot.Headers = r.Header().Clone()
+    r.ResponseWriter.WriteHeader(statusCode)
+}
+
+func (r *ResponseRecorder) Write(data []byte) (int, error) {
+    r.snapshot.Body = append(r.snapshot.Body, data...)
+    return r.ResponseWriter.Write(data)
+}
+
+func (r *ResponseRecorder) finalize() {
+    r.snapshot.Duration = time.Since(r.startTime)
+    r.snapshot.Timestamp = time.Now()
+}
+```
+
+#### Phase 3: Recording System Integration
+
+```go
+type RecordingManager struct {
+    storage   SnapshotStorage
+    recorder  *Recorder
+    patterns  []string
+}
+
+func (rm *RecordingManager) RecordInteraction(snapshotID string, response *ResponseSnapshot) {
+    // Retrieve immutable request snapshot
+    request, exists := rm.storage.Get(snapshotID)
+    if !exists {
+        log.Printf("Request snapshot not found: %s", snapshotID)
+        return
+    }
+
+    // Record with guaranteed data integrity
+    rm.recorder.RecordInteraction(request, response)
+}
+
+func (r *Recorder) RecordInteraction(req *RequestSnapshot, res *ResponseSnapshot) error {
+    // Generate .http file with complete data
+    var buf bytes.Buffer
+
+    // Write request
+    fmt.Fprintf(&buf, "### %s %s\n", req.Method, req.URL.String())
+    fmt.Fprintf(&buf, "%s %s\n", req.Method, req.URL.String())
+    fmt.Fprintf(&buf, "Host: %s\n", req.Host)
+
+    for k, vv := range req.Headers {
+        for _, v := range vv {
+            fmt.Fprintf(&buf, "%s: %s\n", k, v)
+        }
+    }
+
+    buf.WriteString("\n")
+    buf.Write(req.Body)
+    buf.WriteString("\n\n")
+
+    // Write response
+{% raw %}
+    buf.WriteString("> {% \n")
+{% endraw %}
+    fmt.Fprintf(&buf, "    // Response: %d %s\n", res.StatusCode, http.StatusText(res.StatusCode))
+    buf.WriteString("    // Headers:\n")
+
+    for k, vv := range res.Headers {
+        for _, v := range vv {
+            fmt.Fprintf(&buf, "    // %s: %s\n", k, v)
+        }
+    }
+
+{% raw %}
+    buf.WriteString("%}\n\n")
+{% endraw %}
+
+    if len(res.Body) > 0 {
+        buf.WriteString("/*\n")
+        buf.Write(res.Body)
+        buf.WriteString("\n*/\n")
+    } else {
+        buf.WriteString("// [Binary response body: 0 bytes]\n")
+    }
+
+    // Write to file
+    return r.writeToFile(buf.Bytes(), req, res)
+}
+```
+
+## Migration Strategy
+
+### Phase 1: Introduce Snapshot System
+- Add SnapshotMiddleware as first middleware
+- Maintain existing recording system for compatibility
+- Gradual migration of recording points
+
+### Phase 2: Update Mirror System
+- Modify MirrorMiddleware to use snapshots
+- Ensure mirror requests use snapshot data
+- Test parity between old and new systems
+
+### Phase 3: Consolidate Recording
+- Replace existing recording middleware
+- Unified recording system using context-bound snapshots
+- Remove duplicate body reading code
+
+### Phase 4: Cleanup
+- Remove legacy recording code
+- Optimize memory usage with sync.Pool
+- Performance validation on target hardware (Pi Zero)
+
+## Benefits
+
+1. **Zero Extra Disk IO**: Protecs MicroSD by avoiding snapshot disk persistence
+2. **Memory Efficiency**: Natural lifecycle tied to Request Context
+3. **Data Integrity**: Request data is captured once and remains immutable
+4. **Consistency**: All consumers use identical request data
+5. **Traceability**: Clear lineage from original request to all recordings
+6. **Performance**: Reduces duplicate body reads and re-cloning
+
+## Implementation Considerations
+
+### Memory Management
+- Use `sync.Pool` for byte buffers
+- Strict size limits on captured bodies
+- Rely on GC for snapshot cleanup
+
+### Performance Impact
+- Single body read vs multiple reads (net positive)
+- Memory overhead for snapshot storage (manageable)
+- Context propagation overhead (minimal)
+
+### Backward Compatibility
+- Maintain existing .http file format
+- Preserve existing API contracts
+- Gradual migration path
+
+## Testing Strategy
+
+### Unit Tests
+- Snapshot creation and immutability
+- Response recording accuracy
+- Memory cleanup verification
+
+### Integration Tests
+- End-to-end request/response recording
+- Mirror functionality with snapshots
+- Parity validation between old/new systems
+
+### Performance Tests
+- Memory usage comparison
+- Throughput impact analysis
+- Large request body handling
+
+## Future Enhancements
+
+1. **Compression**: Compress stored snapshots for memory efficiency
+2. **Streaming**: Support for streaming request/response bodies
+3. **Filtering**: Selective snapshot creation based on patterns
+4. **Analytics**: Request/response analysis and metrics
+5. **Export**: Snapshot export for debugging and analysis
+
+## Conclusion
+
+This snapshot-based approach provides a robust foundation for reliable request recording while solving the current issues with body consumption and data inconsistency. The phased implementation ensures minimal disruption while delivering immediate benefits.

docs/SCMUDC-ENRICHMENT-IMPLEMENTATION.md

@@ -0,0 +1,192 @@
+# SCMUDC Enrichment Implementation Summary
+
+## Overview
+
+This document summarizes the implementation of SCMUDC (Sound Control Management Usage Data Collection) event enrichment in the AfterTouch toolkit. The enhancement provides human-readable analysis of device telemetry data to improve usability and debugging capabilities.
+
+## Problem Solved
+
+Previously, SCMUDC telemetry events were stored as raw JSON with Base64-encoded XML content, making them difficult to analyze. Users had to manually decode content to understand what device interactions were being recorded.
+
+## Solution Implemented
+
+### 1. Backend Enrichment (`pkg/service/proxy/`)
+
+#### New File: `scmudc.go`
+- **SCMUDCRequest/SCMUDCEvent Structs**: Parse incoming telemetry JSON
+- **EnrichedSCMUDCEvent Struct**: Human-readable analysis with decoded content
+- **DecodedContent Struct**: Parsed XML metadata (track names, artwork URLs, etc.)
+- **enrichSCMUDCRequest()**: Main enrichment function that:
+  - Identifies event origin (app, hardware, or internal system)
+  - Decodes Base64 XML content for device events
+  - Creates human-readable summaries
+- **Helper Functions**: Button formatting, content summarization, origin descriptions
+
+#### Enhanced File: `recorder.go`
+- **Updated save() method**: Extracts SCMUDC data during recording
+- **New writeRequestWithEnrichment()**: Adds enriched comments to .http files
+- **New writeResponseWithEnrichment()**: Includes SCMUDC analysis in response section
+- **Updated Interaction struct**: Added `SCMUDCData` field for API responses
+- **New extractSCMUDCFromFile()**: Parses enrichment data from existing .http files
+- **Enhanced parseInteractionFile()**: Populates SCMUDC data when listing interactions
+
+### 2. Frontend Enhancement
+
+#### Updated HTML (`pkg/service/handlers/web/index.html`)
+- **New Column**: Added "Event Details" to interactions table
+- **Table Structure**: Updated to accommodate SCMUDC enrichment display
+
+#### Enhanced JavaScript (`pkg/service/handlers/web/js/script.js`)
+- **Updated fetchInteractions()**: Displays enriched SCMUDC data with icons
+- **New Helper Functions**:
+  - `getOriginIcon()`: Maps origins to emojis (📱 App, 🎛️ Hardware, 🔄 Internal)
+  - `getActionIcon()`: Maps actions to emojis (▶️ Play, ⏸️ Pause, etc.)
+  - `showSCMUDCDetails()`: Detailed popover for complex events
+  - `displaySCMUDCPopover()`: Modal dialog with full decoded content
+- **Truncation Logic**: Long content shows "(...)" with click-to-expand
+
+## Event Origin Clarification
+
+Based on analysis of recorded data:
+
+| Origin | Source | Description | Example Events |
+|--------|--------|-------------|----------------|
+| `gabbo` | **SoundTouch App** | Mobile/desktop app UI interactions | Play, Pause, Power via app |
+| `console` | **Device Hardware** | Physical buttons on speaker | Preset buttons, hardware power |
+| `device` | **Internal System** | Automatic device responses | Content playback, system actions |
+
+## Enhanced .http File Format
+
+### Before (Raw)
+```http
+### POST /v1/scmudc/A81B6A536A98
+POST /v1/scmudc/A81B6A536A98
+Host: events.api.bosecm.com
+...
+
+{"envelope":...,"payload":{"events":[{"data":{"contentItem":"PD94bWw..."}}]}}
+```
+
+### After (Enriched)
+```http
+### POST /v1/scmudc/A81B6A536A98
+// Origin: Internal System (device)
+// Action: play-item
+// Command: Billie Eilish - bad guy (instrumental version)
+// Summary: Device: Spotify: Billie Eilish - bad guy (instrumental version)
+//
+// Decoded Content:
+// - Source: SPOTIFY
+// - Item: Billie Eilish - bad guy (instrumental version)
+// - Account: gesellix
+// - Artwork: https://i.scdn.co/image/ab67616d0000b273...
+//
+// Full XML Content:
+// <?xml version="1.0" encoding="UTF-8"?>
+// <ContentItem source="SPOTIFY" type="tracklisturl" ...>
+//     <itemName>Billie Eilish - bad guy (instrumental version)</itemName>
+//     <containerArt>https://i.scdn.co/image/ab67616d0000b273...</containerArt>
+// </ContentItem>
+POST /v1/scmudc/A81B6A536A98
+...
+
+{% raw %}
+> {%
+    // Response: 200 OK
+    // SCMUDC Event Analysis:
+    // - Origin: Internal System (device)
+    // - Action: play-item
+    // - Summary: Device: Spotify: Billie Eilish - bad guy (instrumental version)
+    // - Content: Billie Eilish - bad guy (instrumental version)
+    // - Account: gesellix
+%}
+{% endraw %}
+```
+
+## Web UI Enhancement
+
+### Interactions Table
+- **New Column**: "Event Details" shows enriched summaries
+- **Visual Icons**: Origin and action type indicators
+- **Truncation**: Long content abbreviated with "(...)" expansion
+- **Backward Compatibility**: Works with existing recordings
+
+### Event Details Display
+```
+📱 ▶️ Play Button                    (Simple app action)
+🔄 🎵 Billie Eilish - bad guy... (...)  (Complex device event with details)
+🎛️ ⭐ Preset 5                        (Hardware preset button)
+```
+
+### Detailed Popover
+For complex events, clicking "(...)" shows:
+- **Origin Description**: "SoundTouch App" instead of "gabbo"
+- **Full Content Information**: Track names, artwork URLs, account details
+- **Complete XML**: Formatted and readable content item data
+
+## Implementation Benefits
+
+### For Users
+- **Immediate Recognition**: See what actions were performed without decoding
+- **Better Debugging**: Quick identification of app vs. hardware vs. system events
+- **Rich Context**: Track names, accounts, and content sources visible at a glance
+
+### For Developers
+- **Structured Data**: Consistent parsing and enrichment pipeline
+- **Extensible**: Easy to add new event types and origins
+- **Backward Compatible**: Existing recordings work without re-processing
+
+### For Analysis
+- **Pattern Recognition**: Quickly identify user behavior patterns
+- **Service Integration**: See which music services are being used
+- **Device Usage**: Understand app vs. hardware control preferences
+
+## File Structure
+
+```
+pkg/service/proxy/
+├── scmudc.go                 # New: SCMUDC enrichment logic
+├── recorder.go               # Enhanced: Enrichment integration
+│
+pkg/service/handlers/web/
+├── index.html                # Enhanced: New table column
+├── js/script.js              # Enhanced: SCMUDC display logic
+│
+docs/
+├── scmudc-events-analysis.md # New: Analysis documentation
+├── SCMUDC-ENRICHMENT-IMPLEMENTATION.md  # This file
+```
+
+## Technical Decisions
+
+### Base64 Decoding Strategy
+- **When**: During recording (not on-demand) for performance
+- **Fallback**: Parse from .http files if enrichment missing
+- **Storage**: Both enriched comments and structured data in API responses
+
+### Icon Selection
+- **Emoji Usage**: Universal, colorful, intuitive recognition
+- **Semantic Mapping**: Icons match function (📱 for app, 🎛️ for hardware)
+- **Fallback**: Generic icons (❓, 🔘) for unknown types
+
+### Backward Compatibility
+- **Graceful Degradation**: Missing enrichment data doesn't break UI
+- **File Parsing**: Extract enrichment from existing .http files
+- **API Enhancement**: New fields optional in Interaction struct
+
+## Future Enhancement Opportunities
+
+1. **Event Correlation**: Link device events to user actions
+2. **Statistics Dashboard**: Origin-based usage analytics
+3. **Content Recommendations**: Track listening patterns
+4. **Device Health**: Monitor interaction frequency and patterns
+5. **Export Features**: CSV/JSON export of enriched event data
+
+## Testing Considerations
+
+- **Edge Cases**: Malformed Base64, missing XML elements
+- **Performance**: Large numbers of SCMUDC events
+- **Browser Compatibility**: Emoji display across different browsers
+- **Data Validation**: Ensure enrichment doesn't introduce errors
+
+This implementation significantly improves the usability of SCMUDC telemetry data while maintaining full backward compatibility and raw data access for advanced users.

docs/SERVICE-AVAILABILITY-IMPLEMENTATION.md

@@ -23,7 +23,7 @@ This document summarizes the implementation of the `/serviceAvailability` endpoi
 ### Modified Files
 
 1. **`pkg/client/client.go`** - Added `GetServiceAvailability()` method
-2. **`docs/API-Endpoints-Overview.md`** - Updated implementation status
+2. **`docs/reference/API-ENDPOINTS.md`** - Updated implementation status
 3. **`docs/UNIMPLEMENTED-ENDPOINTS.md`** - Marked as implemented
 
 ## API Interface
@@ -263,4 +263,4 @@ BenchmarkGetServiceAvailability-8                         1000    1.2ms/op
 ✅ **Performance benchmarks established**  
 ✅ **Error handling verified**  
 
-The ServiceAvailability implementation is production-ready and provides a solid foundation for building user-friendly SoundTouch applications with better service discovery and user feedback capabilities.
+The ServiceAvailability implementation is production-ready and provides a solid foundation for building user-friendly SoundTouch applications with better service discovery and user feedback capabilities.

docs/SOUNDTOUCH-SERVICE-ANNOUNCEMENT.md

@@ -0,0 +1,190 @@
+# 🎉 Introducing SoundTouch Service: Local Cloud Service Emulation
+
+**Date**: January 2024  
+**Version**: v2.0.0+  
+**Status**: Production Ready
+
+## What's New?
+
+We're excited to announce the addition of `soundtouch-service`, a comprehensive local server that emulates Bose's cloud services for SoundTouch devices. This major addition provides offline operation capabilities and advanced device management features.
+
+## 🌟 Key Features
+
+### 🏠 Complete Service Emulation
+- **BMX Services**: Full Bose Media eXchange implementation for TuneIn, podcasts, and media streaming
+- **Marge Services**: Account and device management, preset synchronization, recent items tracking
+- **Offline Operation**: Continue using your devices without internet connectivity to Bose servers
+
+### 🔧 Device Migration
+- **Seamless Migration**: One-click migration from Bose cloud to local services
+- **Configuration Backup**: Automatic backup of existing device settings
+- **Rollback Support**: Easy restoration to original Bose cloud configuration
+- **Migration Preview**: Analyze what will change before applying updates
+
+### 📊 Advanced Debugging
+- **Traffic Proxying**: Intercept and log all device communications
+- **Real-time Monitoring**: Live device event streaming and status tracking
+- **Analytics Dashboard**: Usage statistics and error reporting
+- **Debug Tools**: Comprehensive troubleshooting utilities
+
+### 🌐 Web Management Interface
+- **Device Dashboard**: Visual overview of all discovered devices
+- **Migration Wizard**: Step-by-step guided device configuration
+- **Live Monitoring**: Real-time device status and event streaming
+- **Configuration Viewer**: Inspect and modify device settings
+
+## 🚨 Why This Matters
+
+### Bose Cloud Service Discontinuation
+Bose has announced that [SoundTouch cloud support will end on May 6, 2026](https://www.bose.com/soundtouch-end-of-life). This service provides a complete local alternative, ensuring your devices continue to work with full functionality beyond the official support timeline.
+
+### Enhanced Privacy & Control
+- **Local Processing**: All data stays on your network
+- **No External Dependencies**: Operate completely offline
+- **Custom Integrations**: Build your own automation and controls
+- **Traffic Visibility**: See exactly what your devices are doing
+
+## 🛠️ Installation & Quick Start
+
+### Install
+```bash
+go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
+```
+
+### Run
+```bash
+soundtouch-service
+```
+
+### Access Web UI
+Open `http://localhost:8000` in your browser and start managing your devices!
+
+## 📖 Implementation Credits
+
+This service implementation builds upon excellent community work:
+
+### 🍾 SoundCork Foundation
+Our implementation is heavily inspired by and based on [SoundCork](https://github.com/deborahgu/soundcork) by Deborah Gu and contributors. SoundCork pioneered the approach of intercepting Bose's cloud services and provided the architectural foundation for offline SoundTouch operation.
+
+**Key contributions from SoundCork:**
+- Service emulation architecture
+- BMX/Marge endpoint discovery  
+- Device migration strategies
+- Python implementation reference
+
+### 🎵 ÜberBöse API Insights
+[ÜberBöse API](https://github.com/julius-d/ueberboese-api) by Julius D. provided valuable insights into advanced SoundTouch API endpoints, helping make our implementation more complete and robust.
+
+### 🏠 SoundTouch Plus Documentation
+The [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) provided comprehensive API documentation that enabled many of the advanced features.
+
+## 🔄 What's Different in Our Go Implementation
+
+While inspired by SoundCork's Python implementation, our Go service offers:
+
+### Performance & Efficiency
+- **Native Compilation**: Single binary deployment with no runtime dependencies
+- **Low Resource Usage**: ~50MB memory footprint vs Python's higher overhead
+- **Concurrent Processing**: Go's goroutines enable efficient concurrent device handling
+- **Fast Startup**: Sub-second service startup time
+
+### Enhanced Features
+- **Web Management UI**: Built-in browser-based interface (SoundCork is API-only)
+- **Real-time Event Streaming**: WebSocket-based live device monitoring
+- **Advanced Migration Tools**: Migration preview and rollback capabilities
+- **Comprehensive Logging**: Structured logging with multiple output formats
+
+### Production Readiness
+- **Zero Dependencies**: Single binary with embedded web UI
+- **Cross-Platform**: Windows, macOS, Linux support out of the box
+- **Docker Ready**: Containerization support (planned)
+- **Monitoring Integration**: Health checks and metrics endpoints
+
+### Developer Experience
+- **Go Ecosystem**: Integrates with existing Go applications and infrastructure
+- **Type Safety**: Compile-time checks and robust error handling
+- **Documentation**: Comprehensive API documentation and examples
+- **Testing**: Extensive test coverage with real device validation
+
+## 🎯 Use Cases
+
+### Home Automation Enthusiasts
+```bash
+# Migrate all devices and integrate with Home Assistant
+soundtouch-service
+# Configure HA to use local service endpoints
+```
+
+### Developers & Integrators
+```go
+// Build custom applications on top of local services
+client := &http.Client{}
+resp, _ := client.Get("http://localhost:8000/setup/devices")
+```
+
+### Privacy-Conscious Users
+```bash
+# Run completely offline with full device functionality
+soundtouch-service --bind 127.0.0.1  # localhost only
+```
+
+### Network Administrators
+```bash
+# Monitor and log all device traffic
+LOG_PROXY_BODY=true soundtouch-service
+```
+
+## 🚀 Future Plans
+
+- **Docker Images**: Official container images for easy deployment
+- **Cluster Support**: Multi-instance deployment for high availability  
+- **Advanced Analytics**: Machine learning-powered usage insights
+- **Extended Protocol Support**: Additional Bose protocol implementations
+- **Mobile App**: Companion mobile application for device management
+
+## 📚 Documentation
+
+- **[Complete Service Guide](guides/SOUNDTOUCH-SERVICE.md)**: Comprehensive setup and configuration
+- **[API Reference](guides/SOUNDTOUCH-SERVICE.md#api-reference)**: Full endpoint documentation
+- **[Migration Guide](guides/SOUNDTOUCH-SERVICE.md#device-migration)**: Step-by-step device migration
+- **[Troubleshooting](guides/SOUNDTOUCH-SERVICE.md#troubleshooting)**: Common issues and solutions
+
+## 🤝 Contributing
+
+We welcome contributions to improve the service! Areas where help is especially appreciated:
+
+- **Protocol Research**: Discovering new Bose service endpoints
+- **Testing**: Validation with different device models and firmware versions
+- **Documentation**: Usage examples and troubleshooting guides
+- **Features**: Additional service implementations and integrations
+
+## 🙏 Community Thanks
+
+This implementation wouldn't have been possible without the groundbreaking work of the SoundTouch community:
+
+- **SoundCork Team**: For pioneering service interception and providing the implementation blueprint
+- **ÜberBöse Project**: For advanced API research and endpoint discovery
+- **SoundTouch Plus**: For comprehensive API documentation and real-world usage patterns
+- **Community Contributors**: For testing, feedback, and continued development
+
+The collaborative spirit of reverse engineering and documentation in the SoundTouch community has been invaluable. We're proud to contribute back to this ecosystem and help ensure SoundTouch devices remain useful beyond Bose's official support timeline.
+
+## 🔗 Links
+
+- **[Main Repository](https://github.com/gesellix/bose-soundtouch)**
+- **[Service Documentation](guides/SOUNDTOUCH-SERVICE.md)**
+- **[CLI Documentation](guides/CLI-REFERENCE.md)**
+- **[Getting Started Guide](guides/GETTING-STARTED.md)**
+- **[SoundCork Project](https://github.com/deborahgu/soundcork)**
+- **[ÜberBöse API](https://github.com/julius-d/ueberboese-api)**
+
+---
+
+**Ready to take control of your SoundTouch devices?** Get started with `soundtouch-service` today!
+
+```bash
+go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
+soundtouch-service
+```
+
+Open `http://localhost:8000` and start your journey to local SoundTouch control! 🎵

docs/SUMMARY.md

@@ -0,0 +1,102 @@
+# Table of Contents
+
+* [Introduction](README.md)
+
+## User Guides
+* [Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)
+* [Self-Hosting AfterTouch](guides/SELF-HOSTING.md)
+* [Connecting Music Services](guides/MUSIC-SERVICES.md)
+* [Migration & Safety Guide](guides/MIGRATION-SAFETY.md)
+* [CLI Reference](guides/CLI-REFERENCE.md)
+* [Backup Tool](../cmd/soundtouch-backup/README.md)
+* [Getting Started](guides/GETTING-STARTED.md)
+* [SoundTouch Service](guides/SOUNDTOUCH-SERVICE.md)
+* [Initial Device Setup](guides/DEVICE-INITIAL-SETUP.md)
+* [Capture Device Pairing Traffic](guides/CAPTURE-DEVICE-PAIRING.md)
+* [Capture Migration Traffic](guides/CAPTURE-MIGRATION-TRAFFIC.md)
+* [Device Setup Flow](DEVICE-SETUP.md)
+* [MAC Address Mapping](guides/MAC-ADDRESS-MAPPING.md)
+* [HTTPS Setup](guides/HTTPS-SETUP.md)
+* [Deployment](guides/DEPLOYMENT.md)
+* [Raspberry Pi Guide](guides/RASPBERRY-PI.md)
+* [Troubleshooting](guides/TROUBLESHOOTING.md)
+* [IoT Implementation Guide](guides/IOT-IMPLEMENTATION-GUIDE.md)
+* [Migration Guide](guides/MIGRATION-GUIDE.md)
+* [MQTT Integration Design](guides/MQTT-INTEGRATION-DESIGN.md)
+* [Useful Links](#useful-links)
+
+### Useful Links
+* [Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)
+* [Raspberry Pi Installer](../scripts/raspberry-pi/README.md)
+* [Updating the Service](../scripts/raspberry-pi/README.md#updating-to-a-new-version)
+* [CLI Reference](guides/CLI-REFERENCE.md)
+
+## Technical Reference
+* [API Cookbook](reference/API-COOKBOOK.md)
+* [API Endpoints](reference/API-ENDPOINTS.md)
+* [Spotify Account Addition](reference/spotify-account-addition.md)
+* [Cloud API Emulation](reference/CLOUD-API.md)
+* [System Endpoints](reference/SYSTEM-ENDPOINTS.md)
+* [Speaker Endpoint](reference/SPEAKER-ENDPOINT.md)
+* [WebSocket Events](reference/WEBSOCKET-EVENTS.md)
+* [Device Pairing Flow](reference/DEVICE-PAIRING-FLOW.md)
+* [Discovery](reference/DISCOVERY.md)
+* [Zone Management](reference/ZONE-MANAGEMENT.md)
+* [Preset Management](reference/PRESET-MANAGEMENT.md)
+* [Source Selection](reference/SOURCE-SELECTION.md)
+* [Volume Controls](reference/VOLUME-CONTROLS.md)
+* [RadioBrowser](reference/radio-browser.md)
+* [Bass Controls](reference/BASS-CONTROLS.md)
+* [Key Controls](reference/KEY-CONTROLS.md)
+* [Feature Mapping](reference/FEATURE-MAPPING.md)
+
+## Concepts
+* [Request Recording](REQUEST_RECORDING_CONCEPT.md)
+* [Spotify Priming Strategy](concepts/spotify-priming-strategy.md)
+* [Spotify OAuth](concepts/spotify-oauth.md)
+
+## Analysis & Research
+* [API Coverage Analysis](analysis/API-COVERAGE.md)
+* [Supported URLs](analysis/SUPPORTED-URLS.md)
+* [Upstream URLs](analysis/UPSTREAM-URLS.md)
+* [Anonymization Summary](analysis/ANONYMIZATION-SUMMARY.md)
+* [Device Redirect Methods](analysis/DEVICE-REDIRECT-METHODS.md)
+* [Wiki API Comparison](analysis/WIKI-COMPARISON.md)
+* [IoT Config Summary](analysis/IOT-CONFIG-SUMMARY.md)
+* [IoT Configuration Analysis](analysis/IOT-CONFIGURATION-ANALYSIS.md)
+* [Bose Lab Runbook](analysis/BOSE-LAB-RUNBOOK.md)
+* [Missing Routes Spotify](analysis/MISSING-ROUTES-SPOTIFY.md)
+* [Bose App ADB Emulator](analysis/BOSE-APP-ADB-Emulator.md)
+* [Community Tools](analysis/bose-soundtouch-community-tools.md)
+
+## Parity Analysis
+* [Parity Improvements](PARITY-IMPROVEMENTS.md)
+* [Parity SoundCork](PARITY-SOUNDCORK.md)
+* [Parity OpenCloudTouch](PARITY-OPENCLOUDTOUCH.md)
+
+## Appendix (Other Documents)
+* [External Services Abstraction](EXTERNAL-SERVICES-ABSTRACTION.md)
+* [API Navigation Reference](API-NAVIGATION-REFERENCE.md)
+* [Claude Instructions](CLAUDE.md)
+* [Content Selection Implementation](CONTENT-SELECTION-IMPLEMENTATION.md)
+* [Device Customization Setup](DEVICE-CUSTOMIZATION-SETUP.md)
+* [Device Logging](DEVICE-LOGGING.md)
+* [Feature History](FEATURE_HISTORY.md)
+* [Host/Port Parsing](HOST-PORT-PARSING.md)
+* [Manual Network Discovery](MANUAL-NETWORK-DISCOVERY.md)
+* [Navigation Guide](NAVIGATION-GUIDE.md)
+* [Official API Verification](OFFICIAL-API-VERIFICATION.md)
+* [Preset Quickstart](PRESET-QUICKSTART.md)
+* [Project Patterns](PROJECT-PATTERNS.md)
+* [Service Availability Implementation](SERVICE-AVAILABILITY-IMPLEMENTATION.md)
+* [SoundTouch Service Announcement](SOUNDTOUCH-SERVICE-ANNOUNCEMENT.md)
+* [Undocumented Community Features](UNDOCUMENTED-COMMUNITY-FEATURES.md)
+* [Unimplemented Endpoints](UNIMPLEMENTED-ENDPOINTS.md)
+* [Preset Store](preset-store.md)
+* [SCMUDC Enrichment Implementation](SCMUDC-ENRICHMENT-IMPLEMENTATION.md)
+* [Device Lifecycle and Power On Enhancement](device-lifecycle-and-power-on-enhancement.md)
+* [Device Lifecycle Summary](device-lifecycle-summary.md)
+* [Power On Implementation Guide](power-on-implementation-guide.md)
+* [SCMUDC Events Analysis](scmudc-events-analysis.md)
+* [Parity Improvements](PARITY-IMPROVEMENTS.md)
+* [Parity SoundCork](PARITY-SOUNDCORK.md)

docs/UNDOCUMENTED-COMMUNITY-FEATURES.md

@@ -0,0 +1,46 @@
+# Undocumented Community Features & API Discoveries
+This document captures advanced API endpoints and device behaviors discovered by the SoundTouch community through reverse engineering projects like **SoundCork** and **ÜberBöse API**. These features are not documented in the official Bose SoundTouch Web API v1.0 but are crucial for full device emulation and offline operation.
+## Cloud Emulation (Marge/BMX) Discoveries
+While the local `/8090` API is well-documented, the cloud-side service emulation reveals deeper device integration points.
+### 1. Stereo Pairing & Cloud-Side Grouping
+SoundCork has pioneered the emulation of "Marge" group endpoints, which differ from the local `/getGroup` API. These are primarily used for persistent configurations like **Stereo Pairs** (e.g., two ST-10s).
+- **GET** `/marge/streaming/account/{account}/device/{device}/group`
+  Returns `<group/>` if ungrouped, or full group configuration for stereo pairs.
+- **POST** `/marge/streaming/account/{account}/group`
+  Creates a new group (returns a 7-digit group ID). Used for initial pairing.
+- **DELETE** `/marge/streaming/account/{account}/group/{group}`
+  Dissolves a group configuration.
+### 2. Device Analytics & Event Reporting
+Devices report real-time telemetry to the cloud. Intercepting these provides a window into device usage without polling.
+- **Endpoint**: `POST /v1/scmudc/{deviceId}`
+- **Function**: Submits event data including `play-state-changed`, `preset-pressed`, `power-pressed`, `source-state-changed`, and `art-changed` (Metadata updates). This endpoint was first extensively documented in the **ÜberBöse API** specification.
+### 3. Power-On Lifecycle
+When a SoundTouch device boots or "powers on" (distinct from waking from standby), it contacts specific support endpoints.
+- **Endpoint**: `POST /streaming/support/power_on`
+- **Behavior**: Reports device serial number, IP address, and diagnostic data.
+- **Critical Finding**: SoundTouch devices fetch `TUNEIN` and `LOCAL_INTERNET_RADIO` source availability from the cloud **ONLY at boot time**. If the cloud is unreachable during a hard reboot (power cycle), these sources will disappear from the device's `/sources` list and become unavailable, even if the local API is working. This behavior was analyzed and reported by the **ÜberBöse API** project (Issue #3).
+### 4. OAuth & Service Tokens
+Integration with music services (Spotify, Pandora, etc.) involves specific token management endpoints.
+- **Endpoint**: `POST /oauth/device/{deviceId}/music/musicprovider/{providerId}/token/{tokenType}`
+- **Usage**: Used to refresh or validate session tokens for cloud-based music providers.
+## Community-Driven Extensions
+The community is working on extending SoundTouch functionality beyond its original design.
+### 1. Radio-Browser.info Integration
+There is an active effort to add `radio-browser.info` as a native `sourceprovider`. This would allow devices to browse a massive directory of thousands of stations without relying on the TuneIn cloud service.
+- **Status**: Research phase in SoundCork (Issue #150).
+- **Implementation**: Requires adding a new source provider entry in the emulated `/streaming/sourceproviders` response.
+### 2. Stockholm Internal App Analysis
+Deep analysis of the Stockholm (device firmware) internal web application reveals a set of internal AJAX/XML calls used by the device's own control interface.
+- **Internal Domains**: `Marge` (XML-based) and `Gabbo` (App-send based).
+- **Reference**: See SoundCork Issue #128 for a comprehensive list of internal JS controllers and their functions.
+### 3. ETag Case-Sensitivity Bug
+The SoundTouch device firmware has a case-sensitivity bug regarding HTTP `ETag` headers.
+- **Discovery**: SoundCork Issue #129.
+- **Detail**: The device expects the `ETag` header to be exactly title-cased. If a server returns `etag` (lowercase), the device fails to use it for `If-None-Match` requests, breaking efficient preset synchronization.
+- **Solution**: Force title-casing of the header via a reverse proxy like Nginx or mitmproxy.
+## References
+- [SoundCork GitHub Repo](https://github.com/deborahgu/soundcork)
+- [ÜberBöse API Spec](https://github.com/julius-d/ueberboese-api)
+- [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
+- [IsItBose Regex Research](https://github.com/deborahgu/soundcork/issues/62#issuecomment-3610563908)
+- [SoundTouch Hook Repo](https://github.com/CodeFinder2/bose-soundtouch-hook)

docs/UNIMPLEMENTED-ENDPOINTS.md

@@ -12,10 +12,10 @@ This document provides comprehensive information about SoundTouch API endpoints
 
 ## Implementation Priority Matrix
 
-### 🔥 Critical Priority (14 endpoints)
+### 🔥 Critical Priority (12 endpoints)
 Essential user functionality that significantly impacts user experience.
 
-### 🎯 High Priority (15 endpoints)  
+### 🎯 High Priority (13 endpoints)
 Smart home integration and advanced user features.
 
 ### 📊 Medium Priority (19 endpoints)
@@ -267,24 +267,7 @@ Rates currently playing media (Pandora only).
 
 ### System Information
 
-#### GET /recents 🔥 **CRITICAL**
-Returns recently played media content.
 
-**Response Example:**
-```xml
-<recents>
-  <recent deviceID="1004567890AA" utcTime="1701202831">
-    <contentItem source="STORED_MUSIC" location="6_a2874b5d_4f83d999" sourceAccount="d09708a1-5953-44bc-a413-123456789012/0" isPresetable="true">
-      <itemName>MercyMe, It's Christmas!</itemName>
-    </contentItem>
-  </recent>
-  <recent deviceID="1004567890AA" utcTime="1700232917" id="2487503626">
-    <contentItem source="LOCAL_MUSIC" type="track" location="track:2590" sourceAccount="3f205110-4a57-4e91-810a-123456789012" isPresetable="true">
-      <itemName>Baby It's Cold Outside - ANNE MURRAY</itemName>
-    </contentItem>
-  </recent>
-</recents>
-```
 
 #### GET /listMediaServers 🔥 **CRITICAL**
 Returns detected UPnP/DLNA media servers.
@@ -323,22 +306,7 @@ Returns source service availability status.
 </serviceAvailability>
 ```
 
-#### POST /introspect 🔥 **CRITICAL**
-Retrieves introspect data for specified music service.
 
-**Request Example:**
-```xml
-<introspect source="SPOTIFY" sourceAccount="SpotifyConnectUserName" />
-```
-
-**Response Example:**
-```xml
-<spotifyAccountIntrospectResponse state="InactiveUnselected" user="SpotifyConnectUserName" isPlaying="false" tokenLastChangedTimeSeconds="1702566495" tokenLastChangedTimeMicroseconds="427884" shuffleMode="OFF" playStatusState="2" currentUri="" receivedPlaybackRequest="false" subscriptionType="">
-  <cachedPlaybackRequest />
-  <nowPlaying skipPreviousSupported="false" seekSupported="false" resumeSupported="true" collectData="true" />
-  <contentItemHistory maxSize="10" />
-</spotifyAccountIntrospectResponse>
-```
 
 ### Power Management
 
@@ -382,60 +350,50 @@ Places device into low-power mode.
 
 ## High Priority Implementation Candidates
 
-### Notification System (ST-10 Series Only)
+### ~~Notification System (ST-10 Series Only)~~ ✅ **IMPLEMENTED**
 
-#### POST /speaker 🎯 **HIGH**
+#### ~~POST /speaker~~ ✅ **IMPLEMENTED**
 Plays TTS messages or URL content for notifications.
 
-**TTS Message Example:**
-```xml
-<play_info>
-  <url>http://translate.google.com/translate_tts?ie=UTF-8&amp;tl=EN&amp;client=tw-ob&amp;q=There%20is%20activity%20at%20the%20front%20door.</url>
-  <app_key>Xp7YGBI9dh763Kj8sY8e86JPXtisddBa</app_key>
-  <service>TTS Notification</service>
-  <message>Google TTS</message>
-  <reason>There is activity at the front door.</reason>
-  <volume>70</volume>
-</play_info>
+**CLI Usage:**
+```bash
+# TTS with multiple languages
+soundtouch-cli speaker tts --text "Hello World" --app-key YOUR_KEY --language EN --volume 70
+
+# URL content playback
+soundtouch-cli speaker url --url "https://example.com/audio.mp3" --app-key YOUR_KEY --volume 60
+
+# Simple notification beep
+soundtouch-cli speaker beep
 ```
 
-**URL Playback Example:**
-```xml
-<play_info>
-  <url>https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_1MB_MP3.mp3</url>
-  <app_key>Xp7YGBI9dh763Kj8sY8e86JPXtisddBa</app_key>
-  <service>FreeTestData.com</service>
-  <message>MP3 Test Data</message>
-  <reason>Free_Test_Data_1MB_MP3</reason>
-  <volume>70</volume>
-</play_info>
+**Go Client Usage:**
+```go
+// Text-to-Speech
+client.PlayTTS("Hello World", "your-app-key", "EN", 70)
+
+// URL content
+client.PlayURL("https://example.com/audio.mp3", "your-app-key", "Service", "Message", "Reason", 60)
+
+// Notification beep
+client.PlayNotificationBeep()
 ```
 
-**Response:**
-```xml
-<status>/speaker</status>
-```
+**Implementation Features:**
+- ✅ Complete TTS support with multi-language (EN, DE, ES, FR, IT, NL, PT, RU, ZH, JA, etc.)
+- ✅ URL content playback with custom metadata
+- ✅ Volume control with automatic restoration
+- ✅ Comprehensive CLI commands with help system
+- ✅ Full validation and error handling
+- ✅ Complete test suite and documentation
 
-**Implementation Notes:**
-- Only works on ST-10 series devices
-- Requires app_key parameter (user-provided)
-- Volume automatically restored after playback
-- Currently playing content paused/resumed automatically
-- NowPlaying status shows notification details during playback
-
-#### GET /playNotification 🎯 **HIGH**
+#### ~~GET /playNotification~~ ✅ **IMPLEMENTED**
 Plays a notification beep sound.
 
-**Response:**
-```xml
-<status>/playNotification</status>
-```
-
-**Implementation Notes:**
-- Causes double beep sound
-- Pauses current media, plays beep, resumes media
-- ST-10 only feature
-- ST-300 does not support this despite documentation
+**Implementation:**
+- ✅ `PlayNotificationBeep()` method
+- ✅ CLI command: `soundtouch-cli speaker beep`
+- ✅ Proper error handling for unsupported devices
 
 ### WiFi Management
 
@@ -1086,4 +1044,4 @@ The SoundTouch Plus Wiki provides comprehensive documentation for **64 additiona
 
 This documentation provides the complete foundation for implementing all endpoints from the SoundTouch Plus Wiki, enabling this Go library to become the definitive SoundTouch integration solution for everything from basic home automation to professional audio installations.
 
-*All examples and XML structures are verified against real SoundTouch hardware and extensively tested by the SoundTouch Plus community.*
+*All examples and XML structures are verified against real SoundTouch hardware and extensively tested by the SoundTouch Plus community.*

docs/_config.yml

@@ -0,0 +1,11 @@
+title: Bose SoundTouch Toolkit
+description: Documentation for controlling and preserving Bose SoundTouch devices
+remote_theme: pages-themes/minimal@v0.2.0
+plugins:
+  - jekyll-remote-theme
+  - jekyll-relative-links
+relative_links:
+  enabled: true
+  collections: true
+include:
+  - SUMMARY.md

docs/analysis/API-COVERAGE.md

@@ -20,7 +20,7 @@ This Go implementation provides **complete coverage** of the Bose SoundTouch Web
 
 ## Official API v1.0 Endpoint Coverage
 
-### Implemented Endpoints: 18/19 (95%)
+### Implemented Endpoints: 20/21 (95%)
 
 | Endpoint | Method | Status | Implementation | Notes |
 |----------|--------|--------|----------------|--------|
@@ -43,8 +43,10 @@ This Go implementation provides **complete coverage** of the Bose SoundTouch Web
 | `/audiodspcontrols` | GET/POST | ✅ **Complete** | `GetAudioDSPControls()`, `SetAudioDSPControls()`, `SetAudioMode()`, `SetVideoSyncAudioDelay()` | DSP audio modes and video sync delay |
 | `/audioproducttonecontrols` | GET/POST | ✅ **Complete** | `GetAudioProductToneControls()`, `SetAudioProductToneControls()`, `SetAdvancedBass()`, `SetAdvancedTreble()` | Advanced bass/treble controls |
 | `/audioproductlevelcontrols` | GET/POST | ✅ **Complete** | `GetAudioProductLevelControls()`, `SetAudioProductLevelControls()`, `SetFrontCenterSpeakerLevel()`, `SetRearSurroundSpeakersLevel()` | Speaker level controls |
+| `/speaker` | POST | ✅ **Complete** | `PlayTTS()`, `PlayURL()`, `PlayCustom()` | TTS and URL content playback for notifications |
+| `/playNotification` | GET | ✅ **Complete** | `PlayNotificationBeep()` | Simple notification beep sound |
 
-### Non-functional Endpoints: 1/19 (5%)
+### Non-functional Endpoints: 1/21 (5%)
 
 | Endpoint | Method | Status | Reason | Impact |
 |----------|--------|--------|--------|---------|
@@ -63,6 +65,8 @@ This Go implementation provides **complete coverage** of the Bose SoundTouch Web
 
 ### Additional Endpoints: 5 Extra Features
 
+**Note**: The `/speaker` and `/playNotification` endpoints were discovered via the [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) and are now part of the official coverage.
+
 | Endpoint | Method | Status | Notes |
 |----------|--------|--------|--------|
 | `/name` | GET | 🔍 **Extra** | Official API only documents POST, but GET works with real hardware |
@@ -204,12 +208,13 @@ Missing only niche professional features:
 ## Conclusion
 
 This implementation achieves **complete API coverage** with:
-- ✅ **95% functional endpoint implementation** (18/19)
-- ✅ **100% official API endpoint implementation** (19/19)
+- ✅ **95% functional endpoint implementation** (20/21)
+- ✅ **100% official API endpoint implementation** (21/21)
 - ✅ **100% essential functionality coverage**
 - ✅ **Superior implementations** for complex operations
 - ✅ **Extended features** beyond official specification
 - ✅ **Complete advanced audio controls** for professional devices
+- ✅ **Complete notification system** (TTS, URL playback, beep notifications)
 - ✅ **Comprehensive testing and validation**
 
 The single non-functional endpoint (`/trackInfo`) is **broken on real devices** despite being documented in the official API, but identical functionality is available via `/now_playing`. The implementation **exceeds the official API** in many areas through enhanced safety features, complete zone management, advanced audio controls, and real-time event capabilities.

docs/analysis/BOSE-APP-ADB-Emulator.md

@@ -0,0 +1,364 @@
+# Bose SoundTouch Traffic Interception Runbook
+
+Intercept HTTPS/WebSocket traffic from the Bose SoundTouch Android app using an Android emulator, mitmproxy, and Frida. Tested on Apple Silicon (ARM64) Mac.
+
+## Automated Setup
+
+The steps in this document are scripted for reproducibility:
+
+```bash
+scripts/android/setup-mitm-avd.sh   # one-time: create AVD, install cert & APK, save snapshot
+scripts/android/start-mitm-session.sh  # per-session: restore snapshot, refresh proxy, start frida-server
+```
+
+Read on for the full manual walkthrough and the rationale behind each step.
+
+> **Note:** The manual steps below use `/tmp/` for intermediate files and reflect the original approach. The automated scripts supersede them — use the scripts for day-to-day use and refer here only to understand how things work.
+
+---
+
+## Prerequisites
+
+- Android Studio installed (for SDK tools and emulator)
+- Docker installed
+- mitmproxy installed (`pip install mitmproxy` or via your preferred method)
+- The Bose SoundTouch APK (extracted from a real device, see below)
+
+> **BLE limitation**: Android emulators do not expose Bluetooth hardware. The Bose app's default setup path (BLE Wi-Fi provisioning) therefore cannot be used to configure a factory-reset speaker from the emulator. Use **AP mode** instead: provision the speaker's Wi-Fi credentials via the Mac command line first (see [DEVICE-INITIAL-SETUP.md § 6](../guides/DEVICE-INITIAL-SETUP.md)), then the app can discover the already-networked speaker via mDNS/SSDP without BLE.
+
+> **Emulator ↔ local network**: The emulator routes all traffic through the Mac's active network interface. Once the speaker is on the same LAN as the Mac, the emulator can reach it at its normal LAN IP (e.g. `192.168.1.50`) — no extra routing is needed. Use `adb shell ping 192.168.1.50` to confirm reachability.
+
+Add Android SDK tools to your PATH (add to `~/.zshrc`):
+
+```bash
+export PATH=$PATH:~/Library/Android/sdk/emulator
+export PATH=$PATH:~/Library/Android/sdk/platform-tools
+```
+
+---
+
+## 1. Extract APK from Real Device
+
+Connect your Android device via USB with USB debugging enabled.
+
+```bash
+adb devices
+# note your device ID, e.g. "ABC123"
+
+adb -s ABC123 shell pm path com.bose.soundtouch
+# output e.g.: package:/data/app/~~xyz/com.bose.soundtouch-abc/base.apk
+
+adb -s ABC123 pull /data/app/~~xyz/com.bose.soundtouch-abc/base.apk bose.apk
+```
+
+---
+
+## 2. Create Android Emulator (ARM64, API 33)
+
+On Apple Silicon you need an ARM64 image. Use the `avdmanager` and `sdkmanager` CLI tools.
+
+```bash
+# Install the system image
+~/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager \
+  "system-images;android-33;google_apis;arm64-v8a"
+
+# Create the AVD
+~/Library/Android/sdk/cmdline-tools/latest/bin/avdmanager create avd \
+  -n Pixel_6_API33 \
+  -k "system-images;android-33;google_apis;arm64-v8a" \
+  -d "pixel_6"
+```
+
+Alternatively create the AVD via Android Studio Device Manager (choose "Google APIs", arm64-v8a, API 33).
+
+---
+
+## 3. Start Emulator with Writable System
+
+```bash
+# List available AVDs
+~/Library/Android/sdk/emulator/emulator -list-avds
+
+# Start with writable system partition
+~/Library/Android/sdk/emulator/emulator -avd Pixel_6_API33 -writable-system
+```
+
+Wait until the emulator has fully booted, then:
+
+```bash
+adb -s emulator-5554 root
+adb -s emulator-5554 shell avbctl disable-verification
+adb -s emulator-5554 reboot
+
+# After reboot:
+adb -s emulator-5554 root
+```
+
+---
+
+## 4. Install Bose APK
+
+```bash
+adb -s emulator-5554 install bose.apk
+```
+
+---
+
+## 5. Set Up mitmproxy
+
+```bash
+# Start mitmproxy (generates CA cert on first run)
+# Use the native macOS app — Docker mitmproxy does not work (NAT blocks emulator traffic)
+mitmweb --listen-port 8080 --mode regular -w bose_traffic.mitm
+```
+
+Extract the CA certificate (without private key):
+
+```bash
+openssl x509 -in ~/.mitmproxy/mitmproxy-ca.pem -out ~/.mitmproxy/mitmproxy-ca-cert.pem
+
+# Verify it's the mitmproxy cert, not another cert:
+openssl x509 -in ~/.mitmproxy/mitmproxy-ca-cert.pem -noout -issuer
+# should show: issuer= /CN=mitmproxy/O=mitmproxy
+```
+
+---
+
+## 6. Install mitmproxy CA Certificate in Emulator
+
+```bash
+HASH=$(openssl x509 -inform PEM -subject_hash_old \
+  -in ~/.mitmproxy/mitmproxy-ca-cert.pem | head -1)
+
+adb -s emulator-5554 push ~/.mitmproxy/mitmproxy-ca-cert.pem /data/local/tmp/mitmproxy.pem
+
+adb -s emulator-5554 shell su 0 mkdir -p /data/misc/user/0/cacerts-added
+
+adb -s emulator-5554 shell su 0 \
+  cp /data/local/tmp/mitmproxy.pem /data/misc/user/0/cacerts-added/${HASH}.0
+
+adb -s emulator-5554 shell su 0 \
+  chmod 644 /data/misc/user/0/cacerts-added/${HASH}.0
+```
+
+---
+
+## 7. Set System Proxy in Emulator
+
+Find your Mac's local IP:
+
+```bash
+ipconfig getifaddr en0
+# e.g. 192.168.1.123
+```
+
+Set the proxy:
+
+```bash
+adb -s emulator-5554 shell settings put global http_proxy 192.168.1.123:8080
+```
+
+---
+
+## 8. Set Up Frida (via Python venv)
+
+```bash
+python3 -m venv /tmp/frida-venv
+/tmp/frida-venv/bin/pip install frida==17.9.1 frida-tools==14.8.1
+```
+
+Download the frida-server binary for ARM64 Android:
+
+```bash
+FRIDA_VERSION=17.9.1
+
+curl -L "https://github.com/frida/frida/releases/download/${FRIDA_VERSION}/frida-server-${FRIDA_VERSION}-android-arm64.xz" \
+  -o /tmp/frida-server.xz
+
+unxz /tmp/frida-server.xz
+mv /tmp/frida-server-${FRIDA_VERSION}-android-arm64 /tmp/frida-server
+```
+
+Push to emulator and start:
+
+```bash
+adb -s emulator-5554 push /tmp/frida-server /data/local/tmp/frida-server
+adb -s emulator-5554 shell su 0 chmod 755 /data/local/tmp/frida-server
+adb -s emulator-5554 shell su 0 /data/local/tmp/frida-server &
+```
+
+---
+
+## 9. Download SSL Bypass Scripts
+
+```bash
+BASE=https://raw.githubusercontent.com/httptoolkit/frida-interception-and-unpinning/main
+
+curl -L "${BASE}/config.js" -o /tmp/config.js
+curl -L "${BASE}/android/android-system-certificate-injection.js" \
+  -o /tmp/android-system-certificate-injection.js
+curl -L "${BASE}/android/android-proxy-override.js" \
+  -o /tmp/android-proxy-override.js
+curl -L "${BASE}/android/android-certificate-unpinning.js" \
+  -o /tmp/android-certificate-unpinning.js
+curl -L "${BASE}/android/android-certificate-unpinning-fallback.js" \
+  -o /tmp/android-certificate-unpinning-fallback.js
+```
+
+---
+
+## 10. Configure config.js
+
+Edit `/tmp/config.js` and set:
+
+```javascript
+const CERT_PEM = `<contents of ~/.mitmproxy/mitmproxy-ca-cert.pem>`;
+
+const PROXY_HOST = '192.168.1.123';  // your Mac IP
+const PROXY_PORT = 8080;
+```
+
+Insert the full PEM content (from `-----BEGIN CERTIFICATE-----` to `-----END CERTIFICATE-----`) between the backticks.
+
+Quick check that the right cert is in place:
+
+```bash
+# The issuer inside config.js should be mitmproxy, not SoundTouch
+grep -A3 "CERT_PEM" /tmp/config.js | head -5
+```
+
+---
+
+## 11. Start Interception
+
+Make sure mitmweb is running, then:
+
+```bash
+scripts/android/frida-venv/bin/frida \
+  -U \
+  -f com.bose.soundtouch \
+  -l scripts/android/frida/config.js \
+  -l scripts/android/frida/native-connect-hook.js \
+  -l scripts/android/frida/android/android-system-certificate-injection.js \
+  -l scripts/android/frida/android/android-proxy-override.js \
+  -l scripts/android/frida/android/android-certificate-unpinning.js \
+  -l scripts/android/frida/android/android-certificate-unpinning-fallback.js
+```
+
+> `native-connect-hook.js` is required — the Bose app uses native networking that bypasses Java proxy settings.
+
+Expected output in the Frida REPL:
+
+```
+== System certificate trust injected ==
+== Proxy system configuration overridden to 192.168.1.123:8080 ==
+== Proxy configuration overridden to 192.168.1.123:8080 ==
+== Certificate unpinning completed ==
+== Unpinning fallback auto-patcher installed ==
+```
+
+Open mitmweb at `http://127.0.0.1:8081` to observe traffic live.
+
+---
+
+## 12. Save & Replay Recordings
+
+Traffic is saved to `bose_traffic.mitm` (set via `-w` flag in step 5).
+
+```bash
+# Replay/analyse a saved recording:
+mitmweb -r bose_traffic.mitm
+```
+
+---
+
+## Cleanup
+
+```bash
+# Remove proxy setting from emulator
+adb -s emulator-5554 shell settings delete global http_proxy
+
+# Remove venv
+rm -rf /tmp/frida-venv /tmp/frida-server /tmp/frida-server.xz
+rm /tmp/config.js /tmp/android-*.js
+
+# Stop emulator
+adb -s emulator-5554 emu kill
+```
+
+---
+
+## Troubleshooting
+
+| Symptom                                 | Cause                                            | Fix                                                                            |
+|-----------------------------------------|--------------------------------------------------|--------------------------------------------------------------------------------|
+| `remount failed`                        | ARM64 emulator doesn't support overlayfs remount | Use `/data/misc/user/0/cacerts-added/` method instead                          |
+| `TLS: Trust anchor not found`           | Wrong certificate in config.js                   | Check issuer: must be mitmproxy, not SoundTouch                                |
+| `Chain validation failed`               | Private key included in cert                     | Re-extract with `openssl x509 -in mitmproxy-ca.pem -out mitmproxy-ca-cert.pem` |
+| `frida-server: connection refused`      | frida-server not running                         | Re-run `adb shell su 0 /data/local/tmp/frida-server &`                         |
+| frida and frida-server version mismatch | Versions must be identical                       | Pin both to same version (e.g. `17.9.1`)                                       |
+| `emulator: multiple AVDs` error         | Emulator already running                         | Kill first: `adb emu kill`, then restart with `-writable-system`               |
+
+---
+
+## App Automation Options
+
+For most traffic-recording purposes, manually operating the app while mitmproxy captures is sufficient. If you need to automate specific interactions (e.g. to repeatably capture the requests triggered by startup or a particular action), the following tools are available.
+
+### Starting the App
+
+```bash
+# Via app drawer: swipe up on the home screen and tap "Bose SoundTouch"
+
+# Via adb monkey (simplest)
+adb -s emulator-5554 shell monkey -p com.bose.soundtouch 1
+
+# Via explicit intent (if the activity name is known)
+adb -s emulator-5554 shell am start -n com.bose.soundtouch/.MainActivity
+
+# Look up all activities if the name is unknown
+adb -s emulator-5554 shell dumpsys package com.bose.soundtouch | grep Activity
+```
+
+### adb — sufficient for simple cases
+
+```bash
+# Tap at screen coordinates
+adb shell input tap 540 960
+
+# Swipe
+adb shell input swipe 540 1500 540 500
+
+# Type text
+adb shell input text "mytext"
+
+# Take a screenshot
+adb shell screencap /sdcard/screen.png && adb pull /sdcard/screen.png
+```
+
+### UIAutomator2 — inspect UI elements
+
+```bash
+# Dump the current UI hierarchy to find element IDs
+adb shell uiautomator dump /sdcard/ui.xml
+adb pull /sdcard/ui.xml
+```
+
+Open `ui.xml` to find element resource IDs, then target them precisely in scripts.
+
+### Appium — full scripted automation
+
+```python
+from appium import webdriver
+
+driver = webdriver.Remote('http://localhost:4723/wd/hub', {
+    'platformName': 'Android',
+    'appPackage': 'com.bose.soundtouch',
+    'appActivity': '.MainActivity',
+})
+
+# Find an element by resource ID and tap it
+driver.find_element('id', 'com.bose.soundtouch:id/play_button').click()
+```
+
+> **Note:** `monkey` is a stress-test tool that sends random events — use it only to launch the app, not to drive specific interactions.

docs/analysis/BOSE-LAB-RUNBOOK.md

@@ -0,0 +1,892 @@
+# Bose SoundTouch – Traffic Analysis Runbook
+
+> **Goal:** Set up a Raspberry Pi as a transparent access point to fully observe the traffic of the Bose SoundTouch app – specifically the pairing flow with the Bose Cloud. This serves as a basis for later reverse engineering / simulation of the cloud endpoints.
+
+---
+
+## Prerequisites
+
+| Component          | Details                                                          |
+|--------------------|------------------------------------------------------------------|
+| Raspberry Pi       | Pi 3 or newer, Raspberry Pi OS (Bullseye, Bookworm, Trixie)      |
+| Network interfaces | `eth0` → LAN cable to FritzBox, `wlan0` → own Access Point       |
+| FritzBox           | Unchanged, assigns an IP to the Pi via DHCP on eth0              |
+| Custom DNS Server  | Already present (or see Appendix A), incl. custom CA certificate |
+| Phone              | Android, connects to the Pi's Wi-Fi                              |
+
+### Network Architecture
+
+```
+Internet
+    ↓
+FritzBox  (existing, unchanged)
+    ↓  LAN cable (eth0)
+Raspberry Pi
+  ├── DNS Server       → selective logging / redirection
+  ├── hostapd          → custom Wi-Fi Access Point ("Bose-Lab")
+  ├── dnsmasq          → DHCP for clients, DNS to custom server
+  ├── iptables         → NAT, Forwarding eth0 ↔ wlan0
+  ├── tcpdump          → full traffic capture
+  └── (optional) mitmproxy → HTTPS decryption
+    ↓  Wi-Fi ("Bose-Lab")
+Android Phone
+  └── Bose SoundTouch App
+```
+
+---
+
+## Step 1 – Install Packages
+
+```bash
+sudo apt update && sudo apt install -y \
+  hostapd \          # Wi-Fi Access Point daemon
+  dnsmasq \          # DHCP + DNS forwarding
+  nftables \         # Modern NAT / firewall / forwarding
+  tcpdump \          # Packet capture at all levels
+  wireshark-common   # tshark CLI (optional, for live analysis)
+```
+
+---
+
+## Step 2 – Enable IP Forwarding
+
+The Pi must forward packets between `wlan0` (phone) and `eth0` (FritzBox).
+
+```bash
+# Active immediately (no reboot required)
+sudo sysctl -w net.ipv4.ip_forward=1
+
+# Permanent (survives reboots)
+# On modern Debian, using a dedicated file in sysctl.d/ is more reliable:
+echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-ip-forward.conf
+
+# Apply changes immediately
+sudo sysctl --system
+```
+
+**Verify:**
+```bash
+# After a reboot, ensure it is still '1'
+cat /proc/sys/net/ipv4/ip_forward
+```
+
+---
+
+## Step 3 – Static IP on wlan0 (systemd-networkd)
+
+On modern Debian (Bookworm/Trixie), `dhcpcd` is replaced by `systemd-networkd`.
+
+```bash
+# Create network configuration
+sudo tee /etc/systemd/network/08-wlan0.network << 'EOF'
+[Match]
+Name=wlan0
+
+[Network]
+Address=192.168.10.1/24
+IPForward=yes
+ConfigureWithoutCarrier=yes
+DHCP=no
+IPv6AcceptRA=no
+EOF
+
+# Restart service
+sudo systemctl enable systemd-networkd
+sudo systemctl restart systemd-networkd
+
+# Ensure wpa_supplicant and NetworkManager don't interfere
+sudo nmcli device set wlan0 managed no
+sudo systemctl stop wpa_supplicant@wlan0
+sudo systemctl mask wpa_supplicant@wlan0
+```
+
+**Verify:**
+```bash
+ip addr show wlan0
+# Expected: ONLY inet 192.168.10.1/24 (NO second DHCP IP)
+```
+
+---
+
+## Step 4 – hostapd (Access Point)
+
+```bash
+sudo tee /etc/hostapd/hostapd.conf << 'EOF'
+interface=wlan0
+driver=nl80211
+ssid=Bose-Lab
+hw_mode=b
+#hw_mode=g
+channel=1
+#channel=6
+wmm_enabled=0
+auth_algs=1
+wpa=2
+wpa_passphrase=secret123
+wpa_key_mgmt=WPA-PSK
+wpa_pairwise=CCMP
+EOF
+
+# The modern way is to just use hostapd.service which defaults to /etc/hostapd/hostapd.conf
+sudo systemctl unmask hostapd
+sudo systemctl enable --now hostapd
+```
+
+**Verify:**
+```bash
+sudo systemctl status hostapd
+# Expected: active (running)
+```
+
+---
+
+## Step 5 – dnsmasq (DHCP + DNS)
+
+dnsmasq gives the phone an IP and forwards DNS queries to the custom DNS server.
+
+```bash
+# Back up original config
+sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.bak
+
+sudo tee /etc/dnsmasq.conf << 'EOF'
+interface=wlan0
+dhcp-range=192.168.10.100,192.168.10.200,24h
+dhcp-option=3,192.168.10.1
+dhcp-option=6,192.168.10.1
+
+# DNS Upstream: custom server on localhost (adjust port if necessary)
+server=127.0.0.1#5353    # Example: custom server on port 5353
+# Alternatively: server=1.1.1.1 if DNS server runs directly on port 53
+
+# Log all DNS queries (for initial analysis)
+log-queries
+log-facility=/var/log/dnsmasq.log
+EOF
+
+sudo systemctl restart dnsmasq
+```
+
+**Observe DNS log live:**
+```bash
+sudo tail -f /var/log/dnsmasq.log
+```
+
+---
+
+## Step 6 – NAT and Forwarding (nftables)
+
+On modern Debian (Bookworm/Trixie), `nftables` is the default and recommended way to manage NAT and traffic forwarding.
+
+```bash
+# Define the NAT and Forwarding rules
+sudo tee /etc/nftables.conf << 'EOF'
+#!/usr/sbin/nft -f
+
+flush ruleset
+
+table inet filter {
+    chain forward {
+        type filter hook forward priority 0; policy drop;
+
+        # Allow traffic from phone (wlan0) to internet (eth0)
+        iifname "wlan0" oifname "eth0" accept
+
+        # Allow established/related traffic back to the phone
+        iifname "eth0" oifname "wlan0" ct state established,related accept
+    }
+}
+
+table ip nat {
+    chain posterouting {
+        type nat hook postrouting priority 100; policy accept;
+
+        # MASQUERADE outgoing packets on eth0
+        oifname "eth0" masquerade
+    }
+}
+EOF
+
+# Enable and start nftables
+sudo systemctl enable nftables
+sudo systemctl restart nftables
+```
+
+**Verify:**
+```bash
+sudo nft list ruleset
+# Expected: ruleset showing the forward and nat chains
+```
+
+### WiFi "Bose-Lab" not visible?
+
+If you cannot see the `Bose-Lab` SSID on your phone:
+
+1.  **Check hostapd status:** `sudo systemctl status hostapd`. If it failed with "nl80211: Driver does not support configured mode", try changing `hw_mode=g` to `hw_mode=b`.
+2.  **Interface blocking:** Ensure `rfkill` hasn't blocked WiFi: `sudo rfkill unblock wlan`.
+3.  **Country Code:** Some systems require a country code in `hostapd.conf` to enable the radio. Add `country_code=DE` (or your country) to the top of `/etc/hostapd/hostapd.conf` and restart hostapd: `sudo systemctl restart hostapd`.
+4.  **Local Radio Check:** You can verify that the radio is actually configured as an AP: `iw dev wlan0 info`. Look for `type AP` and your SSID.
+    > **Note:** Do NOT rely on `iw dev wlan0 scan` for your own SSID; many WiFi drivers cannot "scan" and "broadcast" simultaneously.
+5.  **Debug Mode:** If the scan still returns nothing, stop the service and run hostapd in the foreground to see real-time errors:
+    ```bash
+    sudo systemctl stop hostapd
+    sudo hostapd -dd /etc/hostapd/hostapd.conf
+    ```
+    Look for messages like `nl80211: Failed to set interface wlan0 into AP mode`. This usually means the hardware is busy or doesn't support the current `hw_mode` / `channel` combination.
+6.  **Conflicting Services:** Ensure nothing else is managing `wlan0`. NetworkManager is common on modern Debian:
+    ```bash
+    sudo nmcli device set wlan0 managed no
+    ```
+7.  **Ghost IP Conflict:** If `ip addr show wlan0` shows both `192.168.10.1` and another IP (like `192.168.178.x`), `hostapd` will fail. This is usually caused by NetworkManager managing the interface. Ensure you've run:
+    ```bash
+    sudo nmcli device set wlan0 managed no
+    # If the ghost IP is still there, remove it manually:
+    sudo ip addr del 192.168.178.X/24 dev wlan0
+    ```
+
+---
+
+## Step 7 – Install Custom CA Certificate on the Phone
+
+Since a custom DNS server with a custom CA certificate is used, it must be trusted on the phone – otherwise, the app will block HTTPS connections to redirected domains.
+
+### Copy CA Certificate to the Pi (if not already there)
+
+If you haven't created a CA yet, follow **Appendix A** first.
+
+```bash
+# Certificate is located e.g. at /etc/my-dns-ca/ca.crt
+# Temporarily make reachable via HTTP for easy download:
+cd /etc/my-dns-ca/
+python3 -m http.server 8080
+# → Reachable at http://192.168.10.1:8080/ca.crt
+```
+
+### Install on Android
+
+1. Connect phone to `Bose-Lab`
+2. Open browser → `http://192.168.10.1:8080/ca.crt`
+3. Download certificate
+4. **Settings → Security → Credentials → Install CA Certificate**
+5. Select certificate and confirm
+
+> **Note:** Android distinguishes between system CAs and user CAs. User-installed CAs are accepted by many apps, but apps with certificate pinning (hardcoded certificate hashes) ignore them. Whether Bose uses pinning will be visible in the capture (Connection Reset after TLS ClientHello).
+
+### Android 14+ Special Case
+
+From Android 14 onwards, apps do not trust user CAs by default unless explicitly declared in the manifest. If the Bose app rejects the CA certificate:
+
+```bash
+# Option A: Root + Magisk module "MagiskTrustUserCerts"
+#   → moves user CAs to the system store
+
+# Option B: Root + manually copy to system CA directory
+adb push ca.crt /system/etc/security/cacerts/
+adb shell chmod 644 /system/etc/security/cacerts/ca.crt
+```
+
+---
+
+## Step 8 – Capture Traffic
+
+### All at once (recommended)
+
+```bash
+# Full capture of all protocols on wlan0
+# Filename with timestamp for multiple sessions
+sudo tcpdump -i wlan0 \
+  -w /tmp/bose-$(date +%Y%m%d-%H%M%S).pcap \
+  -s 0        # full packet length (no truncation)
+
+# End session: Ctrl+C
+```
+
+### Targeted by protocol
+
+```bash
+# DNS only (Port 53) – shows if app uses standard DNS
+sudo tcpdump -i wlan0 -n port 53
+
+# HTTPS only – TLS connections to Bose Cloud
+sudo tcpdump -i wlan0 -n 'tcp port 443'
+
+# mDNS (ZeroConf) – device discovery in LAN
+# Multicast group 224.0.0.1, Port 5353
+sudo tcpdump -i wlan0 -n 'udp port 5353'
+
+# SSDP/UPnP – alternative device discovery
+sudo tcpdump -i wlan0 -n 'udp port 1900'
+
+# Everything except DNS (reduces noise)
+sudo tcpdump -i wlan0 -n 'not port 53' -w /tmp/bose-nodns.pcap
+
+# Traffic of a specific host only (filter by phone IP)
+# Read phone IP from dnsmasq.leases beforehand (see below)
+sudo tcpdump -i wlan0 -n host 192.168.10.101
+```
+
+### Read SNI from TLS Traffic (without decryption)
+
+```bash
+# Extract domains from TLS ClientHello (SNI is unencrypted)
+sudo tcpdump -i wlan0 -n 'tcp port 443' -A 2>/dev/null \
+  | grep -oP '(?<=\x00)([a-zA-Z0-9.-]+\.(?:com|net|io|cloud|bose\.com))'
+```
+
+### Readable mDNS Announcements output
+
+```bash
+# tshark decodes mDNS directly
+sudo tshark -i wlan0 -f 'udp port 5353' -T fields \
+  -e dns.qry.name \
+  -e dns.resp.name \
+  -e dns.a
+```
+
+---
+
+## Step 9 – Analysis with Wireshark (on PC)
+
+Transfer `.pcap` files from the Pi to the PC:
+
+```bash
+# From the PC (scp)
+scp pi@192.168.10.1:/tmp/bose-*.pcap ~/Desktop/
+```
+
+**Important Wireshark Filters:**
+
+```
+# DNS only
+dns
+
+# HTTPS only
+tcp.port == 443
+
+# WebSocket connections (HTTP Upgrade)
+websocket
+
+# mDNS
+mdns
+
+# TLS Handshakes (SNI visible)
+tls.handshake.extensions_server_name
+
+# Traffic of a specific domain (resolve by IP)
+http.host contains "bose"
+
+# WebSocket frames
+websocket.payload
+```
+
+> **Tip:** Wireshark decodes WebSocket frames automatically if it sees the HTTP Upgrade handshake in the same capture. For the pairing flow: filtering for `tls.handshake.extensions_server_name` shows all domains the app contacts, even without decryption.
+
+---
+
+## Step 10 – mitmproxy (optional, for HTTPS content)
+
+Only useful if the CA certificate on the phone is trusted and no certificate pinning is active. `mitmproxy` acts as a Man-in-the-Middle by generating fake, on-the-fly certificates for any domain (e.g., `global.api.bose.io`) using your custom CA.
+
+### 1. Configure mitmproxy to use your Custom CA
+
+By default, `mitmproxy` creates its own CA in `~/.mitmproxy/`. To ensure the phone (which already trusts your `ca.crt`) accepts the traffic, you must tell `mitmproxy` to use your existing CA:
+
+```bash
+# mitmproxy expects the CA in a specific PEM format (cert + key in one file)
+sudo mkdir -p ~/.mitmproxy
+sudo cat /etc/my-dns-ca/ca.crt /etc/my-dns-ca/ca.key | sudo tee ~/.mitmproxy/mitmproxy-ca.pem > /dev/null
+```
+
+### 2. Install and Start mitmproxy
+
+```bash
+# Install mitmproxy binary (stable version for aarch64)
+cd /tmp
+wget https://downloads.mitmproxy.org/12.2.1/mitmproxy-12.2.1-linux-aarch64.tar.gz
+tar -xzf mitmproxy-12.2.1-linux-aarch64.tar.gz
+sudo mv mitmproxy mitmdump mitmweb /usr/local/bin/
+rm mitmproxy-12.2.1-linux-aarch64.tar.gz
+
+mitmproxy --version
+
+# Transparent proxy on port 8080
+# It will now use the CA from ~/.mitmproxy/mitmproxy-ca.pem
+mitmproxy --mode transparent --listen-port 8080
+
+# Alternatively: mitmdump for automatic logging to file
+# mitmdump --mode transparent --listen-port 8080 -w /tmp/bose-https.mitm
+```
+
+### 3. Troubleshooting: TLS Handshake Failures
+
+If you see `Client TLS handshake failed. The client does not trust the proxy's certificate for www.google.com` (or other domains) in the `mitmproxy` logs:
+
+1.  **HSTS and Pre-installed Pinning:** High-security sites like `www.google.com` use **HSTS (HTTP Strict Transport Security)** and have their certificates hardcoded (pinned) into browsers like Chrome and the Android system. **These will always fail with a User-installed CA.**
+2.  **User vs. System CA Store:** On Android 7.0+, apps **do not trust User-installed CAs by default**. They only trust the "System" store.
+    *   **The Bose app:** If it fails, it's because it only trusts the System store or uses its own certificate pinning.
+    *   **The Fix (Rooted Phone):** Use a Magisk module like `AlwaysTrustUserCerts` or manually move your `ca.crt` to `/system/etc/security/cacerts/` (see Step 7).
+3.  **The "Golden Rule" - Verify the Proxy is Working:**
+    To confirm your CA and `mitmproxy` are correctly configured, test with a non-HSTS site on the phone's browser (e.g., `http://neverssl.com`). Once redirected to HTTPS, **inspect the certificate**. It should say it was issued by your "Bose-Lab Root CA" (or "SoundTouch Root CA").
+
+    *   **If this works:** Your "factory" (mitmproxy + CA) is 100% correct. Any failure in the Bose app is due to its own security policy (ignore User Store or Pinning).
+    *   **If this fails:** Your CA is not trusted by the browser or `mitmproxy` is not using your PEM file.
+
+    Alternatively, use `curl` from a terminal emulator on the phone:
+    ```bash
+    # This should work if the CA is in the user store and curl is told to use it
+    curl -v --cacert /path/to/ca.crt https://example.com
+    ```
+4.  **Check mitmproxy CA:** Ensure `mitmproxy` is actually using your CA. When it starts, it should NOT generate a new CA in `~/.mitmproxy/mitmproxy-ca.pem` if you've already placed yours there.
+
+---
+
+**nftables rule: redirect HTTPS traffic to mitmproxy**
+
+```bash
+# Create a temporary file for the redirection rule
+sudo nft add table ip mitm
+sudo nft add chain ip mitm prerouting { type nat hook prerouting priority -100 \; }
+sudo nft add rule ip mitm prerouting iifname "wlan0" tcp dport 443 redirect to :8080
+```
+
+**Remove rule when no longer needed:**
+
+```bash
+sudo nft delete table ip mitm
+```
+
+> **Detecting Certificate Pinning:** If the app immediately disconnects after mitmproxy redirection (connection reset directly after TLS ClientHello), pinning is active. In this case, Frida + root is needed to patch the pinning.
+
+---
+
+## Step 11 – Bypassing Android Trust Restrictions
+
+If `neverssl.com` works in the browser but the Bose app shows `TLS handshake failed` in `mitmproxy`, the app is either ignoring the **User CA store** (common on Android 7+) or using **Certificate Pinning**.
+
+### Option A: Move CA to System Store (Requires Root/Magisk)
+
+This is the most reliable way to make apps trust your CA without modifying the app itself.
+
+1.  **Using Magisk (Recommended):**
+    Install the **"AlwaysTrustUserCerts"** or **"Move Certificates"** module in Magisk. It automatically mirrors all certificates from the User store to the System store on every boot.
+
+2.  **Manual Move (via ADB):**
+    Android system certificates are stored in `/system/etc/security/cacerts/` and must be named using the hash of the certificate.
+
+    ```bash
+    # 1. Get the hash of your certificate
+    hash=$(openssl x509 -inform PEM -subject_hash_old -in ca.crt | head -1)
+
+    # 2. Rename the certificate locally
+    cp ca.crt ${hash}.0
+
+    # 3. Push to the phone (requires remounting /system as read-write)
+    adb push ${hash}.0 /sdcard/
+    adb shell
+    su
+    mount -o rw,remount /
+    cp /sdcard/${hash}.0 /system/etc/security/cacerts/
+    chmod 644 /system/etc/security/cacerts/${hash}.0
+    chown root:root /system/etc/security/cacerts/${hash}.0
+    reboot
+    ```
+
+### Option B: Patching the App (No Root Required)
+
+If you cannot root your phone, you can modify the app's APK to trust user-installed certificates. This involves obtaining the APK, decompiling it, adding a network security configuration, and then repackaging and signing it.
+
+#### 0. How to get the .apk file?
+
+You have two main ways to get the official Bose SoundTouch APK:
+
+**Method 1: Extract from your phone (Safest)**
+If the app is already installed on your phone, you can pull it using `adb`:
+```bash
+# 1. Find the package name (usually com.bose.soundtouch)
+adb shell pm list packages | grep bose
+
+# 2. Get the full path to the APK on the phone
+adb shell pm path com.bose.soundtouch
+# Output: package:/data/app/~~...==/com.bose.soundtouch-.../base.apk
+
+# 3. Pull the file to your computer
+adb pull /data/app/~~...==/com.bose.soundtouch-.../base.apk Bose-SoundTouch.apk
+```
+
+**Method 2: Download from a Mirror (Easiest)**
+You can download the APK from reputable third-party sites.
+> **Warning:** Always verify the site's reputation.
+*   [APKMirror](https://www.apkmirror.com/apk/bose-corporation/bose-soundtouch/)
+*   [APKPure](https://apkpure.com/bose-soundtouch/com.bose.soundtouch)
+
+#### 1. Automated Method: apk-mitm (Recommended)
+The easiest way is to use `apk-mitm`, which automates the entire process including fixing common certificate pinning libraries.
+
+```bash
+# Requires Node.js installed on your PC
+npx apk-mitm Bose-SoundTouch.apk
+```
+This will produce a `Bose-SoundTouch-patched.apk` which you can install on your phone.
+
+#### 2. Manual Method: Network Security Config
+If you prefer to do it manually:
+
+1.  **Decompile the APK:**
+    ```bash
+    apktool d Bose-SoundTouch.apk
+    ```
+2.  **Create/Modify `res/xml/network_security_config.xml`:**
+    ```xml
+    <?xml version="1.0" encoding="utf-8"?>
+    <network-security-config>
+        <base-config>
+            <trust-anchors>
+                <certificates src="system" />
+                <certificates src="user" />
+            </trust-anchors>
+        </base-config>
+    </network-security-config>
+    ```
+3.  **Update `AndroidManifest.xml`:**
+    Ensure the `<application>` tag includes: `android:networkSecurityConfig="@xml/network_security_config"`.
+4.  **Repackage and Sign:**
+    ```bash
+    apktool b Bose-SoundTouch -o Bose-SoundTouch-patched.apk
+    # Sign with your own key
+    # 1. Generate a keystore (if you don't have one)
+    # Note: You can use ANY name/values here. The phone does not need to "know" or "trust" this key beforehand.
+    # It only needs the APK to be digitally signed so the Android installer accepts it.
+    keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000
+
+    # 2. Sign the APK
+    apksigner sign --ks my-release-key.keystore --out Bose-SoundTouch-patched-signed.apk Bose-SoundTouch-patched.apk
+
+    # Alternatively, use uber-apk-signer (recommended for simplicity)
+    # It handles zipalign and signing automatically.
+    java -jar uber-apk-signer.jar --apk Bose-SoundTouch-patched.apk
+    ```
+
+#### 3. Install the Patched APK
+
+Once you have your `Bose-SoundTouch-patched.apk` (and it is signed), you need to install it on your phone.
+
+**Important:** You must **uninstall the original Bose app first**. Android will not allow you to "update" the official app with your patched version because the digital signatures won't match.
+
+**Method 1: via ADB (Recommended)**
+```bash
+# 1. Uninstall the original app
+adb uninstall com.bose.soundtouch
+
+# 2. Install your patched version
+adb install Bose-SoundTouch-patched.apk
+```
+
+**Method 2: Manual Transfer**
+1.  Copy the `Bose-SoundTouch-patched.apk` to your phone's storage (via USB, Google Drive, or the Pi's HTTP server).
+2.  On the phone, use a File Manager to open the APK.
+3.  If prompted, allow "Install from Unknown Sources" for your File Manager.
+
+### Option C: Using the macOS Bose SoundTouch App (No Root/Patching Required)
+
+If you have a Mac, using the macOS version of the Bose SoundTouch app is often a good alternative. However, because the app is built on an **older version of Qt (5.7.0)**, it has specific trust and TLS compatibility issues that require extra steps.
+
+#### 1. Install the Custom CA in macOS Keychain
+
+1.  Open **Keychain Access** on your Mac.
+2.  Select the **System** keychain (or **login** if System is locked).
+3.  Drag and drop your `ca.crt` file into the list.
+4.  Double-click the newly added certificate (e.g., "Bose-Lab Root CA").
+5.  Expand the **Trust** section.
+6.  Set "When using this certificate" to **Always Trust**.
+7.  Close the window and authenticate with your Mac password.
+
+#### 2. Configure the Proxy
+
+You can either configure the macOS system proxy manually or use `mitmproxy`'s automatic interception.
+
+**Method 1: System Proxy (Manual)**
+1.  Go to **System Settings → Network → Wi-Fi → Details... → Proxies**.
+2.  Enable **HTTP Proxy** and **HTTPS Proxy**.
+3.  Set Server to your Pi's IP (`192.168.10.1`) and Port to `8080`.
+4.  Click **OK** and **Apply**.
+
+**Method 2: mitmproxy Local Redirect (Automatic)**
+If you are running `mitmproxy` directly on your Mac (instead of the Pi), you can use the modern "Local Redirect" mode which doesn't require proxy settings:
+```bash
+# Install mitmproxy via Homebrew
+brew install mitmproxy
+
+# Start mitmproxy in local redirect mode
+# This uses a macOS Network Extension to intercept traffic from specific apps
+mitmproxy --mode local
+```
+
+#### 3. Special Troubleshooting: Legacy Qt 5.7.0 SSL Failures
+
+If you see `SSL handshake failed` in the `mitmproxy` logs or the app's internal log (`log.txt`), the app's older networking stack is rejecting the connection. This is common because Qt 5.7.0 (2016) lacks support for **TLS 1.3** and many modern root certificates (like Let's Encrypt's **ISRG Root X1**).
+
+**The Solution: Launch with SSL Bypass Flags**
+
+Since the Bose macOS app is a hybrid of **Qt/Chromium** and **Node.js**, you must bypass the trust checks for both engines by launching the app from the terminal:
+
+```bash
+# 1. Bypass QtWebEngine/Chromium (Qt 5.7) trust
+export QTWEBENGINE_CHROMIUM_FLAGS="--ignore-certificate-errors"
+
+# 2. Bypass Node.js (SoundTouch Music Server) trust
+export NODE_TLS_REJECT_UNAUTHORIZED=0
+
+# 3. (Optional) Provide your custom CA directly to Node.js
+export NODE_EXTRA_CA_CERTS="/path/to/your/ca.crt"
+
+# 4. Launch the application
+"/Applications/SoundTouch/SoundTouch.app/Contents/MacOS/SoundTouch"
+```
+
+#### 4. Verify and Capture
+
+1.  Open Safari and visit `https://neverssl.com`. Verify the certificate is issued by your custom CA.
+2.  Launch the Bose app using the terminal command above.
+3.  Watch the traffic flow in `mitmproxy`.
+
+> **Note:** Even on macOS, **Certificate Pinning** is still possible if Bose implemented it specifically in the desktop app code. However, it is much less common on desktop apps than on mobile apps. If it works, you've saved yourself hours of Android patching!
+
+### Option D: Patching the App with Frida (Requires Root)
+
+If the app uses **Certificate Pinning** (hardcoded hashes), even moving the CA to the System store won't work. You must disable the pinning check in the app's code.
+
+1.  **Install Frida** on your PC and `frida-server` on the rooted phone.
+2.  **Use a universal bypass script:**
+    ```bash
+    frida -U -f com.bose.soundtouch -l https://codeshare.frida.re/@pcipolloni/universal-android-ssl-pinning-bypass-with-frida/ --no-pause
+    ```
+    *(Replace `com.bose.soundtouch` with the actual package name if different).*
+
+## Step 12 – Alternative: Regular HTTP Proxy Mode
+
+If the **Transparent AP** setup (Steps 1–6) is too complex or you are experiencing routing issues, you can use `mitmproxy` as a **Regular HTTP Proxy**.
+
+### 1. How it works
+In this mode, the Pi acts as a simple server on port 8080. You tell your phone's Wi-Fi settings to send all traffic to `192.168.10.1:8080`.
+
+*   **Pros:** No complex `nftables` or NAT rules required.
+*   **Cons:** Many Android apps (and background processes) ignore system-wide proxy settings. **HTTPS still requires a trusted CA for decryption.**
+
+### 2. Start mitmproxy in Regular Mode
+```bash
+# Stop transparent mode first if it's running
+# No special flags needed for regular mode
+mitmproxy --listen-port 8080
+```
+
+### 3. Configure the Phone
+1.  Go to **Settings → Wi-Fi → Bose-Lab**.
+2.  Select **Modify Network** (or the "i" icon).
+3.  Set **Proxy** to **Manual**.
+4.  **Proxy hostname:** `192.168.10.1`
+5.  **Proxy port:** `8080`
+6.  Save and try to browse a site.
+
+---
+
+## Step 13 – Extracting for soundtouch-service
+
+You can extract interactions (especially unencrypted WebSockets on port 8090) from a `.pcap` and format them for use in `soundtouch-service`.
+
+### 1. Extract Traffic using Go
+
+A helper script is provided in `scripts/extract-ws.go`. It automatically detects, unmasks, and decompresses (GZIP) WebSocket frames, and also extracts DNS, MDNS, and SSDP traffic.
+
+```bash
+# Install dependencies
+go get github.com/google/gopacket
+
+# Run extraction (outputs multiple files: .ws.http, .dns.txt, .mdns.txt, .ssdp.txt)
+# The results will be saved beside your .pcap file
+go run scripts/extract-ws.go your_capture.pcap [filter_ip]
+
+# Example: Filter for a specific speaker's IP in WebSocket messages
+go run scripts/extract-ws.go capture.pcap 192.168.100.1
+```
+
+### 2. Manual Extraction with tshark
+
+If you only need a quick look at the payloads:
+
+```bash
+# Extract all WebSocket text payloads
+tshark -r your_capture.pcap -Y "websocket.payload.text" -T fields -e websocket.payload.text
+```
+
+---
+
+## Step 14 – Extracting from Internal App Logs (macOS)
+
+If you are using the macOS app and cannot decrypt the cloud traffic due to pinning, you can still extract the JSON/XML messages from the app's internal communication log.
+
+A helper script is provided in `scripts/extract-log-interactions.go`. It parses the interleaved "Native" and "Network" calls to reconstruct the application's internal state and cloud requests.
+
+```bash
+# Run extraction from the log file
+# Outputs a chronological record of internal events and network URLs
+go run scripts/extract-log-interactions.go path/to/log.txt > extracted-interactions.http
+```
+
+**What this shows:**
+- **TO NETWORK:** The URLs the app is about to call (intercepted before encryption).
+- **FROM NATIVE:** Data being returned from the OS or Cloud to the UI.
+- **TO NATIVE:** Commands being sent from the UI to the underlying engines.
+
+This is a powerful "Plan B" when HTTPS decryption is blocked, as the app essentially logs its own decrypted data for you.
+
+---
+
+## Helper Commands / Troubleshooting
+
+After a Pi reboot, everything should come up automatically. If not:
+
+```bash
+# Restart and enable all core services
+sudo systemctl restart systemd-networkd
+sudo systemctl enable --now hostapd
+sudo systemctl enable --now dnsmasq
+sudo systemctl restart nftables
+
+# Verify the unmanaged state of wlan0 (nmcli)
+sudo nmcli device set wlan0 managed no
+```
+
+---
+
+## What to Expect
+
+| Protocol             | Port       | Tool                     | Visibility                                     |
+|----------------------|------------|--------------------------|------------------------------------------------|
+| DNS (Standard)       | UDP 53     | tcpdump, dnsmasq log     | Full, plaintext                                |
+| HTTPS / REST         | TCP 443    | tcpdump (SNI), mitmproxy | SNI without decryption, content with mitmproxy |
+| WebSockets           | TCP 443/80 | Wireshark                | Frames decoded if TLS is broken                |
+| mDNS / ZeroConf      | UDP 5353   | tcpdump, tshark          | Full, plaintext                                |
+| SSDP / UPnP          | UDP 1900   | tcpdump                  | Full, plaintext                                |
+| SoundTouch local API | TCP 8090   | tcpdump                  | Full, plaintext (no TLS)                       |
+
+> **Expectation for Bose SoundTouch:** The app likely uses standard DNS (older app generation), REST/HTTPS for the pairing flow with the cloud, WebSockets for push events from the device, and mDNS for local device discovery. The local device API on port 8090 is HTTP without TLS – this traffic is always readable.
+
+---
+
+## Next Steps After Analysis
+
+1. Extract domains from DNS log and SNI → List of all Bose endpoints
+2. HTTP methods and paths from mitmproxy log → Reconstruct API structure
+3. Document auth flow (OAuth2? Proprietary? Token format?)
+4. Build a minimal mock server simulating the critical endpoints
+5. Testing: App against mock server → does pairing work offline?
+
+---
+
+## Appendix A – Generating a Custom CA Certificate
+
+If you don't have a custom DNS server with a CA yet, you can create one directly on the Pi. Alternatively, if you are already using the `soundtouch-service` from this repository, you can reuse its CA certificate located in the `data/certs/` directory.
+
+### 0. (Optional) Copy an Existing CA from another host
+
+If you are already using the `soundtouch-service` on another machine (e.g., your notebook), you can copy the existing CA to the Pi instead of generating a new one:
+
+```bash
+# On your Pi:
+sudo mkdir -p /etc/my-dns-ca
+sudo chown $USER:$USER /etc/my-dns-ca
+
+# Run this on your notebook (replace hostnames and paths):
+# Note: This is easiest if your SSH key is added to the Pi and soundtouch-service host.
+# If you run into permission issues with sudo, ensure the source user has passwordless sudo for 'cat'.
+
+# Step A: Download from source to your notebook
+ssh soundtouch-service "sudo cat /var/lib/soundtouch-service/certs/ca.crt" > ca.crt
+ssh soundtouch-service "sudo cat /var/lib/soundtouch-service/certs/ca.key" > ca.key
+
+# Step B: Upload from notebook to the Pi
+scp ca.crt ca.key soundtouch-access-point:/tmp/
+ssh soundtouch-access-point "sudo mv /tmp/ca.crt /tmp/ca.key /etc/my-dns-ca/ && sudo chown root:root /etc/my-dns-ca/ca.*"
+rm ca.crt ca.key
+```
+
+### 1. Create CA Key and Certificate
+
+```bash
+sudo mkdir -p /etc/my-dns-ca
+cd /etc/my-dns-ca
+
+# Generate CA private key
+sudo openssl genrsa -out ca.key 4096
+
+# Generate Root CA certificate
+# Note: we explicitly add basicConstraints=CA:TRUE for modern TLS clients
+sudo openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 \
+  -out ca.crt \
+  -subj "/C=DE/O=Bose-Lab/CN=Bose-Lab Root CA" \
+  -addext "basicConstraints=critical,CA:TRUE" \
+  -addext "keyUsage=critical,keyCertSign,cRLSign"
+```
+
+### 2. Generate a Certificate for Interception (Example)
+
+To intercept `global.api.bose.io`, you need a certificate for it, signed by your CA:
+
+```bash
+# Generate server key
+sudo openssl genrsa -out bose.key 2048
+
+# Create CSR (Certificate Signing Request) configuration
+sudo tee bose.ext << 'EOF'
+authorityKeyIdentifier=keyid,issuer
+basicConstraints=CA:FALSE
+keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
+subjectAltName = @alt_names
+
+[alt_names]
+DNS.1 = global.api.bose.io
+DNS.2 = *.bose.io
+EOF
+
+# Generate CSR
+sudo openssl req -new -key bose.key -out bose.csr \
+  -subj "/C=DE/O=Bose-Lab/CN=global.api.bose.io"
+
+# Sign the certificate with your CA
+sudo openssl x509 -req -in bose.csr -CA ca.crt -CAkey ca.key \
+  -CAcreateserial -out bose.crt -days 365 -sha256 -extfile bose.ext
+```
+
+### 3. Usage in your DNS/HTTPS Server
+
+Your custom server (e.g., a small Go or Python script) would then use `bose.crt` and `bose.key` to serve HTTPS traffic for those domains.
+
+## Appendix B – Helpful Commands
+
+```bash
+# Which IPs did the phone receive?
+cat /var/lib/misc/dnsmasq.leases
+
+# Is the access point active?
+sudo systemctl status hostapd
+
+# Is dnsmasq active?
+sudo systemctl status dnsmasq
+
+# Check interfaces and IPs
+ip addr show
+
+# Check routing table
+ip route show
+
+# Show active nftables rules
+sudo nft list ruleset
+
+# All running tcpdump processes
+pgrep -a tcpdump
+
+# Test the Pi's own DNS resolution
+dig @127.0.0.1 -p 5353 global.api.bose.io
+
+# Check network connectivity from the phone (from the Pi)
+ping 192.168.10.101   # Phone IP from dnsmasq.leases
+```

docs/analysis/DEVICE-REDIRECT-METHODS.md

@@ -0,0 +1,198 @@
+# Device Redirect Methods & Custom Service Setup
+
+To enable offline operation or use custom services like **SoundCork** or **ÜberBöse API**, SoundTouch devices must be redirected from Bose's official cloud endpoints to a local or custom server. This document outlines the three known methods to achieve this, gathered from community reverse-engineering efforts in the **SoundCork** and **ÜberBöse API** projects.
+
+## Overview of Redirection Targets
+
+SoundTouch devices primarily communicate with the following domains:
+- `streaming.bose.com`: Marge (Account and streaming services)
+- `updates.bose.com`: Software updates
+- `stats.bose.com`: Telemetry and analytics
+- `bmx.bose.com`: Bose Media eXchange registry
+- `events.api.bosecm.com`: Stockholm app analytics
+- `bose-prod.apigee.net`: Apigee gateway (used by some services)
+- `worldwide.bose.com`: Software update metadata and secondary services
+
+---
+
+## Method 1: XML Configuration Modification (Recommended)
+
+The most robust and granular method involves modifying the device's private configuration file. This is the primary method used by **SoundCork**'s migration logic to redirect devices to a local service instance.
+
+### Technical Details
+- **File Path**: `/opt/Bose/etc/SoundTouchSdkPrivateCfg.xml`
+- **Mechanism**: The device firmware reads this XML file at boot to determine service URLs.
+- **Fields to Modify**:
+  - `<margeServerUrl>`: Redirects account/streaming calls.
+  - `<statsServerUrl>`: Redirects telemetry.
+  - `<swUpdateUrl>`: Redirects update checks.
+  - `<bmxRegistryUrl>`: Redirects service discovery.
+
+### Implementation
+Requires SSH access to the device.
+```xml
+<SoundTouchSdkPrivateCfg>
+  <margeServerUrl>http://192.168.1.10:8000/marge</margeServerUrl>
+  <statsServerUrl>http://192.168.1.10:8000</statsServerUrl>
+  <swUpdateUrl>http://192.168.1.10:8000/updates/soundtouch</swUpdateUrl>
+  <bmxRegistryUrl>http://192.168.1.10:8000/bmx/registry/v1/services</bmxRegistryUrl>
+</SoundTouchSdkPrivateCfg>
+```
+
+### Pros & Cons
+| Pros | Cons |
+| :--- | :--- |
+| **Granular Control**: Redirect specific services while leaving others (e.g., updates) intact. | **Requires SSH**: Must have root/SSH access to the device. |
+| **Persistent**: Survives software updates (usually). | **Syntax Sensitive**: Errors in XML can cause boot issues or service failures. |
+| **Native**: Uses the device's built-in configuration mechanism. | |
+
+---
+
+## Method 2: `/etc/hosts` DNS Override
+
+This method uses the standard Linux hosts file to redirect traffic at the network level within the device. It is often used as a quick alternative in the **ÜberBöse API** community for global redirection.
+
+### Technical Details
+- **File Path**: `/etc/hosts`
+- **Mechanism**: Overrides DNS resolution for Bose domains to point to a local IP.
+- **Resolution Order**: SoundTouch devices use the standard Linux Name Service Switch (`/etc/nsswitch.conf`). The default configuration (`hosts: files dns`) ensures that `/etc/hosts` is consulted *before* any external DNS lookups. This makes the redirection highly reliable for all system processes, including `curl`, `BoseApp`, and `IoT`.
+
+### Implementation
+Requires SSH access. Add entries for the target domains:
+```text
+192.168.1.10  streaming.bose.com
+192.168.1.10  updates.bose.com
+192.168.1.10  stats.bose.com
+```
+
+### Pros & Cons
+| Pros | Cons |
+| :--- | :--- |
+| **Simple**: Easy to understand and implement. | **Requires SSH**: Must have root access. |
+| **Universal**: Affects all processes on the device attempting to reach those domains. | **HTTPS Issues**: Redirecting HTTPS domains to a local IP will cause SSL certificate errors unless the device is patched to skip verification or trust a custom CA. |
+| | **Brittle**: Some firmware versions may overwrite `/etc/hosts` on reboot. |
+
+---
+
+## Method 3: Binary Patching
+
+A low-level approach where the actual compiled binaries (e.g., `BoseApp`, `IoT`) are modified to change hardcoded URL patterns. Research into these patterns has been documented in both **SoundCork** (Issue #128) and **ÜberBöse API** research.
+
+### Technical Details
+- **Target Binaries**: `/opt/Bose/BoseApp`, `/opt/Bose/IoT`, `/opt/Bose/lib/libBmxAccountHsm.so`
+- **Mechanism**:
+    - **URL Replacement**: Using a hex editor to search for string patterns like `https://streaming.bose.com` and replacing them with a custom URL of the **exact same length**.
+    - **Regex Neutralization**: Some libraries (like `libBmxAccountHsm.so`) perform a validation check called `IsItBose` using a hardcoded regex. This regex prevents the device from connecting to non-Bose domains even if the URL is changed in the configuration.
+
+#### The `IsItBose` Regex Patch
+Research in the **SoundCork** community (Issue #62) identified a specific regex in `libBmxAccountHsm.so` that enforces Bose/Apigee domain usage:
+`^https:\/\/bose-[a-zA-Z0-9\.\_\-\$\%]\+\.apigee\.net\/`
+
+By patching this regex to be more "lax", the device can be made to accept any custom domain.
+
+**Example Patch**:
+Using `sed` to replace the strict regex with a broad match while preserving the original string length:
+```bash
+sed "s#\^https:....bose.\+apigee..net..#http[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]*#g" \
+< libBmxAccountHsm.so.orig > libBmxAccountHsm.so.patched
+```
+
+### Implementation
+1. Copy the target binary or library from the device to a PC.
+2. Use a hex editor or `sed` to locate and patch the URL strings or regex patterns.
+3. Copy the patched file back to the device.
+4. Restore execution permissions and reboot.
+
+### Pros & Cons
+| Pros | Cons |
+| :--- | :--- |
+| **Bypass Config**: Works even if the firmware ignores XML settings. | **High Risk**: Modifying binaries can lead to permanent bricks or boot loops. |
+| **Hardcoded Redirects**: Can catch URLs that aren't exposed in configuration files. | **Length Constraint**: Custom URLs must fit within the space of the original strings. |
+| | **Firmware Specific**: Patches must be reapplied after every software update. |
+| | **Complexity**: Requires understanding of binary structures and potential checksums. |
+
+---
+
+## Comparison & Usage Strategy
+
+### Summary Table
+
+| Method | Primary Use Case | Ease | Safety | Persistence | Granularity |
+| :--- | :--- | :---: | :---: | :---: | :---: |
+| **XML Config** | Logical service redirection | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **`/etc/hosts`** | Quick global DNS override | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
+| **Binary Patch** | Bypassing hardcoded checks | ⭐ | ⭐ | ⭐ | ⭐⭐⭐ |
+
+---
+
+## Combining Methods: When is one not enough?
+
+A common question is whether these methods can be used in isolation or if they must be combined. The answer depends on your specific firmware version and the target service.
+
+### Scenario A: XML Config Only (The Ideal Case)
+If your firmware does not strictly enforce the `IsItBose` check for the specific URLs you are changing, **Method 1 (XML)** is sufficient. This is the cleanest approach and is used by the `soundtouch-service` migration tool.
+
+### Scenario B: XML Config + Binary Patching (The "Locked" Case)
+On some newer firmware versions, even if you change the `<margeServerUrl>` in the XML to `http://192.168.1.10`, the internal library (`libBmxAccountHsm.so`) will validate the string against the hardcoded Bose regex.
+*   **Symptom**: The device ignores the XML setting or fails to connect despite the correct URL being present.
+*   **Solution**: You **must** apply the **Binary Patch (Method 3)** to neutralize the `IsItBose` check *in addition* to the XML change.
+
+### Scenario C: `/etc/hosts` + Custom CA (The "Clean Deep Redirect")
+If you use `/etc/hosts` to point `streaming.bose.com` to a local IP and want to avoid binary patching.
+*   **Requirement 1**: Your local server must handle HTTPS (port 443).
+*   **Requirement 2**: You must inject your Root CA into the device's trust store.
+*   **Automated Tool**: The `soundtouch-service` now supports this via the `/setup/migrate/{deviceIP}?method=hosts` endpoint.
+*   **CA Download**: You can download the auto-generated Root CA from `http://<your-server>:8000/setup/ca.crt`.
+*   **Benefit**: Maintains system integrity (no binary changes) and full end-to-end encryption.
+
+### Scenario D: `/etc/hosts` + Binary Patching (The "Legacy Deep Redirect")
+If you cannot or do not want to manage certificates, but still use `/etc/hosts` for DNS redirection.
+*   **Requirement 1**: Your local server must handle HTTPS (port 443).
+*   **Requirement 2**: Since the certificate will be invalid (mismatched domain/CA), you must patch the binary to **skip SSL verification** (see [Option 2](#option-2-ssl-verification-bypass) below).
+*   **Risk**: Less secure and higher risk of bricking due to binary modification.
+
+### Scenario E: The Triple-Threat (Total Control)
+For developers creating a completely isolated "dark" environment (no internet at all):
+1.  **XML**: Point all URLs to local services.
+2.  **Binary Patch**: Neutralize `IsItBose` to allow non-Bose domains/IPs.
+3.  **`/etc/hosts`**: Redirect hardcoded domains that aren't exposed in the XML (like analytics or NTP) to prevent leakage to the real Bose cloud.
+4.  **Process Instrumentation**: Use [SoundTouch Hook](https://github.com/CodeFinder2/bose-soundtouch-hook) to monitor and override internal behavior in real-time. This is particularly useful for handling unknown hostnames or deep-hooking into service discovery logic that might bypass standard DNS lookups.
+
+---
+
+## Handling HTTPS & SSL Certificates
+
+When redirecting HTTPS traffic to a custom service, SoundTouch devices will fail the SSL handshake because they do not trust your local server's certificate.
+
+### Option 1: Custom CA Certificate (Recommended)
+
+As suggested by community members, you can configure the device to trust your own Root CA. This allows for secure HTTPS communication without patching binaries.
+
+**Technical Steps**:
+1.  **Generate a Root CA** and issue a certificate for the target domain (e.g., `streaming.bose.com`).
+2.  **SSH into the device** and copy your `rootCA.crt` to `/usr/share/ca-certificates/custom/`.
+3.  **Update the Trust Store**:
+    - **Method A (Append to Bundle)**: `cat /usr/share/ca-certificates/custom/rootCA.crt >> /etc/pki/tls/certs/ca-bundle.crt`
+    - **Method B (Symlinks)**: Add the certificate to `/etc/ssl/certs/` and create a hash symlink using `c_rehash` (if available) or manual mapping.
+
+**Pros & Cons**:
+| Pros | Cons |
+| :--- | :--- |
+| **Secure**: Maintains end-to-end encryption. | **Requires SSH**: Must have root access to modify the trust store. |
+| **Clean**: No binary patching required for SSL bypass. | **Update Risk**: Firmware updates might overwrite the `ca-bundle.crt`. |
+
+### Option 2: SSL Verification Bypass
+
+If you cannot or do not want to manage certificates, you can patch the binary to skip certificate verification.
+
+**Target**: `libBmxAccountHsm.so` or `BoseApp`
+**Mechanism**: Locating the SSL verification function (often in the internal curl-based or openssl-based logic) and forcing it to return "Success" regardless of the certificate status.
+
+---
+
+## Recommendation
+
+1.  **Start with Method 1 (XML Modification)**. It is the least invasive and most likely to work across different models.
+2.  **Verify connectivity**. If the device refuses to connect to your custom endpoint, check logs for "IsItBose" or validation failures.
+3.  **Apply Method 3 (Binary Patching)** only if Method 1 is being actively blocked by the firmware's validation logic.
+4.  **Avoid Method 2 (`/etc/hosts`)** unless you are prepared to handle SSL certificate complexities or are performing quick temporary tests.

docs/analysis/IOT-CONFIG-SUMMARY.md

@@ -0,0 +1,189 @@
+# IoT Configuration Quick Reference
+
+## Key Files and Locations
+
+| File/Location                           | Purpose                | Notes                                   |
+|-----------------------------------------|------------------------|-----------------------------------------|
+| `/mnt/nv/BoseApp-Persistence/1/IoT.xml` | Main IoT configuration | Contains clientID, endpoint, deployment |
+| `/opt/Bose/IoT`                         | IoT service binary     | ARM executable, AWS IoT SDK             |
+| `/mnt/nv/IoTCerts/`                     | Certificate storage    | Device certs and private keys           |
+| `/etc/init.d/SoundTouch`                | System startup script  | Creates directory structure             |
+| `/opt/Bose/etc/Shepherd-noncore.xml`    | Service configuration  | Defines IoT daemon startup              |
+
+## Configuration Parameters
+
+### IoT.xml Structure
+```xml
+<Configuration 
+    clientID="[UUID]" 
+    iotEndpoint="[AWS_IOT_ENDPOINT]" 
+    deployment="PROD" />
+```
+
+### Device-Specific Values
+- **ST20**: `clientID="577ecfcc-2db3-4989-92c9-76d7704f9fb3"`
+- **ST10**: `clientID="eb1a6d8f-0bb1-4aa7-9113-ea673fcef96e"`
+- **Endpoint**: `a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com` (XML)
+- **Backup Endpoint**: `amqmidtcohfms.iot.us-east-1.amazonaws.com` (hardcoded)
+
+## Protocol Stack
+
+```
+Application Layer:    AWS IoT Device Shadows (JSON)
+Presentation Layer:   RapidJSON parsing/serialization
+Session Layer:        MQTT v3.1.1
+Transport Layer:      TLS v1.2
+Network Layer:        TCP/IP
+```
+
+## Certificate Files
+
+| File                  | Location            | Purpose                   |
+|-----------------------|---------------------|---------------------------|
+| `iot-cert.pem.crt`    | `/mnt/nv/IoTCerts/` | Device client certificate |
+| `iot-private.pem.key` | `/mnt/nv/IoTCerts/` | Device private key        |
+| `rootCA.crt`          | `/var/lib/iot/`     | AWS IoT Root CA           |
+
+## MQTT Topics
+
+### Shadow Operations
+```
+$aws/things/{clientID}/shadow/update
+$aws/things/{clientID}/shadow/update/accepted
+$aws/things/{clientID}/shadow/update/rejected
+$aws/things/{clientID}/shadow/delete
+```
+
+### JSON Payload Examples
+
+#### Device State Report
+```json
+{
+  "state": {
+    "reported": {
+      "deviceState": "CONNECTED",
+      "powerState": "ON",
+      "zoneState": "...",
+      "groupState": "..."
+    }
+  }
+}
+```
+
+#### Disconnection Message
+```json
+{
+  "state": {
+    "reported": {
+      "deviceState": "DISCONNECTED"
+    }
+  }
+}
+```
+
+## Process Information
+
+- **IoT Service PID**: 1837
+- **BoseApp PID**: 1846
+- **Daemon Manager**: Shepherd
+- **Service Type**: Non-core (stopped during updates)
+
+## Registration Flow
+
+1. Device generates X.509 CSR
+2. Calls `https://voice.api.bose.io/alexa/certificate`
+3. Receives device certificate
+4. Stores cert/key in `/mnt/nv/IoTCerts/`
+5. Connects to AWS IoT using certificate auth
+
+## Directory Creation (Init Script)
+
+```bash
+mkdir -p /mnt/nv/BoseLog /mnt/nv/IoTCerts /mnt/nv/BoseApp-Persistence/1
+mkdir -m 700 -p /mnt/nv/BoseApp-Persistence/1/Keys
+```
+
+## Error Messages and Debugging
+
+### Common Log Messages
+- `"Connection attempt %u to MQTT port at host %s"`
+- `"MQTT port not available. Retrying in %u seconds"`
+- `"Device connected with MQTT"`
+- `"got shadow response: accepted. Payload: %s"`
+- `"Failed to register device and get certificate, retrying"`
+
+### Connection States
+- `"MQTT port is open"`
+- `"Successfully connected to MQTT server"`
+- `"Disconnecting from IoT server"`
+- `"UpdateShadow called when network is not ready"`
+
+## Integration Points
+
+### AWS Services
+- AWS IoT Core (MQTT broker)
+- AWS IoT Device Management (certificates)
+- AWS IoT Device Shadows (state sync)
+
+### Bose Ecosystem
+- Mobile apps (remote control)
+- Alexa integration (voice commands)
+- Multi-room audio (zone coordination)
+- OTA updates (firmware management)
+
+## Quick Troubleshooting
+
+1. **No IoT connectivity**: Check certificate files in `/mnt/nv/IoTCerts/`
+2. **Certificate errors**: Verify registration endpoint accessibility
+3. **MQTT failures**: Check both primary and backup endpoints
+4. **Config issues**: Validate IoT.xml format and clientID uniqueness
+5. **Service not starting**: Check Shepherd configuration and process status
+
+## MQTT Monitoring Capabilities
+
+### Direct Access with Device Credentials
+```bash
+# Subscribe to device shadow events (own device only)
+mosquitto_sub -h a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com \
+              -p 8883 --cafile /var/lib/iot/rootCA.crt \
+              --cert /mnt/nv/IoTCerts/iot-cert.pem.crt \
+              --key /mnt/nv/IoTCerts/iot-private.pem.key \
+              -t '$aws/things/577ecfcc-2db3-4989-92c9-76d7704f9fb3/shadow/#'
+```
+
+### AWS IoT Policy Restrictions
+- Device certificates limited to own clientID topics only
+- No wildcard subscriptions across devices
+- IP/location restrictions may apply
+- Certificate revocation for unusual activity
+
+### Alternative Monitoring Methods
+```bash
+# Network traffic capture (less intrusive)
+tcpdump -i eth0 -s0 -w soundtouch_iot.pcap host a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com
+
+# Monitor connection patterns
+tcpdump -i eth0 -n "host a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com and port 8883"
+```
+
+### Expected Message Examples
+```json
+// Power state change
+{"state":{"reported":{"powerState":"ON","deviceState":"CONNECTED"}}}
+
+// Volume adjustment  
+{"state":{"reported":{"volume":25,"muted":false}}}
+
+// Zone configuration
+{"state":{"reported":{"zoneState":"master","groupMembers":["device1"]}}}
+```
+
+## Security Notes
+
+- TLS 1.2 encryption for all communications
+- X.509 mutual authentication
+- Private keys stored with 700 permissions
+- No hardcoded credentials in binaries
+- Automatic certificate lifecycle management
+- **Monitoring Constraints**: Device credentials restricted to own device topics
+- **Ethical Consideration**: Only monitor devices you own

docs/analysis/IOT-CONFIGURATION-ANALYSIS.md

@@ -0,0 +1,370 @@
+# IoT Configuration Analysis
+
+## Overview
+
+This document provides a detailed analysis of the AWS IoT configuration system used by Bose SoundTouch devices, based on firmware backup analysis from ST10 and ST20 models.
+
+## Configuration Files
+
+### IoT.xml Location and Content
+
+The IoT configuration is stored in XML format at:
+- **Path**: `/mnt/nv/BoseApp-Persistence/1/IoT.xml`
+- **Purpose**: Contains AWS IoT Core connection parameters
+
+#### ST20 Configuration
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<Configuration clientID="uuid1"
+               iotEndpoint="a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com"
+               deployment="PROD" />
+```
+
+#### ST10 Configuration
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<Configuration clientID="uuid2"
+               iotEndpoint="a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com"
+               deployment="PROD" />
+```
+
+### Key Observations
+- Each device has a unique `clientID` (UUID format)
+- Both devices use the same AWS IoT endpoint
+- Both are configured for production deployment (`PROD`)
+
+## Binary Analysis
+
+### Primary IoT Service Binary
+
+**Location**: `/opt/Bose/IoT`
+- **Type**: ARM ELF 32-bit executable
+- **Purpose**: Main IoT daemon process
+- **Framework**: AWS IoT SDK for C++
+
+### Certificate and Key Management
+
+The IoT binary manages the following certificate files:
+
+| File                  | Location            | Purpose                     |
+|-----------------------|---------------------|-----------------------------|
+| `iot-cert.pem.crt`    | `/mnt/nv/IoTCerts/` | Device client certificate   |
+| `iot-private.pem.key` | `/mnt/nv/IoTCerts/` | Device private key          |
+| `rootCA.crt`          | `/var/lib/iot/`     | AWS IoT Root CA certificate |
+
+### Certificate Registration Process
+
+1. **CSR Generation**: Device generates X.509 certificate signing request
+2. **Registration Endpoint**: `https://voice.api.bose.io/alexa/certificate`
+3. **Certificate Storage**: Certificates stored in `/mnt/nv/IoTCerts/`
+4. **Automatic Provisioning**: Process appears to be automated during device setup
+
+## Protocol Analysis
+
+### Connection Details
+
+- **Protocol**: MQTT over TLS 1.2
+- **Port**: Standard MQTT over SSL (likely 8883)
+- **Authentication**: X.509 client certificate mutual authentication
+- **Endpoint Redundancy**:
+  - Primary (hardcoded): `amqmidtcohfms.iot.us-east-1.amazonaws.com`
+  - Fallback (XML config): `a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com`
+
+### AWS IoT Device Shadow Integration
+
+The system uses AWS IoT Device Shadows for state management:
+
+#### Topic Structure
+```
+$aws/things/{thing_name}/shadow/update
+$aws/things/{thing_name}/shadow/update/accepted
+$aws/things/{thing_name}/shadow/update/rejected
+$aws/things/{thing_name}/shadow/delete
+```
+
+#### Shadow JSON Format
+```json
+{
+  "state": {
+    "desired": {},
+    "reported": {
+      "deviceState": "CONNECTED|DISCONNECTED",
+      "powerState": "ON|OFF",
+      "zoneState": "...",
+      "groupState": "..."
+    }
+  },
+  "version": 0,
+  "clientToken": "...",
+  "timestamp": 0
+}
+```
+
+### Message Types
+
+1. **Device State Updates**
+   - Connection status (`CONNECTED`/`DISCONNECTED`)
+   - Power state changes
+   - Audio zone configuration
+   - Multi-room grouping status
+
+2. **Shadow Delta Processing**
+   - Receives desired state changes
+   - Updates device configuration
+   - Reports new state back to shadow
+
+## System Integration
+
+### Service Management
+
+The IoT service is managed by the Shepherd daemon system:
+
+**Configuration**: `/opt/Bose/etc/Shepherd-noncore.xml`
+```xml
+<ShepherdConfig>
+  <daemon name="STSCertified"/>
+  <daemon name="IoT"/>
+  <daemon name="TPDA">
+    <arg>-c</arg>
+    <arg>/opt/Bose/etc/Voice.xml</arg>
+  </daemon>
+</ShepherdConfig>
+```
+
+### Directory Structure Creation
+
+The SoundTouch init script (`/etc/init.d/SoundTouch`) ensures proper directory structure:
+
+```bash
+mkdir -p /mnt/nv/BoseLog /mnt/nv/IoTCerts /mnt/nv/BoseApp-Persistence/1
+mkdir -m 700 -p /mnt/nv/BoseApp-Persistence/1/Keys
+```
+
+### Process Information
+
+From runtime analysis (`/var/run/shepherd/pids`):
+- IoT service runs as PID 1837
+- BoseApp service runs as PID 1846
+- Both services are active during normal operation
+
+## Configuration Dependencies
+
+### Files That Reference IoT Configuration
+
+1. **IoT Binary** (`/opt/Bose/IoT`)
+   - Primary consumer of IoT.xml configuration
+   - Contains hardcoded backup endpoints
+   - Manages certificate lifecycle
+
+2. **BoseApp Binary** (`/opt/Bose/BoseApp`)
+   - References BoseApp-Persistence directory structure
+   - May trigger IoT updates based on device state changes
+
+3. **SoundTouch Init Script** (`/etc/init.d/SoundTouch`)
+   - Creates necessary directory structure
+   - Ensures proper permissions for certificate storage
+
+4. **Shepherd Configuration** (`/opt/Bose/etc/Shepherd-noncore.xml`)
+   - Defines IoT service startup parameters
+   - Manages service lifecycle
+
+## Security Considerations
+
+### Certificate Management
+- Private keys stored with 700 permissions
+- Certificates managed automatically by the device
+- Registration process appears to use device-specific authentication
+
+### Network Security
+- All communication over TLS 1.2
+- Mutual authentication using X.509 certificates
+- AWS IoT Core provides additional access controls
+
+### Configuration Protection
+- Configuration files stored in persistent storage
+- Directory structure created with appropriate permissions
+- No hardcoded credentials in binaries (uses certificate-based auth)
+
+## Integration Points
+
+### AWS Services
+- **AWS IoT Core**: Primary messaging and device management
+- **AWS IoT Device Management**: Certificate provisioning
+- **AWS IoT Device Shadows**: State synchronization
+
+### Bose Services
+- **Mobile Applications**: Remote control and monitoring
+- **Alexa Integration**: Voice control capabilities
+- **Multi-room Audio**: Zone and group coordination
+
+### Device Functions
+- **Power Management**: Remote power on/off
+- **Audio Control**: Volume, source selection
+- **Network Configuration**: WiFi and connectivity settings
+- **Firmware Updates**: OTA update coordination
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Certificate Problems**
+   - Check `/mnt/nv/IoTCerts/` for valid certificates
+   - Verify certificate registration endpoint accessibility
+   - Ensure proper file permissions (600 for keys)
+
+2. **Connection Issues**
+   - Verify both primary and fallback endpoints
+   - Check TLS 1.2 support and cipher suites
+   - Validate clientID uniqueness
+
+3. **Configuration Issues**
+   - Ensure IoT.xml has proper XML format
+   - Verify clientID is valid UUID format
+   - Check deployment parameter matches environment
+
+### Debug Information
+
+The IoT binary provides extensive logging for:
+- MQTT connection attempts and status
+- Certificate loading and validation
+- Shadow message processing
+- Network state changes
+
+## MQTT Monitoring and Security Considerations
+
+### Direct MQTT Access with Device Credentials
+
+With access to the device's private key and certificate, it's technically possible to subscribe to MQTT events:
+
+```bash
+# Subscribe to device shadow events
+mosquitto_sub -h a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com \
+              -p 8883 --cafile /var/lib/iot/rootCA.crt \
+              --cert /mnt/nv/IoTCerts/iot-cert.pem.crt \
+              --key /mnt/nv/IoTCerts/iot-private.pem.key \
+              -t '$aws/things/_uuid_/shadow/#'
+```
+
+### Security Constraints and Limitations
+
+#### AWS IoT Policy Restrictions
+Device certificates are bound to specific policies that typically restrict:
+- Access to device-specific topics only (`$aws/things/{clientID}/shadow/*`)
+- No wildcard subscriptions across multiple devices
+- Limited publish/subscribe permissions
+- Possible IP geolocation restrictions
+
+#### Example Policy Structure
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": "iot:Connect",
+      "Resource": "arn:aws:iot:us-east-1:*:client/${iot:ClientId}"
+    },
+    {
+      "Effect": "Allow",
+      "Action": ["iot:Publish", "iot:Subscribe", "iot:Receive"],
+      "Resource": [
+        "arn:aws:iot:us-east-1:*:topic/$aws/things/${iot:ClientId}/shadow/*",
+        "arn:aws:iot:us-east-1:*:topicfilter/$aws/things/${iot:ClientId}/shadow/*"
+      ]
+    }
+  ]
+}
+```
+
+#### Additional Security Measures
+- Certificate revocation for unusual activity
+- Device fingerprinting and connection frequency limits
+- Service shutdown timeline (May 2026) affecting endpoint availability
+
+### Alternative Monitoring Approaches
+
+#### Network Traffic Capture
+A less intrusive method to analyze MQTT communication patterns:
+
+```bash
+# Capture encrypted MQTT traffic from the actual device
+tcpdump -i eth0 -s0 -w soundtouch_iot.pcap host a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com
+
+# Monitor connection patterns
+tcpdump -i eth0 -n "host a2bhvr9c4wn4ya.iot.us-east-1.amazonaws.com and port 8883"
+```
+
+#### Local MQTT Broker Setup
+For development and testing, create a local MQTT broker that mimics AWS IoT behavior:
+
+```bash
+# Install and configure Mosquitto
+sudo apt-get install mosquitto mosquitto-clients
+
+# Create test shadow topics
+mosquitto_pub -h localhost -t '$aws/things/test-device/shadow/update' \
+              -m '{"state":{"reported":{"deviceState":"CONNECTED"}}}'
+```
+
+### Ethical and Legal Considerations
+
+- **Device Ownership**: Only monitor devices you own
+- **Terms of Service**: Using credentials outside device context may violate Bose ToS
+- **Unauthorized Access**: Accessing Bose's AWS infrastructure could be considered inappropriate
+- **Research Purpose**: Limit monitoring to understanding message formats for local alternatives
+
+### Expected Message Examples
+
+If monitoring is successful, typical shadow messages include:
+
+```json
+// Power state change
+{
+  "state": {
+    "reported": {
+      "powerState": "ON",
+      "deviceState": "CONNECTED",
+      "timestamp": 1703875200
+    }
+  }
+}
+
+// Volume adjustment
+{
+  "state": {
+    "reported": {
+      "volume": 25,
+      "muted": false
+    }
+  }
+}
+
+// Zone configuration
+{
+  "state": {
+    "reported": {
+      "zoneState": "master",
+      "groupMembers": ["device1", "device2"]
+    }
+  }
+}
+```
+
+### Recommended Research Approach
+
+1. **Document Message Formats**: Capture and analyze JSON structures
+2. **Understand State Transitions**: Map device actions to shadow updates
+3. **Build Local Alternative**: Use insights to create local MQTT shadow service
+4. **Prepare for Service Shutdown**: Develop migration strategy before May 2026
+
+## Conclusion
+
+The Bose SoundTouch IoT configuration system is a sophisticated implementation using AWS IoT Core for real-time device management. The system provides:
+
+- Secure, certificate-based authentication
+- Reliable bi-directional communication
+- Comprehensive device state management
+- Integration with voice assistants and mobile applications
+- Robust error handling and retry mechanisms
+
+This architecture enables seamless remote control, monitoring, and coordination of SoundTouch devices across multiple platforms and services.

docs/analysis/MISSING-ROUTES-SPOTIFY.md

@@ -0,0 +1,43 @@
+# Spotify Account Addition Implementation Status
+
+To fully replace Bose cloud services for the Spotify account addition flow in the "Stockholm" SoundTouch application, the following routes have been implemented in the `soundtouch-service`:
+
+## 1. OAuth Token Exchange (Bose Cloud)
+
+The Stockholm background worker (in `worker_common.js` and `spotify_worker.js`) performs a token exchange using an authorization code.
+
+*   **Route**: `POST /oauth/account/{account}/music/musicprovider/{sourceID}/token/cs`
+*   **Purpose**: To exchange the Spotify authorization code for a Bose-mediated token.
+*   **Implementation**: `HandleBoseAccountToken` in `pkg/service/handlers/handlers_oauth.go`.
+*   **Registration**: Registered in `cmd/soundtouch-service/main.go` under the `/oauth` route group.
+
+## 2. Cloud Source Registration (Marge Service)
+
+The SoundTouch application registers a new music source (e.g., Spotify) with the Bose cloud profile.
+
+*   **Route**: `POST /streaming/account/{account}/source`
+*   **Purpose**: To add the new source (username, credentials, display name) to the user's emulated cloud profile.
+*   **Implementation**: `HandleMargeAddSource` in `pkg/service/handlers/handlers_marge.go`.
+*   **Registration**: Registered in `cmd/soundtouch-service/main.go` under the `/streaming` route group.
+*   **Payload Format**: XML `application/vnd.bose.streaming-v1.1+xml` containing `<source>` with `<username>`, `<sourceproviderid>`, and `<credential type="token_version_3">`.
+
+## 3. Redirect Handling (Browser to App)
+
+The `soundtouch://` deep link redirect URI is handled by the management interface which provides the OAuth callback.
+
+*   **Callback Route**: `GET /mgmt/spotify/callback`
+*   **Implementation**: `HandleMgmtSpotifyCallback` in `pkg/service/handlers/handlers_mgmt.go`.
+*   **Confirmation Route**: `POST /mgmt/spotify/confirm` (used by mobile apps for deep-link codes).
+*   **Implementation**: `HandleMgmtSpotifyConfirm` in `pkg/service/handlers/handlers_mgmt.go`.
+
+## Implementation Details
+
+1.  **Marge Add Source**:
+    *   `HandleMargeAddSource` in `pkg/service/handlers/handlers_marge.go` parses the incoming XML and persists the new source to the `DataStore` for the corresponding account.
+
+2.  **OAuth Account Token Exchange**:
+    *   `HandleBoseAccountToken` in `pkg/service/handlers/handlers_oauth.go` supports the `/oauth/account/.../token/cs` path.
+    *   It responds with a JSON payload including `access_token` and `token_type` "Bearer" after exchanging the code via `ExchangeCodeAndStore`.
+
+3.  **Router Registration**:
+    *   These paths are registered in `cmd/soundtouch-service/main.go` within the `/streaming`, `/oauth`, and `/mgmt` route blocks.

docs/analysis/UPSTREAM-URLS.md

@@ -0,0 +1,84 @@
+# Upstream URLs & Domains Analysis
+
+This document provides a comprehensive overview of the upstream Bose cloud services and domains that SoundTouch devices communicate with. These details were gathered from firmware analysis of ST10/ST20 devices, binary string extraction, and community research from the **SoundCork** project (Issue #128).
+
+## Core Service Domains
+
+SoundTouch devices use a set of primary domains for their operation. These are often configurable via the `SoundTouchSdkPrivateCfg.xml` file.
+
+| Service             | Primary Domain          | Purpose                                                             |
+|:--------------------|:------------------------|:--------------------------------------------------------------------|
+| **Marge**           | `streaming.bose.com`    | Account management, streaming source providers, and preset sync.    |
+| **BMX Registry**    | `content.api.bose.io`   | Bose Media eXchange service discovery and registry.                 |
+| **Stats/Analytics** | `events.api.bosecm.com` | Telemetry, device events, and usage statistics.                     |
+| **Software Update** | `worldwide.bose.com`    | Firmware update checks and downloads (path: `/updates/soundtouch`). |
+| **Voice/Alexa**     | `voice.api.bose.io`     | Token management for Amazon Alexa integration.                      |
+
+## Internal & Development Domains
+
+Analysis of device binaries (`BoseApp`, `IoT`) and community findings revealed several internal, integration, and development domains used by Bose.
+
+### Marge & Auth Proxies
+- `bose-test.apigee.net/margeproxy` (Integration/Test proxy)
+- `bose-test.apigee.net/margeproxyefe`
+- `streamingstg.bose.com` (Staging)
+- `streamingintoauth.bose.com` (Internal Auth)
+- `streamingefeintoauth.bose.com` (Internal EFE Auth)
+- `streamingefeint.bose.com`
+
+### BMX & Content Registry
+- `test.content.api.bose.io`
+- `content.api.bose.io/bmx/registry/v1/services`
+- `test.content.api.bose.io/bmx/int-registry/v1/services`
+- `test.content.api.bose.io/bmx/efe-registry/v1/services`
+
+### Stats & Analytics
+- `eventsdev.api.bosecm.com`
+- `eventsefe.api.bosecm.com`
+- `eventsdev.bosecm.com`
+
+### Software Updates
+- `worldwide.bose.com/updates/soundtouch-int`
+- `worldwide.bose.com/updates/soundtouch-efe`
+
+## Third-Party Services
+
+Devices also communicate directly with third-party providers for specific features.
+
+- **Pandora**: 
+    - `device-tuner.pandora.com`
+    - `device-tuner-beta.savagebeast.com`
+- **Amazon AVS**:
+    - `avs.na.amazonalexa.com`
+
+## Hardcoded Validation (IsItBose)
+
+As documented in [DEVICE-REDIRECT-METHODS.md](DEVICE-REDIRECT-METHODS.md#method-3-binary-patching), the `libBmxAccountHsm.so` library contains a hardcoded regex to validate these URLs:
+
+`^https:\/\/bose-[a-zA-Z0-9\.\_\-\$\%]\+\.apigee\.net\/`
+
+This regex ensures that certain critical services must reside on the `apigee.net` domain under a `bose-` prefix, unless patched.
+
+## Configuration File References
+
+On-device, these URLs are primarily managed in the following files:
+
+1.  **`/opt/Bose/etc/SoundTouchSdkPrivateCfg.xml`**:
+    *   `<margeServerUrl>`
+    *   `<statsServerUrl>`
+    *   `<swUpdateUrl>`
+    *   `<bmxRegistryUrl>`
+2.  **`/opt/Bose/etc/Voice.xml`**:
+    *   `<TPDATokenUrl>` (Points to `voice.api.bose.io`)
+3.  **`/opt/Bose/etc/HandCraftedWebServer-SoundTouch.xml`**:
+    *   Contains internal local API mapping.
+
+## Conclusion for Offline Operation
+
+To achieve full offline operation or redirection to a custom service (like `soundtouch-service`), all of the above domains must either be redirected via DNS (`/etc/hosts`) or updated in the device's XML configuration files. For domains not exposed in XML, binary patching or DNS-level redirection is the only option.
+
+---
+
+## References
+- [SoundCork Issue #128: Endpoint and URL Listing](https://github.com/deborahgu/soundcork/issues/128#issuecomment-3892933337)
+- [Bose SoundTouch Web API v1.0 Specification](https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf)

docs/analysis/WIKI-COMPARISON.md

@@ -1,7 +1,7 @@
 # SoundTouch API Comparison: Community Wiki vs Current Implementation
 
 **Date:** January 2026
-**Source:** [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)  
+**Source:** [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
 **Our Implementation:** Bose-SoundTouch Go Library v1.0
 
 ## Executive Summary
@@ -20,84 +20,84 @@ The SoundTouch Plus community wiki documents **87 distinct API endpoints** with
 
 ### ✅ Already Implemented (23 endpoints)
 
-| Endpoint | Wiki Status | Our Status | Notes |
-|----------|-------------|------------|-------|
-| `/info` | ✅ Documented | ✅ Complete | Device information |
-| `/now_playing` | ✅ Documented | ✅ Complete | Current playback status |
-| `/key` | ✅ Documented | ✅ Complete | Key press/release simulation |
-| `/volume` | ✅ Documented | ✅ Complete | Volume and mute control |
-| `/bass` | ✅ Documented | ✅ Complete | Bass level control |
-| `/bassCapabilities` | ✅ Documented | ✅ Complete | Bass capability detection |
-| `/sources` | ✅ Documented | ✅ Complete | Available audio sources |
-| `/select` | ✅ Documented | ✅ Complete | Source selection |
-| `/presets` | ✅ Documented | ✅ Complete | Preset configurations (read-only) |
-| `/getZone` | ✅ Documented | ✅ Complete | Zone status and membership |
-| `/setZone` | ✅ Documented | ✅ Complete | Zone creation and management |
-| `/addZoneSlave` | ✅ Documented | ✅ Complete | Add device to zone |
-| `/removeZoneSlave` | ✅ Documented | ✅ Complete | Remove device from zone |
-| `/capabilities` | ✅ Documented | ✅ Complete | Device feature capabilities |
-| `/audiodspcontrols` | ✅ Documented | ✅ Complete | Audio DSP modes and video sync |
-| `/audioproducttonecontrols` | ✅ Documented | ✅ Complete | Advanced bass/treble controls |
-| `/audioproductlevelcontrols` | ✅ Documented | ✅ Complete | Speaker level controls |
-| `/name` (GET/POST) | ✅ Documented | ✅ Complete | Device name management |
-| `/balance` | ✅ Documented | ✅ Complete | Stereo balance control |
-| `/clockTime` | ✅ Documented | ✅ Complete | Device time management |
-| `/clockDisplay` | ✅ Documented | ✅ Complete | Clock display settings |
-| `/networkInfo` | ✅ Documented | ✅ Complete | Network connectivity info |
-| `/requestToken` | ✅ Documented | ✅ Complete | Bearer token generation |
+| Endpoint                     | Wiki Status  | Our Status | Notes                             |
+|------------------------------|--------------|------------|-----------------------------------|
+| `/info`                      | ✅ Documented | ✅ Complete | Device information                |
+| `/now_playing`               | ✅ Documented | ✅ Complete | Current playback status           |
+| `/key`                       | ✅ Documented | ✅ Complete | Key press/release simulation      |
+| `/volume`                    | ✅ Documented | ✅ Complete | Volume and mute control           |
+| `/bass`                      | ✅ Documented | ✅ Complete | Bass level control                |
+| `/bassCapabilities`          | ✅ Documented | ✅ Complete | Bass capability detection         |
+| `/sources`                   | ✅ Documented | ✅ Complete | Available audio sources           |
+| `/select`                    | ✅ Documented | ✅ Complete | Source selection                  |
+| `/presets`                   | ✅ Documented | ✅ Complete | Preset configurations (read-only) |
+| `/getZone`                   | ✅ Documented | ✅ Complete | Zone status and membership        |
+| `/setZone`                   | ✅ Documented | ✅ Complete | Zone creation and management      |
+| `/addZoneSlave`              | ✅ Documented | ✅ Complete | Add device to zone                |
+| `/removeZoneSlave`           | ✅ Documented | ✅ Complete | Remove device from zone           |
+| `/capabilities`              | ✅ Documented | ✅ Complete | Device feature capabilities       |
+| `/audiodspcontrols`          | ✅ Documented | ✅ Complete | Audio DSP modes and video sync    |
+| `/audioproducttonecontrols`  | ✅ Documented | ✅ Complete | Advanced bass/treble controls     |
+| `/audioproductlevelcontrols` | ✅ Documented | ✅ Complete | Speaker level controls            |
+| `/name` (GET/POST)           | ✅ Documented | ✅ Complete | Device name management            |
+| `/balance`                   | ✅ Documented | ✅ Complete | Stereo balance control            |
+| `/clockTime`                 | ✅ Documented | ✅ Complete | Device time management            |
+| `/clockDisplay`              | ✅ Documented | ✅ Complete | Clock display settings            |
+| `/networkInfo`               | ✅ Documented | ✅ Complete | Network connectivity info         |
+| `/requestToken`              | ✅ Documented | ✅ Complete | Bearer token generation           |
 
 ### 🔥 High Priority Missing (20 endpoints)
 
-| Endpoint | Wiki Status | Priority | Use Case |
-|----------|-------------|----------|----------|
-| `/storePreset` | ✅ Detailed | **HIGH** | Save stations/playlists to presets |
-| `/removePreset` | ✅ Detailed | **HIGH** | Delete saved presets |
-| `/selectPreset` | ✅ Detailed | **HIGH** | Play preset by ID |
-| `/setMusicServiceAccount` | ✅ Detailed | **HIGH** | Add Spotify/Pandora accounts |
-| `/removeMusicServiceAccount` | ✅ Detailed | **HIGH** | Remove music service accounts |
-| `/searchStation` | ✅ Detailed | **HIGH** | Find Pandora/Spotify content |
-| `/addStation` | ✅ Detailed | **HIGH** | Add stations to favorites |
-| `/removeStation` | ✅ Detailed | **HIGH** | Remove stations from favorites |
-| `/navigate` | ✅ Detailed | **HIGH** | Browse music libraries/services |
-| `/search` | ✅ Detailed | **HIGH** | Search music content |
-| `/userPlayControl` | ✅ Detailed | **HIGH** | Play/pause/stop controls |
-| `/userRating` | ✅ Detailed | **HIGH** | Thumbs up/down ratings |
-| `/recents` | ✅ Detailed | **HIGH** | Recently played content |
-| `/standby` | ✅ Detailed | **HIGH** | Power management |
-| `/powerManagement` | ✅ Detailed | **HIGH** | Power state information |
-| `/lowPowerStandby` | ✅ Detailed | **HIGH** | Low-power mode |
-| `/listMediaServers` | ✅ Detailed | **HIGH** | UPnP/DLNA server discovery |
-| `/serviceAvailability` | ✅ Detailed | **HIGH** | Source availability status |
-| `/introspect` | ✅ Detailed | **HIGH** | Music service account status |
-| `/language` | ✅ Detailed | **HIGH** | Device language settings |
+| Endpoint                     | Wiki Status | Priority | Use Case                           |
+|------------------------------|-------------|----------|------------------------------------|
+| `/storePreset`               | ✅ Detailed  | **HIGH** | Save stations/playlists to presets |
+| `/removePreset`              | ✅ Detailed  | **HIGH** | Delete saved presets               |
+| `/selectPreset`              | ✅ Detailed  | **HIGH** | Play preset by ID                  |
+| `/setMusicServiceAccount`    | ✅ Detailed  | **HIGH** | Add Spotify/Pandora accounts       |
+| `/removeMusicServiceAccount` | ✅ Detailed  | **HIGH** | Remove music service accounts      |
+| `/searchStation`             | ✅ Detailed  | **HIGH** | Find Pandora/Spotify content       |
+| `/addStation`                | ✅ Detailed  | **HIGH** | Add stations to favorites          |
+| `/removeStation`             | ✅ Detailed  | **HIGH** | Remove stations from favorites     |
+| `/navigate`                  | ✅ Detailed  | **HIGH** | Browse music libraries/services    |
+| `/search`                    | ✅ Detailed  | **HIGH** | Search music content               |
+| `/userPlayControl`           | ✅ Detailed  | **HIGH** | Play/pause/stop controls           |
+| `/userRating`                | ✅ Detailed  | **HIGH** | Thumbs up/down ratings             |
+| `/recents`                   | ✅ Detailed  | **HIGH** | Recently played content            |
+| `/standby`                   | ✅ Detailed  | **HIGH** | Power management                   |
+| `/powerManagement`           | ✅ Detailed  | **HIGH** | Power state information            |
+| `/lowPowerStandby`           | ✅ Detailed  | **HIGH** | Low-power mode                     |
+| `/listMediaServers`          | ✅ Detailed  | **HIGH** | UPnP/DLNA server discovery         |
+| `/serviceAvailability`       | ✅ Detailed  | **HIGH** | Source availability status         |
+| `/introspect`                | ✅ Detailed  | **HIGH** | Music service account status       |
+| `/language`                  | ✅ Detailed  | **HIGH** | Device language settings           |
 
 ### 🎵 Music Service Management (12 endpoints)
 
-| Category | Endpoints | Wiki Coverage | Notes |
-|----------|-----------|---------------|-------|
-| **Account Management** | `/setMusicServiceAccount`, `/removeMusicServiceAccount` | ✅ Full XML examples | Pandora, Spotify, NAS setup |
-| **Station Management** | `/searchStation`, `/addStation`, `/removeStation` | ✅ Pandora tested | Station discovery and favorites |
-| **Content Navigation** | `/navigate`, `/search` | ✅ Detailed examples | Music library browsing |
-| **Track Information** | `/trackInfo`, `/introspect` | ✅ Service-specific | Extended metadata |
+| Category               | Endpoints                                               | Wiki Coverage       | Notes                           |
+|------------------------|---------------------------------------------------------|---------------------|---------------------------------|
+| **Account Management** | `/setMusicServiceAccount`, `/removeMusicServiceAccount` | ✅ Full XML examples | Pandora, Spotify, NAS setup     |
+| **Station Management** | `/searchStation`, `/addStation`, `/removeStation`       | ✅ Pandora tested    | Station discovery and favorites |
+| **Content Navigation** | `/navigate`, `/search`                                  | ✅ Detailed examples | Music library browsing          |
+| **Track Information**  | `/trackInfo`, `/introspect`                             | ✅ Service-specific  | Extended metadata               |
 
 ### 🏠 Smart Home Integration (15 endpoints)
 
-| Category | Endpoints | Wiki Coverage | Notes |
-|----------|-----------|---------------|-------|
-| **Notifications** | `/speaker`, `/playNotification` | ✅ TTS examples | Text-to-speech, URL playback |
-| **Power Management** | `/standby`, `/powerManagement`, `/lowPowerStandby` | ✅ Complete | Smart home automation |
-| **Network Management** | `/performWirelessSiteSurvey`, `/addWirelessProfile`, `/getActiveWirelessProfile` | ✅ WiFi setup | Network configuration |
-| **Bluetooth** | `/enterBluetoothPairing`, `/clearBluetoothPaired`, `/bluetoothInfo` | ✅ Pairing control | Bluetooth management |
-| **Source Control** | `/selectLastSource`, `/selectLastSoundTouchSource`, `/selectLocalSource` | ✅ Source switching | Quick source access |
+| Category               | Endpoints                                                                        | Wiki Coverage      | Notes                        |
+|------------------------|----------------------------------------------------------------------------------|--------------------|------------------------------|
+| **Notifications**      | `/speaker`, `/playNotification`                                                  | ✅ TTS examples     | Text-to-speech, URL playback |
+| **Power Management**   | `/standby`, `/powerManagement`, `/lowPowerStandby`                               | ✅ Complete         | Smart home automation        |
+| **Network Management** | `/performWirelessSiteSurvey`, `/addWirelessProfile`, `/getActiveWirelessProfile` | ✅ WiFi setup       | Network configuration        |
+| **Bluetooth**          | `/enterBluetoothPairing`, `/clearBluetoothPaired`, `/bluetoothInfo`              | ✅ Pairing control  | Bluetooth management         |
+| **Source Control**     | `/selectLastSource`, `/selectLastSoundTouchSource`, `/selectLocalSource`         | ✅ Source switching | Quick source access          |
 
 ### 📱 Advanced Device Features (19 endpoints)
 
-| Category | Endpoints | Wiki Coverage | Notes |
-|----------|-----------|---------------|-------|
-| **Stereo Pairs** | `/getGroup`, `/addGroup`, `/removeGroup`, `/updateGroup` | ✅ ST-10 specific | L/R speaker pairing |
-| **System Info** | `/soundTouchConfigurationStatus`, `/systemtimeout`, `/rebroadcastlatencymode` | ✅ Configuration | Device state management |
-| **Software Updates** | `/swUpdateCheck`, `/swUpdateQuery`, `/swUpdateAbort`, `/swUpdateStart` | ✅ Update process | Firmware management |
-| **Audio Processing** | `/DSPMonoStereo`, `/audiospeakerattributeandsetting` | ✅ Hardware-specific | Advanced audio features |
+| Category             | Endpoints                                                                     | Wiki Coverage       | Notes                   |
+|----------------------|-------------------------------------------------------------------------------|---------------------|-------------------------|
+| **Stereo Pairs**     | `/getGroup`, `/addGroup`, `/removeGroup`, `/updateGroup`                      | ✅ ST-10 specific    | L/R speaker pairing     |
+| **System Info**      | `/soundTouchConfigurationStatus`, `/systemtimeout`, `/rebroadcastlatencymode` | ✅ Configuration     | Device state management |
+| **Software Updates** | `/swUpdateCheck`, `/swUpdateQuery`, `/swUpdateAbort`, `/swUpdateStart`        | ✅ Update process    | Firmware management     |
+| **Audio Processing** | `/DSPMonoStereo`, `/audiospeakerattributeandsetting`                          | ✅ Hardware-specific | Advanced audio features |
 
 ---
 
@@ -137,7 +137,7 @@ The SoundTouch Plus community wiki documents **87 distinct API endpoints** with
 
 **WebSocket Events Documented:**
 - `presetsUpdated` - Preset changes
-- `groupUpdated` - Stereo pair changes  
+- `groupUpdated` - Stereo pair changes
 - `zoneUpdated` - Multi-room changes
 - `nowPlayingUpdated` - Source/playback changes
 - `volumeUpdated` - Volume/mute changes
@@ -194,7 +194,7 @@ func (c *Client) RateCurrentTrack(rating RatingValue) error
 func (c *Client) CreateStereoPair(leftIP, rightIP string, name string) error
 func (c *Client) GetStereoPairStatus() (*StereoPair, error)
 
-// System Management  
+// System Management
 func (c *Client) CheckSoftwareUpdate() (*UpdateInfo, error)
 func (c *Client) GetSystemTimeout() (*TimeoutConfig, error)
 ```
@@ -283,7 +283,7 @@ The SoundTouch Plus Wiki represents a **treasure trove** of production-ready API
 ### Key Opportunities:
 - 🎯 **3x Coverage Expansion**: From 23 to 87+ endpoints
 - 🏠 **Smart Home Ready**: Complete automation integration
-- 🎵 **Music Service Integration**: Full streaming service support  
+- 🎵 **Music Service Integration**: Full streaming service support
 - 📱 **Professional Features**: Advanced audio and system control
 - ✅ **Production Ready**: Real-world tested examples and error handling
 
@@ -297,4 +297,4 @@ The SoundTouch Plus Wiki represents a **treasure trove** of production-ready API
 
 ---
 
-*Note: All endpoints documented in the wiki are tested against real hardware. Device-specific limitations are clearly documented with compatibility matrices for ST-10, ST-300, and other SoundTouch models.*
+*Note: All endpoints documented in the wiki are tested against real hardware. Device-specific limitations are clearly documented with compatibility matrices for ST-10, ST-300, and other SoundTouch models.*

docs/analysis/bose-soundtouch-community-tools.md

@@ -0,0 +1,297 @@
+# Bose SoundTouch — Community Tools for Post-EOL Preservation
+
+> **Context:** Bose announced the shutdown of SoundTouch cloud services, extended to **May 6, 2026**. On that date the official SoundTouch app will update to a local-only version. Bose has released the [SoundTouch Web API documentation](https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf) as open-source to enable community-driven development. This document surveys the active community projects, their feature coverage, and open development opportunities.
+
+---
+
+## What Bose Is Doing
+
+After the May 6, 2026 shutdown, the following will **continue to work**:
+
+- Streaming via Bluetooth, AirPlay, Spotify Connect, and AUX
+- Local device control and grouping via an updated SoundTouch app
+- Remote control features (play, pause, skip, volume)
+- HDMI/optical connections on soundbars
+
+The following will **stop working**:
+
+- Physical and app-based presets
+- In-app music service browsing (TuneIn, Pandora, etc.)
+- Stereo pairing for SoundTouch 10
+- Security and firmware updates
+
+---
+
+## Community Projects
+
+### 1. soundcork
+**[github.com/deborahgu/soundcork](https://github.com/deborahgu/soundcork)**
+| | |
+|---|---|
+| Language | Python |
+| License | MIT |
+| Stars | 111 |
+| Contributors | 8 |
+| Commits | 287 |
+| Status | Pre-alpha, actively developed |
+
+A reverse-engineered intercept API that replaces the Bose cloud servers locally. Works by redirecting the speaker's internal `SoundTouchSdkPrivateCfg.xml` to a self-hosted FastAPI server, emulating the `marge` server (required for basic network functionality) and the `bmx` server (required for TuneIn). Deployable as a Docker container or systemd daemon. The most community-engaged project, with a dedicated discussion thread tracking Bose cloud service status.
+
+---
+
+### 2. Überböse API
+**[github.com/julius-d/ueberboese-api](https://github.com/julius-d/ueberboese-api)**
+| | |
+|---|---|
+| Language | Java (Spring Boot) |
+| License | MIT |
+| Stars | 10 |
+| Contributors | 1 |
+| Commits | 224 |
+| Tags/Releases | 163 |
+| Documentation | [julius-d.github.io/ueberboese-api](https://julius-d.github.io/ueberboese-api/) |
+
+Reverse-engineers and rebuilds the Bose streaming HTTP API. Unique in publishing a machine-readable OpenAPI specification (`ueberboese-api.yaml`) and comprehensive request logging — making it the best research instrument for understanding what speakers actually call upstream. Implements Spotify OAuth integration and TuneIn. Companion to the Überböse App.
+
+---
+
+### 3. Überböse App
+**[github.com/julius-d/ueberboese-app](https://github.com/julius-d/ueberboese-app)**
+| | |
+|---|---|
+| Language | Flutter (Dart) |
+| License | MIT |
+| Latest version | 0.26.0 (March 2026) |
+| Distribution | [F-Droid](https://f-droid.org/en/packages/io.github.juliusd.ueberboese.app/) |
+| Platform | Android |
+
+The only native installable phone app in the ecosystem. Pairs with the Überböse API server. Features: preset view/play/reprogram, multi-room zone management, volume control, now-playing display, Spotify authentication setup. Controls speakers directly via the local SoundTouch WebServices API (no server required for basic control).
+
+---
+
+### 4. SoundTouch Hybrid 2026
+**[github.com/TJGigs/Bose-SoundTouch-Hybrid-2026](https://github.com/TJGigs/Bose-SoundTouch-Hybrid-2026)**
+| | |
+|---|---|
+| Language | Node.js (JavaScript) |
+| License | — |
+| Stars | 1 |
+| Commits | 3 (V1) / 12 (V3) |
+| Status | Experimental / testing |
+
+A self-hosted private cloud that emulates and replaces the Bose Cloud Service. Runs locally on a NAS or PC, intercepts the complex server handshakes needed to keep the SoundTouch infrastructure functional. Relies on **Music Assistant** for backend audio routing and provider aggregation. Features a setup wizard including USB config generation (`OverrideSdkPrivateCfg.xml`) and an on-screen Bose Cloud Emulation Setup guide. Targets users who want the broadest streaming provider support via Music Assistant's ecosystem.
+
+---
+
+### 5. OpenCloudTouch (OCT)
+**[github.com/scheilch/opencloudtouch](https://github.com/scheilch/opencloudtouch)**
+| | |
+|---|---|
+| Language | Python (FastAPI) + TypeScript (React) |
+| License | Apache 2.0 |
+| Stars | 9 |
+| Commits | 313 |
+| Latest release | v1.1.1 (April 12, 2026) |
+| Documentation | GitHub Wiki (EN/DE) |
+
+A single Docker container combining a FastAPI backend and React frontend. The most production-ready project in the ecosystem in terms of release discipline and deployment accessibility. Features: internet radio with full hardware preset support (buttons 1–6), responsive web UI, device discovery via SSDP/UPnP, multi-room zone management, BMX-compatible endpoints, TuneIn stream resolver, RadioBrowser as a built-in first-class search provider, and pre-built Raspberry Pi SD card images for Pi 3/4/5. Deployable on amd64, arm64, and arm/v7. Documented in English and German. Spotify and Music Assistant integration are on the roadmap.
+
+---
+
+### 6. AfterTouch
+**[github.com/gesellix/Bose-SoundTouch](https://github.com/gesellix/Bose-SoundTouch)** by gesellix
+| | |
+|---|---|
+| Language | Go |
+| License | MIT |
+| Stars | 16 |
+| Contributors | 2 |
+| Commits | 217 |
+| Releases | 51 (latest: v0.28.0, Feb 15, 2026) |
+| Documentation | [gesellix.github.io/Bose-SoundTouch](https://gesellix.github.io/Bose-SoundTouch/) |
+
+The most comprehensive single toolkit in the ecosystem. Comprises three components: a Go library (importable package), a CLI (`soundtouch-cli`), and a local cloud emulation service (`soundtouch-service`). Covers the widest range of dimensions of any single project. Implements the complete Bose Spotify OAuth relay including surrogate secret generation and token refresh proxy. Includes a built-in DNS server for device redirection without SSH, HTTPS/custom CA injection, HTTP session recording, traffic proxy/logging, and a web management UI. Tested on real SoundTouch 10 and 20 hardware. Has a Patreon for ongoing support.
+
+---
+
+### 7. soundcork-stockholm-app
+**[github.com/krahl/soundcork-stockholm-app](https://github.com/krahl/soundcork-stockholm-app)**
+| | |
+|---|---|
+| Language | Java |
+| License | — |
+| Stars | 2 |
+| Commits | 21 |
+| Status | Active development, bugs expected |
+
+A Java-based middleware that hosts the original Bose Stockholm frontend (extracted from the APK) in a local web browser at `http://127.0.0.1:8088/`. Bridges the Stockholm UI to local speakers via an HTTP proxy that resolves cross-origin issues, with SSDP-based device discovery and JSON state persistence. Unlike every other tool in the ecosystem, it runs the **official Bose UI** rather than a custom replacement — preserving the familiar Bose UX at the cost of requiring the Stockholm APK. Notable limitations: OAuth flows are unreliable, and WebSocket connections to speakers over HTTPS have blocking issues. Works alongside soundcork's backend for full cloud emulation.
+
+---
+
+### 8. jaas666/bose-soundtouch-web-api (Reference)
+**[github.com/jaas666/bose-soundtouch-web-api](https://github.com/jaas666/bose-soundtouch-web-api)**
+
+Community-maintained Markdown conversion of the official Bose SoundTouch Web API PDF (v1.0, January 7, 2026). Useful as a developer reference. Not a deployable tool.
+
+---
+
+## Feature Coverage Matrix
+
+Legend: ● Yes/complete · ◑ Partial/planned · ○ No
+
+| Dimension                                          | soundcork | Überböse API | Überböse App | ST Hybrid 2026 | OpenCloudTouch | AfterTouch | Stockholm App |
+|----------------------------------------------------|:---------:|:------------:|:------------:|:--------------:|:--------------:|:----------:|:-------------:|
+| **① App layer — local HTTP/WS control**            |           |              |              |                |                |            |               |
+| Playback control (play/pause/vol)                  |     ○     |      ○       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Preset view & trigger                              |     ○     |      ○       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Preset write / reprogram                           |     ○     |      ○       |      ●       |       ●        |       ◑        |     ●      |       ●       |
+| Multi-room zone management                         |     ○     |      ○       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Now playing / status display                       |     ○     |      ○       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Device discovery (SSDP/mDNS)                       |     ○     |      ○       |      ●       |       ○        |       ●        |     ●      |       ●       |
+| WebSocket real-time events                         |     ○     |      ○       |      ◑       |       ●        |       ◑        |     ●      |       ◑       |
+| **② Cloud/service layer — replaces Bose upstream** |           |              |              |                |                |            |               |
+| Marge server emulation                             |     ●     |      ●       |      ○       |       ●        |       ○        |     ●      |       ○       |
+| BMX / content registry                             |     ◑     |      ◑       |      ○       |       ●        |       ●        |     ●      |       ○       |
+| Account / OAuth token relay                        |     ○     |      ●       |      ○       |       ◑        |       ○        |     ●      |       ◑       |
+| Preset sync (cloud-side)                           |     ●     |      ●       |      ○       |       ●        |       ○        |     ●      |       ○       |
+| Recents sync                                       |     ●     |      ◑       |      ○       |       ◑        |       ○        |     ●      |       ○       |
+| Sources / device info persistence                  |     ●     |      ●       |      ○       |       ●        |       ○        |     ●      |       ○       |
+| Stereo group CRUD (ST10 pairs)                     |     ●     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| **③ Device redirection — USB/SSH setup**           |           |              |              |                |                |            |               |
+| Setup wizard / guided redirect                     |     ◑     |      ◑       |      ○       |       ●        |       ●        |     ●      |       ○       |
+| USB image / config generation                      |     ○     |      ○       |      ○       |       ●        |       ○        |     ◑      |       ○       |
+| HTTPS / custom CA support                          |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| **④ Streaming provider integration**               |           |              |              |                |                |            |               |
+| Internet radio (RadioBrowser)                      |     ○     |      ◑       |      ◑       |       ◑        |       ●        |     ◑      |       ○       |
+| TuneIn stream resolver                             |     ●     |      ●       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Spotify OAuth / Connect                            |     ○     |      ●       |      ●       |       ◑        |       ◑        |     ●      |       ◑       |
+| Pandora                                            |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ◑       |
+| Music Assistant backend                            |     ○     |      ○       |      ○       |       ●        |       ◑        |     ○      |       ○       |
+| **⑤ Mobile / native app**                          |           |              |              |                |                |            |               |
+| Android app (installable)                          |     ○     |      ○       |      ●       |       ○        |       ○        |     ○      |       ○       |
+| iOS app                                            |     ○     |      ○       |      ○       |       ○        |       ○        |     ○      |       ○       |
+| Mobile-responsive web UI                           |     ○     |      ○       |      ○       |       ●        |       ●        |     ●      |       ●       |
+| **⑥ Smart home / ecosystem integration**           |           |              |              |                |                |            |               |
+| Home Assistant integration                         |     ○     |      ○       |      ○       |       ○        |       ○        |     ◑      |       ○       |
+| Music Assistant integration                        |     ○     |      ○       |      ○       |       ●        |       ◑        |     ○      |       ○       |
+| **⑦ CLI / automation tools**                       |           |              |              |                |                |            |               |
+| CLI for scripting / automation                     |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| Traffic proxy / API logging                        |     ◑     |      ●       |      ○       |       ○        |       ○        |     ●      |       ◑       |
+| HTTP session recording                             |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| **⑧ Library / SDK**                                |           |              |              |                |                |            |               |
+| Importable library / package                       |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| Published API spec / docs                          |     ○     |      ●       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| Docker deployment                                  |     ●     |      ●       |      ○       |       ●        |       ●        |     ●      |       ●       |
+| Raspberry Pi SD card image                         |     ○     |      ○       |      ○       |       ○        |       ●        |     ○      |       ○       |
+
+---
+
+## Making AfterTouch the One-Stop Solution — Open Tasks
+
+AfterTouch is the strongest single project across the service and developer layers. Its remaining gaps are on the consumer-facing and ecosystem-integration sides.
+
+### Priority 1 — PWA installability
+
+The web UI is already fully responsive — it has Bootstrap grid columns, `@media (max-width: 768px)` and `@media (max-width: 576px)` breakpoints, and a proper viewport meta tag. It works on iPhone and Android browsers today. What's missing is **installability**: no `manifest.json` and no service worker, so it cannot be added to the home screen as a standalone app. Adding these would close the iOS app gap ecosystem-wide (no project has an iOS app) at minimal effort.
+
+### Priority 2 — RadioBrowser as a first-class provider
+
+AfterTouch can proxy and play any stream URL, but there is no built-in station search. OpenCloudTouch's RadioBrowser integration is the reference. Tasks:
+- Wire the [RadioBrowser API](https://www.radio-browser.info/) into the `soundtouch-web` web UI as a browsable/searchable source.
+- Make discovered stations directly presetable to hardware buttons.
+- This is the most common replacement for TuneIn for users who listened to internet radio via presets.
+
+### Priority 3 — Raspberry Pi SD card image
+
+OpenCloudTouch ships a flashable Pi image and it dramatically lowers the barrier for the most common "always-on local server" deployment. AfterTouch already has Docker and a web management UI; this is largely a CI/packaging task:
+- Build a Pi image (using e.g. `pi-gen` or `rpi-imager`-compatible tooling) that boots directly into `soundtouch-service`.
+- Auto-starts on boot, auto-discovers devices, opens the web UI on a known port.
+- Target Pi 3/4/5 with amd64/arm64/arm/v7 variants (mirroring OCT's approach).
+
+### Priority 4 — USB config generation in the web UI
+
+AfterTouch modifies `SoundTouchSdkPrivateCfg.xml` via SSH (`pkg/service/setup/setup.go`) and documents the redirect process thoroughly, but does not yet generate the USB stick content for users without SSH access. A "prepare USB stick" button in the web UI would remove the last manual step:
+- Generate `OverrideSdkPrivateCfg.xml` pre-populated with the running server's URL.
+- Optionally include the custom CA certificate for HTTPS-capable devices.
+- Surface alongside the existing guided migration wizard.
+
+### Priority 5 — Music Assistant integration
+
+SoundTouch Hybrid 2026 uses Music Assistant as its streaming backend, giving access to Apple Music, Deezer, local libraries, and many other providers. A formal Music Assistant **player provider** for AfterTouch would give power users a path to sources beyond Spotify, TuneIn, Pandora, and RadioBrowser. The Music Assistant community has an open discussion thread on this ([#4766](https://github.com/orgs/music-assistant/discussions/4766)).
+
+### Priority 6 — DNS-based migration documentation
+
+AfterTouch includes a built-in DNS server (`ENABLE_DNS_DISCOVERY`, `DNS_BIND_ADDR`, `DNS_UPSTREAM`) that intercepts `*.bose.com` queries and forwards everything else upstream — no Pi-hole, AdGuard, or any other external tool required. The ResolvConf migration path already treats DNS as a first-class option. The remaining gap is awareness: users unfamiliar with the project may not realise no external DNS infrastructure is needed. Tasks:
+- Surface the built-in DNS server more prominently in the getting-started documentation.
+- Document Pi-hole / AdGuard Home as an *alternative* for users who already run those, not a requirement.
+
+### Priority 7 — MQTT integration
+
+A design document exists (`docs/guides/MQTT-INTEGRATION-DESIGN.md`) but no code has been written. Implementing it would unlock home automation use cases without requiring the full Home Assistant stack — enabling triggers like "play preset 1 when front door opens" via any MQTT-capable automation platform.
+
+---
+
+## soundcork ↔ AfterTouch
+
+soundcork and AfterTouch share the most functional overlap of any two projects in the ecosystem. For the implementation-level parity analysis and remaining tasks see [docs/PARITY-SOUNDCORK.md](../PARITY-SOUNDCORK.md).
+
+### Architectural differences (not gaps)
+
+These exist in soundcork but are deliberate architectural choices in AfterTouch, not missing features:
+
+| Area                     | soundcork                             | AfterTouch                                                |
+|--------------------------|---------------------------------------|-----------------------------------------------------------|
+| Web UI                   | FastAPI + Jinja2 miniapp and admin UI | Separate `soundtouch-web` component (Go + plain HTML/JS)  |
+| Direct device management | SSH/SCP access into speakers          | HTTP API only; no SSH                                     |
+| Device discovery client  | Python `upnpclient` library           | mDNS + UPnP in Go, with dedicated DNS interception server |
+| Token delivery           | Push (ZeroConf priming to port 8200)  | Pull (device calls back to fetch)                         |
+| Persistence format       | Flat files                            | XML flat files + atomic writes                            |
+
+### AfterTouch capabilities soundcork lacks
+
+| Feature                                   | Notes                                                           |
+|-------------------------------------------|-----------------------------------------------------------------|
+| DNS server for device redirect            | Intercepts Bose domain queries; no Pi-hole required             |
+| HTTPS / custom CA injection               | Full TLS with certificate generation and trust workflow         |
+| HTTP interaction recording & replay       | Captures real device traffic for debugging and regression tests |
+| Device migration (serial → MAC path)      | Handles legacy device ID formats automatically                  |
+| Transparent proxy mode with upstream sync | Can mirror to real Bose cloud while running locally             |
+| CLI (`soundtouch-cli`)                    | Scriptable control of speakers                                  |
+| Importable Go library                     | `github.com/gesellix/bose-soundtouch/pkg/client`                |
+
+---
+
+
+
+### Ecosystem fragmentation vs. convergence
+
+The community is currently covering different parts of the problem in parallel rather than converging. AfterTouch explicitly credits soundcork, Überböse, and SoundTouch Plus in its README and describes its `soundtouch-service` as "heavily inspired by SoundCork". There is an opportunity — and arguably a need — for these projects to formally coordinate: shared test fixtures, a common compatibility matrix against specific firmware versions, and agreed-on API contracts would all reduce duplicated effort.
+
+### Firmware version sensitivity
+
+The SoundTouch 10 is most dependent on Marge for basic network functionality; the 20 and 30 are somewhat more tolerant. Compatibility across firmware versions is not systematically documented anywhere. A community firmware compatibility matrix (model × firmware version × which emulation features work) would be high value and is currently missing.
+
+### Security posture
+
+All projects warn that speakers should only be used on a private, firewalled network after cloud shutdown. AfterTouch is the only project to implement HTTPS/custom CA, which matters if devices are ever on a network where traffic could be inspected. soundcork's SECURITY.md explicitly warns against running on open networks.
+
+### No iOS app — a structural gap
+
+The original SoundTouch app was iOS-first. Every community replacement is Android-only (Überböse App) or browser-based. This is the largest unaddressed user segment in the ecosystem.
+
+### Bose's open-source move as a precedent
+
+Bose's decision to release API documentation rather than simply shutting down is notable — it mirrors what Pebble users did themselves with Rebble after that shutdown, but here the manufacturer initiated it. This sets a useful precedent and gives the community a solid legal and technical foundation to build on.
+
+### Related community resources
+
+- [Bose SoundTouch Plus (Home Assistant component)](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus) — comprehensive HA integration by Todd Lucas, extensive API wiki
+- [Bose SoundTouch Hook](https://github.com/CodeFinder2/bose-soundtouch-hook) — `LD_PRELOAD`-based reverse engineering framework used by AfterTouch for protocol research
+- [Bose SoundTouch Web API (community Markdown)](https://github.com/jaas666/bose-soundtouch-web-api) — official API PDF converted to Markdown
+- [Bose Wiki — SoundTouch App Alternatives](https://bose.fandom.com/wiki/SoundTouch_app_alternatives) — community-maintained living list of workarounds and projects
+- [Reddit megathread — Bose alternatives](https://www.reddit.com/r/bose) — ongoing community discussion
+- [Radio Browser](https://www.radio-browser.info/) — the free, community-maintained internet radio directory used as a TuneIn replacement
+
+---
+
+*Document compiled April 2026. Project details sourced directly from GitHub repositories and official documentation. Star counts, commit counts, and release dates reflect the state at time of writing and will change as projects evolve. soundcork-stockholm-app added April 2026.*

docs/archive/MERGE_PROJECTS.md

@@ -0,0 +1,75 @@
+# Merging Bose-SoundTouch-API into Bose-SoundTouch
+
+This document outlines the plan to merge the [Bose-SoundTouch-API](https://github.com/gesellix/Bose-SoundTouch-API) project into this repository. The actual Go implementation in that repository is located in the `soundcork-go` subdirectory. The goal is to provide both a CLI (`soundtouch-cli`) and a service (`soundtouch-service`) from a single codebase.
+
+## Goals
+
+- [x] Maintain the existing `soundtouch-cli` functionality.
+- [x] Introduce `soundtouch-service` as a new command (based on the `soundcork-go` project).
+- [x] Consolidate shared logic (models, clients, discovery) into the `pkg/` directory.
+- [x] Simplify maintenance by having a single Go module and shared CI/CD pipeline.
+
+## Current Directory Structure
+
+```text
+.
+├── cmd/
+│   ├── soundtouch-cli/        # Existing CLI implementation
+│   │   └── main.go
+│   └── soundtouch-service/    # New service implementation (REST API / Websocket)
+│       └── main.go
+├── pkg/
+│   ├── client/                # Shared SoundTouch API client
+│   ├── models/                # Shared data models
+│   ├── discovery/             # Shared device discovery logic
+│   └── service/               # Service-specific logic (from Bose-SoundTouch-API)
+│       ├── bmx/               # BMX service logic
+│       ├── marge/             # Marge service logic
+│       ├── datastore/         # Device and configuration storage
+│       ├── proxy/             # Logging proxy logic
+│       ├── setup/             # Device setup and migration logic
+│       └── handlers/          # HTTP handlers (adapted from soundcork-go/soundcork-go)
+│           └── soundcork/     # Embedded resources (index.html, media/, etc.)
+├── docs/
+│   └── MERGE_PROJECTS.md      # This document
+├── go.mod
+└── go.sum
+```
+
+## Step-by-Step Merge Status
+
+### 1. Preparation
+- [x] Review `go.mod` in both projects to identify dependency overlaps and conflicts.
+
+### 2. Code Integration
+- [x] **Models & Client**: Merged missing functionality from `soundcork-go/internal/models` into `pkg/models`. Renamed overlapping models to `Service*` (e.g., `ServiceContentItem`, `ServicePreset`).
+- [x] **Service Logic**: Adapted internal packages from `soundcork-go/internal/` to `pkg/service/`.
+- [x] **Handlers**: Moved and adapted HTTP handlers into `pkg/service/handlers/`.
+- [x] **New Command**: Created `cmd/soundtouch-service/main.go` as the service entry point using `chi` router.
+- [x] **Embedded Resources**: Integrated `index.html`, `bmx_services.json`, `swupdate.xml`, and `media/` folder into the binary using `//go:embed`.
+
+### 3. Dependency Management
+- [x] Update `go.mod` to include:
+    - `github.com/go-chi/chi/v5`
+    - `github.com/srwiley/oksvg` and `github.com/srwiley/rasterx`
+    - `golang.org/x/crypto`
+- [x] Run `go mod tidy` to clean up dependencies.
+
+### 4. Shared Logic Refactoring
+- [x] Identify common code between `soundtouch-cli` and the new service.
+- [x] Move shared logic into `pkg/` to ensure both commands use the same underlying implementation.
+
+### 5. Documentation & Examples
+- [x] Update `README.md` to mention the new `soundtouch-service` command.
+- [x] Add service-specific documentation in `docs/SOUNDTOUCH-SERVICE.md`.
+- [x] Provide examples of how to run and interact with the service in `examples/service-demo/`.
+
+### 6. CI/CD Updates
+- [x] Update `.github/workflows/release.yml` to build and release the `soundtouch-service` binary alongside `soundtouch-cli`.
+- [x] Update any test workflows to include tests for the service logic.
+
+## Verification
+- [x] `go build ./cmd/soundtouch-cli` works as expected.
+- [x] `go build ./cmd/soundtouch-service` works as expected.
+- [x] All tests pass: `go test ./...`.
+- [x] Resources are correctly served from the embedded filesystem.

docs/archive/PLAN.md

@@ -185,7 +185,7 @@ type NowPlaying struct {
 type PlayStatus string
 const (
     PlayStatusPlaying PlayStatus = "PLAY_STATE"
-    PlayStatusPaused  PlayStatus = "PAUSE_STATE" 
+    PlayStatusPaused  PlayStatus = "PAUSE_STATE"
     PlayStatusStopped PlayStatus = "STOP_STATE"
 )
 
@@ -277,19 +277,19 @@ type Config struct {
     // Server configuration
     WebPort      int           `env:"WEB_PORT" default:"8080"`
     APITimeout   time.Duration `env:"API_TIMEOUT" default:"10s"`
-    
-    // Discovery configuration  
+
+    // Discovery configuration
     DiscoveryTimeout time.Duration `env:"DISCOVERY_TIMEOUT" default:"5s"`
     CacheDevices     bool          `env:"CACHE_DEVICES" default:"true"`
     CacheTTL         time.Duration `env:"CACHE_TTL" default:"5m"`
-    
+
     // CORS configuration (for web proxy)
     CORSOrigins      []string `env:"CORS_ORIGINS" default:"*"`
-    
+
     // Logging
     LogLevel    string `env:"LOG_LEVEL" default:"info"`
     LogFormat   string `env:"LOG_FORMAT" default:"json"`
-    
+
     // Development
     DevMode     bool `env:"DEV_MODE" default:"false"`
 }
@@ -537,7 +537,7 @@ build-all: build-linux build-darwin build-windows
 dev-cli:
 	air -c .air-cli.toml
 
-dev-webapp: 
+dev-webapp:
 	air -c .air-webapp.toml
 
 dev-wasm:
@@ -556,7 +556,7 @@ check: fmt vet lint test
 
 # Docker development environment
 docker-dev:
-	docker-compose up --build
+	docker compose up --build
 
 # Release packaging
 release: build-all
@@ -596,7 +596,7 @@ import (
     "fmt"
     "log"
     "time"
-    
+
     "github.com/gesellix/bose-soundtouch/pkg/client"
     "github.com/gesellix/bose-soundtouch/pkg/discovery"
     "github.com/gesellix/bose-soundtouch/pkg/models"
@@ -609,36 +609,36 @@ func main() {
     if err != nil {
         log.Fatal(err)
     }
-    
+
     if len(devices) == 0 {
         log.Fatal("No SoundTouch devices found")
     }
-    
+
     // Create client for first device
     client := client.NewClient(client.ClientConfig{
         Host:    devices[0].Host,
         Port:    8090,
         Timeout: 10 * time.Second,
     })
-    
+
     // Get device info
     info, err := client.GetDeviceInfo()
     if err != nil {
         log.Fatal(err)
     }
     fmt.Printf("Connected to: %s\n", info.Name)
-    
+
     // Get current playback
     nowPlaying, err := client.GetNowPlaying()
     if err != nil {
         log.Fatal(err)
     }
-    
+
     if nowPlaying.PlayStatus == models.PlayStatusPlaying {
-        fmt.Printf("Playing: %s - %s (%s)\n", 
+        fmt.Printf("Playing: %s - %s (%s)\n",
             nowPlaying.Artist, nowPlaying.Track, nowPlaying.Album)
     }
-    
+
     // Control playback
     if nowPlaying.PlayStatus == models.PlayStatusPlaying {
         client.SendKey(models.KeyPause)
@@ -737,11 +737,11 @@ docker run -p 8080:8080 soundtouch-webapp
 ```bash
 # Local development with hot reload
 make dev-webapp    # Web app development
-make dev-wasm      # WASM development  
+make dev-wasm      # WASM development
 make dev-cli       # CLI development
 
 # Full development environment
-docker-compose up  # Mock devices + web app
+docker compose up  # Mock devices + web app
 ```
 
 ## Success Criteria
@@ -781,7 +781,7 @@ docker-compose up  # Mock devices + web app
 
 - [Bose SoundTouch Web API Documentation](https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf)
 - [Go WebAssembly](https://github.com/golang/go/wiki/WebAssembly)
-- [UPnP Device Architecture](http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0.pdf) 
+- [UPnP Device Architecture](http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0.pdf)
 - [Go Embed Directive](https://pkg.go.dev/embed)
 - [Gorilla WebSocket](https://github.com/gorilla/websocket)
-- [PROJECT-PATTERNS.md](./PROJECT-PATTERNS.md) - Detailed pattern documentation
+- [PROJECT-PATTERNS.md](../PROJECT-PATTERNS.md) - Detailed pattern documentation

docs/archive/STATUS.md

@@ -36,6 +36,13 @@ This project implements a comprehensive Go client library and CLI tool for Bose
   - Incremental volume control
   - Safety features and validation
   - Volume level categorization
+- `POST /speaker` - TTS and URL playback ✅ Complete
+  - Text-to-Speech with multi-language support
+  - URL content playback with metadata
+  - Volume control with automatic restoration
+- `GET /playNotification` - Notification beep ✅ Complete
+  - Simple notification beep sound
+  - Pauses current media during playback
 
 #### CLI Tool ✅
 - Device discovery via UPnP ✅ Complete
@@ -72,6 +79,7 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 - `GET /networkInfo` - Network information ✅ Complete
 - `WebSocket /` - Real-time event streaming ✅ Complete
 - `GET /getZone`, `POST /setZone` - Multiroom zone management ✅ Complete
+- `POST /speaker`, `GET /playNotification` - Notification system ✅ Complete
 
 ### **ℹ️ API Limitations**
 - None! All functional endpoints are now implemented including preset management endpoints discovered via the [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
@@ -90,8 +98,9 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 | **Preset Management** | 1/1 | 1 | 100% |
 | **Zone Management** | 4/4 | 4 | 100% |
 | **Advanced Audio Controls** | 3/3 | 3 | 100% |
+| **Notification System** | 2/2 | 2 | 100% |
 | **Track Info** | 1/1 | 1 | **100%** |
-| **Overall Progress** | 26/26 | 26 | **100%** |
+| **Overall Progress** | 28/28 | 28 | **100%** |
 
 **Note**: All functional endpoints implemented including preset management (`/storePreset`, `/removePreset`) discovered via the [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API). Official API marked preset creation as "N/A" but working endpoints were documented by the SoundTouch Plus community.
 
@@ -141,6 +150,14 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 - ✅ Device-specific feature validation
 - ✅ Professional-grade audio adjustment features
 
+### Phase 6: Notification System (COMPLETE)
+- ✅ TTS (Text-to-Speech) playback (POST /speaker) with multi-language support
+- ✅ URL content playback (POST /speaker) with custom metadata
+- ✅ Notification beep (GET /playNotification) for simple alerts
+- ✅ Volume control with automatic restoration
+- ✅ Content interruption and resume functionality
+- ✅ ST-10 Series device compatibility
+
 ### Key Technical Achievements
 - **Complete Key Controls**: All 24 documented key commands implemented
 - **Source Selection**: Full source switching with convenience methods (-spotify, -bluetooth, -aux)
@@ -151,6 +168,7 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 - **Zone Management**: Complete multiroom zone operations with validation
 - **Zone Status**: Query zone membership, master/slave status, device counting
 - **System Management**: Clock time, display settings, and network information
+- **Notification System**: TTS and URL playback with multi-language support
 - **API Compliance**: Proper press+release key pattern implementation
 - **Safety First**: Volume warnings and limits for user protection
 - **User Experience**: Host:port parsing (e.g., `-host 192.168.1.100:8090`)
@@ -169,6 +187,7 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 - **WebSocket Events**: 50+ test cases for event parsing, handling, and connection management
 - **System Endpoints**: 20+ test cases for clock, display, and network functionality
 - **Balance Control**: 30+ test cases for stereo balance adjustment and clamping
+- **Notification System**: 30+ test cases for TTS, URL playback, and beep functionality
 - **Host Parsing**: 20+ test cases for various formats
 - **XML Models**: Comprehensive marshaling/unmarshaling tests
 - **HTTP Client**: Mock server tests with real response data
@@ -179,6 +198,7 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 - **Source Selection**: Tested with Spotify, TuneIn, and other available sources
 - **Bass Control**: Tested bass adjustment, validation, and device-specific behavior
 - **Balance Control**: Tested stereo balance (device-dependent feature)
+- **Notification System**: Tested TTS playback, URL content, and beep notifications on real devices
 - **Error Scenarios**: Network timeouts, invalid responses, invalid sources
 - **Safety Features**: Volume, bass, and balance limits tested on real devices
 
@@ -186,13 +206,14 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 
 ### ✅ Complete Documentation
 - `README.md` - Project overview and usage examples ✅
-- `docs/API-Endpoints-Overview.md` - API reference with status ✅
-- `docs/KEY-CONTROLS.md` - Media control implementation ✅
-- `docs/VOLUME-CONTROLS.md` - Volume management guide ✅
-- `docs/PRESET-MANAGEMENT.md` - Preset analysis and limitations ✅
+- `docs/reference/API-ENDPOINTS.md` - API reference with status ✅
+- `docs/reference/KEY-CONTROLS.md` - Media control implementation ✅
+- `docs/guides/VOLUME-CONTROLS.md` - Volume management guide ✅
+- `docs/reference/PRESET-MANAGEMENT.md` - Preset analysis and limitations ✅
 - `docs/HOST-PORT-PARSING.md` - Enhanced CLI feature ✅
-- `docs/PLAN.md` - Development roadmap (updated) ✅
+- `docs/archive/PLAN.md` - Development roadmap (updated) ✅
 - `docs/PROJECT-PATTERNS.md` - Development guidelines ✅
+- `docs/reference/SPEAKER-ENDPOINT.md` - Complete speaker notification documentation ✅
 
 ### 📝 Documentation Notes
 - All docs are synchronized with current implementation
@@ -234,6 +255,7 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 ### ✅ Production Ready Features
 - **Core Device Control**: Information, media controls, volume
 - **Audio Management**: Complete bass and balance control
+- **Notification System**: TTS, URL playback, and beep notifications
 - **Preset Management**: Complete preset analysis (API is read-only by design)
 - **Safety Features**: Volume warnings, input validation
 - **Error Handling**: Comprehensive error messages
@@ -263,6 +285,15 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 - [ ] Web application interface
 
 ### Recent Major Updates
+- **2026-02-01**: Speaker endpoint implementation - Complete notification system
+  - ✅ TTS (Text-to-Speech) with multi-language support (EN, DE, ES, FR, IT, NL, PT, RU, ZH, JA, etc.)
+  - ✅ URL content playback with custom metadata for NowPlaying display
+  - ✅ Notification beep functionality for simple alerts
+  - ✅ Volume control with automatic restoration
+  - ✅ Comprehensive CLI commands: `speaker tts`, `speaker url`, `speaker beep`
+  - ✅ Complete Go client methods: `PlayTTS()`, `PlayURL()`, `PlayCustom()`, `PlayNotificationBeep()`
+  - ✅ Full validation, error handling, and test coverage
+  - ✅ ST-10 Series device compatibility with proper device detection
 - **2026-02-01**: Code quality improvements - Resolved all golangci-lint issues (59→0)
   - ✅ Security: Updated Go 1.25.5→1.25.6 to fix TLS vulnerability GO-2026-4340
   - ✅ Complexity: Refactored 5 high-complexity functions for better maintainability

docs/archive/WIKI-IMPLEMENTATION-PLAN.md

@@ -108,8 +108,8 @@ Essential for browsing music libraries and searching content.
 // pkg/api/content.go (new file)
 func (c *Client) Navigate(source, sourceAccount string, options NavigateOptions) (*NavigateResponse, error)
 func (c *Client) Search(source, sourceAccount, searchTerm string, options SearchOptions) (*SearchResponse, error)
-func (c *Client) GetRecents() (*RecentsResponse, error)
-func (c *Client) Introspect(source, sourceAccount string) (*IntrospectResponse, error)
+func (c *Client) GetRecents() (*RecentsResponse, error) // ✅ IMPLEMENTED
+func (c *Client) Introspect(source, sourceAccount string) (*IntrospectResponse, error) // ✅ IMPLEMENTED
 ```
 
 #### Data Structures:

docs/concepts/README.md

@@ -0,0 +1,181 @@
+# Upstream Bose Service Simulation - Concept Overview
+
+## Executive Summary
+
+This document serves as the entry point for understanding the comprehensive plan to enhance the SoundTouch service with advanced state management capabilities, preparing for the eventual shutdown of Bose's upstream services while providing a superior local management experience.
+
+## Project Objectives
+
+### Primary Goal
+Create a robust, local replacement for Bose's upstream services that can seamlessly handle the transition from cloud-dependent to fully autonomous operation while maintaining and improving upon the existing functionality.
+
+### Key Outcomes
+- **Zero-downtime transition** from Bose services to local management
+- **Enhanced visibility** into device states, health, and system operations
+- **Data preservation** during migrations with full rollback capabilities
+- **Improved reliability** through local control and reduced external dependencies
+- **Future-proof architecture** that can evolve beyond Bose's original design
+
+## Architecture Vision
+
+### Current State
+The existing SoundTouch service provides:
+- BMX service for TuneIn integration
+- Marge service for account and device management  
+- Basic mirroring of upstream Bose endpoints
+- File-based persistence for device data
+- Migration support for device directory structures
+
+### Enhanced State (This Project)
+The enhanced system will add:
+- **Comprehensive Account Management** with explicit creation and migration tracking
+- **Device Lifecycle Management** with full state machine and event processing
+- **Advanced Mirroring** with disparity detection and analysis
+- **Dual-Source Data Management** supporting gradual migration strategies
+- **Real-time Monitoring** with health checks and performance metrics
+- **Text-based Storage** optimized for debugging and small hardware deployments
+
+## Use Case Coverage
+
+### Case 0: Account Management
+- **Explicit Account Creation**: Accounts created through deliberate user action
+- **Mirror-Enhanced Setup**: Use upstream data to enrich account creation
+- **Passive Data Collection**: Record account information during normal operations
+
+### Case 1a: Fresh Device Registration  
+- **Factory Reset Support**: Handle devices with no prior Bose association
+- **Default Configuration**: Initialize devices with sensible presets and sources
+- **Local-First Setup**: Complete registration without upstream dependencies
+
+### Case 1b: Bose Account Migration
+- **Data Preservation**: Maintain existing presets, recents, and sources
+- **Gradual Migration**: Support partial migration while maintaining upstream compatibility
+- **Rollback Capability**: Revert to Bose services if needed
+
+### Case 2: Lifecycle and State Management
+- **Real-time State Tracking**: Monitor device states and health continuously
+- **Event-Driven Updates**: Process device events asynchronously
+- **Disparity Detection**: Identify differences between local and upstream behavior
+- **Comprehensive Logging**: Maintain detailed audit trails for troubleshooting
+
+## Technical Approach
+
+### Design Principles
+1. **Text-First Storage**: Human-readable formats (JSON, XML, logs) for easy debugging
+2. **Small Hardware Optimization**: Designed for Raspberry Pi Zero 2W deployments
+3. **Mirror-First Strategy**: Keep upstream mirroring active until migration complete
+4. **Event-Driven Architecture**: Asynchronous processing with comprehensive event tracking
+5. **Backward Compatibility**: Seamless integration with existing installations
+
+### Data Structure
+```
+data/
+├── accounts/{account-id}/
+│   ├── account.json              # Account metadata and settings
+│   ├── account-events.log        # High-level account behavior tracking
+│   ├── devices/{device-id}/
+│   │   ├── lifecycle.json        # Device state and history
+│   │   ├── info.xml             # Device information (existing)
+│   │   ├── presets.xml          # Device presets (existing)
+│   │   ├── recents.xml          # Recent plays (existing)
+│   │   ├── sources.xml          # Configured sources (existing)
+│   │   └── events.log           # Device event history
+│   └── sessions/                # Recorded interaction sessions (existing)
+└── system/
+    ├── discovery.log            # Device discovery events
+    └── migration.log           # Migration activities
+```
+
+### Development Targets
+- **Simplicity**: Keep It Simple, Stupid (KISS) principle over optimization
+- **Quality**: 100% test pass rate and lint-clean code for every change
+- **Compatibility**: Zero breaking changes to existing functionality
+- **Leveraging**: Reuse existing systems (interaction recording, parity detection)
+
+## Implementation Strategy
+
+### Phase 1: Foundation (2-3 weeks) - Small, Testable Steps
+- Account management foundation with basic create/read operations
+- Device lifecycle data models and simple state tracking
+- Basic API endpoints with comprehensive testing
+- Integration with existing datastore patterns
+
+### Phase 2: Device Lifecycle (2-3 weeks) - Build on Existing Systems  
+- Event processing using existing WebSocket system
+- Lifecycle integration with current discovery and migration
+- Enhanced logging building on existing parity detection
+- Simple state machine with thorough testing
+
+### Phase 3: Enhanced Features (2-3 weeks) - Leverage Current Systems
+- Improve existing parity mismatch detection with better categorization
+- Smart data source routing with fallback mechanisms
+- Basic monitoring using existing health check patterns
+- Reuse interaction recording for request/response tracking
+
+## Key Benefits
+
+### For Users
+- **Continuity**: Seamless operation when Bose services shut down
+- **Reliability**: Local control reduces dependency on external services
+- **Visibility**: Clear insight into device states and system health
+- **Control**: Full management of device data and configurations
+
+### For Developers
+- **Simplicity**: KISS principle makes code easy to understand and maintain
+- **Quality**: Comprehensive testing and linting ensures reliable code
+- **Debugging**: Text-based storage enables easy troubleshooting
+- **Testing**: Every change requires full test suite pass and lint compliance
+
+### For Community
+- **Open Source**: Transparent implementation available for community contributions
+- **Standards**: Well-documented APIs and data formats
+- **Collaboration**: Disparity detection helps improve implementation accuracy
+- **Future-Proof**: Architecture designed to outlast original Bose services
+
+### Technical Risks
+- **Data Loss Prevention**: Atomic file operations and comprehensive testing
+- **Complexity Creep**: KISS principle and simple-first approach
+- **Compatibility Issues**: Extensive regression testing and existing system reuse
+- **Code Quality**: Mandatory linting and test coverage for every change
+
+### Operational Risks
+- **Service Disruption**: Small, incremental changes with rollback capability
+- **Testing Overhead**: Automated quality gates (`golangci-lint run --fix` + `go test ./...`)
+- **Migration Challenges**: Leverage existing migration system and patterns
+- **Maintenance Burden**: Simple, well-tested code is easier to maintain
+
+### Technical
+- All tests pass consistently (100%)
+- Zero linting issues in codebase
+- No breaking changes to existing functionality
+- Code coverage maintained or improved
+
+### Quality Assurance
+- Every commit passes `golangci-lint run --fix`
+- Every milestone passes `go test ./...`
+- Integration tests verify existing functionality
+- Simple, maintainable code that follows Go idioms
+
+## Documentation Structure
+
+This concept is detailed across several documents:
+
+- **[upstream-service-simulation.md](./upstream-service-simulation.md)**: Complete architectural concept with detailed use cases and implementation guidelines
+- **[implementation-roadmap.md](./implementation-roadmap.md)**: Detailed project phases, milestones, and delivery timeline
+- **[technical-specification.md](./technical-specification.md)**: Comprehensive technical details including APIs, data models, and performance requirements
+
+## Getting Started
+
+1. **Review the Concept**: Read through the main concept document to understand the full scope
+2. **Examine Technical Details**: Review the technical specification for implementation details
+3. **Follow the Roadmap**: Use the implementation roadmap for project planning and execution
+4. **Integration Planning**: Consider how the enhanced features will integrate with existing deployments
+
+## Next Steps
+
+1. **Stakeholder Review**: Gather feedback on the concept and approach
+2. **Technical Validation**: Prototype key components to validate technical assumptions
+3. **Resource Planning**: Allocate development resources for the three-phase implementation
+4. **Community Engagement**: Share plans with the community for feedback and contributions
+
+This enhanced state management system represents a significant evolution of the SoundTouch service, transforming it from a basic cloud replacement into a comprehensive, future-proof device management platform that can serve users well beyond the Bose service shutdown timeline.

docs/concepts/amazon-music-oauth.md

@@ -0,0 +1,369 @@
+# Amazon Music OAuth Integration
+
+This document describes the plan and specification for adding Amazon Music OAuth support to the SoundTouch service, enabling continued Amazon Music playback after the Bose cloud shutdown (May 2026).
+
+The implementation mirrors the [Spotify OAuth integration](spotify-oauth.md) closely. Read that document first — this one calls out only the differences.
+
+## Status
+
+**Infrastructure complete — streaming blocked by API access.**
+
+All eight implementation steps are done. The OAuth flow (account linking, token storage, token refresh) works end-to-end with a standard Login with Amazon app. Token exchange (`/oauth/device/.../token/cs1`) succeeds and the speaker receives a valid `Atza|` access token.
+
+However, real-world testing shows that the speaker then calls `https://music-api.amazon.com/` with that token and receives a `401 Unauthorized` (no redirect to a regional endpoint). This means the token does not carry the scopes required to access the Amazon Music streaming API.
+
+**Root cause (confirmed):** Amazon Music streaming requires the `amazon_music:access` scope, which is only available to **device client IDs** — a separate credential type obtained through Amazon's Music partner programme. Standard Login with Amazon application client IDs (`amzn1.application-oa2-client.*`) cannot request this scope: attempting to include it in the authorization URL returns `lwa-invalid-parameter-bad-scope` (HTTP 400) from the LWA authorization endpoint. Bose would have held a device client ID as a registered Amazon Music partner.
+
+**What still works:**
+- Account linking and token storage
+- Token refresh (the service correctly exchanges the refresh token for a fresh access token)
+- Marge source registration (the speaker sees Amazon Music as a configured source)
+
+**What does not work:**
+- Actual music playback — the speaker's `AmazonClient` cannot authenticate to `music-api.amazon.com` with a standard LWA token
+
+**Path forward:** Obtaining a device client ID requires registering with Amazon's Music partner programme. If such a credential is obtained, the only code change needed is swapping the `client_id`/`client_secret` for the device credentials and adding `amazon_music:access` to `AmazonScopes` in `pkg/service/amazon/service.go` — everything else is already in place. The `site_id` field is a secondary open question that may also affect regional routing once the scope issue is resolved.
+
+---
+
+## Secret Format (confirmed from a live Bose system)
+
+A real Amazon source entry from a migrated device's `Sources.xml`:
+
+```xml
+<source secretType="token">
+    <credential type="token">{"AmazonSecret":{"refresh_token":"Atzr|...","site_id":"1464855981"}}</credential>
+    <sourceKey type="AMAZON" account="user@example.com"/>
+</source>
+```
+
+Key observations:
+
+- **Secret envelope**: `{"AmazonSecret":{"refresh_token":"...","site_id":"..."}}` — JSON-encoded, HTML-entity-escaped in XML attributes, stored as the credential value.
+- **`Atzr|` prefix**: This is the standard Amazon LWA (Login with Amazon) refresh token prefix from the **authorization code grant** — confirming that Web OAuth is the correct flow, not CBL.
+- **`site_id`**: A numeric string (`"1464855981"`). Origin is not yet fully confirmed; candidates are:
+  - A static Bose partner identifier baked into the Bose app/firmware (same value for all users), or
+  - A per-user Amazon Music identifier returned by a Music API device registration call.
+  - Needs verification — possibly obtained by calling the Amazon Music API after initial authentication.
+- **`account` field**: The user's Amazon email address (obtained from the LWA `/user/profile` endpoint).
+
+When `HandleBoseAmazonToken` receives a refresh request from the speaker, it must:
+1. Parse the `AmazonSecret` JSON from the stored credential to extract `refresh_token`.
+2. Call the LWA token endpoint with a `refresh_token` grant.
+3. Return the fresh `access_token` to the speaker.
+4. Persist the rotated `refresh_token` back into the `AmazonSecret` envelope.
+
+---
+
+## How the Speaker Uses This
+
+When the SoundTouch firmware tries to play Amazon Music after migration, it sends a token refresh request to the local service:
+
+```
+POST /oauth/device/{deviceID}/music/musicprovider/20/token/cs1
+```
+
+The service must respond with a fresh Amazon access token. The speaker then uses that token directly with Amazon's playback infrastructure.
+
+The `cs1` suffix (credential schema 1) is Amazon-specific; Spotify uses `cs3`. This route is already registered.
+
+> **DNS note:** The speaker constructs the OAuth hostname by appending `oauth` to the streaming service subdomain. If the service is reachable at `myhost.local`, the speaker will call `myhostoauth.local`. A DNS alias pointing `myhostoauth.<domain>` to the same IP as the service is required.
+
+---
+
+## OAuth Flows
+
+### 1. Browser-based Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (curl/app)
+    participant Service as Service
+    participant Amazon as Amazon Auth Server (LWA)
+    participant Browser as User's Browser
+
+    Client->>Service: POST /mgmt/amazon/init [Basic Auth]
+    Service-->>Client: {"redirectUrl": "https://www.amazon.com/ap/oa?..."}
+
+    Client->>Browser: User opens URL
+    Browser->>Amazon: User logs in & grants access
+    Amazon-->>Browser: Redirect to /mgmt/amazon/callback?code=abc
+
+    Browser->>Service: GET /mgmt/amazon/callback?code=abc
+    Note over Service: No auth needed for callback
+
+    Service->>Amazon: POST /auth/o2/token (exchange code)
+    Amazon-->>Service: {access_token, refresh_token}
+
+    Service->>Amazon: GET /user/profile (fetch profile)
+    Amazon-->>Service: {user_id, name, email}
+
+    Note over Service: Store account to disk
+
+    Service-->>Browser: HTML: "Amazon Music Connected. You can close this window."
+```
+
+### 2. Mobile App Flow (ueberboese)
+
+```mermaid
+sequenceDiagram
+    participant App as ueberboese Flutter App
+    participant Service as Service
+    participant Amazon as Amazon Auth Server (LWA)
+
+    App->>Service: POST /mgmt/amazon/init [Basic Auth]
+    Service-->>App: {"redirectUrl": "https://www.amazon.com/ap/oa?..."}
+
+    App->>Amazon: Open in-app browser (User authorizes)
+    Amazon-->>App: Deep link redirect: ueberboese-login://amazon?code=abc
+
+    App->>Service: POST /mgmt/amazon/confirm?code=abc [Basic Auth]
+
+    Service->>Amazon: POST /auth/o2/token (exchange code)
+    Amazon-->>Service: {access_token, refresh_token}
+
+    Service->>Amazon: GET /user/profile (fetch profile)
+    Amazon-->>Service: {profile}
+
+    Service-->>App: {"ok": true}
+```
+
+### 3. Token Retrieval (Speaker Token Refresh)
+
+```mermaid
+sequenceDiagram
+    participant Speaker as SoundTouch Speaker
+    participant Service as Service
+    participant Amazon as Amazon Token API (LWA)
+
+    Speaker->>Service: POST /oauth/device/{deviceID}/music/musicprovider/20/token/cs1
+    Note over Service: Body contains stored AmazonSecret JSON;<br/>extract refresh_token from {"AmazonSecret":{...}}
+
+    alt Token expired or near expiry
+        Service->>Amazon: POST /auth/o2/token (refresh_token grant, body credentials)
+        Amazon-->>Service: {access_token, refresh_token, expires_in}
+        Note over Service: Persist rotated refresh_token back into AmazonSecret envelope
+    end
+
+    Service-->>Speaker: {"access_token": "...", "token_type": "Bearer", "expires_in": 3600}
+```
+
+---
+
+## Implementation Steps
+
+### Step 1 — Extract ZeroConf into a shared package
+
+**Why first:** The DH-blob encryption in `pkg/service/spotify/zeroconf.go` is entirely provider-agnostic. Extracting it to `pkg/service/zeroconf/` before adding Amazon avoids duplicating ~200 lines of crypto code.
+
+**What changes:**
+- Create `pkg/service/zeroconf/zeroconf.go` — move `generateDHKeyPair`, `computeSharedSecret`, `deriveKeys`, `buildCredentialsBlob`, `encryptBlob` and helpers. Expose `authType` as a parameter (Spotify and Amazon both use `AuthTypeOAuthToken = 4`, but this makes it explicit).
+- Update `pkg/service/spotify/zeroconf.go` — delete moved code; `PushSpotifyCredentials` becomes a one-line wrapper calling `zeroconf.PushCredentials(...)`.
+
+### Step 2 — Create `pkg/service/amazon/service.go`
+
+Mirror `pkg/service/spotify/service.go`. The `Account` struct is identical; copy it unchanged.
+
+**Amazon-specific differences:**
+
+| Item                      | Spotify                                  | Amazon                                          |
+|---------------------------|------------------------------------------|-------------------------------------------------|
+| Authorization URL         | `https://accounts.spotify.com/authorize` | `https://www.amazon.com/ap/oa`                  |
+| Token endpoint            | `https://accounts.spotify.com/api/token` | `https://api.amazon.com/auth/o2/token`          |
+| Profile endpoint          | `https://api.spotify.com/v1/me`          | `https://api.amazon.com/user/profile`           |
+| Token request credentials | HTTP Basic Auth (clientID:clientSecret)  | POST body fields `client_id` / `client_secret`  |
+| Profile fields            | `id`, `display_name`, `email`            | `user_id`, `name`, `email`                      |
+| Scopes                    | `streaming user-read-private ...`        | `profile` (expand to `music::*` when available) |
+| Entity resolution         | `ResolveEntity()` via Spotify API        | Not implemented (API in closed beta)            |
+
+Accounts persist to `{dataDir}/amazon/accounts.json`.
+
+The token request credential difference (body vs. Basic Auth) is the most important implementation detail.
+
+### Step 3 — Create `pkg/service/amazon/zeroconf.go`
+
+A single exported function `PushAmazonCredentials(zcBaseURL, username, accessToken string) error` delegating to the shared `zeroconf.PushCredentials(...)`.
+
+### Step 4 — Implement `HandleBoseAmazonToken`
+
+Replace the 501 stub in `pkg/service/handlers/handlers_oauth.go` with the full mirror of `HandleBoseSpotifyToken`:
+- Parse body for `refresh_token` / `code`
+- Look up account by BoseSecret; refresh and return token
+- Fall back to first account via `GetFreshToken()` if no matching account
+- Fall back to `HandleBoseProxy` if no Amazon service is configured
+- **Omit `scope` from the response** — Amazon Music scopes are undocumented; sending invented values risks firmware rejection
+
+### Step 5 — Add Amazon fields to `Server`
+
+In `pkg/service/handlers/server.go`, add alongside the Spotify fields:
+
+```go
+amazonClientID     string
+amazonClientSecret string
+amazonRedirectURI  string
+amazonService      *amazon.Service
+```
+
+Add methods: `SetAmazonConfig`, `SetAmazonService`, `IsAmazonConfigured`, `PrimeDeviceWithAmazon`.
+
+### Step 6 — Add management handlers
+
+In `pkg/service/handlers/handlers_mgmt.go`, add six handlers mirroring Spotify:
+
+| Handler                       | Notes                                   |
+|-------------------------------|-----------------------------------------|
+| `HandleMgmtAmazonInit`        | Returns LWA authorize URL               |
+| `HandleMgmtAmazonCallback`    | No auth; calls `bridgeAmazonToMarge`    |
+| `HandleMgmtAmazonConfirm`     | Basic Auth; calls `bridgeAmazonToMarge` |
+| `HandleMgmtAmazonAccounts`    | Returns account list (tokens stripped)  |
+| `HandleMgmtAmazonToken`       | Returns fresh access token              |
+| `HandleMgmtPrimeDeviceAmazon` | Pushes token to speaker via ZeroConf    |
+
+`bridgeAmazonToMarge` must encode the stored secret as `{"AmazonSecret":{"refresh_token":"<token>","site_id":"<id>"}}` and use `CredentialTypeToken` ("token") — **not** `CredentialTypeTokenV3`. Amazon uses `cs1` semantics.
+
+### Step 7 — Wire CLI flags and router
+
+**`main.go` flags** (env vars in parentheses):
+- `--amazon-client-id` (`AMAZON_CLIENT_ID`)
+- `--amazon-client-secret` (`AMAZON_CLIENT_SECRET`)
+- `--amazon-redirect-uri` (`AMAZON_REDIRECT_URI`, default: `ueberboese-login://amazon`)
+- `--amazon-token-url` (`AMAZON_TOKEN_URL`, for testing overrides)
+- `--amazon-profile-url` (`AMAZON_PROFILE_URL`, for testing overrides)
+
+**Router** (`setupRouter`): Add `/mgmt/amazon/*` sub-routes next to the Spotify block. The `/oauth/.../token/cs1` route is already registered and dispatches to `HandleBoseAmazonToken`.
+
+**`pkg/service/marge/marge.go`**: Extend the `AddSource` provider-label branch to map `AmazonProviderID (20) → "AMAZON"` so stored sources carry the correct type string rather than the raw numeric ID.
+
+**`pkg/models/account.go`**: Add `NewAmazonOAuthCredentials` with `Source: "AMAZON"`, `Version: "token"`.
+
+### Step 8 — Tests
+
+Mirror the Spotify test suite for the Amazon package:
+
+- `TestBuildAuthorizeURL` — verify LWA URL structure
+- `TestExchangeCodeAndStore` — mock token + profile servers; assert POST body credentials (not Basic Auth)
+- `TestRefreshAccessToken` — verify body credentials, token rotation
+- `TestGetFreshToken*` — copy Spotify variants verbatim
+- `TestSaveAndLoad` — verify persistence under `amazon/accounts.json`
+
+Add `pkg/testutils/amazon/handlers.go` and `tests/integration/mocks/amazon.go` mock servers mirroring the Spotify equivalents.
+
+Update `cmd/soundtouch-service/testdata/router_routes.txt` snapshot after wiring.
+
+---
+
+## Trying It Out
+
+### 1. Create a Login with Amazon (LWA) app
+
+Go to [developer.amazon.com](https://developer.amazon.com) → **Login with Amazon** → **Create a New Security Profile**.
+
+You will receive a **Client ID** and **Client Secret**. Under *Web Settings*, add an **Allowed Return URL** that matches `--amazon-redirect-uri`:
+
+- **Browser flow** (easiest to test): `http://<your-host>:8000/mgmt/amazon/callback`
+- **Mobile deep-link flow**: `ueberboese-login://amazon` (the default)
+
+The `profile` scope is sufficient — `music::` scopes are in closed beta and not required. The service only brokers tokens; the speaker communicates with Amazon's playback infrastructure directly.
+
+### 2. Start the service
+
+```bash
+./soundtouch-service \
+  --amazon-client-id  amzn1.application-oa2-client.xxx \
+  --amazon-client-secret yyy \
+  --amazon-redirect-uri http://<your-host>:8000/mgmt/amazon/callback
+```
+
+Or set the equivalent environment variables: `AMAZON_CLIENT_ID`, `AMAZON_CLIENT_SECRET`, `AMAZON_REDIRECT_URI`.
+
+### 3. Trigger the OAuth flow
+
+```bash
+# Get the LWA authorization URL
+curl -u admin:change_me! -X POST http://localhost:8000/mgmt/amazon/init
+# → {"redirectUrl":"https://www.amazon.com/ap/oa?client_id=...&scope=profile&..."}
+```
+
+Open the `redirectUrl` in a browser, log in with your Amazon account, and authorize the app. Amazon redirects back to `/mgmt/amazon/callback`, which responds with an HTML page saying "Amazon Music Connected".
+
+### 4. Verify the account is linked
+
+```bash
+curl -u admin:change_me! http://localhost:8000/mgmt/amazon/accounts
+# → {"accounts":[{"user_id":"amzn1.account.xxx","display_name":"Your Name","email":"you@example.com",...}]}
+```
+
+### 5. Prime a speaker
+
+```bash
+# Discover device IDs first
+curl -u admin:change_me! http://localhost:8000/mgmt/accounts/default/speakers
+
+# Push the token to a specific speaker via ZeroConf
+curl -u admin:change_me! -X POST \
+  "http://localhost:8000/mgmt/amazon/prime?deviceId=<deviceId>"
+# → {"status":"Priming triggered"}
+```
+
+### 6. Verify token refresh from the speaker
+
+Once a speaker has Amazon Music as a source, it will periodically POST to:
+
+```
+POST /oauth/device/{deviceID}/music/musicprovider/20/token/cs1
+```
+
+The service looks up the account by refresh token, refreshes it via LWA, and returns a fresh `access_token`. Check the service logs for `[Amazon]` entries confirming this flow.
+
+### DNS requirement
+
+The speaker derives the OAuth hostname by appending `oauth` to its configured streaming subdomain. If the service is at `myhost.local`, the speaker calls `myhostoauth.local`. A DNS alias pointing `myhostoauth.<domain>` to the same IP is required — the built-in DNS discovery server handles this automatically when `--dns-discovery` is enabled.
+
+### Open question: `site_id`
+
+The `AmazonSecret` credential envelope contains a `site_id` field (e.g. `"1464855981"` seen in a real migrated device). Its origin is unconfirmed — it may be a static Bose partner ID or a per-user Amazon Music identifier. The service currently stores an empty string.
+
+Real-world testing shows the device's `AmazonClient` calls `CheckBaseUrlRedirect` with empty `data` (the `site_id`) and then tries `https://music-api.amazon.com/` directly, receiving a 401 with no redirect to a regional endpoint (e.g. `music-api.amazon.de` for a German account). This suggests that:
+
+1. A correct `site_id` might cause the device to use the right regional endpoint instead of the US default.
+2. Even so, the token scope issue (see Status above) would still block playback — resolving `site_id` alone is not sufficient.
+
+`site_id` is likely secondary to the partner scope problem. It remains an open question for the post-scope-resolution phase.
+
+---
+
+## Endpoints
+
+| Method | Path                                                        | Auth  | Purpose                                            |
+|--------|-------------------------------------------------------------|-------|----------------------------------------------------|
+| `POST` | `/oauth/device/{deviceID}/music/musicprovider/20/token/cs1` | None  | Token refresh from speaker                         |
+| `GET`  | `/mgmt/amazon/callback`                                     | None  | Browser OAuth callback (redirect from Amazon LWA)  |
+| `POST` | `/mgmt/amazon/init`                                         | Basic | Start OAuth flow, returns authorization URL        |
+| `POST` | `/mgmt/amazon/confirm`                                      | Basic | Mobile app confirm (deep link delivers code)       |
+| `GET`  | `/mgmt/amazon/accounts`                                     | Basic | List linked Amazon accounts (tokens stripped)      |
+| `GET`  | `/mgmt/amazon/token`                                        | Basic | Get fresh access token (auto-refreshes if expired) |
+| `POST` | `/mgmt/amazon/prime`                                        | Basic | Push token to speaker via ZeroConf                 |
+
+## Security
+
+Same model as Spotify:
+- `/mgmt/amazon/callback` is intentionally outside Basic Auth to allow direct redirects from Amazon's authorization server.
+- All other `/mgmt/*` endpoints require Basic Auth.
+- Accounts persist to `{dataDir}/amazon/accounts.json` with `0600` permissions.
+- `GetAccounts` strips `AccessToken` and `RefreshToken` from responses.
+
+## Key Design Decisions
+
+**Secret is a JSON envelope, not a bare token.** The stored credential is `{"AmazonSecret":{"refresh_token":"Atzr|...","site_id":"..."}}`, HTML-entity-escaped when written to XML attributes. This was confirmed from a real migrated device's `Sources.xml`. `HandleBoseAmazonToken` must parse this structure to extract the `refresh_token`, and `bridgeAmazonToMarge` must produce it when storing after OAuth.
+
+**`site_id` origin is unconfirmed.** It may be a static Bose partner ID or a per-user Amazon Music identifier. Needs verification — likely obtained by calling the Amazon Music API or the LWA profile endpoint post-authentication.
+
+**Credential type is `token`, not `token_version_3`.** `CredentialTypeTokenV3` is Spotify-specific (`cs3`). Amazon uses `cs1`, which maps to the plain `CredentialTypeToken` ("token") constant. Do not upgrade Amazon credentials to v3 in `marge.go`.
+
+**POST body credentials, not Basic Auth.** The Amazon LWA token endpoint (`/auth/o2/token`) expects `client_id` and `client_secret` as POST body fields, not as an HTTP Basic Auth header. This is the single most important difference from the Spotify implementation.
+
+**No entity resolution.** `ResolveEntity()` is not implemented for Amazon — the Amazon Music API is in closed beta. Return HTTP 501 if an entity endpoint is ever requested.
+
+**`scope` omitted from token response.** The Spotify handler returns a hardcoded scope string. Amazon Music scopes for playback are undocumented; returning an empty or absent `scope` is safer than inventing values.
+
+**ZeroConf extraction is a prerequisite.** The DH-blob crypto in `spotify/zeroconf.go` should be extracted to a shared package before Amazon is added to avoid duplicating cryptographic code.

docs/concepts/implementation-plan.md

@@ -0,0 +1,355 @@
+# Implementation Plan - Enhanced State Management System
+
+## Overview
+
+This document provides a detailed, step-by-step implementation plan for the enhanced state management system. Each step is designed to be small, testable, and independently valuable while maintaining backward compatibility.
+
+## Development Principles
+
+### Quality Gates
+Every step must pass these checks before proceeding:
+1. `golangci-lint run --fix` - no linting issues
+2. `go test ./...` - all tests pass
+3. Existing functionality remains intact
+4. New functionality has appropriate test coverage
+
+### KISS Principle
+- Write the simplest code that works
+- Avoid premature optimization
+- Use straightforward algorithms
+- Build incrementally with small changes
+
+### Leverage Existing Systems
+- Reuse interaction recording for request/response tracking
+- Build upon current parity mismatch detection
+- Extend existing datastore patterns
+- Integrate with established workflows
+
+## Phase 1: Foundation Preparation (2-3 weeks)
+
+### Step 1.1: Code Organization Preparation
+**Duration**: 2-3 days
+**Goal**: Prepare package structure without changing behavior
+
+#### Mini-milestone 1.1.1: Create account package structure
+- Create `pkg/service/account/` directory
+- Add basic `account.go` with placeholder structs
+- Add `account_test.go` with basic test structure
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 1.1.2: Create lifecycle package structure  
+- Create `pkg/service/lifecycle/` directory
+- Add basic `lifecycle.go` with placeholder structs
+- Add `lifecycle_test.go` with basic test structure
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 1.1.3: Extend datastore interface preparation
+- Add placeholder methods to existing datastore for account operations
+- Ensure all existing functionality still works
+- Add tests for new placeholder methods
+- **Quality Check**: Lint + test all packages
+
+### Step 1.2: Account Management Foundation
+**Duration**: 3-4 days
+**Goal**: Basic account creation and retrieval
+
+#### Mini-milestone 1.2.1: Account data model
+- Define `Account` struct with basic fields
+- Add validation functions
+- Add comprehensive unit tests
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 1.2.2: Account persistence
+- Implement account.json file read/write
+- Add atomic file operations
+- Test file operations thoroughly
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 1.2.3: Account manager basic operations
+- Implement `CreateAccount()` function
+- Implement `GetAccount()` function
+- Add error handling and validation
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 1.2.4: Integration with existing datastore
+- Modify datastore to use account manager
+- Ensure backward compatibility with existing accounts
+- Test migration of existing data structure
+- **Quality Check**: Lint + test all packages
+
+### Step 1.3: Basic API Endpoints
+**Duration**: 2-3 days
+**Goal**: Add REST endpoints for account management
+
+#### Mini-milestone 1.3.1: Account creation endpoint
+- Add `POST /api/v1/accounts` handler
+- Integrate with existing HTTP router
+- Add input validation and error responses
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 1.3.2: Account retrieval endpoint
+- Add `GET /api/v1/accounts/{id}` handler
+- Add proper JSON serialization
+- Test endpoint functionality
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 1.3.3: Integration testing
+- Test new endpoints with existing functionality
+- Ensure XML endpoints still work
+- Verify no breaking changes
+- **Quality Check**: Lint + test all packages
+
+## Phase 2: Device Lifecycle Foundation (2-3 weeks)
+
+### Step 2.1: Device State Model
+**Duration**: 3-4 days
+**Goal**: Basic device lifecycle tracking
+
+#### Mini-milestone 2.1.1: Device lifecycle data model
+- Define `DeviceLifecycle` struct
+- Define device states and transitions
+- Add validation and helper functions
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 2.1.2: State transition logic
+- Implement basic state machine
+- Add transition validation
+- Create comprehensive tests for all transitions
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 2.1.3: Lifecycle persistence
+- Implement lifecycle.json file operations
+- Add atomic updates and error handling
+- Test persistence thoroughly
+- **Quality Check**: Lint + test all packages
+
+### Step 2.2: Event Processing Foundation
+**Duration**: 3-4 days
+**Goal**: Basic event handling and logging
+
+#### Mini-milestone 2.2.1: Event data model
+- Define `DeviceEvent` struct
+- Add event types and validation
+- Create event builder helpers
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 2.2.2: Simple event logging
+- Implement append-only event log writing
+- Add structured log format
+- Test log operations and rotation
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 2.2.3: Event processing pipeline
+- Create basic synchronous event processor
+- Add event validation and filtering
+- Integrate with existing WebSocket events
+- **Quality Check**: Lint + test all packages
+
+### Step 2.3: Lifecycle Integration
+**Duration**: 2-3 days
+**Goal**: Connect lifecycle to existing systems
+
+#### Mini-milestone 2.3.1: Discovery integration
+- Trigger lifecycle events on device discovery
+- Update device state on discovery
+- Test discovery workflow with lifecycle
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 2.3.2: WebSocket integration
+- Process WebSocket events through lifecycle
+- Update device state based on events
+- Log significant state changes
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 2.3.3: Migration integration
+- Integrate lifecycle with existing migration system
+- Track migration events and state changes
+- Ensure existing migration still works
+- **Quality Check**: Lint + test all packages
+
+## Phase 3: Enhanced Features (2-3 weeks)
+
+### Step 3.1: Enhanced Mirroring
+**Duration**: 3-4 days
+**Goal**: Improve existing parity detection
+
+#### Mini-milestone 3.1.1: Extended disparity logging
+- Enhance existing parity mismatch logging
+- Add more detailed disparity information
+- Improve log format for analysis
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 3.1.2: Disparity categorization
+- Add severity levels to disparities
+- Categorize different types of mismatches
+- Add filtering and search capabilities
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 3.1.3: Enhanced mirror middleware
+- Extend existing mirror functionality
+- Add better response comparison
+- Integrate with lifecycle events
+- **Quality Check**: Lint + test all packages
+
+### Step 3.2: Data Source Management
+**Duration**: 3-4 days
+**Goal**: Smart routing between local and upstream
+
+#### Mini-milestone 3.2.1: Data source configuration
+- Add per-device source preferences
+- Implement source switching logic
+- Add configuration persistence
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 3.2.2: Fallback mechanisms
+- Add graceful fallback on source failure
+- Implement simple health checking
+- Test fallback scenarios
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 3.2.3: Migration orchestration
+- Add device-by-device migration control
+- Track migration progress
+- Add rollback capabilities
+- **Quality Check**: Lint + test all packages
+
+### Step 3.3: Monitoring and Health
+**Duration**: 2-3 days
+**Goal**: Basic system monitoring
+
+#### Mini-milestone 3.3.1: Health check endpoints
+- Add system health endpoints
+- Report service status
+- Add basic metrics collection
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 3.3.2: Device health tracking
+- Track device connectivity
+- Monitor response times
+- Log health status changes
+- **Quality Check**: Lint + test all packages
+
+#### Mini-milestone 3.3.3: System metrics
+- Add basic performance metrics
+- Track resource usage
+- Add metrics endpoints
+- **Quality Check**: Lint + test all packages
+
+## Quality Assurance Strategy
+
+### Testing Requirements
+Each mini-milestone must include:
+- Unit tests for new functions
+- Integration tests for modified workflows
+- Regression tests for existing functionality
+- Performance tests for critical paths
+
+### Test Categories
+
+#### Unit Tests
+- Test individual functions and methods
+- Mock external dependencies
+- Cover error conditions and edge cases
+- Aim for >90% code coverage on new code
+
+#### Integration Tests
+- Test component interactions
+- Use real file operations in test environment
+- Test HTTP endpoints end-to-end
+- Verify existing functionality unchanged
+
+#### Regression Tests
+- Ensure existing XML endpoints work
+- Verify device discovery still functions
+- Check migration compatibility
+- Test WebSocket event processing
+
+### Continuous Quality Checks
+
+#### Pre-commit Checks
+```bash
+# Before each commit
+golangci-lint run --fix
+go test ./...
+go test -race ./...
+```
+
+#### Milestone Validation
+```bash
+# Before marking milestone complete
+golangci-lint run --fix
+go test ./... -v
+go test -race ./... -v
+go test ./... -bench=.
+```
+
+#### Integration Validation
+```bash
+# Test with real soundtouch-service
+make build
+./soundtouch-service &
+# Run integration test suite
+make integration-test
+```
+
+## Risk Mitigation
+
+### Backward Compatibility
+- All existing APIs must continue working
+- File structure changes must be additive
+- Configuration changes must have defaults
+- Migration paths for existing data
+
+### Rollback Strategy
+- Each step can be independently reverted
+- Configuration flags for new features
+- Graceful degradation when features disabled
+- Clear rollback documentation
+
+### Performance Impact
+- Monitor memory usage during development
+- Profile critical paths before and after changes
+- Set performance regression alerts
+- Simple before complex solutions
+
+## Documentation Requirements
+
+### Code Documentation
+- Comprehensive godoc comments
+- Example usage in comments
+- Error conditions documented
+- Performance characteristics noted
+
+### User Documentation  
+- Update existing guides for new features
+- Add migration guides for new functionality
+- Create troubleshooting documentation
+- Update API documentation
+
+### Development Documentation
+- Architecture decision records
+- Testing strategy documentation
+- Deployment and rollback procedures
+- Performance benchmarking results
+
+## Success Criteria
+
+### Technical Metrics
+- All tests pass consistently
+- No linting issues
+- Memory usage increase <50MB
+- Response time degradation <10%
+
+### Functional Metrics
+- All existing functionality preserved
+- New account management works reliably
+- Device lifecycle tracking is accurate
+- Enhanced monitoring provides value
+
+### Quality Metrics
+- Code coverage maintained >85%
+- No critical security issues
+- Documentation completeness >95%
+- Community feedback positive
+
+This implementation plan ensures steady, reliable progress while maintaining the quality and simplicity principles essential for the project's success.

docs/concepts/implementation-roadmap.md

@@ -0,0 +1,403 @@
+# Implementation Roadmap for Upstream Service Simulation
+
+## Overview
+
+This document provides a detailed implementation roadmap for the upstream Bose service simulation concept. It breaks down the implementation into manageable phases with specific deliverables, technical requirements, and integration points.
+
+## Phase 1: Foundation and Enhanced State Tracking (4-6 weeks)
+
+### Milestone 1.1: Account Management Service (1-2 weeks)
+
+#### Deliverables
+- `pkg/service/account/` package with core account management
+- Account creation, retrieval, and status management APIs
+- Text-based account persistence in JSON format
+- Integration with existing datastore structure
+
+#### Implementation Tasks
+1. **Create Account Manager**
+   ```
+   pkg/service/account/
+   ├── account.go           # Core account management
+   ├── manager.go          # Account manager implementation
+   ├── persistence.go      # File-based persistence
+   └── account_test.go     # Comprehensive tests
+   ```
+
+2. **Account Data Structure**
+   - JSON-based account metadata storage
+   - Integration with existing `data/accounts/{id}/` structure
+   - Account status tracking (active, migrating, suspended)
+   - Migration metadata tracking
+
+3. **API Integration**
+   - Add account management endpoints to existing HTTP router
+   - RESTful API alongside existing XML endpoints
+   - Account creation validation and error handling
+
+#### Technical Requirements
+- Maintain backward compatibility with existing account structure
+- Thread-safe account operations
+- Atomic file operations for account metadata
+- Comprehensive error handling and logging
+
+### Milestone 1.2: Device Lifecycle Manager (2-3 weeks)
+
+#### Deliverables
+- `pkg/service/lifecycle/` package for device state management
+- Device state machine with comprehensive state tracking
+- Event-driven state transitions
+- Integration with existing device discovery and migration
+
+#### Implementation Tasks
+1. **Lifecycle Core**
+   ```
+   pkg/service/lifecycle/
+   ├── lifecycle.go        # Device lifecycle management
+   ├── states.go          # State definitions and transitions
+   ├── events.go          # Event processing
+   ├── persistence.go     # Lifecycle persistence
+   └── lifecycle_test.go  # State machine tests
+   ```
+
+2. **State Machine Implementation**
+   - Define device states: unregistered → registering → active → migrating → offline → retired
+   - Implement state transition rules and validation
+   - Event-driven state changes with history tracking
+   - Integration with existing migration system
+
+3. **Event Processing**
+   - Asynchronous event queue for device events
+   - Event categorization and filtering
+   - Text-based event logging with structured format
+   - Event replay capabilities for debugging
+
+#### Technical Requirements
+- Non-blocking event processing
+- Persistent state across service restarts
+- Integration with existing WebSocket event system
+- Memory-efficient event storage
+
+### Milestone 1.3: Enhanced Mirror System (1-2 weeks)
+
+#### Deliverables
+- Extended mirroring with disparity detection
+- Parity analysis logging and reporting
+- Selective data source switching
+- Integration with existing mirror middleware
+
+#### Implementation Tasks
+1. **Disparity Detection**
+   ```
+   pkg/service/mirror/
+   ├── disparity.go        # Disparity detection logic
+   ├── analyzer.go         # Response analysis and comparison
+   ├── logger.go          # Structured disparity logging
+   └── disparity_test.go  # Analysis tests
+   ```
+
+2. **Enhanced Mirror Middleware**
+   - Extend existing mirror functionality
+   - Add response comparison and hash calculation
+   - Structured logging of disparities
+   - Configurable disparity sensitivity
+
+3. **Data Source Management**
+   - Smart routing between local and upstream sources
+   - Per-endpoint source preference configuration
+   - Fallback mechanisms for upstream unavailability
+   - Source switching with history tracking
+
+#### Technical Requirements
+- Minimal performance impact on request processing
+- Configurable disparity detection sensitivity
+- Structured logging for analysis tools
+- Integration with existing mirror configuration
+
+## Phase 2: Migration and Dual-Source Management (3-4 weeks)
+
+### Milestone 2.1: Migration Controller (2-3 weeks)
+
+#### Deliverables
+- Device-by-device migration orchestration
+- Migration progress tracking and status reporting
+- Rollback capabilities with state preservation
+- Integration with existing setup manager
+
+#### Implementation Tasks
+1. **Migration Orchestration**
+   ```
+   pkg/service/migration/
+   ├── controller.go       # Migration orchestration
+   ├── strategy.go        # Migration strategies
+   ├── rollback.go        # Rollback functionality
+   ├── progress.go        # Progress tracking
+   └── migration_integration_test.go
+   ```
+
+2. **Migration Strategies**
+   - Fresh device registration flow
+   - Bose account data migration flow
+   - Gradual migration with dual-source support
+   - Emergency migration for service outages
+
+3. **Progress Tracking**
+   - Real-time migration status updates
+   - Migration timeline and milestone tracking
+   - Error handling and recovery procedures
+   - Migration completion verification
+
+#### Technical Requirements
+- Integration with existing migration system
+- Atomic migration operations with rollback
+- Progress persistence across service restarts
+- Comprehensive migration logging
+
+### Milestone 2.2: Dual-Source Data Management (1-2 weeks)
+
+#### Deliverables
+- Smart data routing between local and upstream sources
+- Graceful fallback mechanisms
+- Data source preference management
+- Conflict resolution strategies
+
+#### Implementation Tasks
+1. **Data Source Router**
+   ```
+   pkg/service/datasource/
+   ├── router.go          # Smart routing logic
+   ├── preferences.go     # Source preference management
+   ├── fallback.go        # Fallback mechanisms
+   └── conflict.go        # Conflict resolution
+   ```
+
+2. **Source Management**
+   - Per-device, per-endpoint source preferences
+   - Dynamic source switching based on availability
+   - Conflict detection and resolution
+   - Source health monitoring
+
+3. **Integration Points**
+   - Marge service integration for account data
+   - BMX service integration for content data
+   - Preset and recent management integration
+   - Source configuration management
+
+#### Technical Requirements
+- Zero-downtime source switching
+- Conflict resolution without data loss
+- Health check integration
+- Performance monitoring and metrics
+
+## Phase 3: Advanced Features and Analytics (2-3 weeks)
+
+### Milestone 3.1: System Monitoring and Health Checks (1-2 weeks)
+
+#### Deliverables
+- Comprehensive system health monitoring
+- Device connectivity and availability tracking
+- Performance metrics collection
+- Health check endpoints and dashboards
+
+#### Implementation Tasks
+1. **Health Monitoring**
+   ```
+   pkg/service/health/
+   ├── monitor.go         # System health monitoring
+   ├── metrics.go         # Performance metrics
+   ├── connectivity.go    # Device connectivity tracking
+   └── alerts.go          # Health alerting
+   ```
+
+2. **Metrics Collection**
+   - Device availability tracking
+   - Response time monitoring
+   - Error rate tracking
+   - Migration success rates
+
+3. **Dashboard Integration**
+   - Health status endpoints
+   - Metrics export for monitoring tools
+   - Real-time status updates
+   - Historical trend analysis
+
+#### Technical Requirements
+- Minimal performance overhead
+- Configurable monitoring intervals
+- Integration with existing health checks
+- Memory-efficient metrics storage
+
+### Milestone 3.2: Data Export and Backup (1 week)
+
+#### Deliverables
+- Account data export functionality
+- Incremental backup strategies
+- Data integrity verification
+- Migration-ready data formats
+
+#### Implementation Tasks
+1. **Export Functionality**
+   ```
+   pkg/service/export/
+   ├── exporter.go        # Data export logic
+   ├── formats.go         # Export format definitions
+   ├── validation.go      # Data integrity checks
+   └── backup.go          # Backup strategies
+   ```
+
+2. **Backup Management**
+   - Incremental backup creation
+   - Backup validation and verification
+   - Automated backup scheduling
+   - Restore functionality
+
+3. **Data Formats**
+   - Migration-ready JSON exports
+   - XML compatibility for device imports
+   - Compressed archive support
+   - Selective export capabilities
+
+#### Technical Requirements
+- Consistent data export across all account types
+- Backup integrity verification
+- Configurable export scheduling
+- Resource-efficient backup operations
+
+## Integration Strategy
+
+### Existing Service Integration Points
+
+#### 1. Datastore Integration
+- Extend existing datastore with lifecycle and account management
+- Maintain backward compatibility with current file structure
+- Add new persistence methods for enhanced state tracking
+- Implement migration for existing data to new formats
+
+#### 2. Handler Integration
+- Integrate account management into existing HTTP handlers
+- Add lifecycle information to device responses
+- Extend mirror middleware with disparity detection
+- Add new management endpoints alongside existing XML APIs
+
+#### 3. Discovery Integration
+- Link device discovery to lifecycle state transitions
+- Integrate migration triggers with discovery events
+- Add account association during discovery
+- Maintain existing discovery functionality
+
+#### 4. Migration System Integration
+- Extend existing migration manager with new capabilities
+- Integrate lifecycle management with device migrations
+- Add rollback functionality to existing migration flows
+- Maintain compatibility with current migration methods
+
+### Configuration Management
+
+#### New Configuration Options
+```yaml
+accounts:
+  auto_create: false
+  mirror_enhanced_creation: true
+  default_migration_strategy: "gradual"
+
+lifecycle:
+  event_retention_days: 30
+  state_transition_timeout: "5m"
+  async_processing: true
+
+mirror:
+  disparity_detection: true
+  disparity_sensitivity: "medium"
+  source_switching_enabled: true
+  fallback_timeout: "10s"
+
+migration:
+  batch_size: 1
+  progress_reporting: true
+  rollback_enabled: true
+  verification_required: true
+```
+
+### Performance Considerations
+
+#### Resource Usage
+- Target: <100MB additional memory usage on Raspberry Pi Zero 2W
+- CPU usage: <5% additional overhead during normal operations
+- Storage: Text-based logs with configurable rotation
+- Network: Minimal additional upstream requests
+
+#### Optimization Strategies
+- Lazy loading of historical data
+- Configurable log retention policies
+- Memory-efficient event processing
+- Background cleanup processes
+- Efficient file I/O operations
+
+## Testing Strategy
+
+### Unit Testing
+- Comprehensive test coverage for all new packages
+- State machine transition testing
+- Data persistence and integrity tests
+- Mock integration tests for external dependencies
+
+### Integration Testing
+- End-to-end migration flow testing
+- Multi-device scenario testing
+- Disparity detection accuracy testing
+- Performance impact testing
+
+### Compatibility Testing
+- Backward compatibility with existing installations
+- Device compatibility across SoundTouch models
+- Migration from various existing configurations
+- Stress testing with multiple concurrent devices
+
+## Deployment Strategy
+
+### Rollout Plan
+1. **Alpha Release**: Core functionality with limited device support
+2. **Beta Release**: Full feature set with extensive testing
+3. **Stable Release**: Production-ready with documentation
+
+### Migration Path
+1. Existing installations can upgrade incrementally
+2. New features are opt-in with configuration flags
+3. Existing data structures are preserved and extended
+4. Rollback capability for critical issues
+
+### Documentation Requirements
+- Updated API documentation with new endpoints
+- Migration guide for existing users
+- Configuration reference for new options
+- Troubleshooting guide for common issues
+
+## Risk Mitigation
+
+### Technical Risks
+- **Data Loss**: Atomic operations and rollback capabilities
+- **Performance Impact**: Gradual rollout and monitoring
+- **Compatibility Issues**: Comprehensive testing and fallback options
+- **Resource Constraints**: Efficient algorithms and configurable limits
+
+### Operational Risks
+- **Service Disruption**: Zero-downtime deployment strategies
+- **Configuration Complexity**: Sensible defaults and validation
+- **User Adoption**: Clear documentation and migration assistance
+- **Support Burden**: Comprehensive logging and diagnostic tools
+
+## Success Metrics
+
+### Technical Metrics
+- Migration success rate >95%
+- Disparity detection accuracy >90%
+- Performance overhead <5%
+- System availability >99.5%
+
+### User Experience Metrics
+- Reduced support requests
+- Improved device reliability
+- Faster problem resolution
+- Enhanced system visibility
+
+This roadmap provides a structured approach to implementing the upstream service simulation concept while maintaining compatibility with existing deployments and ensuring smooth migration paths for users.

docs/concepts/spotify-oauth.md

@@ -0,0 +1,137 @@
+# Spotify OAuth Integration
+
+The SoundTouch service supports Spotify OAuth integration to broker access tokens for SoundTouch speakers. This is particularly useful for maintaining Spotify Connect functionality after the Bose cloud shutdown (scheduled for May 2026).
+
+## OAuth Flows
+
+The service supports two primary OAuth flows: a browser-based flow and a mobile app-based flow (specifically for the [ueberboese](https://github.com/julius-d/ueberboese-app) app).
+
+### 1. Browser-based Flow
+
+The user initiates the flow, completes authorization in their browser, and is redirected back to the service.
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (curl/app)
+    participant Service as Service
+    participant Spotify as Spotify Auth Server
+    participant Browser as User's Browser
+
+    Client->>Service: POST /mgmt/spotify/init [Basic Auth]
+    Service-->>Client: {"redirectUrl": "https://accounts.spotify.com/authorize?..."}
+    
+    Client->>Browser: User opens URL
+    Browser->>Spotify: User logs in & grants access
+    Spotify-->>Browser: Redirect to /mgmt/spotify/callback?code=abc
+    
+    Browser->>Service: GET /mgmt/spotify/callback?code=abc
+    Note over Service: No auth needed for callback
+    
+    Service->>Spotify: POST /api/token (exchange code)
+    Spotify-->>Service: {access_token, refresh_token}
+    
+    Service->>Spotify: GET /v1/me (fetch profile)
+    Spotify-->>Service: {id, display_name, email}
+    
+    Note over Service: Store account to disk
+    
+    Service-->>Browser: HTML: "Spotify Connected. You can close this window."
+```
+
+### 2. Mobile App Flow (ueberboese)
+
+The mobile app handles the redirect via a deep link and then confirms the authorization with the service.
+
+```mermaid
+sequenceDiagram
+    participant App as ueberboese Flutter App
+    participant Service as Service
+    participant Spotify as Spotify Auth Server
+
+    App->>Service: POST /mgmt/spotify/init [Basic Auth]
+    Service-->>App: {"redirectUrl": "https://..."}
+    
+    App->>Spotify: Open in-app browser (User authorizes)
+    Spotify-->>App: Deep link redirect: ueberboese-login://spotify?code=abc
+    
+    App->>Service: POST /mgmt/spotify/confirm?code=abc [Basic Auth]
+    
+    Service->>Spotify: POST /api/token (exchange code)
+    Spotify-->>Service: {access_token, refresh_token}
+    
+    Service->>Spotify: GET /v1/me (fetch profile)
+    Spotify-->>Service: {profile}
+    
+    Service-->>App: {"ok": true}
+```
+
+### 3. Token Retrieval (Boot Primer / Speaker Setup)
+
+Once an account is linked, access tokens can be retrieved for use with speakers (e.g., via the `addUser` ZeroConf command).
+
+```mermaid
+sequenceDiagram
+    participant Primer as Boot Primer Script
+    participant Service as Service
+    participant Spotify as Spotify Token API
+    participant Speaker as Speaker (Bose ST 20)
+
+    Primer->>Service: GET /mgmt/spotify/token [Basic Auth]
+    
+    alt Token expired
+        Service->>Spotify: POST /api/token (refresh)
+        Spotify-->>Service: new tokens
+    end
+    
+    Service-->>Primer: {"access_token": "...", "username": "..."}
+    
+    Note over Primer: Spotify Connect ZeroConf
+    Primer->>Speaker: POST /SpotifyConnect (addUser with token)
+    Speaker-->>Primer: OK
+    Note over Speaker: Speaker now has Spotify access
+```
+
+## Boot Primer Script
+
+A boot primer script that uses these endpoints to feed Spotify tokens to speakers via ZeroConf is available in the `scripts/spotify/` directory: [spotify-boot-primer.sh](../../scripts/spotify/spotify-boot-primer.sh).
+
+This script can be installed on the speaker itself (which runs embedded Linux) to automatically prime Spotify Connect at boot time. See [README.md](../../scripts/spotify/README.md) and [INSTALL.md](../../scripts/spotify/INSTALL.md) for instructions.
+
+### Automated Installation via Service
+
+The SoundTouch service provides a dedicated management endpoint to automatically handle the installation of the Spotify boot primer on the speaker:
+`POST /mgmt/devices/{deviceId}/spotify/install-primer`
+
+### Automated Installation Steps
+When you run the Spotify primer installation, the service performs the following:
+1.  **Directories**: Creates `/mnt/nv/bin` and `/mnt/nv/BoseApp-Persistence/1` on the speaker.
+2.  **Binary**: Uploads the `spotify-boot-primer` script to the speaker.
+3.  **Configuration**: Automatically generates and uploads `spotify-primer.conf` containing the service's URL and management credentials.
+4.  **Boot Hook**: Injects a call to the primer in the speaker's `/mnt/nv/rc.local` using idempotent markers.
+5.  **Environment**: Updates `/mnt/nv/.profile` to include `/mnt/nv/bin` in the `PATH` for easier manual troubleshooting via SSH.
+
+- **Idempotent Patching**: The service uses explicit markers to inject the hook, ensuring it doesn't corrupt existing content.
+- **Coexistence**: The service-injected hook is designed to coexist with a manually installed `rc.local` (e.g., from the community gist). It only adds a call to `/mnt/nv/bin/spotify-boot-primer` if it's not already managed by a service-controlled block.
+- **Markers**: Look for the following markers in your speaker's `/mnt/nv/rc.local`:
+  - `# --- Aftertouch Spotify hook START ---`
+  - `# --- Aftertouch Spotify hook END ---`
+- **Cleanup**: Reverting a migration via the service will cleanly remove these marker-delimited blocks.
+
+## Endpoints
+
+| Method | Path                                              | Auth  | Purpose                                                               |
+|--------|---------------------------------------------------|-------|-----------------------------------------------------------------------|
+| POST   | `/mgmt/devices/{deviceId}/spotify/install-primer` | Basic | Install Spotify boot primer on speaker (deviceId or IP)               |
+| GET    | `/mgmt/spotify/callback`                          | None  | Browser OAuth callback (redirect from Spotify, returns HTML)          |
+| POST   | `/mgmt/spotify/init`                              | Basic | Start OAuth flow, returns authorization URL                           |
+| POST   | `/mgmt/spotify/confirm`                           | Basic | Mobile app confirm (ueberboese deep link delivers code, returns JSON) |
+| GET    | `/mgmt/spotify/accounts`                          | Basic | List linked Spotify accounts (tokens stripped)                        |
+| GET    | `/mgmt/spotify/token`                             | Basic | Get fresh access token (auto-refreshes if expired)                    |
+| POST   | `/mgmt/spotify/entity`                            | Basic | Resolve Spotify URI to name + image URL                               |
+
+## Security
+
+- `/mgmt/spotify/callback` is intentionally outside Basic Auth to allow direct redirects from Spotify's authorization server.
+- All other `/mgmt/*` endpoints require Basic Auth as configured by `--mgmt-username` and `--mgmt-password`.
+- Tokens are persisted to disk as JSON with restricted file permissions (`0600`).
+- The `GetAccounts` endpoint strips sensitive tokens from the response.

docs/concepts/spotify-priming-strategy.md

@@ -0,0 +1,112 @@
+# Spotify Priming Strategy
+
+This document outlines the strategy for ensuring Bose SoundTouch devices are correctly "primed" for Spotify Connect integration within the AfterTouch ecosystem.
+
+## Overview
+
+To enable Spotify Connect for SoundTouch devices, especially for remote availability outside the local network, the speaker must be associated with a Spotify account via a process called "priming." This involves a two-step exchange with the speaker's ZeroConf API (port 8200):
+
+1. **`getInfo`** — retrieve the speaker's Diffie-Hellman public key and device metadata.
+2. **`addUser`** — push encrypted Spotify credentials using the shared DH secret.
+
+This is the standard Spotify Connect ZeroConf protocol. Once the speaker holds a properly encrypted credential blob it can independently authenticate with Spotify's servers and refresh its own session without any further involvement from AfterTouch.
+
+### ZeroConf Protocol
+
+The current implementation follows the full Spotify Connect ZeroConf protocol (`pkg/service/spotify/zeroconf.go`):
+
+1. `GET http://{ip}:8200/zc?action=getInfo` → parse `publicKey` (base64 DH key, 768-bit Oakley Group 1 prime) from the response.
+2. Generate a client DH key pair using the same group parameters.
+3. Compute `sharedSecret = DH(clientPrivate, speakerPublicKey)`.
+4. Derive keys: `baseKey = SHA1(sharedSecret)[:16]`, then HMAC-SHA1 with labels `"encryption"` and `"checksum"`.
+5. Encrypt a protobuf-encoded `LoginCredentials` blob (username, `AUTHENTICATION_SPOTIFY_TOKEN=4`, access token) using AES-128-CTR + HMAC-SHA1 checksum.
+6. `POST http://{ip}:8200/zc?action=addUser` with `blob={encryptedBlob}`, `clientKey={clientPublicKeyBase64}`.
+
+The speaker decrypts the blob, stores long-lived credentials, and can handle token refresh with Spotify independently. No periodic re-priming is required for token expiry.
+
+The algorithm is based on [librespot](https://github.com/librespot-org/librespot) (Rust reference implementation).
+
+### Fallback for Older Firmware
+
+If `getInfo` fails (e.g. firmware that does not implement the DH exchange), `PushSpotifyCredentials` automatically falls back to the simplified `tokenType=accesstoken` approach: the raw OAuth access token is sent as the `blob` with an empty `clientKey`. This token expires after ~60 minutes and the speaker cannot self-refresh, so periodic re-priming is required in that case.
+
+AfterTouch adopts a **Server-Centric Hybrid Model** that prioritizes device cleanliness and user intent while providing automated self-healing.
+
+## Core Principles
+
+### 1. User Intent (Opt-in)
+AfterTouch replicates the native Bose "Add Source" experience. No Spotify priming occurs until a user explicitly links their Spotify account through the AfterTouch Management Dashboard. This ensures privacy and respects users who do not wish to use Spotify.
+
+### 2. Device Cleanliness (Minimalist Footprint)
+We avoid invasive modifications to the speaker's filesystem.
+- **No On-Device Scripts:** We deprecate the use of internal boot-primer scripts.
+- **Native Communication:** We rely on the speaker's native ability to talk to Bose services, which are intercepted via DNS to point to the AfterTouch server.
+
+### 3. Triggers for Priming
+Priming is triggered when the speaker signals it is active and ready, specifically:
+
+- **Power On:** When the speaker calls the `/marge/streaming/support/power_on` endpoint, AfterTouch ensures the device's ZeroConf state is correctly primed. This is the primary trigger.
+- **Manual Override:** Users can manually trigger a "Prime Spotify" from the device list in the UI if needed.
+
+During any of these events, the server:
+1. Checks if a Spotify account is linked in AfterTouch.
+2. Checks the device's current priming status (via ZeroConf).
+3. If unprimed and an account is linked, it pushes the priming command.
+
+### 4. Automated Recovery
+AfterTouch ensures that if a speaker loses its session (due to a crash or power loss), it is re-primed when it next powers on and reaches out to the service.
+
+### 5. Decoupling
+The logic for account management and device interaction remains decoupled:
+- **Spotify Service:** Manages OAuth tokens and account state.
+- **Discovery Service:** Finds devices and tracks their network presence.
+- **Orchestrator:** Connects the two, deciding when to push tokens to discovered devices based on the current link status.
+
+## Workflow
+
+### Initial Setup (The "Add Source" UX)
+1. User opens the AfterTouch Dashboard.
+2. User selects "Link Spotify Account."
+3. OAuth flow completes; AfterTouch stores the token.
+4. AfterTouch immediately triggers a discovery run to find and prime all compatible speakers.
+
+### Maintenance (The "Watchdog" UX)
+1. A speaker reboots or loses its token.
+2. A discovery event occurs (periodic or triggered by UI).
+3. AfterTouch detects the "Empty" user state on the speaker.
+4. AfterTouch pushes a fresh token from the Spotify Service.
+5. UI reflects that the device is "Managed by AfterTouch" and healthy.
+
+> **Note:** With the proper encrypted-blob flow now in place, the watchdog is only needed for the "speaker reboots and loses state" case — not for token expiry. Speakers running older firmware that trigger the `tokenType=accesstoken` fallback still require periodic re-priming (~45 min) because the raw access token expires.
+
+### Manual Override
+Users can manually trigger a "Re-prime" or "Refresh Link" from the device list in the UI if they suspect the automated self-healing is delayed or if they want to force a specific account onto a device.
+
+## Network Topology & Deployment Scenarios
+
+The strategy adapts based on where the AfterTouch server is deployed:
+
+### Local Deployment (Home Server / Docker)
+- **Mechanism:** Both "Pull" (Marge) and "Push" (ZeroConf side-channel) are used.
+- **Advantage:** The server can proactively fix the speaker's state via port 8200 as soon as it sees a "Liveness Signal."
+
+### External Deployment (Cloud VPS)
+- **Mechanism:** Primarily relies on "Pull" (Marge).
+- **Constraint:** The server cannot reach port 8200 on the speaker due to NAT/Firewall.
+- **Strategy:** In this scenario, AfterTouch acts as a passive token provider. The speaker must initiate the connection to our intercepted Bose endpoints to receive its Spotify configuration. If the speaker completely loses its user state and stops "pulling," a manual re-prime from a local machine or a temporary local discovery run might be required.
+
+## Transition & Cleanup
+
+As AfterTouch moves to the Server-Centric model, we will:
+1.  **Revert On-Device Migration:** Update the Setup Manager to remove legacy `spotify-boot-primer` scripts and `rc.local` hooks from the speakers.
+2.  **Consolidated Directory:** We maintain the `/mnt/nv/soundtouch-service/` base directory for other configuration needs (e.g., `aftertouch.resolv.conf`), but it will no longer contain Spotify-specific credentials or scripts.
+3.  **No On-Device Credentials:** The `/mnt/nv/soundtouch-service/spotify-primer.conf` will be removed, ensuring that no sensitive AfterTouch login details are stored on the speaker in plain text.
+
+## Implementation Roadmap
+
+1. ✅ **Server-Side Priming Logic:** `PrimeDeviceWithSpotify(ip)` and `pushSpotifyTokenToDevice` in `pkg/service/handlers/server.go`. Triggered on device registration (marge handlers) and via the manual `HandleMgmtPrimeDevice` endpoint.
+2. ✅ **Discovery Hook:** `handleDiscoveredDevice` calls `PrimeDeviceWithSpotify` when a speaker is found.
+3. ✅ **Proper ZeroConf Blob:** Full DH key exchange + AES-128-CTR encrypted `LoginCredentials` blob implemented in `pkg/service/spotify/zeroconf.go`. Automatically falls back to `tokenType=accesstoken` if `getInfo` fails (older firmware).
+4. ⬜ **Watchdog / Session Refresh:** Background timer to re-prime all known devices on a schedule. Only strictly needed for older firmware (fallback path) or "speaker lost state" recovery; not required for token expiry on modern firmware.
+5. ⬜ **Revert On-Device Migration:** Update the Setup Manager to remove legacy `spotify-boot-primer` scripts and `rc.local` hooks from the speakers.
+6. ⬜ **UI Enhancements:** Update the Speaker List to show "Spotify Linked" status and provide manual refresh buttons.

docs/concepts/upstream-service-simulation.md

@@ -0,0 +1,393 @@
+# Upstream Bose Service Simulation - State Management Concept
+
+## Overview
+
+This document outlines the concept for simulating and replacing upstream Bose services with enhanced state management capabilities. The goal is to create a comprehensive local replacement that can handle device lifecycles, account management, and state synchronization while maintaining compatibility with existing SoundTouch devices.
+
+## Use Cases
+
+### Case 0: Account Management
+- **Explicit Account Creation**: Accounts must be created through deliberate action (web UI, API call)
+- **Mirror-Enhanced Creation**: Account creation can be enriched using mirrored data from upstream Bose endpoints when devices make requests
+- **Data Recording**: Passively record account information during normal device operations for future use
+
+### Case 1a: Fresh Device Registration
+- Initial setup/registration of a factory-reset or new device
+- Device has no prior Bose account association
+- Full local initialization with default configurations
+
+### Case 1b: Device Migration from Bose Account
+- Migrate existing registered device from Bose services to local management
+- Preserve existing device data (presets, recents, sources)
+- Support gradual migration while maintaining Bose compatibility
+- Mirror Bose account data for seamless transition
+
+### Case 2: Device Lifecycle and State Management
+- Track and manage device lifecycle states and activities
+- Maintain internal state based on incoming events from devices
+- Detect disparities between local and upstream behavior
+- Provide visibility into state changes and system health
+
+## Architecture Principles
+
+### 1. **Text-Based Storage for Debugging**
+- Maintain all state in human-readable text formats (XML, JSON, plain text)
+- Use small, focused files for each data aspect
+- Enable easy debugging and manual inspection
+- Optimize for small hardware deployments (Raspberry Pi Zero 2W)
+
+### 2. **Mirror-First Strategy**
+- Keep mirror functionality active as long as possible
+- Primary source switches from upstream to local only during:
+  - Explicit migration
+  - Sufficient local data accumulation
+  - Upstream service unavailability
+- Record and mirror as much data as possible, even if not immediately used
+
+### 3. **Disparity Detection**
+- Track differences between local and upstream responses
+- Log discrepancies for analysis and improvement
+- Provide visibility into implementation gaps
+- Support parity testing and validation
+
+### 4. **Event-Driven State Management**
+- Process device events asynchronously
+- Track comprehensive event history in text files
+- Support event replay and analysis
+- Minimize noise while capturing important state changes
+
+## Enhanced Data Structure
+
+### Account Management
+
+```
+data/
+├── accounts/
+│   ├── {account-id}/
+│   │   ├── account.json           # Account metadata
+│   ├── account-events.log     # High-level account behavior tracking
+│   │   ├── devices/
+│   │   │   └── {device-id}/
+│   │   │       ├── lifecycle.json    # Device state and history
+│   │   │       ├── info.xml         # Device information
+│   │   │       ├── presets.xml      # Device presets
+│   │   │       ├── recents.xml      # Recent plays
+│   │   │       ├── sources.xml      # Configured sources
+│   │   │       └── events.log       # Device event history
+│   │   └── sessions/
+│   │       └── {session-id}/        # Recorded interaction sessions
+└── system/
+    ├── discovery.log                # Device discovery events
+    └── migration.log               # Migration activities
+```
+
+### Account Metadata Format
+
+```json
+{
+  "id": "account-12345",
+  "name": "User Account",
+  "email": "user@example.com",
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-20T15:45:00Z",
+  "status": "active",
+  "device_count": 3,
+  "migration_status": {
+    "started_at": "2024-01-18T09:00:00Z",
+    "devices_migrated": 1,
+    "devices_pending": 2,
+    "mirror_active": true
+  },
+  "bose_account_id": "bose-original-id",
+  "data_sources": {
+    "local": true,
+    "bose_mirror": true,
+    "primary": "bose"
+  }
+}
+```
+
+### Device Lifecycle Format
+
+```json
+{
+  "device_id": "A81B6A536A98",
+  "account_id": "account-12345",
+  "state": "active",
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-20T16:22:00Z",
+  "state_history": [
+    {
+      "from": "unregistered",
+      "to": "registering",
+      "timestamp": "2024-01-15T10:30:00Z",
+      "reason": "fresh_device_setup",
+      "source": "discovery"
+    },
+    {
+      "from": "registering",
+      "to": "active",
+      "timestamp": "2024-01-15T10:35:00Z",
+      "reason": "registration_complete",
+      "source": "system"
+    }
+  ],
+  "metadata": {
+    "name": "Living Room Speaker",
+    "type": "SoundTouch 30",
+    "serial_number": "I6332527703739342000020",
+    "firmware_version": "4.8.1.25341.2677643.1597353330",
+    "mac_address": "A8:1B:6A:53:6A:98",
+    "ip_address": "192.168.1.100",
+    "last_seen": "2024-01-20T16:20:00Z",
+    "is_legacy_id": false
+  },
+  "data_sources": {
+    "presets": "local",
+    "recents": "mirror_primary", 
+    "sources": "local"
+  },
+  "migration": {
+    "from_bose_account": "bose-account-xyz",
+    "migrated_at": "2024-01-18T14:30:00Z",
+    "method": "gradual",
+    "rollback_available": true
+  }
+}
+```
+
+### Event Log Format
+
+```
+# Device Events Log - A81B6A536A98
+# Format: TIMESTAMP|EVENT_TYPE|SOURCE|DATA
+
+2024-01-20T16:15:00Z|now_playing|websocket|{"source":"SPOTIFY","track":"Song Name","artist":"Artist Name"}
+2024-01-20T16:15:30Z|volume_changed|websocket|{"volume":45,"muted":false}
+2024-01-20T16:16:00Z|preset_selected|websocket|{"preset":1,"source":"SPOTIFY","location":"spotify:track:123"}
+2024-01-20T16:18:00Z|disparity_detected|mirror|{"endpoint":"/v1/account/full","local_hash":"abc123","upstream_hash":"def456"}
+2024-01-20T16:20:00Z|device_online|discovery|{"ip":"192.168.1.100","method":"mdns"}
+```
+
+### Disparity Log Format
+
+```
+# Parity Analysis Log
+# Format: TIMESTAMP|ENDPOINT|DEVICE|ACCOUNT|DISPARITY_TYPE|DETAILS
+
+2024-01-20T16:18:00Z|/v1/account/full|A81B6A536A98|account-12345|content_mismatch|preset_count:local=5,upstream=4
+2024-01-20T16:19:15Z|/v1/presets|A81B6A536A98|account-12345|xml_structure|missing_container_art_in_local
+2024-01-20T16:20:30Z|/v1/recents|A81B6A536A98|account-12345|timestamp_format|local=RFC3339,upstream=custom
+```
+
+## Implementation Strategy
+
+### Phase 1: Enhanced State Tracking
+
+1. **Account Management Service**
+   - Explicit account creation API
+   - Mirror-enhanced account initialization
+   - Account status and migration tracking
+
+2. **Device Lifecycle Manager**
+   - Comprehensive state machine for device lifecycle
+   - Event-driven state transitions
+   - Text-based state persistence
+
+3. **Enhanced Mirror System**
+   - Extended mirroring with disparity detection
+   - Selective data source switching
+   - Parity analysis and logging
+
+### Phase 2: Gradual Migration Support
+
+1. **Migration Controller**
+   - Device-by-device migration orchestration
+   - Rollback capability with state preservation
+   - Migration progress tracking
+
+2. **Dual-Source Data Management**
+   - Smart routing between local and upstream data
+   - Graceful fallback mechanisms
+   - Data source preference management
+
+3. **State Synchronization**
+   - Bidirectional sync capabilities
+   - Conflict resolution strategies
+   - Sync status monitoring
+
+### Phase 3: Advanced Analytics
+
+1. **Disparity Analysis Engine**
+   - Automated disparity detection and classification
+   - Trend analysis and reporting
+   - Implementation gap identification
+
+2. **System Health Monitoring**
+   - Device connectivity monitoring
+   - Service availability tracking
+   - Performance metrics collection
+
+3. **Data Export and Backup**
+   - Account data export for migration
+   - Incremental backup strategies
+   - Data integrity verification
+
+## API Enhancements
+
+### Account Management APIs
+
+```http
+# Create account explicitly
+POST /api/v1/accounts
+Content-Type: application/json
+
+{
+  "name": "User Account",
+  "email": "user@example.com"
+}
+
+# Get account with migration status
+GET /api/v1/accounts/{account-id}
+
+# Initiate account migration from Bose
+POST /api/v1/accounts/{account-id}/migrate
+Content-Type: application/json
+
+{
+  "bose_account_id": "bose-original-id",
+  "strategy": "gradual"
+}
+```
+
+### Device Lifecycle APIs
+
+```http
+# Register fresh device
+POST /api/v1/accounts/{account-id}/devices
+Content-Type: application/json
+
+{
+  "device_id": "A81B6A536A98",
+  "name": "Living Room Speaker",
+  "registration_type": "fresh"
+}
+
+# Get device state and lifecycle
+GET /api/v1/accounts/{account-id}/devices/{device-id}/state
+
+# Migrate device from Bose account
+POST /api/v1/accounts/{account-id}/devices/{device-id}/migrate
+Content-Type: application/json
+
+{
+  "from_bose_account": "bose-account-xyz",
+  "preserve_data": true
+}
+```
+
+### Monitoring and Analysis APIs
+
+```http
+# Get disparity analysis
+GET /api/v1/system/disparities?since=2024-01-20T00:00:00Z
+
+# Get migration status
+GET /api/v1/system/migration/status
+
+# Export account data
+GET /api/v1/accounts/{account-id}/export
+```
+
+## Integration with Existing Services
+
+### Enhanced Marge Service
+
+- Integrate lifecycle information into account responses
+- Add migration status to device listings
+- Support dual-source data routing
+- Include disparity metadata in responses
+
+### Enhanced BMX Service
+
+- Track content source preferences by account
+- Mirror and compare content recommendations
+- Log streaming behavior for analysis
+- Support gradual source migration
+
+### Discovery Service Integration
+
+- Link discovered devices to lifecycle manager
+- Trigger lifecycle state transitions on discovery events
+- Support both fresh registration and migration flows
+- Handle legacy device ID migration automatically
+
+## Performance Considerations
+
+### Simplicity First (KISS Principle)
+
+- Favor simple, readable code over premature optimization
+- Use straightforward algorithms and data structures
+- Minimize complexity in favor of maintainability
+- Build incrementally with small, testable changes
+
+### Quality Assurance
+
+- Complete test coverage for all new functionality
+- Comprehensive linting with `golangci-lint run --fix` 
+- Full test suite execution `go test ./...` for each milestone
+- Integration tests with existing functionality
+
+### File Management
+
+- Simple line-based append operations for logs
+- Basic log rotation when needed
+- Direct file operations without complex caching
+- Straightforward data persistence
+
+## Development Principles
+
+### KISS (Keep It Simple, Stupid)
+- Prioritize simplicity and readability over performance optimization
+- Use standard Go idioms and patterns
+- Avoid premature abstraction and optimization
+- Build the simplest thing that works first
+
+### Quality First
+- Every milestone must pass `golangci-lint run --fix` without issues
+- Complete test suite must pass `go test ./...` before proceeding
+- Integration tests ensure existing functionality remains intact
+- Code coverage should be maintained or improved
+
+### Incremental Development
+- Make small, focused changes that can be easily reviewed
+- Each step should be independently testable and valuable
+- Maintain backward compatibility throughout development
+- Enable rollback at any point in the process
+
+### Leverage Existing Systems
+- Reuse existing interaction recording for request/response tracking
+- Build upon current parity mismatch detection system
+- Extend existing datastore and handler patterns
+- Integrate with established discovery and migration workflows
+
+## Future Enhancements
+
+Future improvements should maintain the simplicity-first approach:
+
+1. **Enhanced Web Interface**
+   - Simple dashboard for account and device management
+   - Basic migration progress tracking
+   - Straightforward device health monitoring
+
+2. **Extended Logging**
+   - Additional high-level behavior tracking
+   - Simple analytics based on existing parity data
+   - Enhanced debugging information
+
+3. **Community Integration**
+   - Standardized data export formats
+   - Simple reporting mechanisms
+   - Clear documentation for community contributions
+
+This concept provides a solid, maintainable foundation for replacing Bose's upstream services. The emphasis on simplicity, existing system reuse, and comprehensive testing ensures reliable functionality while maintaining the debugging capabilities needed for small hardware deployments.