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