Architecture
navigateur ──HTTPS──► Caddy (BHS64, MacLustr Tunnel) ──WireGuard──► nœud:8670 Next.js (sp-tv-web)
│ │ lit/écrit
│ lecture directe des flux (hls.js / natif), logos ▼
▼ SQLite $DATA_DIR/sp-tv.db (WAL)
sources publiques (diffuseurs, CDN) ▲ lit/écrit
│
iptv-org.github.io (M3U + API) ◄── sync ──┐ │
flux publics ◄── tests de disponibilité ──┼── worker (sp-tv-worker) ────┘
sites de programmes ◄── grabber iptv-org/epg ──┘Deux processus Node.js, une base SQLite, aucun autre service (pas de Redis, pas de proxy vidéo).
Pile
Next.js 16 (App Router) · React 19 · TypeScript · Tailwind CSS 4 · composants maison dans l'esprit shadcn/ui (src/components/ui.tsx)
· lucide-react · hls.js · SQLite via node:sqlite (intégré à Node ≥ 24, aucun module natif) · undici · zod · @simplewebauthn.
SQLite a été préféré à PostgreSQL : un seul utilisateur, ~10 000 chaînes, écritures rares ; la base tient dans un fichier facile à sauvegarder, et la recherche se fait en mémoire.
Arborescence
| Chemin | Contenu |
|---|---|
src/server/env.ts, db.ts |
configuration, connexion SQLite, migrations (PRAGMA user_version), paramètres, journal |
src/server/m3u.ts |
analyseur M3U / #EXTINF / #EXTVLCOPT |
src/server/sync.ts |
synchronisation du catalogue (API IPTV-org + playlists) |
src/server/checker.ts |
test d'un flux, file polie par hôte |
src/server/epg.ts |
XMLTV, grabber IPTV-org, ingestion des programmes |
src/server/catalog.ts |
index mémoire, recherche floue, favoris, listes, masquées, historique, programmes |
src/server/auth.ts, ssrf.ts |
mots de passe, sessions, anti-force brute ; garde SSRF et safeFetch |
src/server/api/*.ts |
API REST (/api/...), un petit routeur, routes privées par défaut |
src/worker/index.ts |
worker : file de tâches, planificateur, surveillance continue |
src/app/(tv)/… |
pages Accueil, Chaînes, Guide TV, Favoris, Admin (toutes derrière une session) |
src/components/player.tsx, shell.tsx, ui.tsx |
lecteur global, navigation + navigation directionnelle, cartes |
scripts/ |
bootstrap, set-password, run-job, backup.sh |
Modèle de données (résumé)
sources(playlists M3U, intégrées ou ajoutées) →streams(une ligne par URL, unique) →channels(identifiant IPTV-orgNom.cc, oux-<nom>pour une entrée sanstvg-id). Statut de test porté par le flux :status,http_status,check_error,checked_at,cors,content_type, plus le résultat réel de lecture dans le navigateur (play_ok,play_at).categories,countries,languages,guides(sites de programmes par chaîne) : copies de l'API IPTV-org.- État utilisateur, jamais touché par une synchronisation :
lists,list_items(favoris = liste n° 1),hidden,history,settings. programs(guide),epg_state(site retenu par chaîne),epg_sources(XMLTV ajoutés).sessions,passkeys,login_attempts;jobs,logs.
Synchronisation (sync.ts)
- Télécharge l'API IPTV-org (
channels,feeds,logos,guides,blocklist,categories,countries,languages). Une erreur ici est signalée mais n'empêche pas l'import des playlists (les métadonnées existantes sont gardées). - Télécharge et analyse chaque source active ; écarte les protocoles non http(s), les chaînes de la liste de blocage IPTV-org et les chaînes marquées NSFW.
- Dédoublonne par URL (la playlist principale d'abord) ; regroupe les flux par chaîne (
tvg-idavant@). - Associe nom officiel, pays, catégories, langues (du « feed » du flux), logo (
tvg-logo, sinon API). - Écrit le tout dans une transaction. Les flux disparus d'une source synchronisée avec succès sont retirés ; une source en échec garde les siens. Une chaîne sans flux n'est conservée que si l'utilisateur y tient (favori, masquée, historique).
- Publie une nouvelle
catalog_version: le processus web reconstruit son index (≈ 50 ms).
Planification : toutes les sync_interval_hours (24 h par défaut) ; bouton « Synchroniser maintenant » = tâche en file.
Disponibilité (checker.ts)
Un test = au plus deux petites requêtes GET (playlist, puis première playlist de variante si c'est une playlist maître) ;
aucun segment vidéo n'est téléchargé. Sont notés : code HTTP, raison lisible, présence de CORS, type de contenu, latence.
Politesse : check_concurrency tests simultanés au total (6), un seul à la fois par hôte, check_host_delay_ms (1,5 s)
entre deux tests d'un même hôte, délai d'expiration 10 s. Ordre : favoris et chaînes regardées (toutes les 6 h), flux jamais
testés (pays du guide d'abord), puis le reste toutes les 24 h. Un catalogue complet prend quelques heures.
Guide TV (epg.ts)
IPTV-org ne publie pas de fichier de guide : il publie la correspondance chaîne → site de programmes et un outil de
collecte. Le worker installe cet outil ($DATA_DIR/epg-grabber, mis à jour chaque semaine), lui passe la liste des chaînes
à couvrir (favoris, chaînes regardées, puis pays de epg_countries, plafonnée par epg_max_channels), et importe le XMLTV
produit. Si un site ne renvoie rien pour une chaîne, le site suivant est essayé à la collecte suivante. Les sources XMLTV
ajoutées dans l'admin sont importées de la même façon. Aucun programme n'est jamais généré.
Lecteur (player.tsx)
Un seul élément <video> vit dans la coquille de l'application : changer de page ou de chaîne ne recharge rien.
HLS : lecteur natif si le navigateur le propose (Safari, iOS — AirPlay), sinon hls.js. Les flux d'une chaîne sont essayés
dans l'ordre (déjà lu ici, disponible, HTTPS, sans en-têtes exigés, CORS, meilleure qualité) ; en cas d'échec fatal la
source suivante est tentée, puis un panneau explique la cause (contenu mixte, CORS, HTTP 403/451, DASH, hors ligne…).
Le lecteur signale au serveur ce qui s'est réellement passé (/api/channels/:id/played), ce qui alimente l'historique.
Recherche
Index en mémoire de toutes les chaînes ; par mot de la requête : égalité, préfixe, sous-chaîne, puis distance de Damerau-Levenshtein bornée (1 à 3 selon la longueur). Mesuré : 1 à 10 ms sur 10 368 chaînes.
Films et séries (vod.ts, titles.ts)
Import hebdomadaire (tâche vod) :
- Wikidata (SPARQL) : œuvres de type film / série ayant un statut « domaine public » ou une licence libre et un identifiant Internet Archive ou une vidéo Wikimedia Commons. Requêtes volontairement légères (le point d'accès public coupe à 60 s) : identifiants d'abord, métadonnées par lots de 60, libellés de droits à part.
- Internet Archive (
/metadata/{id}, 4 requêtes/s au plus) : l'élément doit exister, ne pas être restreint, correspondre au film (mots significatifs du titre + année à ± 2 ans) et contenir un MP4 H.264 ; la meilleure déclinaison est retenue et les fichiers de sous-titres voisins sont rattachés. Sinon, vidéo WebM de Commons. Sinon le titre est écarté : un titre sans source lisible n'est jamais listé. - Wikipédia : synopsis en français, sinon en anglais (1 lot de 20 par seconde, arrêt poli en cas de limitation ; les manquants sont redemandés à l'import suivant).
- Séries : fichiers multiples d'un même élément (numérotation
S01E02,1x02, « Episode 3 », « Chapter 4 ») ou éléments frères numérotés d'un feuilleton.
Tables : titles (statut et justification des droits, source, lien de preuve), episodes, media (URL distante ou chemin
local, conteneur, codecs, sous-titres, pistes audio, mode de lecture), progress (position, terminé, nombre de lectures),
title_favs, vod_sources. titles.ts tient un index mémoire des titres ayant au moins un média et fournit recherche,
rangées, fiche, point de reprise, « continuer à regarder ». Les rangées « populaires » n'utilisent que les lectures
réellement enregistrées par l'application.
Bibliothèque personnelle (library.ts)
- Dossiers déclarés dans l'admin, obligatoirement sous un emplacement autorisé (
LIBRARY_ROOTS, par défaut~/media,~/nas_clustr,~/nas2_clustr,/Volumes), chemins réels résolus, dossiers cachés refusés. - Analyse (toutes les 15 min et à la demande) : parcours récursif,
ffprobesur les fichiers nouveaux ou modifiés (taille + date), reconnaissance du nom (Titre (Année),Série S01E02 Nom), recherche Wikidata pour l'affiche, le synopsis et l'équipe, miniature parffmpegà défaut d'affiche. Un fichier disparu est retiré ; un dossier injoignable (NAS éteint) est signalé et rien n'est supprimé. - Mode de lecture par fichier :
direct(MP4 H.264/AAC, WebM VP9/AV1),direct-hevc(HEVChvc1: direct sur Safari),remux(codecs lisibles, conteneur à changer : copie de flux vers HLS),transcode(réencodage H.264 parh264_videotoolbox, AAC stéréo). - Conversion à la volée :
GET /api/media/:id/hls/index.m3u8lanceffmpeg(deux conversions simultanées au plus) vers$DATA_DIR/transcode/<id>-a<piste>/; la playlist est servie pendant qu'elle grandit, puis comme VOD une fois terminée ; cache borné (transcode_cache_gb, éviction des plus anciens). - Service des fichiers :
GET /api/media/:id/file(requêtesRange), sous-titres convertis en WebVTT, miniatures — toujours par identifiant numérique, toujours derrière la session, après vérification que le fichier est encore dans son dossier.
Lecteur à la demande (vod-player.tsx)
Lecture directe (URL distante ou route de fichier) ou HLS (natif Safari, hls.js ailleurs) selon le mode ; repli automatique
sur la conversion si le navigateur refuse le fichier d'origine. Reprise à la dernière position, ±10 s, barre de
progression, vitesse, sous-titres (<track> WebVTT), piste audio (nouvelle déclinaison HLS), épisode suivant avec
compte à rebours, position enregistrée toutes les 10 s, à la pause, au déplacement et à la fermeture.
Recherche unifiée
GET /api/search interroge l'index des chaînes et celui des titres (mêmes règles : exact, préfixe, sous-chaîne, puis
distance d'édition bornée ; noms de réalisateurs et d'interprètes compris pour les titres) et les noms d'épisodes.
Playlists M3U personnelles (playlists.ts, app/m3u/[file]/route.ts)
Une playlist est une sélection enregistrée (listes de favoris, pays, catégories, langues, options). Son contenu est
recalculé à chaque requête depuis le catalogue : favoris d'abord (dans leur ordre), puis chaînes canadiennes francophones,
canadiennes, francophones, autres ; pour chaque chaîne, le meilleur flux selon le dernier test (ou jusqu'à quatre). Les
contraintes propres aux navigateurs (HTTP, CORS) ne comptent pas ici ; un Referer ou un User-Agent exigé est écrit dans la
playlist (http-referrer, http-user-agent, #EXTVLCOPT). Le guide XMLTV du même jeton reprend les programmes réels déjà
en base. Rien n'est relayé : l'appareil lit chaque flux chez son diffuseur.
Moteur universel de sources (engine.ts, connectors/)
Toute entrée de contenu passe par un connecteur qui a le même contrat : se décrire (champs du formulaire, déclaration d'autorisation), tester une configuration sans rien enregistrer, importer. Ajouter une source se fait dans Admin → Sources, jamais dans le code.
| Famille | Connecteurs | Aboutissement |
|---|---|---|
| Télévision en direct | m3u-url, m3u-file (fichier importé), stream (une adresse HLS ou MPEG-DASH), xtream (fournisseur autorisé), listes intégrées |
même chaîne de traitement (sync.ts) : filtres, dédoublonnage par adresse, regroupement des variantes, tests de disponibilité |
| Guide | xmltv, guide du fournisseur |
programs |
| Films et séries | wikidata, onf, arte, nasa, jellyfin, xtream |
titles / episodes / media |
| Bibliothèque | dossiers locaux ou NAS montés | idem, fichiers servis par ce serveur |
engine.ts est le point d'entrée unique : TYPES (catalogue des connecteurs), test, create, remove, setEnabled,
setPriority, instances() (vue unifiée avec métriques réelles), loadLive (entrées d'une source en direct, quel que soit
son connecteur), imports VOD, refreshSources() (tâche quotidienne sources : ARTE, NASA, Jellyfin, fournisseurs).
Le stockage reste dans les tables existantes (sources, epg_sources, vod_sources, library_dirs), enrichies de
config, secret (chiffré), content, priority.
Mesure de l'apport d'une source (Admin → Sources) : entrées lues, flux retenus après dédoublonnage, chaînes, chaînes que cette source est seule à fournir, et parmi elles celles qui ont répondu au dernier test.
Méthodes de lecture identifiées par média : HLS (natif ou hls.js), MPEG-DASH non protégé (dash.js), fichier direct, conversion locale (ffmpeg), lecteur officiel intégré (ONF, ARTE), redirection vers un fournisseur ou vers Jellyfin.
Adresses de fournisseurs
Un flux de fournisseur ou un média Jellyfin est stocké comme une référence opaque (provider://live/12/101.m3u8,
provider://jf/5/<id>). L'adresse réelle — qui contient souvent les identifiants — n'est reconstruite que sur le serveur,
au moment de lire ou de tester, et envoyée au lecteur comme une redirection (/api/provider/...). Comme hls.js ne peut
suivre une redirection vers une autre origine qu'en requête sans cookie, ces deux routes acceptent aussi un ticket signé de
12 heures, propre au média, délivré avec les informations de lecture à une session ouverte.
ARTE et NASA
- ARTE : pages thématiques de l'API d'ARTE (documentaires, cinéma, séries, sciences, histoire, voyages, société,
culture), puis pour chaque programme la configuration de son lecteur : intégration autorisée (
allowEmbed), pas de restriction géographique pour ce serveur, droits en cours. Lecture dans le lecteur d'ARTE intégré (https://www.arte.tv/embeds/fr/{id}). Chaque titre porte sa date de fin de droits (titles.expires_at) ; il est retiré à l'échéance (contrôle toutes les 30 s par le planificateur) ou dès qu'il sort de l'offre. - NASA : bibliothèque
images-api.nasa.govpar thèmes (Apollo, Artemis, Lune, Mars, Hubble, James Webb, station spatiale…), fichiers MP4 lus directement, sous-titres quand ils existent ; les fichiers bruts sans titre lisible et les notices mentionnant des droits de tiers sont écartés ; 500 nouveautés au plus par jour.
Moteur de relais (relay/)
Six services (SourceManager, RelayManager, StreamSessionManager, TranscodeManager, StreamHealthMonitor,
RelayAccessControl), MediaMTX en boucle locale, FFmpeg à la demande. Décrit dans RELAY.md. La lecture directe reste
la règle ; le relais ne sert que les sources déclarées autorisées.
Choix d'architecture maintenus (et pourquoi)
- SQLite plutôt que PostgreSQL : un utilisateur, une machine, ≈ 12 000 chaînes et ≈ 7 000 titres ; recherche en
mémoire mesurée entre 1 et 40 ms ; sauvegarde = un fichier. PostgreSQL n'apporterait rien de mesurable ici et ajouterait
un service à exploiter. La couche d'accès est isolée dans
db.tssi le besoin changeait. - Pas de Redis : pas de cache partagé entre machines à tenir ; l'index mémoire est reconstruit en ≈ 50 ms.
- Jellyfin : pris en charge comme connecteur (testé contre un vrai serveur Jellyfin 12.4), mais non installé sur le cluster : la bibliothèque intégrée (ffprobe + ffmpeg/VideoToolbox) couvre déjà l'indexation et la conversion. Installer Jellyfin reste possible : il suffira d'ajouter son adresse dans Admin → Sources.