Spotibox

Kindgerechter Spotify-Hörspiel-Player als Progressive Web App für das iPad. Ausgeliefert über GitHub Pages: https://schdief.github.io/spotibox/

Kinder wählen Hörspiele über große Bilder aus, sehen auf einen Blick, was neu, angefangen oder schon gehört ist – und können nach einem versehentlichen Verlassen der App an genau derselben Stelle weiterhören. Der Katalog wird von den Eltern über ein verstecktes Menü gepflegt.

Der vollständige Umsetzungsplan steht in PLAN.md.

Bildschirme

Folgenauswahl	Abspielen

Alles ohne Text bedienbar, denn die Zielgruppe kann nicht lesen:

Symbol	Bedeutung
🎁	Neu – noch nie gehört
▶	Angefangen, Balken am Coverrand zeigt wie weit
✓	Durchgehört, Cover abgedunkelt
⌂	Zurück zur Startseite
⏮ ⏭	Ein Kapitel zurück / vor
↺ ↻	15 Sekunden zurück / vor

Im Player zeigt der obere Balken die Position im laufenden Kapitel, die Blockreihe darunter den Fortschritt in der gesamten Folge – ein Block je Kapitel.

Wie es funktioniert

Die App spielt Audio nicht selbst ab. Das iPad ist reine Fernbedienung: Über die Spotify Web API steuert Spotibox ein Spotify-Connect-Gerät, üblicherweise einen Lautsprecher im Kinderzimmer (z. B. einen Amazon Echo).

Das ist bewusst so gewählt. Ein älteres iPad (etwa ein iPad Air 2 mit iPadOS 15) kann die Spotify-App gar nicht installieren, weil sie iOS 16 verlangt. Und ein fest installierter Lautsprecher ist ohnehin das stabilere Ziel als eine mobile App, die das Betriebssystem jederzeit aus dem Speicher werfen kann.

Vorteile dieser Aufteilung:

• Kein App-Wechsel nötig → der Geführte Zugriff auf dem iPad ist uneingeschränkt nutzbar
• Der Ton kommt aus einem richtigen Lautsprecher im Zimmer
• Hintergrundwiedergabe und Bildschirmsperre sind kein Thema

Ist kein Gerät erreichbar, sieht das Kind keine Fehlermeldung, sondern einen ruhigen Bildschirm mit einem Foto der Eltern.

Voraussetzungen

• Spotify Premium (Family-Account genügt) – die Playback-Endpunkte sind Premium-only
• Ein Spotify-Connect-Gerät, z. B. ein Echo oder ein anderer vernetzter Lautsprecher. Taucht ein Echo nicht in der Geräteliste auf: einmal per Sprachbefehl Spotify darauf starten
• Eine eigene App im Spotify Developer Dashboard (Development Mode reicht: bis zu 25 manuell freigegebene Konten)

Einrichtung

1. Im Spotify Developer Dashboard eine App anlegen, unter APIs used Web API wählen.
2. Als Redirect URI exakt eintragen (inklusive Slash am Ende):
   • Produktion: https://schdief.github.io/spotibox/
   • Entwicklung: http://127.0.0.1:5173/spotibox/ (Spotify akzeptiert bei HTTP nur die Loopback-IP, nicht localhost)
3. Die eigenen Spotify-Konten unter User Management freigeben.
4. Die App öffnen, die Client ID eintragen und anmelden.
5. Im Elternmenü unter Abspielgerät den Lautsprecher als Standardgerät festlegen.
6. Über Gruppen und Folgen suchen den Katalog befüllen.

Es wird kein Client Secret verwendet – die Anmeldung läuft über Authorization Code Flow mit PKCE, alles rein clientseitig.

Hinweis zur Datenhaltung: Katalog und Hörfortschritt liegen in IndexedDB, Tokens und Einstellungen im localStorage – ausschließlich auf dem Gerät. Es gibt keinen Server. iOS kann Browserspeicher unter Umständen verwerfen; eine Export-Funktion als Sicherung steht noch aus.

Browser-Unterstützung

Zielgerät ist ein iPad Air 2 mit iPadOS 15 (Safari 15). Der Build ist entsprechend auf safari15/ios15 festgelegt. Ohne diese Vorgabe liefert Vite modernere Syntax aus, die auf dem Gerät nur eine weiße Seite ergibt. Nicht verwenden: CSS :has(), crypto.randomUUID(), Array.prototype.at(), Object.hasOwn(), structuredClone(), Container Queries.

Entwicklung

Benötigt Node 20+ (siehe .nvmrc). Falls Node über Homebrew als node@22 installiert ist (keg-only), muss der Pfad ergänzt werden:

export PATH="/opt/homebrew/opt/node@22/bin:$PATH"

npm install
npm run dev              # Dev-Server auf http://127.0.0.1:5173/spotibox/
npm run build            # Typprüfung + Produktions-Build nach dist/
npm run preview          # Produktions-Build lokal testen
npm run generate-assets  # PWA-Icons aus public/favicon.svg neu erzeugen

Deployment

Jeder Push auf main baut und veröffentlicht über GitHub Actions (.github/workflows/deploy.yml). Einmalig nötig: in den Repo-Einstellungen unter Settings → Pages als Source GitHub Actions auswählen.

Auf dem iPad installieren

In Safari öffnen → Teilen → Zum Home-Bildschirm. Danach startet die App im Vollbild ohne Browserleiste. Für den Kinderbetrieb empfiehlt sich zusätzlich der Geführte Zugriff (Einstellungen → Bedienungshilfen), damit die App nicht verlassen werden kann.

Projektstand

• Fundament: PKCE-Login, API-Client, PWA-Setup, Pages-Deployment
• Machbarkeit bestätigt: Sprung auf Kapitel + Position funktioniert
• Kinder-UI: Gruppen, Folgen, Player, Erwachsenen-Bildschirm
• Fortschritt & Weiterhören
• Elternmenü: Geräte, Gruppen, Katalogsuche, Eltern-Foto
• PIN-Schutz für das Elternmenü
• Export/Import als Sicherung
• Sleep-Timer und Lautstärkegrenze

Bedienung

Wo	Wie
Elternmenü	Auf der Startseite 2,5 Sekunden auf das Noten-Symbol oben rechts halten
Elternmenü (Notausgang)	URL direkt aufrufen: …/spotibox/#/eltern
Einrichtung & Diagnose	Im Elternmenü oben rechts
Zurück zum Kind	Haus-Symbol links oben

Das Abspielgerät lässt sich im Elternmenü unter Abspielgerät umstellen – Standardgerät und Ersatzgerät werden über den Gerätenamen gemerkt, nicht über die ID.