playwish/README.md

# Playwish – Musikwünsche für Partys

Gäste scannen einen QR-Code und wünschen sich Songs. Ein **Player** spielt über Spotify
zufällige Titel aus einer Grund-Playlist – jeder N-te Titel ist ein Wunsch. Gibt es keine
Wünsche, läuft einfach die Playlist weiter. Der Gastgeber steuert alles über einen
Admin-Bereich, auch vom Handy.

- **Gäste:** Spotify-Suche, Wünschen (optional mit Namen), „Läuft gerade“, Warteschlange – ohne Spotify-Konto
- **Schutz:** Zugang nur per Einladungslink/QR-Code, Limit pro Gast, keine Duplikate, Sperrzeit für Wiederholungen, Sperrliste, optional Moderation und Cloudflare Turnstile
- **Admin:** Play/Pause/Weiter/Lautstärke, „Als Nächstes spielen“, Not-Aus, Wünsche freigeben/umsortieren/löschen, Gäste sperren, Playlist wechseln, Bluetooth-Lautsprecher suchen und wechseln, Verlauf
- **Abwechslung:** Ein Playlist-Titel kommt erst wieder, wenn seit seinem letzten Einsatz mindestens X % der Playlist gelaufen sind (einstellbar, auch über Neustarts); Wünsche haben eine eigene Sperrzeit in Minuten
- **Robust:** Ohne Server spielt der Player die Playlist weiter; Bedienung über die normale Spotify-App bleibt möglich; Pause des Gastgebers wird auch über Neustarts respektiert

## Aufbau

```
Gast-Handy ──HTTPS──▶ Server: Caddy → playwish-web (FastAPI + SQLite)
                                        ▲ Player-API (Bearer-Token)
                                        │ nur ausgehend vom Player
Player: raspotify (Spotify Connect) + playwish-controller
        └─▶ Bluetooth-Lautsprecher (BlueALSA) oder Kabel/HDMI/USB (ALSA)
```

| Rolle | Läuft auf | Braucht |
|---|---|---|
| **Server** | VPS, Heimserver, VM … | Debian 12+, öffentliche (Sub-)Domain, Ports 80/443 |
| **Player** | Raspberry Pi, Mini-PC, VM mit Audio … | Debian 12+ (arm64/armhf/amd64), Lautsprecher, Internet |

Beide Rollen können auch auf demselben Gerät laufen. Der Player braucht **keine**
Portfreigabe am Router.

## Voraussetzungen

1. **Spotify Premium** für das Konto, das abspielt.
2. Eine eigene **Spotify-App** (kostenlos, ca. 5 Minuten) – siehe
   [Spotify-App anlegen](#spotify-app-anlegen). Eine App reicht für Server und Player.
3. Eine **eigene Playlist** als Grund-Playlist (im Development Mode lassen sich nur eigene Playlists lesen).
4. Für den Server eine **Domain**, deren A/AAAA-Record auf den Server zeigt.

## Spotify-App anlegen

Playwish steuert Spotify über die offizielle Web API. Dafür braucht jede Installation eine
eigene, kostenlose „App“ im Spotify-Developer-Bereich. Gäste brauchen nichts davon.

**Was du brauchst:** das Spotify-Konto, das später abspielt – mit **Premium**.
Die Bezeichnungen im Dashboard können sich leicht ändern; sinngemäß:

1. **Anmelden:** <https://developer.spotify.com/dashboard> öffnen, mit dem Spotify-Konto
   einloggen und beim ersten Mal den Entwickler-Bedingungen zustimmen.
2. **App erstellen:** „Create app“ wählen und ausfüllen:

   | Feld | Eintrag |
   |---|---|
   | App name | z. B. `Playwish` |
   | App description | z. B. `Musikwünsche für meine Party` |
   | Website | leer lassen |
   | **Redirect URI** | **`http://127.0.0.1:8888/callback`** – genau so, dann „Add“ |
   | Which API/SDKs | **Web API** |

   Den Bedingungen zustimmen und speichern.
   Wichtig: `127.0.0.1` verwenden – Spotify akzeptiert `localhost` nicht mehr.
3. **Zugangsdaten notieren:** In der App unter „Settings“ stehen die **Client ID** und –
   hinter „View client secret“ – das **Client Secret**. Beides fragen die Install-Skripte ab.
   Das Secret ist ein Passwort: nicht weitergeben, nicht in Chats oder Repositorys posten.
4. **Konto freischalten:** Unter „User Management“ das Spotify-Konto eintragen, das
   abspielt (Name und die E-Mail-Adresse des Spotify-Kontos) – auch wenn es dein eigenes ist.
5. **Fertig.** Bei der Installation fragen die Skripte Client ID und Secret ab und starten
   danach den **Spotify-Login**:
   - Die angezeigte Adresse in einem beliebigen Browser öffnen (auch am Handy) und anmelden.
   - Der Browser landet auf `http://127.0.0.1:8888/callback?code=…` und zeigt einen Fehler –
     **das ist normal.** Die komplette Adresse aus der Adresszeile kopieren und ins
     Terminal einfügen.
   - Server und Player melden sich jeweils einmal an (der Server nur für die Suche).

**Was der Development Mode bedeutet:** Neue Apps laufen im „Development Mode“. Dort gilt
(Stand 2026): Der App-Besitzer braucht Premium, nur eingetragene Konten dürfen die App
nutzen, die Suche liefert höchstens 10 Treffer, nur **eigene** Playlists sind lesbar, und
die Nutzung muss **nicht kommerziell** sein. Für Playwish reicht das völlig – abgespielt
wird nur über dein eigenes Konto.

**Typische Fehler beim Login**

| Meldung | Lösung |
|---|---|
| `INVALID_CLIENT: Invalid redirect URI` | Redirect-URI im Dashboard muss exakt `http://127.0.0.1:8888/callback` lauten. |
| „User not registered in the Developer Dashboard“ / 403 | Konto unter „User Management“ eintragen (Schritt 4). |
| `invalid_client` / „Token-Anfrage fehlgeschlagen (400)“ | Client ID oder Secret falsch eingegeben. |
| Abspielen scheitert mit „Premium required“ | Das Konto hat kein Premium. |
| „State passt nicht“ | Adresse aus einem älteren Login-Versuch eingefügt – Login neu starten. |

**Secret erneuern** (falls es versehentlich öffentlich wurde): im Dashboard unter
„Settings“ → „Rotate client secret“, dann den neuen Wert als `SPOTIFY_CLIENT_SECRET` in
**beiden** `.env`-Dateien (Server und Player) eintragen und die Dienste neu starten.

## Installation

**Per Einzeiler** – als Benutzer mit sudo-Rechten (oder als root) in einem Terminal:

```
curl -fsSL https://git.wind8000.de/0/playwish/raw/branch/main/install/get.sh | bash -s -- server
curl -fsSL https://git.wind8000.de/0/playwish/raw/branch/main/install/get.sh | bash -s -- player
```

Das Startskript installiert bei Bedarf `git`, holt Playwish nach `/usr/local/src/playwish` und
startet das passende Install-Skript. Später aktualisieren: denselben Befehl mit `--update`
am Ende (`… | bash -s -- server --update`).

Vorsichtiger – erst ansehen, dann ausführen:

```
curl -fsSLO https://git.wind8000.de/0/playwish/raw/branch/main/install/get.sh
less get.sh
bash get.sh server        # bzw. player
```

**Oder von Hand:** Repository klonen (`git clone https://git.wind8000.de/0/playwish.git`) und
die Install-Skripte direkt starten:

**1. Server**

```
install/install-server.sh
```

Fragt Domain, E-Mail für Let's Encrypt, Spotify-Zugang und Playlist ab, richtet Dienst-Benutzer,
Python-Umgebung, systemd-Dienst und Caddy (HTTPS) ein und optional Firewall (ufw), fail2ban und
automatische Sicherheitsupdates. Danach folgen der Spotify-Login (nur für die Suche) und das
Admin-Passwort.

Am Ende zeigt das Skript, wie du den **`PLAYER_API_TOKEN`** für den Player abrufst.

**2. Player**

```
install/install-player.sh
```

Fragt Gerätename, Audio-Ausgabe (Bluetooth oder ALSA), Server-Adresse, `PLAYER_API_TOKEN`,
Spotify-Zugang und Playlist ab, installiert raspotify, koppelt auf Wunsch gleich den
Bluetooth-Lautsprecher und richtet den Controller als Dienst ein. Danach folgt der
Spotify-Login für die Wiedergabe-Steuerung.

**3. Einmalig in der Spotify-App** das neue Gerät (Standard: „Playwish“) auswählen – im selben
Netz wie der Player. Damit speichert raspotify seine Anmeldung und ist nach jedem Neustart
von selbst wieder da.

**4. Admin-Bereich** unter `https://<domain>/admin` öffnen, unter **Gäste** den Gastzugang
einschalten und den QR-Code zeigen oder ausdrucken.

## Betrieb

| Aufgabe | Befehl |
|---|---|
| Status | `systemctl status playwish-web` (Server) · `systemctl status playwish-controller raspotify` (Player) |
| Logs live | `journalctl -u playwish-web -f` · `journalctl -u playwish-controller -f` |
| Neustart | `sudo systemctl restart playwish-web` bzw. `playwish-controller` |
| Update | Einzeiler mit `--update` – oder im Repository `git pull && install/install-server.sh --update` bzw. `install/install-player.sh --update` |

`--update` ersetzt nur Code, Python-Umgebung und Dienstdatei; Konfiguration, Datenbank,
Caddy, Firewall und raspotify bleiben unverändert.

**Dateien**

| Pfad | Inhalt |
|---|---|
| `/opt/playwish/app` | Code (gehört root, der Dienst darf nur lesen) |
| `/opt/playwish/.env` (Server) | Geheimnisse: Spotify, Admin-Passwort-Hash, Turnstile, `PLAYER_API_TOKEN` |
| `/opt/playwish/data/playwish.db` (Server) | Wünsche, Verlauf, Einstellungen |
| `/opt/playwish/config/.env` (Player) | Geheimnisse: Spotify, `SERVER_URL`, `PLAYER_API_TOKEN`, Lautsprecher |

Die `.env`-Dateien gehören dem Dienst-Benutzer `playwish` (Rechte 600). **Sichere sie an einem
sicheren Ort** (z. B. Passwort-Manager) – sie stehen bewusst nicht im Repository.

**Verwaltung** (interaktiv, im eigenen Terminal):

```
# Server: Admin-Passwort bzw. Turnstile-Schlüssel ändern
sudo -u playwish /opt/playwish/.venv/bin/python /opt/playwish/app/verwaltung.py passwort  --env /opt/playwish/.env
sudo -u playwish /opt/playwish/.venv/bin/python /opt/playwish/app/verwaltung.py turnstile --env /opt/playwish/.env
# Spotify-Login erneuern – Server bzw. Player
sudo -u playwish /opt/playwish/.venv/bin/python /opt/playwish/app/auth.py --profil server --env /opt/playwish/.env
sudo -u playwish /opt/playwish/.venv/bin/python /opt/playwish/app/auth.py --profil player --env /opt/playwish/config/.env
```

Danach den jeweiligen Dienst neu starten.

**Datenbank sichern** (Server):

```
sudo -u playwish sqlite3 /opt/playwish/data/playwish.db ".backup /opt/playwish/data/sicherung.db"
```

## Server härten (empfohlen, von Hand)

Das Install-Skript ändert die SSH-Konfiguration bewusst **nicht** – damit sperrt man sich
leicht aus. Vorlage: `install/vorlagen/sshd-10-playwish.conf` (anderer Port, nur Schlüssel,
kein root, nur ein Admin-Benutzer). Vorgehen:

1. Eigenen Admin-Benutzer mit sudo anlegen, SSH-Schlüssel hinterlegen, Login testen.
2. Neuen Port in ufw **und** einer eventuellen Cloud-Firewall öffnen.
3. Vorlage ausgefüllt nach `/etc/ssh/sshd_config.d/10-playwish.conf` legen, `sudo sshd -t`, `sudo systemctl restart ssh`.
4. **In einer zweiten Sitzung** testen – die alte bleibt offen, bis es klappt.
5. Erst dann den alten Port in ufw/Cloud-Firewall schließen und fail2ban auf den neuen Port umstellen.

## Fehlerbehebung

| Problem | Ursache / Lösung |
|---|---|
| Keine Musik, Log: „Lautsprecher nicht verbunden“ | Lautsprecher einschalten – der Player verbindet ihn neu und startet die Musik von selbst. |
| Lautsprecher verbindet sich nicht mehr („Permission denied“) | Kopplung verloren. Im Admin unter Einstellungen → Lautsprecher neu suchen und verbinden (Lautsprecher im Kopplungsmodus). |
| „Gerät nicht gefunden“ | `systemctl status raspotify`. Nach einer Neuinstallation einmal in der Spotify-App das Gerät auswählen. |
| Admin: „Player offline“ | `systemctl status playwish-controller`, Internet des Players prüfen. Die Musik läuft trotzdem mit der Playlist weiter. |
| Admin: „Grund-Playlist nicht lesbar“ | Nur eigene Playlists funktionieren (Spotify Development Mode). |
| Befehle „No active device“ | Spotify hatte kein aktives Gerät; „Play“ startet dann die Playlist auf dem Player. |
| Nach Neustart bleibt es still | Gewollt, wenn vorher pausiert oder Not-Aus aktiv war – im Admin „Play“ bzw. „Freigeben“. |
| Musik stockt während der Lautsprecher-Suche | Normal: WLAN und Bluetooth teilen sich oft einen Funkchip. |
| Gäste: „Kein Zugang“ | Gastzugang im Admin eingeschaltet? Nach „Neuen Link erzeugen“ gilt nur der neue QR-Code. |
| Zu viele Admin-Login-Versuche | 15 Minuten warten (max. 5 Versuche pro IP). |


## Entwicklung

```
cd server && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt pytest
.venv/bin/python -m pytest -q          # Server
cd ../player && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt pytest
.venv/bin/python -m pytest -q tests    # Player (Wiederholungsregel)
```

## Lizenz

Copyright © 2026 Dominic Alexander Windolph

Playwish ist freie Software: Du kannst es unter den Bedingungen der **GNU General Public
License**, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder
verändern – entweder gemäß Version 3 der Lizenz oder (nach deiner Wahl) jeder späteren
Version. Der vollständige Lizenztext steht in [`LICENSE`](LICENSE).

Playwish wird in der Hoffnung verbreitet, dass es nützlich ist, aber **ohne jede
Gewährleistung** – sogar ohne die implizite Gewährleistung der Marktreife oder der
Eignung für einen bestimmten Zweck. Details stehen in der GNU General Public License.

Playwish ist kein Produkt von Spotify und steht in keiner Verbindung zu Spotify AB.
Spotify ist eine Marke der Spotify AB.