HTTP-API der MuPiBox
Die lokale HTTP-Schnittstelle der Box – Status abfragen, Wiedergabe steuern, Durchsagen und Nachrichten senden, mit Beispielen für curl und Hausautomation.
Die MuPiBox hat eine lokale HTTP-API. Über sie arbeiten Touch-Oberfläche, Verwaltung und MuPiBox-App – und du kannst sie für eigene Skripte oder die Hausautomation nutzen. Alle Adressen beginnen mit http://<Box>:8090/api/ (Box = IP-Adresse oder Name, siehe Der erste Start). Antworten sind JSON.
Zugriff und Sicherheit
| Bereich | Wer darf zugreifen? |
|---|---|
Player und Status (/api/status, /api/command, /api/speak, /api/message …) | jedes Gerät im Heimnetz, ohne Anmeldung |
Verwaltung (/api/admin/…) | nur mit Admin-Anmeldung, sobald ein Admin-Passwort gesetzt ist |
Netzwerk (/api/connectivity/…) | aus dem Heimnetz nur mit Admin-Anmeldung |
Home-Assistant-Schnittstelle (/api/ha/v1/…) | nur über HTTPS (Port 8443) mit gekoppeltem Token – nutzt die Integration |
Schreibende Anfragen aus fremden Webseiten im Browser blockiert die Box. Skripte wie curl oder Hausautomationen senden keinen solchen Browser-Herkunftsnachweis und sind erlaubt.
Status abfragen
| Methode und Pfad | Liefert |
|---|---|
GET /api/health | {"status":"ok","version":"…"} – ideal für Erreichbarkeitsprüfungen |
GET /api/status | Player-Zustand: state (playing, paused, stopped, error), folder, queue, index, position, duration (Sekunden), volume, max_volume, now_playing (Radiotitel) |
GET /api/info | Version, Sprache und die für Oberflächen nötigen Einstellungen |
GET /api/library | lokale Bibliothek mit Ordnern (id, name) und Titeln |
GET /api/home | Kategorien und Medien der Startseite |
GET /api/mupihat/status | Akku, Laden und Spannung beim MuPiHAT |
GET /api/system/metrics | CPU, Arbeitsspeicher, Speicherplatz und Temperatur |
curl http://mupibox.local:8090/api/statusWiedergabe steuern
POST /api/command mit einem JSON-Objekt. Das Feld action bestimmt den Befehl:
action | Weitere Felder | Wirkung |
|---|---|---|
toggle | – | Wiedergabe/Pause umschalten |
play, pause, stop | – | abspielen, pausieren, stoppen |
next, previous | – | nächster bzw. vorheriger Titel |
seek | value (Sekunden) | an eine Stelle springen |
volume | value (0 bis Maximallautstärke) | Lautstärke setzen |
volume_delta | value (z. B. 5 oder -5) | Lautstärke relativ ändern |
folder | folder_id | Ordner/Hörspiel von vorn starten |
resume | folder_id, item_index | Ordner ab einem bestimmten Titel starten (0 = erster) |
Die folder_id steht in GET /api/library. Die Lautstärke wird immer auf die eingestellte Maximallautstärke begrenzt, Einstellungen der Elternkontrolle können auch API-Befehle einschränken.
# Pause/Weiter
curl -X POST -H 'Content-Type: application/json' \
-d '{"action":"toggle"}' http://mupibox.local:8090/api/command
# Lautstärke auf 30
curl -X POST -H 'Content-Type: application/json' \
-d '{"action":"volume","value":30}' http://mupibox.local:8090/api/commandDurchsagen und Nachrichten
| Methode und Pfad | JSON | Wirkung |
|---|---|---|
POST /api/speak | {"text":"Zeit fürs Abendessen!"} | liest den Text mit der eingestellten Stimme vor; laufende Musik pausiert und läuft danach weiter |
POST /api/message | {"title":"Hallo","message":"Gleich ist Schlafenszeit","duration_ms":8000} | zeigt eine Nachricht auf dem Display (title und duration_ms optional) |
curl -X POST -H 'Content-Type: application/json' \
-d '{"text":"Zähne putzen nicht vergessen!"}' http://mupibox.local:8090/api/speakEine Durchsage kann beim ersten Mal einige Sekunden dauern, weil die Box die Sprache erst erzeugt; wiederholte Sätze kommen aus dem Zwischenspeicher.
Fehler und Antworten
Fehler kommen als JSON {"error":"…"} mit passendem HTTP-Status: 400 (Anfrage fehlerhaft), 401 (Anmeldung nötig), 403 (nicht erlaubt), 409 (gerade nicht möglich, z. B. ohne Admin-Passwort), 503 (Dienst nicht verfügbar).