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
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'utilisateuringest(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
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 diffuseTests 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.