Repository Public
1<div align="center">23# 📺 SP TV45**Télévision personnelle auto-hébergée — chaînes en direct, films, séries, documentaires et bibliothèque privée dans le navigateur. La vidéo va directement du diffuseur à l'appareil ; un moteur de relais (MediaMTX + FFmpeg) sert en plus les sources que vous déclarez autorisées — voir `docs/RELAY.md`.**67[](https://tv.spboucher.ai)891011121314151617181920212223242526272829[](https://git.spboucher.ai/sp-tv/commits)30[](https://git.spboucher.ai/sp-tv/commits)31[](https://git.spboucher.ai/sp-tv/insights)32[](https://git.spboucher.ai/sp-tv)33[](https://git.spboucher.ai/sp-tv/insights)34[](https://git.spboucher.ai/sp-tv)35[](https://git.spboucher.ai/sp-tv/branches)36[](https://git.spboucher.ai/sp-tv/tags)37[](https://git.spboucher.ai/sp-tv)38394041424344454647484950515253545556</div>5758---5960## Sommaire6162- [Présentation](#-présentation)63- [Fonctionnalités](#-fonctionnalités)64- [Architecture](#-architecture)65- [Pile technique](#-pile-technique)66- [Arborescence](#-arborescence)67- [Démarrage rapide (développement)](#-démarrage-rapide-développement)68- [Commandes](#-commandes)69- [Configuration](#-configuration)70- [Pages de l'application](#-pages-de-lapplication)71- [API REST](#-api-rest)72- [Moteur universel de sources](#-moteur-universel-de-sources)73- [Modèle de données](#-modèle-de-données)74- [Worker et tâches planifiées](#-worker-et-tâches-planifiées)75- [Tests et qualité](#-tests-et-qualité)76- [Déploiement (MacLustr, `mld`)](#-déploiement-maclustr-mld)77- [Sécurité](#-sécurité)78- [Limites à connaître (pas de simulation)](#-limites-à-connaître-pas-de-simulation)79- [Historique des versions et état](#-historique-des-versions-et-état)80- [Documentation](#-documentation)81- [Auteur et licence](#-auteur-et-licence)8283---8485## 🎯 Présentation8687Télévision personnelle auto-hébergée — **https://tv.spboucher.ai** — pour consulter et regarder, dans le navigateur, les88chaînes publiques référencées par [IPTV-org](https://github.com/iptv-org/iptv). Usage strictement personnel et privé :89aucune revente, aucune redistribution, aucun relais vidéo.9091L'application est à **utilisateur unique** : aucune page ni route d'API (hors connexion, `/api/health` et les adresses de92playlists à jeton) ne répond sans session valide. Elle tient en **deux processus Node.js et une base SQLite** — pas de93Redis, pas de PostgreSQL, pas de proxy vidéo : le navigateur lit chaque flux directement à sa source.9495## ✨ Fonctionnalités9697- **TV en direct** : catalogue agrégé de plusieurs sources vérifiées (IPTV-org, Free-TV, Nexonic, Pluto TV et Samsung TV Plus98 Canada/France), doublons regroupés, plusieurs flux de secours par chaîne, chaînes canadiennes et francophones en tête,99 synchronisation quotidienne. Détail et sources refusées : [SOURCES.md](docs/SOURCES.md).100- **Moteur de sources universel** : chaque source est un connecteur (playlist M3U par adresse ou fichier, flux HLS/DASH,101 guide XMLTV, fournisseur autorisé à API compatible Xtream, Jellyfin, catalogues libres) ajouté, testé, priorisé et mesuré102 depuis Admin → Sources, sans toucher au code ; identifiants chiffrés.103- **Films, séries, documentaires** : œuvres du domaine public ou sous licence libre (droits documentés par Wikidata), lues104 directement sur Internet Archive ou Wikimedia Commons ; ONF et ARTE dans leur lecteur officiel intégré ; vidéos de la NASA ;105 fiche avec affiche, synopsis, équipe, statut des droits.106- **Ma bibliothèque** : dossiers locaux ou partages NAS montés, analysés automatiquement (ffprobe), reconnus (affiche,107 synopsis), lus tels quels ou convertis à la volée seulement si nécessaire (ffmpeg + VideoToolbox).108- **Lecteurs** : direct (hls.js / natif Safari / dash.js pour le MPEG-DASH non protégé, AirPlay, zapping, bascule entre sources) et à la demande (reprise, ±10 s,109 vitesse, sous-titres, pistes audio, épisode suivant, marquage « vu »).110- **Recherche unifiée** tolérante aux fautes : chaînes, films, séries, épisodes, bibliothèque ; filtres type, genre, année,111 langue, pays, disponibilité, source.112- **Playlists M3U personnelles** pour les applications IPTV des téléviseurs (TiviMate, IPTV Smarters, VLC, Kodi…) : sélection113 par favoris, pays, catégories, langues ; adresse secrète révocable ; guide XMLTV associé ; mise à jour automatique.114- Surveillance polie de la disponibilité des flux, guide TV réel, favoris et listes, « Continuer à regarder ».115- Accès privé : mot de passe + clés d'accès (passkeys), sessions HttpOnly/Secure, anti-force brute ; les fichiers116 personnels ne sont servis qu'à une session ouverte.117- Interface pensée d'abord pour le téléphone, utilisable à la télécommande / au clavier, PWA installable.118119<details>120<summary><b>Détail par domaine</b></summary>121122| Domaine | Ce que fait le code | Module |123|---|---|---|124| Analyse M3U | `#EXTINF`, `#EXTVLCOPT`, `tvg-id`, logos, groupes, virgules entre guillemets | `src/server/m3u.ts` |125| Synchronisation | API IPTV-org + playlists, filtres (protocoles non http(s), liste de blocage, NSFW), dédoublonnage par URL, une seule transaction | `src/server/sync.ts` |126| Disponibilité | au plus deux petites requêtes GET par test, aucun segment téléchargé, un seul test à la fois par hôte | `src/server/checker.ts` |127| Guide TV | grabber IPTV-org installé dans `$DATA_DIR/epg-grabber`, import XMLTV, aucun programme généré | `src/server/epg.ts` |128| Recherche | index en mémoire ; égalité, préfixe, sous-chaîne, puis distance de Damerau-Levenshtein bornée | `src/server/catalog.ts`, `titles.ts` |129| Films et séries | Wikidata (SPARQL) → Internet Archive / Wikimedia Commons → synopsis Wikipédia ; un titre sans source lisible n'est jamais listé | `src/server/vod.ts` |130| ONF, ARTE, NASA | lecteurs officiels intégrés (ONF, ARTE), MP4 directs (NASA), droits datés pour ARTE | `src/server/onf.ts`, `connectors/arte.ts`, `connectors/nasa.ts` |131| Bibliothèque | parcours récursif, `ffprobe`, modes `direct` / `direct-hevc` / `remux` / `transcode`, HLS à la volée, cache borné | `src/server/library.ts` |132| Playlists M3U | contenu recalculé à chaque requête, jeton révocable, guide XMLTV du même jeton | `src/server/playlists.ts`, `src/app/m3u/` |133| Enrichissement TMDB | affiches et synopsis français si une clé est fournie (jamais pour la vidéo) | `src/server/tmdb.ts` |134| Chiffrement des identifiants | AES-256-GCM, clé dérivée de `APP_SECRET` | `src/server/secrets.ts` |135| Garde SSRF | contrôle dans la résolution DNS de la connexion, redirections suivies à la main | `src/server/ssrf.ts` |136137</details>138139## 🏗 Architecture140141```mermaid142flowchart TB143 subgraph Client["Navigateur / téléviseur"]144 UI["Interface Next.js (PWA)"]145 PL["Lecteurs<br/>hls.js · HLS natif · dash.js"]146 APP["Application IPTV<br/>(playlist M3U à jeton)"]147 end148 subgraph GW["Passerelle MacLustr Tunnel"]149 CADDY["Caddy · HTTPS"]150 end151 subgraph NODE["Nœud m4mn"]152 WEB["sp-tv-web<br/>next start · port 8670"]153 WRK["sp-tv-worker<br/>tsx src/worker/index.ts"]154 BKP["sp-tv-backup<br/>cron 03:50"]155 DB[("SQLite · WAL<br/>$DATA_DIR/sp-tv.db")]156 FF["ffprobe / ffmpeg<br/>VideoToolbox"]157 JF["Jellyfin (facultatif)<br/>/jellyfin"]158 end159 subgraph EXT["Sources publiques"]160 IPTV["IPTV-org · Free-TV · Nexonic<br/>Pluto TV · Samsung TV Plus"]161 VOD["Wikidata · Internet Archive<br/>Wikimedia Commons · Wikipédia"]162 OFF["ONF · ARTE · NASA"]163 BRD["Diffuseurs et CDN"]164 end165 UI -->|HTTPS| CADDY -->|WireGuard| WEB166 APP -->|"/m3u/<jeton>.m3u"| CADDY167 WEB <--> DB168 WRK <--> DB169 BKP --> DB170 WEB --> FF171 WEB -. réécriture .-> JF172 WRK -->|sync| IPTV173 WRK -->|import| VOD174 WRK -->|import| OFF175 WRK -->|tests de disponibilité| BRD176 PL ==>|"lecture directe, sans relais"| BRD177```178179Le processus web et le worker ne se parlent **que par la base SQLite** : le worker publie une nouvelle `catalog_version`180et le processus web reconstruit son index mémoire (≈ 50 ms). Détail : [ARCHITECTURE.md](docs/ARCHITECTURE.md).181182## 🧰 Pile technique183184| Rôle | Technologie | Version (lockfile) |185|---|---|---|186| Framework web | Next.js (App Router) | 16.4.6 |187| Interface | React / React DOM | 19.3.1 |188| Langage | TypeScript | 6.0.3 |189| Styles | Tailwind CSS (`@tailwindcss/postcss`) | 4.3.5 |190| Composants | composants maison dans l'esprit shadcn/ui (`class-variance-authority`, `clsx`, `tailwind-merge`) | — |191| Icônes | lucide-react | 1.73.0 |192| Lecture HLS | hls.js | 1.7.4 |193| Lecture MPEG-DASH | dash.js (`dashjs`) | 5.3.0 |194| Base de données | SQLite via `node:sqlite` (intégré à Node ≥ 24, aucun module natif), mode WAL | — |195| Requêtes sortantes | undici | 8.12.4 |196| Validation | zod | 4.6.7 |197| Clés d'accès | `@simplewebauthn/server` / `@simplewebauthn/browser` | 14.1.0 / ^14.0.0 |198| Exécution des scripts et du worker | tsx | 4.23.15 |199| Vidéo locale | ffmpeg + ffprobe (Homebrew), `h264_videotoolbox` | — |200| Tests unitaires | Vitest | 5.1.0 |201| Tests de bout en bout | Playwright | 1.65.1 |202| Gestionnaire de paquets | pnpm | — |203| Gestionnaire de processus | PM2 | — |204205## 🗂 Arborescence206207```text208sp-tv/209├── src/210│ ├── app/211│ │ ├── (tv)/ # 16 pages derrière une session (accueil, chaînes, films, guide, admin…)212│ │ ├── connexion/ # page de connexion (mot de passe, clé d'accès)213│ │ ├── api/[...path]/route.ts # point d'entrée unique de l'API REST → src/server/api214│ │ ├── m3u/[file]/ # playlists M3U et guides XMLTV à jeton (seule partie lisible sans session)215│ │ ├── manifest.ts # manifeste PWA216│ │ └── layout.tsx, globals.css217│ ├── components/218│ │ ├── player.tsx # lecteur en direct global (un seul <video>)219│ │ ├── vod-player.tsx # lecteur à la demande220│ │ ├── shell.tsx # navigation + navigation directionnelle (télécommande / clavier)221│ │ ├── engine-admin.tsx # Admin → Sources222│ │ └── ui.tsx, ui-static.ts, vod-section.tsx223│ ├── lib/ # client HTTP du navigateur, liens vers les services officiels224│ ├── proxy.ts # premier contrôle d'accès : sans cookie → /connexion225│ ├── server/226│ │ ├── api/ # 71 routes : auth, catalog, admin, vod, engine + routeur (core.ts)227│ │ ├── connectors/ # arte, jellyfin, nasa, xtream228│ │ ├── db.ts, env.ts # SQLite, migrations (PRAGMA user_version), paramètres, journal229│ │ ├── sync.ts, m3u.ts # synchronisation du catalogue, analyseur M3U230│ │ ├── checker.ts, epg.ts # disponibilité des flux, guide TV231│ │ ├── catalog.ts, titles.ts # index mémoire, recherche floue232│ │ ├── vod.ts, onf.ts, tmdb.ts, library.ts233│ │ ├── engine.ts # moteur universel de sources234│ │ ├── playlists.ts # playlists M3U personnelles235│ │ └── auth.ts, secrets.ts, ssrf.ts, jobs.ts236│ └── worker/index.ts # worker : file de tâches, planificateur, surveillance continue237├── scripts/ # bootstrap.ts, set-password.ts, run-job.ts, backup.sh238├── sources/official-verified.m3u # sélection vérifiée de 112 flux de diffuseurs officiels239├── tests/240│ ├── unit/ # 5 fichiers Vitest241│ └── e2e/ # 3 fichiers Playwright242├── docs/ # 9 documents (architecture, déploiement, sécurité, sources, tests, recherches)243├── public/ # icônes PWA, robots.txt, sw.js244└── next.config.ts, playwright.config.ts, vitest.config.ts, pnpm-workspace.yaml, .env.example245```246247## 🚀 Démarrage rapide (développement)248249```bash250pnpm install251cp .env.example .env # en dev, les valeurs par défaut suffisent (DATA_DIR=./data, http://localhost:8670)252pnpm bootstrap # crée la base et écrit un mot de passe initial dans data/initial-password.txt253pnpm sync # première importation IPTV-org (≈ 1 s)254pnpm dev # http://localhost:8670 (identifiant : sp)255pnpm worker # dans un 2e terminal : synchronisation planifiée, vérification des flux, guide256```257258Prérequis : Node.js ≥ 24 (`node:sqlite`), pnpm ; `ffmpeg` et `ffprobe` pour la bibliothèque personnelle ; `git` et `npm`259pour le grabber du guide TV ; `/usr/bin/sqlite3` pour la sauvegarde.260261## ⌨️ Commandes262263| Commande | Rôle |264|---|---|265| `pnpm build` / `pnpm start` | build de production / serveur web (port 8670) |266| `pnpm worker` | worker d'arrière-plan |267| `pnpm sync` | synchronisation immédiate, au premier plan |268| `node_modules/.bin/tsx scripts/run-job.ts epg` | mise à jour du guide TV au premier plan |269| `node_modules/.bin/tsx scripts/run-job.ts vod` | import des films et séries libres (≈ 25 min la première fois) |270| `node_modules/.bin/tsx scripts/run-job.ts library` | analyse immédiate des dossiers de la bibliothèque |271| `node_modules/.bin/tsx scripts/run-job.ts check 100` | teste 100 flux et affiche chaque résultat |272| `node_modules/.bin/tsx scripts/run-job.ts sources` | actualisation des sources (ARTE, NASA, Jellyfin, fournisseurs) |273| `node_modules/.bin/tsx scripts/run-job.ts tmdb` | passe d'enrichissement TMDB |274| `node_modules/.bin/tsx scripts/run-job.ts onf` | import ONF |275| `pnpm set-password` | génère (ou définit avec `SPTV_PASSWORD=…`) le mot de passe et ferme toutes les sessions |276| `scripts/backup.sh` | sauvegarde de la base |277| `pnpm typecheck` | vérification des types (`tsc --noEmit`) |278| `pnpm test` | tests unitaires et d'intégration (Vitest) |279| `SPTV_URL=… SPTV_PASSWORD=… node_modules/.bin/playwright test` | tests de bout en bout |280281## ⚙️ Configuration282283Copier `.env.example` vers `.env` (mode `600`). **Aucune valeur réelle ne doit entrer dans Git.**284285| Variable | Rôle | Défaut |286|---|---|---|287| `APP_URL` | origine publique exacte (HTTPS) : cookies, contrôle d'origine, clés d'accès (WebAuthn) | `http://localhost:8670` en développement ; obligatoire en production |288| `APP_SECRET` | clé HMAC (≥ 32 caractères) : sessions, défis WebAuthn, chiffrement des identifiants de sources | valeur de développement ; obligatoire en production |289| `DATA_DIR` | dossier des données : base `sp-tv.db`, grabber EPG, fichiers de travail | `./data` en développement ; obligatoire en production |290| `BACKUP_DIR` | dossier des sauvegardes quotidiennes (`scripts/backup.sh`) | `~/backups/sp-tv` |291| `OWNER_USERNAME` | identifiant de connexion du propriétaire | `sp` |292| `DATABASE_PATH` | chemin explicite de la base (facultatif) | `$DATA_DIR/sp-tv.db` |293| `JELLYFIN_PROXY` | serveur Jellyfin local publié sous `/jellyfin` du site, derrière la session ; lu au `next build` | non défini |294| `TMDB_API_KEY` | clé TMDB v3 facultative : affiches et synopsis français (jamais pour la vidéo) | non définie |295| `LIBRARY_ROOTS` | racines absolues (séparées par `:`) sous lesquelles un dossier de bibliothèque peut être déclaré | voir [ARCHITECTURE.md](docs/ARCHITECTURE.md) |296| `SPTV_URL`, `SPTV_USERNAME`, `SPTV_PASSWORD` | cible et identifiants des tests de bout en bout ; `SPTV_PASSWORD` sert aussi à `pnpm set-password` | `http://localhost:8670` pour `SPTV_URL` |297| `SPTV_ALLOW_PRIVATE_HOSTS` | tests automatisés seulement : laisse le garde SSRF atteindre des cibles de bouclage ; refusé en production | désactivé |298299<details>300<summary><b>Paramètres réglables depuis l'admin (table <code>settings</code>, valeurs par défaut)</b></summary>301302| Paramètre | Défaut | Rôle |303|---|---|---|304| `sync_interval_hours` | 24 | intervalle de synchronisation du catalogue |305| `check_enabled` | 1 | surveillance de disponibilité active |306| `check_concurrency` | 6 | tests simultanés au total |307| `check_host_delay_ms` | 1500 | pause entre deux tests d'un même hôte |308| `check_timeout_ms` | 10000 | délai d'expiration d'un test |309| `check_recheck_hours` | 24 | nouveau test de l'ensemble du catalogue |310| `check_priority_hours` | 6 | nouveau test des favoris et chaînes regardées |311| `epg_enabled` | 1 | guide TV actif |312| `epg_interval_hours` | 12 | intervalle de collecte du guide |313| `epg_countries` | CA,FR | pays couverts en priorité par le guide |314| `epg_max_channels` | 250 | plafond de chaînes couvertes par le guide |315| `epg_days` | 2 | jours de programmes collectés |316| `session_days` | 60 | durée d'une session |317| `vod_interval_hours` | 168 | import des films et séries libres |318| `library_interval_minutes` | 15 | analyse de la bibliothèque |319| `transcode_cache_gb` | 30 | taille maximale du cache de conversion |320| `sources_interval_hours` | 24 | actualisation ARTE, NASA, Jellyfin, fournisseurs |321| `auto_resume`, `premium_filter` | 1 | reprise automatique ; filtre des chaînes payantes présumées |322323</details>324325## 🧭 Pages de l'application32632717 pages (`page.tsx`) : 16 derrière une session dans `src/app/(tv)/`, plus `/connexion`.328329| Route | Page | Route | Page |330|---|---|---|---|331| `/` | Accueil | `/favoris` | Favoris et listes |332| `/chaines` | TV en direct | `/continuer` | Continuer à regarder |333| `/sports` | Sports | `/guide` | Guide TV |334| `/films` | Films | `/playlists` | Playlists M3U personnelles |335| `/series` | Séries | `/recherche` | Recherche unifiée |336| `/documentaires` | Documentaires | `/parametres` | Paramètres |337| `/bibliotheque` | Ma bibliothèque | `/admin` | Administration |338| `/catalogue` | Catalogue | `/titre/[id]` | Fiche d'un titre |339| `/connexion` | Connexion | | |340341Hors pages : `/m3u/<jeton>.m3u` et `/m3u/<jeton>.xml` (playlist et guide XMLTV d'une playlist personnelle),342`/manifest.webmanifest`, `/sw.js`.343344## 🔌 API REST345346Un petit routeur maison (`src/server/api/core.ts`) sert **71 routes** sous `/api`. Les routes sont **privées par347défaut** ; toute requête non-GET doit porter l'en-tête `Origin` de l'application ; les corps sont validés par zod.348349| Module | Routes | Contenu |350|---|---|---|351| `auth.ts` | 10 | connexion, déconnexion, clés d'accès, mot de passe, sessions |352| `catalog.ts` | 25 | santé, chaînes, accueil, favoris, listes, masquées, historique, guide, playlists |353| `vod.ts` | 20 | titres, lecture, progression, « Ma liste », recherche, médias, bibliothèque |354| `admin.ts` | 9 | aperçu, tâches, sources, guides, paramètres, journaux |355| `engine.ts` | 7 | moteur de sources, redirections vers un fournisseur |356357Routes publiques (sans session) : `GET /api/health`, `POST /api/auth/login`, `POST /api/auth/passkey/options`,358`POST /api/auth/passkey/verify` ; `GET /api/provider/stream/:id` et `GET /api/provider/media/:id` acceptent une session359**ou** un ticket signé de 12 heures propre au média.360361<details>362<summary><b>Liste complète des 71 routes</b></summary>363364**Authentification (`auth.ts`)**365366| Méthode | Route |367|---|---|368| POST | `/api/auth/login` |369| POST | `/api/auth/logout` |370| POST | `/api/auth/passkey/options` |371| POST | `/api/auth/passkey/verify` |372| POST | `/api/auth/passkey/register-options` |373| POST | `/api/auth/passkey/register` |374| DELETE | `/api/auth/passkey/:id` |375| GET | `/api/auth/security` |376| POST | `/api/auth/password` |377| DELETE | `/api/auth/sessions/:id` |378379**Catalogue en direct (`catalog.ts`)**380381| Méthode | Route |382|---|---|383| GET | `/api/health` |384| GET | `/api/channels` |385| GET | `/api/meta` |386| GET | `/api/home` |387| GET | `/api/channels/:id` |388| POST | `/api/channels/:id/check` |389| POST | `/api/channels/:id/played` |390| POST | `/api/favorites` |391| POST | `/api/hidden` |392| GET | `/api/lists` |393| GET | `/api/lists/:id` |394| POST | `/api/lists` |395| PATCH | `/api/lists/:id` |396| DELETE | `/api/lists/:id` |397| PUT | `/api/lists` |398| GET | `/api/now` |399| GET | `/api/history` |400| DELETE | `/api/history` |401| GET | `/api/guide` |402| GET | `/api/playlists` |403| POST | `/api/playlists/preview` |404| POST | `/api/playlists` |405| PATCH | `/api/playlists/:id` |406| POST | `/api/playlists/:id/rotate` |407| DELETE | `/api/playlists/:id` |408409**Films, séries, bibliothèque (`vod.ts`)**410411| Méthode | Route |412|---|---|413| GET | `/api/titles` |414| GET | `/api/titles/facets` |415| GET | `/api/titles/:id` |416| GET | `/api/play/:id` |417| POST | `/api/progress` |418| POST | `/api/watched` |419| POST | `/api/title-favs` |420| GET | `/api/title-favs` |421| GET | `/api/continue` |422| GET | `/api/vod/home` |423| GET | `/api/search` |424| GET | `/api/media/:id/file` |425| GET | `/api/media/:id/thumb` |426| GET | `/api/media/:id/hls/:file` |427| GET | `/api/media/:id/subs/:n` |428| GET | `/api/admin/vod` |429| PATCH | `/api/admin/vod-sources/:id` |430| GET | `/api/admin/library` |431| POST | `/api/admin/library` |432| DELETE | `/api/admin/library/:id` |433434**Administration (`admin.ts`)**435436| Méthode | Route |437|---|---|438| GET | `/api/admin/overview` |439| POST | `/api/admin/jobs` |440| POST | `/api/admin/sources` |441| PATCH | `/api/admin/sources/:id` |442| DELETE | `/api/admin/sources/:id` |443| POST | `/api/admin/epg-sources` |444| DELETE | `/api/admin/epg-sources/:id` |445| PUT | `/api/admin/settings` |446| GET | `/api/admin/logs` |447448**Moteur de sources (`engine.ts`)**449450| Méthode | Route |451|---|---|452| GET | `/api/admin/engine` |453| POST | `/api/admin/engine/test` |454| POST | `/api/admin/engine` |455| PATCH | `/api/admin/engine/:uid` |456| DELETE | `/api/admin/engine/:uid` |457| GET | `/api/provider/stream/:id` |458| GET | `/api/provider/media/:id` |459460</details>461462## 🧩 Moteur universel de sources463464Toute entrée de contenu passe par un **connecteur** qui a le même contrat : se décrire (champs du formulaire, déclaration465d'autorisation), **tester** une configuration sans rien enregistrer, **importer**. Ajouter une source se fait dans466Admin → Sources, jamais dans le code. `src/server/engine.ts` déclare **11 types de connecteurs** (`TYPES`), auxquels s'ajoutent les listes intégrées :467468| Type | Famille | Rôle | Ajoutable sans code |469|---|---|---|---|470| `m3u-url` | direct | playlist M3U / M3U8 publiée à une adresse, relue à chaque synchronisation | oui |471| `m3u-file` | direct | contenu d'un fichier `.m3u` importé, conservé dans la base | oui |472| `stream` | direct | une seule adresse HLS ou MPEG-DASH non protégée, ajoutée comme chaîne | oui |473| `xtream` | direct | fournisseur IPTV auquel on est abonné (API compatible Xtream) : chaînes, films, séries, guide | oui |474| `xmltv` | guide | fichier XMLTV (`.xml` ou `.xml.gz`) | oui |475| `jellyfin` | films et séries | bibliothèque d'un serveur Jellyfin que l'on exploite | oui |476| `wikidata` | films et séries | œuvres libres (Wikidata × Internet Archive / Commons) | intégré |477| `onf` | films et séries | Office national du film du Canada, lecteur officiel intégré | intégré |478| `arte` | films et séries | ARTE, lecteur officiel intégré, droits datés | intégré |479| `nasa` | films et séries | bibliothèque vidéo de la NASA (MP4 directs) | intégré |480| `folder` | bibliothèque | dossier local ou NAS monté (onglet Bibliothèque) | oui |481| listes intégrées | direct | playlists livrées avec l'application (dont `sources/official-verified.m3u`, 112 flux) | intégré |482483Mesure de l'apport d'une source : entrées lues, flux retenus après dédoublonnage, chaînes, **chaînes que cette source est484seule à fournir**, et parmi elles celles qui ont répondu au dernier test.485486Un flux de fournisseur ou un média Jellyfin est stocké comme une **référence opaque** (`provider://…`) : l'adresse réelle,487qui contient souvent les identifiants, n'est reconstruite que sur le serveur au moment de lire, et envoyée au lecteur488comme une redirection.489490## 🗄 Modèle de données491492SQLite (`$DATA_DIR/sp-tv.db`, WAL) — **28 tables** créées par **6 migrations** (`MIGRATIONS` dans `src/server/db.ts`,493appliquées seules au démarrage via `PRAGMA user_version`).494495| Groupe | Tables |496|---|---|497| Catalogue en direct | `sources`, `streams`, `channels`, `categories`, `countries`, `languages`, `guides` |498| Guide TV | `programs`, `epg_state`, `epg_sources` |499| État utilisateur (jamais touché par une synchronisation) | `lists`, `list_items`, `hidden`, `history`, `settings`, `playlists` |500| Films, séries, bibliothèque | `titles`, `episodes`, `media`, `progress`, `title_favs`, `vod_sources`, `library_dirs` |501| Accès | `sessions`, `passkeys`, `login_attempts` |502| Exploitation | `jobs`, `logs` |503504```mermaid505erDiagram506 sources ||--o{ streams : fournit507 channels ||--o{ streams : regroupe508 lists ||--o{ list_items : contient509 titles ||--o{ episodes : contient510 titles ||--o{ media : "lu par"511 episodes ||--o{ media : "lu par"512 media ||--o| progress : reprise513 titles ||--o| title_favs : "Ma liste"514```515516Le diagramme ne montre que les clés étrangères déclarées dans le schéma ; les autres liens (favoris, masquées, historique,517programmes → chaîne) se font par l'identifiant de chaîne, sans contrainte, pour que l'état utilisateur survive aux518synchronisations.519520| Migration | Apport |521|---|---|522| 1 | catalogue en direct, guide, état utilisateur, sessions, clés d'accès, tâches, journal |523| 2 | films, séries, bibliothèque personnelle, progression de lecture |524| 3 | identifiant brut de playlist de chaque flux (rattachement d'un guide XMLTV propre à une playlist) |525| 4 | playlists M3U personnelles, chacune à son adresse secrète |526| 5 | moteur universel de sources : configuration par source, identifiants chiffrés, playlists importées, priorité de lecture, droits datés (ARTE) |527| 6 | suivi de l'enrichissement TMDB |528529## ⏱ Worker et tâches planifiées530531`src/worker/index.ts` fait tourner quatre boucles : deux files de tâches (`sync`/`epg`/`library` et `vod`/`sources`), un532planificateur (toutes les 30 s) et la surveillance continue de disponibilité.533534| Tâche | Fréquence par défaut | Rôle |535|---|---|---|536| `sync` | 24 h (et au premier démarrage) | synchronisation du catalogue de chaînes |537| `epg` | 12 h | collecte du guide TV ; redemandé dans l'heure si un fichier a échoué |538| `vod` | 168 h | import des films et séries libres |539| `sources` | 24 h | ARTE (droits tournants), NASA, Jellyfin, fournisseurs |540| `library` | 15 min | analyse légère des dossiers de la bibliothèque |541| surveillance | en continu, par lots de 400 flux | tests de disponibilité polis |542| expiration | toutes les 30 s | retrait des titres dont les droits sont échus |543| purge du journal | toutes les 30 s | suppression des entrées de plus de 30 jours |544545Le planificateur écrit un battement (`worker_heartbeat`) : l'admin affiche « Le worker ne répond pas » s'il s'arrête.546547## ✅ Tests et qualité548549```bash550pnpm typecheck # tsc --noEmit551pnpm test # Vitest552node_modules/.bin/playwright install chromium firefox webkit # une fois553SPTV_URL=https://tv.spboucher.ai SPTV_PASSWORD='…' node_modules/.bin/playwright test554```555556| Suite | Fichiers | Cas déclarés | Portée |557|---|---|---|---|558| Vitest (`tests/unit`) | 5 | 64 | analyseur M3U (9), catalogue et recherche (19), moteur de sources (10), sécurité (7), films et bibliothèque (19) |559| Playwright (`tests/e2e`) | 3 | 23 | application (10), films et séries (8), moteur de sources (5) |560561Les tests de bout en bout visent une **instance réelle** (production ou build local) et tournent sur 4 profils :562`chromium-desktop`, `firefox-desktop`, `webkit-iphone` (iPhone 15), `webkit-ipad` (iPad Pro 11) — soit 92 exécutions.563La lecture vidéo n'est vérifiée que sous Firefox et WebKit : le Chromium de Playwright n'a pas de décodeur H.264/AAC.564565Résultats mesurés, plateformes réellement testées et limites : [TESTING.md](docs/TESTING.md).566567## 🚢 Déploiement (MacLustr, `mld`)568569SP TV est déployée par `mld` (maclustr-dispatch) comme les autres applications du cluster.570571| Élément | Valeur |572|---|---|573| URL | https://tv.spboucher.ai |574| App `mld` | `sp-tv` |575| Nœud | **m4mn** (Mac mini M4 Pro, épinglé), dossier `~/apps/sp-tv` = clone git, `origin` = spbgit `sp-tv.git` |576| Port | **8670** (HTTP ; seul le tunnel y accède de l'extérieur) |577| Reverse proxy HTTPS | Caddy sur la passerelle du MacLustr Tunnel (certificat Let's Encrypt automatique, HTTP → HTTPS), trafic acheminé par WireGuard |578| Processus PM2 | `sp-tv-web` (`next start`), `sp-tv-worker` (tsx), `sp-tv-backup` (cron 03:50) |579| Données | `~/data/sp-tv/sp-tv.db` (SQLite, WAL), `epg-grabber/`, `epg/`, `transcode/` (borné à 30 Go par défaut), `thumbs/` |580| Sauvegardes | `~/backups/sp-tv/sp-tv-AAAAMMJJ-HHMMSS.db.gz`, 14 jours |581| Secrets | `~/apps/sp-tv/.env` (mode 600), hors Git |582| Dépendances | Node.js ≥ 24, pnpm, pm2, git + npm (grabber EPG), `/usr/bin/sqlite3` (sauvegarde), ffmpeg + ffprobe |583584```bash585# Mise à jour « remote-first » : sur le nœud586cd ~/apps/sp-tv587pnpm install --frozen-lockfile588node_modules/.bin/next build589pm2 restart sp-tv-web sp-tv-worker590git add -A && git commit -m "…" && git push origin main591592# Exploitation593mld status --live | grep sp-tv594mld logs sp-tv595curl -s https://tv.spboucher.ai/api/health596```597598- `scripts/bootstrap.ts` (crochet de déploiement, idempotent) crée la base et, s'il n'y en a pas, un mot de passe599 aléatoire écrit une seule fois dans `$DATA_DIR/initial-password.txt` (mode 600).600- `scripts/backup.sh` : copie cohérente à chaud (`sqlite3 .backup`), contrôle d'intégrité, gzip, purge après 14 jours.601- La base ne suit pas l'application : ne pas faire `mld move sp-tv` sans copier `sp-tv.db`.602- Jellyfin (dépôt [`jellyfin`](https://git.spboucher.ai/jellyfin)) n'a pas de domaine propre : SP TV le publie sous603 `https://tv.spboucher.ai/jellyfin/` par une réécriture (`JELLYFIN_PROXY`), derrière sa session.604605Procédures complètes (première installation, restauration, NAS, dépannage) : [DEPLOYMENT.md](docs/DEPLOYMENT.md).606607## 🔒 Sécurité608609| Sujet | Mesure |610|---|---|611| Mot de passe | scrypt (N = 2¹⁵, r = 8, p = 1, sel de 16 octets), comparaison à temps constant, 12 caractères minimum |612| Clés d'accès | WebAuthn, identifiants découvrables, défis signés (HMAC, 5 min) dans un cookie HttpOnly limité à `/api/auth` |613| Sessions | jeton aléatoire de 256 bits, seule l'empreinte SHA-256 est stockée ; cookie `__Host-sptv` `HttpOnly`, `Secure`, `SameSite=Lax` |614| Force brute | 5 échecs en 15 minutes bloquent l'adresse 15 minutes ; 30 échecs toutes adresses confondues bloquent toute connexion |615| Double contrôle | `src/proxy.ts` redirige vers `/connexion` sans cookie ; la mise en page et chaque route d'API revalident la session en base |616| CSRF | `SameSite=Lax` + en-tête `Origin` exigé sur toute requête non-GET |617| SSRF | protocoles http(s) seulement, adresses privées / bouclage / lien-local / CGNAT refusées, contrôle dans la résolution DNS de la connexion, 5 redirections au plus |618| Identifiants de sources | AES-256-GCM, clé dérivée de `APP_SECRET` ; jamais renvoyés par l'API ni journalisés |619| Playlists à jeton | jeton aléatoire de 192 bits, 404 sur jeton inconnu, 20 essais ratés en 15 minutes bloqués, révocation immédiate |620| Fichiers personnels | servis par identifiant numérique, derrière la session, après vérification du chemin réel ; `ffmpeg` lancé sans interpréteur de commandes |621| En-têtes | `Content-Security-Policy` (`frame-ancestors 'none'`, `frame-src` limité aux lecteurs ONF et ARTE), HSTS, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: same-origin`, `Permissions-Policy`, `X-Robots-Tag: noindex` |622| Respect des sources | lecture directe uniquement, aucun proxy vidéo, aucun contournement (DRM, VPN, injection d'en-têtes), liste de blocage IPTV-org appliquée |623624Limites connues : pas de second facteur distinct (la clé d'accès remplace le mot de passe), sauvegardes non chiffrées et625sur le même nœud, CSP avec `'unsafe-inline'` pour les scripts. Détail : [SECURITY.md](docs/SECURITY.md).626627## ⚠️ Limites à connaître (pas de simulation)628629- SP TV **ne relaie pas la vidéo** : le navigateur lit chaque flux directement à sa source. Un flux en HTTP non chiffré est630 bloqué par les navigateurs sur une page HTTPS ; un flux sans en-têtes CORS n'est lisible que par le lecteur natif de631 Safari ; un flux qui exige un Referer/User-Agent, géobloqué ou protégé ne sera pas lu. L'application le dit, avec la cause.632- Le statut d'un flux est celui du **dernier test fait par le serveur** (depuis le réseau du cluster), pas une garantie.633- Films et séries : le statut « domaine public » vient de Wikidata et vaut le plus souvent pour les États-Unis ; chaque634 fiche l'indique. Les films hébergés en WebM par Wikimedia Commons ne se lisent pas sur les anciens Safari.635- Bibliothèque : un fichier converti à la volée n'est entièrement navigable qu'une fois sa conversion terminée.636- Le guide TV n'existe que pour les chaînes dont IPTV-org référence une source de programmes, et dans la limite configurée.637638## 🗺 Historique des versions et état639640| Version | Date | Apport principal |641|---|---|---|642| 1.0 | 2026-11-16 | TV en direct IPTV-org, guide, favoris, recherche, authentification, déploiement |643| 2.0 | 2026-11-16 | sources supplémentaires, films, séries, ONF, bibliothèque, lecteur à la demande, playlists M3U, nouvelle interface |644| 3.0 | 2026-11-17 | moteur universel de sources, ARTE, NASA, Jellyfin, fournisseurs à API compatible Xtream, MPEG-DASH |645646Le champ `version` de `package.json` est resté à `1.0.0` ; les versions ci-dessus sont celles du647[rapport avant / après](docs/RAPPORT-AVANT-APRES.md), qui donne les chiffres mesurés en production pour chacune.648649Non vérifié ou en attente (voir [TESTING.md](docs/TESTING.md)) : lecture depuis un vrai partage NAS, Safari sur un vrai650iPhone / iPad et AirPlay réel, Chrome et Edge officiels, Android TV et navigateurs de Smart TV, PWA installée sur651appareil, import dans une vraie application de téléviseur.652653## 📚 Documentation654655- [RAPPORT-AVANT-APRES.md](docs/RAPPORT-AVANT-APRES.md) — ce que chaque version a réellement changé, chiffres mesurés.656- [SOURCES.md](docs/SOURCES.md) — sources intégrées, désactivées, refusées, et règles de droits.657- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — composants, modèle de données, flux de synchronisation, lecteur.658- [DEPLOYMENT.md](docs/DEPLOYMENT.md) — MacLustr (`mld`), ports, services, journaux, sauvegarde, mise à jour, dépannage.659- [SECURITY.md](docs/SECURITY.md) — authentification, sessions, SSRF, en-têtes, secrets, respect des sources.660- [TESTING.md](docs/TESTING.md) — tests exécutés, résultats, plateformes réellement testées, limites connues.661- [RECHERCHE-DEPOTS-IPTV.md](docs/RECHERCHE-DEPOTS-IPTV.md), [RECHERCHE-FLUX-OFFICIELS.md](docs/RECHERCHE-FLUX-OFFICIELS.md),662 [RECHERCHE-CATALOGUES-VOD.md](docs/RECHERCHE-CATALOGUES-VOD.md) — recherches de sources ayant mené aux choix ci-dessus.663664## 👤 Auteur et licence665666**Simon-Pierre Boucher** — [contact@spboucher.ai](mailto:contact@spboucher.ai) · forge : [git.spboucher.ai](https://git.spboucher.ai)667668Tous droits réservés. Instance privée à utilisateur unique : qu'un flux soit publiquement accessible n'autorise pas sa669redistribution.670