L'API HTTP de la MuPiBox
L'interface HTTP locale du boîtier : consulter l'état, piloter la lecture, envoyer des annonces et des messages, avec des exemples pour curl et la domotique.
La MuPiBox dispose d'une API HTTP locale. L'interface tactile, l'administration et l'appli MuPiBox l'utilisent, et vous pouvez l'utiliser pour vos propres scripts ou votre domotique. Toutes les adresses commencent par http://<boîtier>:8090/api/ (boîtier = adresse IP ou nom, voir Premier démarrage). Les réponses sont en JSON.
Accès et sécurité
| Domaine | Qui peut y accéder ? |
|---|---|
Lecteur et état (/api/status, /api/command, /api/speak, /api/message …) | tout appareil du réseau domestique, sans connexion |
Administration (/api/admin/…) | uniquement connecté à l'administration dès qu'un mot de passe d'administration est défini |
Réseau (/api/connectivity/…) | depuis le réseau domestique uniquement connecté à l'administration |
Interface Home Assistant (/api/ha/v1/…) | uniquement en HTTPS (port 8443) avec un jeton appairé ; utilisée par l'intégration |
Le boîtier bloque les requêtes d'écriture provenant d'autres sites dans un navigateur. Les scripts comme curl ou les systèmes domotiques n'envoient pas cette origine de navigateur et sont autorisés.
Consulter l'état
| Méthode et chemin | Renvoie |
|---|---|
GET /api/health | {"status":"ok","version":"…"}, idéal pour vérifier que le boîtier répond |
GET /api/status | état du lecteur : state (playing, paused, stopped, error), folder, queue, index, position, duration (secondes), volume, max_volume, now_playing (titre radio) |
GET /api/info | version, langue et réglages nécessaires aux interfaces |
GET /api/library | bibliothèque locale avec dossiers (id, name) et titres |
GET /api/home | catégories et médias de l'écran d'accueil |
GET /api/mupihat/status | batterie, charge et tension avec le MuPiHAT |
GET /api/system/metrics | processeur, mémoire, stockage et température |
curl http://mupibox.local:8090/api/statusPiloter la lecture
POST /api/command avec un objet JSON. Le champ action choisit la commande :
action | Autres champs | Effet |
|---|---|---|
toggle | – | basculer lecture/pause |
play, pause, stop | – | lire, mettre en pause, arrêter |
next, previous | – | titre suivant ou précédent |
seek | value (secondes) | aller à une position |
volume | value (0 jusqu'au volume maximal) | régler le volume |
volume_delta | value (p. ex. 5 ou -5) | modifier le volume de façon relative |
folder | folder_id | lancer un dossier/une histoire depuis le début |
resume | folder_id, item_index | lancer un dossier à partir d'un titre donné (0 = premier) |
Le folder_id figure dans GET /api/library. Le volume est toujours limité au volume maximal réglé, et les réglages du contrôle parental peuvent aussi restreindre les commandes de l'API.
# Lecture/pause
curl -X POST -H 'Content-Type: application/json' \
-d '{"action":"toggle"}' http://mupibox.local:8090/api/command
# Volume à 30
curl -X POST -H 'Content-Type: application/json' \
-d '{"action":"volume","value":30}' http://mupibox.local:8090/api/commandAnnonces et messages
| Méthode et chemin | JSON | Effet |
|---|---|---|
POST /api/speak | {"text":"À table !"} | lit le texte avec la voix réglée ; la musique se met en pause puis reprend |
POST /api/message | {"title":"Coucou","message":"Bientôt l'heure de dormir","duration_ms":8000} | affiche un message à l'écran (title et duration_ms facultatifs) |
curl -X POST -H 'Content-Type: application/json' \
-d '{"text":"N’oublie pas de te brosser les dents !"}' http://mupibox.local:8090/api/speakLa première annonce d'une phrase peut prendre quelques secondes, car le boîtier génère d'abord la voix ; les phrases répétées viennent du cache.
Erreurs et réponses
Les erreurs arrivent en JSON {"error":"…"} avec le statut HTTP correspondant : 400 (requête incorrecte), 401 (connexion requise), 403 (non autorisé), 409 (impossible pour l'instant, p. ex. sans mot de passe d'administration), 503 (service indisponible).