Sonos-Websteuerung

Lokale, responsive Weboberfläche für Sonos mit automatischer Erkennung über SoCo. Sie steuert Wiedergabe und Lautstärke, verwaltet Gruppen und spielt Sonos-Favoriten, Einträge der aktuellen Warteschlange oder direkte HTTP(S)-Streams ab. Es wird kein Zustand gespeichert und keine Datenbank benötigt.

Sicherheitsgrenze

Diese Anwendung hat absichtlich keine Anmeldung. Sie darf ausschließlich in einem vertrauenswürdigen LAN betrieben und niemals per Portfreigabe, Reverse Proxy oder öffentlicher IP ins Internet gestellt werden. Jeder Client mit Zugriff auf Port 5000 kann alle gefundenen Sonos-Geräte steuern. Firewall-Regeln sollten den Zugriff auf das lokale Verwaltungsnetz begrenzen.

Voraussetzungen

• Linux x86_64 mit Docker Engine und Docker Compose v2
• Sonos-Geräte und Docker-Host im selben LAN/VLAN
• Multicast/SSDP (UDP 1900) und UPnP-Verkehr zwischen Host und Sonos erlaubt

Start mit Docker Compose

git clone <repository-url>
cd Multi-Messenger
docker compose up -d --build
docker compose ps

Danach http://<IP-des-Docker-Hosts>:5000 öffnen. Logs: docker compose logs -f. Stoppen: docker compose down.

Warum network_mode: host zwingend ist

SoCo erkennt Geräte per SSDP-Multicast und kommuniziert per UPnP direkt mit ihnen. Das übliche Docker-Bridge-Netz leitet Multicast nicht zuverlässig zwischen LAN und Container weiter. network_mode: host gibt dem Container den Netzwerk-Stack des Linux-Hosts und ermöglicht Discovery sowie Ereignis-/Gerätekommunikation. Darum gibt es in Compose kein ports:-Mapping. Host Networking funktioniert in dieser Form nur zuverlässig unter Linux.

Bedienung

• Räume: „Räume suchen“ aktualisiert die Erkennung. Wiedergabe, Pause, Stopp und Lautstärke stehen auf jeder Raumkarte bereit. Status und aktueller Titel werden alle zehn Sekunden aktualisiert.
• Gruppen: Coordinator wählen, ein oder mehrere Mitglieder markieren und „Gruppe bilden“ drücken. „Aus Gruppe lösen“ trennt eine Zone.
• Musik: Raum wählen und Favorit oder Queue-Eintrag starten. Unter „Stream-URL“ eine vollständige http://- oder https://-URL eingeben. Ob ein Stream abspielbar ist, hängt von Format und Erreichbarkeit durch den Sonos-Player ab.

Konfiguration

Variable	Standard	Bedeutung
SONOS_DISCOVERY_TIMEOUT	5	Discovery-Timeout in Sekunden
SONOS_OPERATION_TIMEOUT	8	maximales Warten einer API-Anfrage auf eine Geräteoperation
SONOS_MAX_JSON_BYTES	16384	maximale Größe eines JSON-Request-Bodys in Bytes
LOG_LEVEL	INFO	Python-Loglevel

Timeouts müssen positiv und endlich sein. SONOS_OPERATION_TIMEOUT wird als SoCo-HTTP/SOAP-Request-Timeout gesetzt; eine höherwertige Aktion kann mehrere solcher begrenzten Requests enthalten und daher insgesamt länger dauern. Es werden keine Geräteaufrufe nach einem künstlichen Future-Timeout im Hintergrund weitergeführt. Der Discovery-Cache wird nur während kurzer Speicherzugriffe gesperrt. Statusabfragen laufen je Gerät unabhängig in einem kurzlebigen, auf acht Threads begrenzten Pool; ein nicht erreichbarer Raum verhindert deshalb nicht die Statusdaten der übrigen Räume. API-Antworten enthalten bei Fehlern ein maschinenlesbares error und eine deutsche message.

Healthcheck: GET /health prüft bewusst nur den Webprozess; fehlende Lautsprecher machen den Container nicht „unhealthy“.

Lokale Entwicklung und Tests

Python 3.12 verwenden:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
pytest -q
python -m compileall -q app tests

Die Tests verwenden ausschließlich Mocks; Discovery oder echte Lautsprecher werden nicht angesprochen.

API-Kurzüberblick

• GET /api/zones
• POST /api/zones/<uid>/transport (play, pause, stop)
• PUT /api/zones/<uid>/volume
• POST /api/groups, DELETE /api/groups/<uid>
• GET /api/zones/<uid>/favorites, GET /api/zones/<uid>/queue
• POST /api/zones/<uid>/play/favorite|queue|stream