Documentation Développeurs & Architecture
Cette documentation constitue la référence technique pour les développeurs et intégrateurs du système Bobine : architecture système, endpoints de l'API REST locale, protocole d'événements WebSockets temps réel, superviseurs systemd et guide de contribution AGPL-3.0.
Stack Technique Détaillée
| Couche | Technologie | Rôle & Responsabilité |
|---|---|---|
| Backend API | Python 3.11+, FastAPI, Uvicorn | API REST asynchrone ultra-rapide et gestion des connexions WebSockets |
| Persistance | SQLite + SQLAlchemy 2.0 | Métadonnées des vidéos, planning hebdomadaire, playlists et paramètres |
| Moteur de Lecture | MPV + VA-API (Intel iHD & AMD mesa-va-drivers) | Décodage matériel vidéo zero-copy (1080p60 et 4K) piloté via socket IPC Unix |
| Interface Frontend | Next.js 16 (App Router), React 19, TS | Application web universelle et réactive (Admin, Kiosque, Télécommande, Radio) |
| Routage Audio | ALSA | Routage de la sortie audio multi-canaux et gestion du volume |
Développement Local & Console Interactive d'API
Prérequis : Node.js ≥ 20, Python ≥ 3.11.
Référence de l'API REST Locale
Le démon Bobine expose une API REST complète et typée sur http://bobine.local/api (ou http://127.0.0.1:8000/api) :
Point de contrôle de santé machine interrogé en continu par le chien de garde systemd.
// Réponse JSON (200 OK)
{
"status": "healthy",
"database": "ok",
"kiosk_active": true,
"uptime_seconds": 86420
}Retourne l'état de diffusion en temps réel, le cours en cours, le timecode et le volume.
// Réponse JSON (200 OK)
{
"state": "playing",
"current_workout": {
"id": "w_982a7f",
"title": "RPM Sprint 45",
"category": "Spinning",
"duration_seconds": 2700
},
"timecode": 1420.5,
"volume": 80,
"next_scheduled_class": {
"title": "Yoga Vinyasa",
"starts_in_seconds": 840
}
}Déclenche la lecture immédiate d'une vidéo par son identifiant unique.
// Corps de requête
{ "workout_id": "w_982a7f", "target_display": "hdmi_wired" }
// Réponse JSON (200 OK)
{ "success": true, "message": "Lecture démarrée" }Ajuste le volume sonore général de la salle (valeur de 0 à 100).
// Corps de requête
{ "level": 85 }
// Réponse JSON (200 OK)
{ "success": true, "current_volume": 85 }Génère une archive ZIP complète de la vidéothèque, du planning et des réglages pour sauvegarde ou migration.
Protocole d'Événements WebSockets
Les interfaces clientes se connectent à ws://bobine.local/ws/events pour recevoir les mises à jour en direct :
// Message JSON diffusé à tous les clients connectés :
{
"event": "PLAYBACK_STATE_CHANGED",
"payload": {
"state": "playing",
"workout_id": "w_982a7f",
"timecode": 45.2,
"volume": 80
}
}Architecture des Services Systemd
Bobine est orchestré par 3 unités systemd indépendantes :
bobine-backend.service— Application FastAPI Python et démon SQLite.bobine-kiosk.service— Session graphique X11 allégée affichant Chromium en plein écran sur la TV.bobine-watchdog.service— Superviseur de résilience interrogeant/api/healthtoutes les 10s avec relance automatique.
Communauté, Contact & Contribution
Bobine est publié sous licence AGPL-3.0. Les contributions de code, rapports de bugs et retours d'expérience matériel sont les bienvenus.
Distribution via Tor (.onion)
En soutien à la communauté du logiciel libre et au projet Tor, je distribue aussi Bobine via deux services onion (v3), sans journal de visite et avec une disponibilité au mieux :
- Site :
http://bobinedaoki42tt33rxacmtaab2gxvxb2orqgcyhvowv3aggxhruvrid.onion/ - Dépôt APT :
tor+http://rzvwjat5pidtxtwzcsvew7yc5ugfjvzz432ecpn3s5mlch4cs7vvmqad.onion/(même clé de signature que packages.bobine.fit/debian, vérifiée parapt; installer d'abordapt-transport-tor)
Le miroir est un export statique de ce site, sans aucune route serveur ; la boutique matériel et l'assistant Baamix n'y sont volontairement pas proposés. Pour en savoir plus sur Tor : torproject.org et son code source sur GitHub.