Sonos Web Controller 4 Kids

Ein kinderfreundlicher Web-Controller für Sonos-Lautsprecher mit Touchscreen-optimierter Oberfläche (800×480px).

Features

• 🎵 Kinderfreundliche UI - Optimiert für 5" Touchscreen (800×480px)
• 🎨 Raumsymbole - Emoji-Icons für bessere Orientierung
• 🖼️ Fünf Themes - Kinder wechseln per Klick zwischen den im Admin freigegebenen Designs
• 🏠 Home-Button - Aus jeder Auswahl direkt zurück zur Startansicht, ohne die Wiedergabe zu stoppen
• 📐 Einheitliche Albumkacheln - Zwei reservierte Titelzeilen in allen Themes
• 📚 Apple Music Integration - Alben und Hörbücher direkt hinzufügen
• 🎯 Track-Navigation - Einzelne Tracks aus Alben abspielen
• 🔀 Filter - Nach Musik/Hörbücher filtern
• 🔄 Auto-Updates - Automatisches Docker Image Building via GitHub Actions

Bedienung der Kinderansicht

• Home-Symbol oben links: Öffnet die Startansicht mit allen Figuren und Interpreten und setzt den Medienfilter auf „Alles“ zurück. Raum, Theme und laufende Wiedergabe bleiben erhalten; die Seite wird nicht neu geladen.
• Theme-Name neben dem Home-Symbol: Schaltet mit jedem Klick zum nächsten freigegebenen Theme. Nach dem letzten beginnt die Reihenfolge von vorne, ohne Auswahlliste.
• Zurück: Führt eine Ebene zurück, zum Beispiel vom Album zu den Alben des Interpreten.
• Albumtitel: Jede Albumkachel reserviert zwei Textzeilen, auch bei kurzen Titeln. Längere Titel werden mit „…“ gekürzt. Der vollständige Titel bleibt in der Detailansicht und für Screenreader verfügbar. Die Höhe des Titelbereichs passt sich der Schriftgröße an.

Home-Button und Theme-Wechsel sind auch per Tastatur bedienbar und haben eine sichtbare Fokusmarkierung. Der Theme-Name wird beim Darüberfahren mit der Maus nicht unterstrichen.

Themes für Kinder freigeben

Theme	Kennung in der Konfiguration	Gestaltung
Default	default	Überarbeitetes dunkles Theme mit dauerhaftem Player
Classic (Original)	classic	Ursprüngliche Default-Kinderansicht
Colorful Kids	colorful	Bunte Kinderansicht
Hörinsel	hoerinsel	Ruhige, bildorientierte Kinderansicht
Wolkenklang (Pink & Lila)	wolkenklang	Pink-lila Kindertheme

Im Elternbereich (?admin=1) unter Einstellungen → Design der Kinderansicht:

• Die oberen Schaltflächen setzen das Standard-Theme für neue Browser und geben es frei.
• Unter Für Kinder freigegebene Themes mehrere Designs ankreuzen und Theme-Freigaben speichern wählen.
• Mindestens ein Theme bleibt freigegeben. Wird das Standard-Theme abgewählt, wird das erste freigegebene Theme zum Standard.

Kinder tippen oben links auf den Theme-Namen: Jeder Klick wechselt zum nächsten freigegebenen Design, nach dem letzten wieder zum ersten – ohne Auswahlliste. Die Auswahl wird nur in diesem Browser gespeichert und verändert nicht den globalen Standard. Bei nur einem freigegebenen Theme ist der Name nicht klickbar. Geänderte Freigaben werden bei erreichbarem Backend beim nächsten 30-Sekunden-Abgleich oder beim Zurückkehren zum Browserfenster übernommen. Eine gespeicherte Auswahl wird nur verwendet, solange das Theme noch freigegeben ist. Bestehende Installationen behalten zunächst ausschließlich ihr bisheriges Theme; weitere Designs müssen freigegeben werden.

In media-data/config.json bezeichnet activeTemplate das Standard-Theme und enabledTemplates die freigegebenen Themes. Änderungen am besten im Admin speichern. Fehlt enabledTemplates in einer älteren Konfiguration, wird nur das bisherige Standard-Theme angeboten. Die persönliche Auswahl der Kinder liegt im Browser, nicht in dieser Datei.

Quick Start mit Docker

Voraussetzungen

• Docker & Docker Compose (oder Portainer)
• Sonos HTTP API läuft (z.B. http://192.168.114.21:5005)
• Synology NAS oder Linux Server

Deployment mit Portainer

1. In Portainer → Stacks → Add stack
2. Name: sonos-webcontroller4kids
3. Web editor - Kopiere folgenden Code:

version: '3.8'

services:
  sonos-webcontroller:
    image: smartnightly/sonos-webcontroller4kids:latest
    container_name: sonos-webcontroller4kids
    
    # Ändere hier den Port direkt (Format: "host-port:container-port")
    ports:
      - "3344:3344"  # z.B. "8080:8080" für Port 8080
    
    volumes:
      # Passe den Pfad an deine Synology-Struktur an
      - /volume1/docker/sonos-webcontroller4kids/media-data:/app/media-data
    
    restart: unless-stopped
    
    environment:
      - NODE_ENV=production
      - PORT=3344  # Muss mit container-port oben übereinstimmen

4. Passe den Volume-Pfad an (z.B. /volume1/docker/...)
5. Optional: Ändere beide Port-Werte (in ports: und PORT=)
6. Deploy the stack
7. Zugriff: http://synology-ip:3344 (oder dein konfigurierter Port)

Port ändern: Einfach beide Werte im Stack-Editor anpassen:

• ports: - "8080:8080"
• PORT=8080

Deployment mit Docker Compose

# docker-compose.yml verwenden
docker-compose -f docker-compose.portainer.yml up -d

Updates

Das Docker Image wird automatisch bei jedem Push auf main gebaut und auf Docker Hub veröffentlicht.

AMD64 und ARM64 werden parallel auf nativen GitHub-Runnern gebaut, ohne QEMU-Emulation. Erst wenn beide Builds erfolgreich sind, veröffentlicht der Workflow das gemeinsame Multi-Plattform-Image unter den bisherigen Tags (main, latest bzw. Versionstags). Docker wählt beim Pull automatisch die passende Architektur. Pull Requests bauen beide Varianten nur zur Prüfung und veröffentlichen nichts. Architekturgetrennte Caches, 20-Minuten-Build-Limits und das Ablösen älterer Läufe desselben Branches verhindern unnötig lange oder überholte Builds.

In Portainer: Einfach "Pull and redeploy" klicken

Mit Docker Compose:

docker-compose pull
docker-compose up -d

Development

Lokale Entwicklung

Verwende Node.js 22 (mindestens 22.13). Docker und CI verwenden ebenfalls Node.js 22.

# Backend
cd backend
npm install
npm run dev  # läuft auf Port 3344

# Frontend (in neuem Terminal)
cd frontend
npm install
npm run dev  # läuft auf Port 5173

Backend: http://localhost:3344
Frontend: http://localhost:5173 (API-Aufrufe im Entwicklungsmodus direkt an http://localhost:3344)

Lokales Docker Build

docker build -t sonos-webcontroller4kids:latest .
docker run -p 3344:3344 -v ./media-data:/app/media-data sonos-webcontroller4kids:latest

# Mit eigenem Port:
# PORT=8080 docker run -p 8080:8080 -e PORT=8080 -v ./media-data:/app/media-data sonos-webcontroller4kids:latest

Konfiguration

Port-Konfiguration

Der Port kann über die Umgebungsvariable PORT angepasst werden:

• Standard: 3344
• Docker Compose: Setze PORT=8080 in der .env Datei oder direkt in docker-compose.yml
• Portainer: Setze PORT=8080 unter "Environment variables"

Admin-Interface

Die Konfiguration erfolgt über das Admin-Interface unter http://your-ip:3344?admin=1.

Wichtige Einstellungen:

• Sonos Base URL: URL zur Sonos HTTP API
• Räume: Verfügbare Sonos-Räume
• Raumsymbole: Emoji-Icons für Räume
• Shuffle/Repeat: Anzeige aktivieren/deaktivieren
• Themes: Standard-Theme und Mehrfachauswahl der für Kinder freigegebenen Designs

Eine leere Liste aktivierter Räume sperrt die Wiedergabe in allen Räumen; das Backend prüft diese Freigabe auch bei direkten Steuerungsanfragen. Eine erneute Raumsuche erhält bestehende Einstellungen und Freigaben. Nur bei der ersten Einrichtung werden alle gefundenen Räume automatisch aktiviert.

Lautstärkeänderungen werden pro Raum nacheinander ausgeführt und auf die konfigurierte Grenze beschränkt. Kann die aktuelle Lautstärke nicht ermittelt werden, wird die Änderung abgelehnt. Diese Begrenzung betrifft Befehle dieses Controllers; die Sonos-App und physische Lautsprechertasten werden dadurch nicht eingeschränkt.

Dokumentation

• Docker Deployment Guide - Ausführliche Deployment-Anleitung
• Docker Setup - Docker-Grundlagen
• GitHub Actions Setup - CI/CD Konfiguration
• Docker-Hub-Beschreibung - Englische Beschreibung; Änderungen müssen separat auf Docker Hub übernommen werden, ein Image-Push aktualisiert den Text nicht

Technologie-Stack

• Frontend: React + TypeScript + Vite
• Backend: Node.js + Express + TypeScript
• Deployment: Docker + GitHub Actions
• API: iTunes Search API, Sonos HTTP API

Lizenz

MIT