From 9e835c02c712e4e0616a753562dfdf4e07c1a77c Mon Sep 17 00:00:00 2001 From: Tom Ernst Date: Fri, 11 Sep 2026 23:47:02 +0200 Subject: [PATCH] docs: translate documentation to English --- README.md | 58 +++++++++++++++++++++++++++---------------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 45bd107..dc41d3a 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,54 @@ -# Sonos-Websteuerung +# Sonos Web Controller -Lokale, responsive Weboberfläche für Sonos mit automatischer Erkennung über [SoCo](https://github.com/SoCo/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. +A local, responsive web interface for Sonos with automatic device discovery through [SoCo](https://github.com/SoCo/SoCo). It controls playback and volume, manages groups, and plays Sonos favorites, items from the current queue, or direct HTTP(S) streams. The application stores no state and does not require a database. -## Sicherheitsgrenze +## Security boundary -**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. +**This application intentionally has no authentication. Run it exclusively on a trusted LAN and never expose it to the internet through port forwarding, a reverse proxy, or a public IP address.** Any client with access to port 5000 can control every discovered Sonos device. Firewall rules should restrict access to the local management network. -## Voraussetzungen +## Requirements -- 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 +- Linux x86_64 with Docker Engine and Docker Compose v2 +- Sonos devices and the Docker host on the same LAN/VLAN +- Multicast/SSDP (UDP 1900) and UPnP traffic allowed between the host and Sonos devices -## Start mit Docker Compose +## Start with Docker Compose ```bash -git clone +git clone https://git.citr.one/tom/Multi-Messenger.git cd Multi-Messenger docker compose up -d --build docker compose ps ``` -Danach `http://:5000` öffnen. Logs: `docker compose logs -f`. Stoppen: `docker compose down`. +Open `http://:5000`. View logs with `docker compose logs -f`. Stop the application with `docker compose down`. -### Warum `network_mode: host` zwingend ist +### Why `network_mode: host` is required -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. +SoCo discovers devices through SSDP multicast and communicates with them directly through UPnP. Docker's standard bridge network does not reliably forward multicast traffic between the LAN and a container. `network_mode: host` gives the container access to the Linux host's network stack, enabling discovery and device communication. As a result, the Compose configuration does not contain a `ports:` mapping. Host networking in this configuration is supported reliably only on Linux. -## Bedienung +## Usage -- **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. +- **Rooms:** Select "Search rooms" to refresh device discovery. Playback, pause, stop, and volume controls are available on every room card. Status and current track information refresh every ten seconds. +- **Groups:** Select a coordinator, choose one or more members, and select "Create group." Use "Leave group" to remove a zone from its group. +- **Music:** Select a room and play a favorite or queue item. Under "Stream URL," enter a complete `http://` or `https://` URL. Whether a stream can be played depends on its format and whether the Sonos player can reach it. -## Konfiguration +## Configuration -| Variable | Standard | Bedeutung | +| Variable | Default | Description | |---|---:|---| -| `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 | +| `SONOS_DISCOVERY_TIMEOUT` | `5` | Discovery timeout in seconds | +| `SONOS_OPERATION_TIMEOUT` | `8` | SoCo HTTP/SOAP request timeout in seconds | +| `SONOS_MAX_JSON_BYTES` | `16384` | Maximum JSON request body size in bytes | +| `LOG_LEVEL` | `INFO` | Python log level | -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`. +Timeout values must be positive and finite. `SONOS_OPERATION_TIMEOUT` configures the SoCo HTTP/SOAP request timeout. A high-level operation may contain several bounded requests and can therefore take longer overall. Device calls are not left running in the background after an artificial future timeout. The discovery cache is locked only during short in-memory operations. Status requests run independently for each device in a short-lived pool limited to eight threads, so an unreachable room does not prevent status data from being returned for other rooms. Error responses contain a machine-readable `error` field and a German `message` intended for the current user interface. -Healthcheck: `GET /health` prüft bewusst nur den Webprozess; fehlende Lautsprecher machen den Container nicht „unhealthy“. +The `GET /health` endpoint intentionally checks only the web process. Missing or unreachable speakers do not mark the container as unhealthy. -## Lokale Entwicklung und Tests +## Local development and testing -Python 3.12 verwenden: +Use Python 3.12: ```bash python -m venv .venv @@ -58,9 +58,9 @@ pytest -q python -m compileall -q app tests ``` -Die Tests verwenden ausschließlich Mocks; Discovery oder echte Lautsprecher werden nicht angesprochen. +The tests use mocks exclusively. They do not run discovery or contact real speakers. -## API-Kurzüberblick +## API overview - `GET /api/zones` - `POST /api/zones//transport` (`play`, `pause`, `stop`) -- 2.54.0