playwish/README.md

Audiofy – 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 → audiofy-web (FastAPI + SQLite)
                                        ▲ Player-API (Bearer-Token)
                                        │ nur ausgehend vom Player
Player: raspotify (Spotify Connect) + audiofy-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. 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

Audiofy 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. Audiofy
   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 Audiofy 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/audiofy/raw/branch/main/install/get.sh | bash -s -- server
curl -fsSL https://git.wind8000.de/0/audiofy/raw/branch/main/install/get.sh | bash -s -- player

Das Startskript installiert bei Bedarf git, holt Audiofy nach /usr/local/src/audiofy 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/audiofy/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/audiofy.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: „Audiofy“) 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 audiofy-web (Server) · systemctl status audiofy-controller raspotify (Player)
Logs live	journalctl -u audiofy-web -f · journalctl -u audiofy-controller -f
Neustart	sudo systemctl restart audiofy-web bzw. audiofy-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/audiofy/app	Code (gehört root, der Dienst darf nur lesen)
/opt/audiofy/.env (Server)	Geheimnisse: Spotify, Admin-Passwort-Hash, Turnstile, PLAYER_API_TOKEN
/opt/audiofy/data/audiofy.db (Server)	Wünsche, Verlauf, Einstellungen
/opt/audiofy/config/.env (Player)	Geheimnisse: Spotify, SERVER_URL, PLAYER_API_TOKEN, Lautsprecher

Die .env-Dateien gehören dem Dienst-Benutzer audiofy (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 audiofy /opt/audiofy/.venv/bin/python /opt/audiofy/app/verwaltung.py passwort  --env /opt/audiofy/.env
sudo -u audiofy /opt/audiofy/.venv/bin/python /opt/audiofy/app/verwaltung.py turnstile --env /opt/audiofy/.env
# Spotify-Login erneuern – Server bzw. Player
sudo -u audiofy /opt/audiofy/.venv/bin/python /opt/audiofy/app/auth.py --profil server --env /opt/audiofy/.env
sudo -u audiofy /opt/audiofy/.venv/bin/python /opt/audiofy/app/auth.py --profil player --env /opt/audiofy/config/.env

Danach den jeweiligen Dienst neu starten.

Datenbank sichern (Server):

sudo -u audiofy sqlite3 /opt/audiofy/data/audiofy.db ".backup /opt/audiofy/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-audiofy.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-audiofy.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 audiofy-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

Audiofy 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.

Audiofy 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.

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