SPB Git

Repository Public

RELAY.md 11.2 KB

# Relay Engine — moteur de relais vidéo de SP TV

Mis en service le 2026-11-17 sur m4mn. SP TV garde son fonctionnement d'origine — l'appareil lit le flux directement chez le diffuseur — et y ajoute un moteur de relais pour les seules sources que le propriétaire déclare autorisées : ses propres fichiers (« chaînes maison »), ses serveurs, un fournisseur dont les conditions permettent la rediffusion privée, un flux sous licence libre. Pour ces sources, le serveur ouvre une connexion vers la source et la sert à autant d'écrans que voulu.

# Ce que le moteur fait, et ce qu'il ne fait pas

Fait Ne fait pas
une connexion entrante par chaîne, partagée entre les lecteurs relayer une source non autorisée (refus 403, quelle que soit la demande)
copie du flux sans réencodage quand c'est du H.264 ; transcodage (VideoToolbox) sinon contourner un DRM : un flux protégé échoue à l'analyse et le dit
démarrage à la demande, arrêt après le délai d'inactivité forger des en-têtes (Referer, User-Agent) : ces flux ne sont pas relayés
tampon de lecture réglable, différé (retour en arrière) si l'enregistrement est autorisé changer d'adresse IP ou de pays : l'ingestion part du nœud, rien d'autre
mesure réelle du processeur, de la mémoire et des débits dépasser le nombre de connexions qu'une source permet
adresses de lecture temporaires, liées à la connexion du propriétaire exposer MediaMTX : il n'écoute que sur 127.0.0.1

# Architecture

text
navigateur / télé ──HTTPS──▶ Caddy (BHS64) ──wg──▶ Next.js :8670
                                                     │  /api/relay/open   session → URL temporaire
                                                     │  /relay/<jeton>/…  playlists, segments, différé
                                                     ▼
                                      MediaMTX 127.0.0.1:8672 (HLS) · 8673 (API) · 8674 (différé) · 8675 (RTSP)
                                                     ▲ publication RTSP locale
                              src/relay/ingest.ts ── FFmpeg ──▶ source autorisée (ou fichiers de la bibliothèque)
Service (brief) Fichier Rôle
SourceManager src/server/relay/sources.ts sources et leur autorisation, résolution de l'entrée d'un relais (adresse ou fichiers), contrôle de destination
RelayManager src/server/relay/relays.ts un relais par flux (ou par connexion si la source interdit le partage), limites, arrêt
StreamSessionManager src/server/relay/sessions.ts une session par lecteur, compteurs, expiration
TranscodeManager src/server/relay/transcode.ts analyse ffprobe, choix copie / transcodage, arguments FFmpeg
StreamHealthMonitor src/server/relay/health.ts (dans le worker) mesures toutes les 5 s, sessions muettes fermées, source figée relancée
RelayAccessControl src/server/relay/access.ts autorisation par source, éligibilité d'un flux, jetons de session
— src/server/relay/config.ts, mtx.ts, events.ts configuration générée de MediaMTX, client de son API, journal
— src/relay/ingest.ts processus d'ingestion lancé par MediaMTX (runOnDemand)
— src/app/relay/[...path]/route.ts seule porte d'entrée vers MediaMTX

Déroulement quand une chaîne relayée est choisie : 1. session SP TV vérifiée (POST /api/relay/open) ; 2. la source autorise-t-elle le relais ? ; 3. un relais existe-t-il déjà pour ce flux ? il est réutilisé ; 4. sinon le flux est analysé (ffprobe) et le relais préparé, limites vérifiées ; 5. une adresse /relay/<jeton>/index.m3u8 est rendue ; 6. à la première requête, MediaMTX lance l'ingestion ; 7. le worker mesure ; 8. sans lecteur pendant le délai d'inactivité, MediaMTX arrête l'ingestion (SIGINT) et FFmpeg avec elle.

Le relais publie toujours H.264 + AAC en HLS (segments MPEG-TS de 2 s), ce que lisent Safari (natif), hls.js et les applications de télévision. Tables : relays, relay_sessions, relay_events, relay_samples ; colonne sources.relay (migration 7).

# Autoriser une source

Administration → Relay Engine → « Sources et autorisation de relais ». Pour chaque source : le fondement de l'autorisation (texte obligatoire), une déclaration à cocher, puis trois options — mutualiser le flux, autoriser l'enregistrement (différé), nombre de connexions simultanées permises par la source. Retirer l'autorisation arrête les relais en cours de cette source.

Chaîne maison : Administration → Sources → « Chaîne maison (vos fichiers en boucle) ». Un film ou une série de la bibliothèque personnelle devient une chaîne continue ; un seul fichier H.264 est recopié, plusieurs fichiers sont réencodés en un format uniforme (720p).

# Réglages (Administration → Relay Engine → Réglages)

Réglage Défaut Effet
Relais simultanés 6 au-delà : « Nombre maximal de relais simultanés atteint » (vérifié à l'ouverture et au démarrage de l'ingestion)
Transcodages simultanés 2 ne compte que les relais qui réencodent la vidéo
Lecteurs simultanés 12 tous relais confondus
Tampon de lecture 12 s retard volontaire sur le direct (hls.js) et fenêtre gardée par MediaMTX
Délai d'inactivité 30 s sans lecteur : arrêt du relais (observé : 35 à 60 s après le dernier lecteur)
Débit sortant par lecteur 0 (sans limite) limitation appliquée par la route /relay
Débit vidéo des transcodages 4 500 kb/s plafond ; 3 500 en 720p, 1 600 en 480p
Durée du différé 120 min enregistrements dans ~/data/sp-tv/relay/rec, effacés par MediaMTX
Tentatives de reconnexion 8 délai croissant (1, 2, 4… 15 s)

Un changement réécrit ~/data/sp-tv/relay/mediamtx.yml, que MediaMTX recharge seul.

# Reconnexion

  • Pendant le démarrage (la source ne répond pas encore) : l'ingestion relance FFmpeg avec un délai croissant ; après le nombre maximal de tentatives le relais passe « En échec » et le lecteur reçoit l'erreur réelle.
  • En cours de lecture : quand la source tombe, MediaMTX ferme le flux et ses lecteurs (son option « toujours disponible » est incompatible avec le démarrage à la demande — vérifié, erreur de configuration). Le lecteur de SP TV rouvre alors lui-même sa session, deux fois au plus, ce qui redémarre le relais.
  • Source figée (connexion ouverte, plus aucune donnée pendant 20 s) : le moniteur termine le FFmpeg bloqué.
  • Une application de télévision qui lit une playlist M3U redemande simplement l'adresse de la chaîne.

# Sécurité

  • MediaMTX : toutes les écoutes sur 127.0.0.1 (HLS, API, différé, RTSP) ; RTMP, WebRTC, SRT, MoQ, métriques désactivés ; publication réservée à l'utilisateur ingest (secret dérivé d'APP_SECRET) depuis la boucle locale.
  • Lecture : jeton aléatoire de 256 bits dans le chemin, dont seul le SHA-256 est stocké ; valable tant que la session dure (12 h au plus, fermée après silence) et tant que la connexion SP TV qui l'a ouverte existe — se déconnecter invalide aussitôt l'adresse (401, puis 410). HTTPS par Caddy.
  • SSRF : adresse http(s) publique seulement, vérifiée sur le nom et sur chaque adresse résolue avant FFmpeg ; FFmpeg est lancé avec -protocol_whitelist http,https,tcp,tls,crypto (aucun accès aux fichiers locaux par une playlist).
  • L'adresse réelle d'une source n'apparaît dans aucune réponse, page ou journal ; le journal du relais masque toute adresse.
  • Limites : l'adresse de la source et le secret de publication sont visibles dans la liste des processus du nœud (arguments de FFmpeg) ; une redirection HTTP suivie par FFmpeg n'est pas revérifiée contre les adresses privées.

# Exploitation

bash
ssh m4mn
pm2 logs sp-tv-relay            # MediaMTX
pm2 restart sp-tv-relay         # régénère la configuration puis relance (les relais en cours s'arrêtent)
bash ~/apps/sp-tv/scripts/relay-install.sh   # (ré)installe MediaMTX v1.21.4 dans ~/opt/mediamtx, somme vérifiée
curl -s http://127.0.0.1:8673/v3/paths/list  # ce que MediaMTX diffuse

# Tests réels (2026-11-17)

Sources utilisées : trois chaînes maison faites des films Blender de la bibliothèque (CC BY) et, en local, une mire générée sur le poste. Aucun flux tiers n'a été relayé.

Scénario du brief Test Résultat
Une chaîne, un lecteur production, Firefox + WebKit iPhone + iPad : image décodée, horloge qui avance, relais « En diffusion », débit entrant mesuré réussi ; première image en 5 à 15 s (dépend de l'intervalle des images clés du fichier recopié)
Une chaîne, trois lecteurs trois sessions de navigateur distinctes sur la même chaîne 3 lus, 1 relais, 1 FFmpeg, 3 clients comptés
Plusieurs chaînes simultanées 3 chaînes en même temps en production 3 lues ; 61 % d'un cœur et 569 Mo au total (copie 360p : 3,7 % ; HEVC → H.264 240p : 14,6 % ; 3 fichiers 1080p → 720p : 39 %)
Déconnexion et reconnexion FFmpeg tué sur le nœud pendant la lecture (production) ; source HTTP coupée 14 s puis rétablie (local) lecture rétablie seule, sans message d'erreur, en 33 s environ (local) ; relais redémarré et lecture confirmée 54 s après la coupure (production)
Arrêt automatique lecteur fermé, puis interrogation de l'administration relais arrêté et 0 FFmpeg 35 à 60 s plus tard
Transcodage compatible Sintel HEVC + AC-3 (MKV) → H.264 + AAC ; série de 3 fichiers → 720p uniforme lus dans Firefox et WebKit
Authentification sans session : 401 ; jeton inconnu : 410 ; adresse valide puis déconnexion : 401 puis 410 ; source non autorisée : 403 ; autorisation sans déclaration : 400 réussi
Résistance aux erreurs réseau voir « Déconnexion et reconnexion » ; MediaMTX injoignable hors boucle locale (connexion refusée depuis l'adresse LAN) réussi
Différé −30 s depuis l'enregistrement, puis retour au direct réussi dans Firefox et WebKit (extrait servi par plages d'octets)

Suite automatisée : tests/unit/relay.test.ts (16 tests) et tests/e2e/relay.spec.ts — en production, 17 réussis et 3 exclus prévus (le Chromium de Playwright n'a pas de décodeur H.264) sur 20.

# Non vérifié

  • Le relais d'une source tierce réelle (fournisseur à API Xtream, flux public sous licence) : aucune n'a été déclarée autorisée ; le chemin « adresse réseau » n'a été exercé qu'avec une mire locale.
  • Un vrai téléphone, AirPlay, une application de télévision lisant une playlist M3U qui passe par le relais (la route est écrite et renvoie une adresse de session ; aucun appareil réel ne l'a lue).
  • Une source non partageable (un relais par connexion) et le plafond de connexions d'une source : couverts par les tests unitaires seulement.
  • La limitation du débit sortant en conditions réelles ; plus de 3 chaînes ou plus de 3 lecteurs simultanés.
  • Un fichier recopié dont les images clés sont espacées de 10 s donne des segments de 10 s (MediaMTX prévient que la durée variable peut gêner iOS) : Big Buck Bunny est dans ce cas et a été lu sous WebKit, pas sur un vrai iPhone.
Files main
Menu

Theme