Architecture & Référence API

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.

100% Local & Respect de la vie privée

L'ensemble des APIs et flux WebSockets s'exécute exclusivement sur le réseau local (LAN / Wi-Fi) du mini PC. Aucun média, clé d'authentification ou donnée télémétrique n'est transmis à des serveurs tiers.

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.

Démarrage du serveur Backend avec rechargement à chaud (Hot Reload)

Lance FastAPI sur le port 8000 avec documentation Swagger interactive disponible sur http://localhost:8000/docs.

bash — environnement dev & console api bobine

fanta@wyse:~$cd backend && .venv/bin/uvicorn app.main:app --reload --port 8000

INFO: Will watch for changes in ['/home/fanta/Bobine/backend']

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

INFO: Started reloader process [19450] using WatchFiles

INFO: FastAPI app initialized: routes registered (/api/playback, /api/settings, /api/audio, /api/kiosk)

Documentation interactive OpenAPI disponible sur http://127.0.0.1:8000/docs

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) :

GET/api/health

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
}

GET/api/status

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
  }
}

POST/api/playout/play

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" }

POST/api/playout/volume

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 }

POST/api/backup/export

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

WS/ws/events

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/health toutes 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.