99admandClaude Opus 5.5
fc15f2b933
Name, Seitentitel, Dienste (playwish-web, playwish-controller), Dienst-Benutzer (playwish), Pfade (/opt/playwish, /usr/local/src/playwish), Vorlagen und Repository-Adresse. „Audiofy“ war bereits von mehreren Produkten belegt. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
245 lines
13 KiB
Markdown
245 lines
13 KiB
Markdown
# 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.
|