📺 SP TV
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.
Sommaire
- Présentation
- Fonctionnalités
- Architecture
- Pile technique
- Arborescence
- Démarrage rapide (développement)
- Commandes
- Configuration
- Pages de l'application
- API REST
- Moteur universel de sources
- Modèle de données
- Worker et tâches planifiées
- Tests et qualité
- Déploiement (MacLustr,
mld) - Sécurité
- Limites à connaître (pas de simulation)
- Historique des versions et état
- Documentation
- Auteur et licence
🎯 Présentation
Télévision personnelle auto-hébergée — https://tv.spboucher.ai — pour consulter et regarder, dans le navigateur, les chaînes publiques référencées par IPTV-org. Usage strictement personnel et privé : aucune revente, aucune redistribution, aucun relais vidéo.
L'application est à utilisateur unique : aucune page ni route d'API (hors connexion, /api/health et les adresses de
playlists à jeton) ne répond sans session valide. Elle tient en deux processus Node.js et une base SQLite — pas de
Redis, pas de PostgreSQL, pas de proxy vidéo : le navigateur lit chaque flux directement à sa source.
✨ Fonctionnalités
- TV en direct : catalogue agrégé de plusieurs sources vérifiées (IPTV-org, Free-TV, Nexonic, Pluto TV et Samsung TV Plus Canada/France), doublons regroupés, plusieurs flux de secours par chaîne, chaînes canadiennes et francophones en tête, synchronisation quotidienne. Détail et sources refusées : SOURCES.md.
- Moteur de sources universel : chaque source est un connecteur (playlist M3U par adresse ou fichier, flux HLS/DASH, guide XMLTV, fournisseur autorisé à API compatible Xtream, Jellyfin, catalogues libres) ajouté, testé, priorisé et mesuré depuis Admin → Sources, sans toucher au code ; identifiants chiffrés.
- Films, séries, documentaires : œuvres du domaine public ou sous licence libre (droits documentés par Wikidata), lues directement sur Internet Archive ou Wikimedia Commons ; ONF et ARTE dans leur lecteur officiel intégré ; vidéos de la NASA ; fiche avec affiche, synopsis, équipe, statut des droits.
- Ma bibliothèque : dossiers locaux ou partages NAS montés, analysés automatiquement (ffprobe), reconnus (affiche, synopsis), lus tels quels ou convertis à la volée seulement si nécessaire (ffmpeg + VideoToolbox).
- 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, vitesse, sous-titres, pistes audio, épisode suivant, marquage « vu »).
- Recherche unifiée tolérante aux fautes : chaînes, films, séries, épisodes, bibliothèque ; filtres type, genre, année, langue, pays, disponibilité, source.
- Playlists M3U personnelles pour les applications IPTV des téléviseurs (TiviMate, IPTV Smarters, VLC, Kodi…) : sélection par favoris, pays, catégories, langues ; adresse secrète révocable ; guide XMLTV associé ; mise à jour automatique.
- Surveillance polie de la disponibilité des flux, guide TV réel, favoris et listes, « Continuer à regarder ».
- Accès privé : mot de passe + clés d'accès (passkeys), sessions HttpOnly/Secure, anti-force brute ; les fichiers personnels ne sont servis qu'à une session ouverte.
- Interface pensée d'abord pour le téléphone, utilisable à la télécommande / au clavier, PWA installable.
Détail par domaine
| Domaine | Ce que fait le code | Module |
|---|---|---|
| Analyse M3U | #EXTINF, #EXTVLCOPT, tvg-id, logos, groupes, virgules entre guillemets |
src/server/m3u.ts |
| 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 |
| 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 |
| Guide TV | grabber IPTV-org installé dans $DATA_DIR/epg-grabber, import XMLTV, aucun programme généré |
src/server/epg.ts |
| Recherche | index en mémoire ; égalité, préfixe, sous-chaîne, puis distance de Damerau-Levenshtein bornée | src/server/catalog.ts, titles.ts |
| 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 |
| 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 |
| Bibliothèque | parcours récursif, ffprobe, modes direct / direct-hevc / remux / transcode, HLS à la volée, cache borné |
src/server/library.ts |
| Playlists M3U | contenu recalculé à chaque requête, jeton révocable, guide XMLTV du même jeton | src/server/playlists.ts, src/app/m3u/ |
| Enrichissement TMDB | affiches et synopsis français si une clé est fournie (jamais pour la vidéo) | src/server/tmdb.ts |
| Chiffrement des identifiants | AES-256-GCM, clé dérivée de APP_SECRET |
src/server/secrets.ts |
| Garde SSRF | contrôle dans la résolution DNS de la connexion, redirections suivies à la main | src/server/ssrf.ts |
🏗 Architecture
flowchart TB
subgraph Client["Navigateur / téléviseur"]
UI["Interface Next.js (PWA)"]
PL["Lecteurs<br/>hls.js · HLS natif · dash.js"]
APP["Application IPTV<br/>(playlist M3U à jeton)"]
end
subgraph GW["Passerelle MacLustr Tunnel"]
CADDY["Caddy · HTTPS"]
end
subgraph NODE["Nœud m4mn"]
WEB["sp-tv-web<br/>next start · port 8670"]
WRK["sp-tv-worker<br/>tsx src/worker/index.ts"]
BKP["sp-tv-backup<br/>cron 03:50"]
DB[("SQLite · WAL<br/>$DATA_DIR/sp-tv.db")]
FF["ffprobe / ffmpeg<br/>VideoToolbox"]
JF["Jellyfin (facultatif)<br/>/jellyfin"]
end
subgraph EXT["Sources publiques"]
IPTV["IPTV-org · Free-TV · Nexonic<br/>Pluto TV · Samsung TV Plus"]
VOD["Wikidata · Internet Archive<br/>Wikimedia Commons · Wikipédia"]
OFF["ONF · ARTE · NASA"]
BRD["Diffuseurs et CDN"]
end
UI -->|HTTPS| CADDY -->|WireGuard| WEB
APP -->|"/m3u/<jeton>.m3u"| CADDY
WEB <--> DB
WRK <--> DB
BKP --> DB
WEB --> FF
WEB -. réécriture .-> JF
WRK -->|sync| IPTV
WRK -->|import| VOD
WRK -->|import| OFF
WRK -->|tests de disponibilité| BRD
PL ==>|"lecture directe, sans relais"| BRD
Le processus web et le worker ne se parlent que par la base SQLite : le worker publie une nouvelle catalog_version
et le processus web reconstruit son index mémoire (≈ 50 ms). Détail : ARCHITECTURE.md.
🧰 Pile technique
| Rôle | Technologie | Version (lockfile) |
|---|---|---|
| Framework web | Next.js (App Router) | 16.4.6 |
| Interface | React / React DOM | 19.3.1 |
| Langage | TypeScript | 6.0.3 |
| Styles | Tailwind CSS (@tailwindcss/postcss) |
4.3.5 |
| Composants | composants maison dans l'esprit shadcn/ui (class-variance-authority, clsx, tailwind-merge) |
— |
| Icônes | lucide-react | 1.73.0 |
| Lecture HLS | hls.js | 1.7.4 |
| Lecture MPEG-DASH | dash.js (dashjs) |
5.3.0 |
| Base de données | SQLite via node:sqlite (intégré à Node ≥ 24, aucun module natif), mode WAL |
— |
| Requêtes sortantes | undici | 8.12.4 |
| Validation | zod | 4.6.7 |
| Clés d'accès | @simplewebauthn/server / @simplewebauthn/browser |
14.1.0 / ^14.0.0 |
| Exécution des scripts et du worker | tsx | 4.23.15 |
| Vidéo locale | ffmpeg + ffprobe (Homebrew), h264_videotoolbox |
— |
| Tests unitaires | Vitest | 5.1.0 |
| Tests de bout en bout | Playwright | 1.65.1 |
| Gestionnaire de paquets | pnpm | — |
| Gestionnaire de processus | PM2 | — |
🗂 Arborescence
sp-tv/
├── src/
│ ├── app/
│ │ ├── (tv)/ # 16 pages derrière une session (accueil, chaînes, films, guide, admin…)
│ │ ├── connexion/ # page de connexion (mot de passe, clé d'accès)
│ │ ├── api/[...path]/route.ts # point d'entrée unique de l'API REST → src/server/api
│ │ ├── m3u/[file]/ # playlists M3U et guides XMLTV à jeton (seule partie lisible sans session)
│ │ ├── manifest.ts # manifeste PWA
│ │ └── layout.tsx, globals.css
│ ├── components/
│ │ ├── player.tsx # lecteur en direct global (un seul <video>)
│ │ ├── vod-player.tsx # lecteur à la demande
│ │ ├── shell.tsx # navigation + navigation directionnelle (télécommande / clavier)
│ │ ├── engine-admin.tsx # Admin → Sources
│ │ └── ui.tsx, ui-static.ts, vod-section.tsx
│ ├── lib/ # client HTTP du navigateur, liens vers les services officiels
│ ├── proxy.ts # premier contrôle d'accès : sans cookie → /connexion
│ ├── server/
│ │ ├── api/ # 71 routes : auth, catalog, admin, vod, engine + routeur (core.ts)
│ │ ├── connectors/ # arte, jellyfin, nasa, xtream
│ │ ├── db.ts, env.ts # SQLite, migrations (PRAGMA user_version), paramètres, journal
│ │ ├── sync.ts, m3u.ts # synchronisation du catalogue, analyseur M3U
│ │ ├── checker.ts, epg.ts # disponibilité des flux, guide TV
│ │ ├── catalog.ts, titles.ts # index mémoire, recherche floue
│ │ ├── vod.ts, onf.ts, tmdb.ts, library.ts
│ │ ├── engine.ts # moteur universel de sources
│ │ ├── playlists.ts # playlists M3U personnelles
│ │ └── auth.ts, secrets.ts, ssrf.ts, jobs.ts
│ └── worker/index.ts # worker : file de tâches, planificateur, surveillance continue
├── scripts/ # bootstrap.ts, set-password.ts, run-job.ts, backup.sh
├── sources/official-verified.m3u # sélection vérifiée de 112 flux de diffuseurs officiels
├── tests/
│ ├── unit/ # 5 fichiers Vitest
│ └── e2e/ # 3 fichiers Playwright
├── docs/ # 9 documents (architecture, déploiement, sécurité, sources, tests, recherches)
├── public/ # icônes PWA, robots.txt, sw.js
└── next.config.ts, playwright.config.ts, vitest.config.ts, pnpm-workspace.yaml, .env.example🚀 Démarrage rapide (développement)
pnpm install
cp .env.example .env # en dev, les valeurs par défaut suffisent (DATA_DIR=./data, http://localhost:8670)
pnpm bootstrap # crée la base et écrit un mot de passe initial dans data/initial-password.txt
pnpm sync # première importation IPTV-org (≈ 1 s)
pnpm dev # http://localhost:8670 (identifiant : sp)
pnpm worker # dans un 2e terminal : synchronisation planifiée, vérification des flux, guidePrérequis : Node.js ≥ 24 (node:sqlite), pnpm ; ffmpeg et ffprobe pour la bibliothèque personnelle ; git et npm
pour le grabber du guide TV ; /usr/bin/sqlite3 pour la sauvegarde.
⌨️ Commandes
| Commande | Rôle |
|---|---|
pnpm build / pnpm start |
build de production / serveur web (port 8670) |
pnpm worker |
worker d'arrière-plan |
pnpm sync |
synchronisation immédiate, au premier plan |
node_modules/.bin/tsx scripts/run-job.ts epg |
mise à jour du guide TV au premier plan |
node_modules/.bin/tsx scripts/run-job.ts vod |
import des films et séries libres (≈ 25 min la première fois) |
node_modules/.bin/tsx scripts/run-job.ts library |
analyse immédiate des dossiers de la bibliothèque |
node_modules/.bin/tsx scripts/run-job.ts check 100 |
teste 100 flux et affiche chaque résultat |
node_modules/.bin/tsx scripts/run-job.ts sources |
actualisation des sources (ARTE, NASA, Jellyfin, fournisseurs) |
node_modules/.bin/tsx scripts/run-job.ts tmdb |
passe d'enrichissement TMDB |
node_modules/.bin/tsx scripts/run-job.ts onf |
import ONF |
pnpm set-password |
génère (ou définit avec SPTV_PASSWORD=…) le mot de passe et ferme toutes les sessions |
scripts/backup.sh |
sauvegarde de la base |
pnpm typecheck |
vérification des types (tsc --noEmit) |
pnpm test |
tests unitaires et d'intégration (Vitest) |
SPTV_URL=… SPTV_PASSWORD=… node_modules/.bin/playwright test |
tests de bout en bout |
⚙️ Configuration
Copier .env.example vers .env (mode 600). Aucune valeur réelle ne doit entrer dans Git.
| Variable | Rôle | Défaut |
|---|---|---|
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 |
APP_SECRET |
clé HMAC (≥ 32 caractères) : sessions, défis WebAuthn, chiffrement des identifiants de sources | valeur de développement ; obligatoire en production |
DATA_DIR |
dossier des données : base sp-tv.db, grabber EPG, fichiers de travail |
./data en développement ; obligatoire en production |
BACKUP_DIR |
dossier des sauvegardes quotidiennes (scripts/backup.sh) |
~/backups/sp-tv |
OWNER_USERNAME |
identifiant de connexion du propriétaire | sp |
DATABASE_PATH |
chemin explicite de la base (facultatif) | $DATA_DIR/sp-tv.db |
JELLYFIN_PROXY |
serveur Jellyfin local publié sous /jellyfin du site, derrière la session ; lu au next build |
non défini |
TMDB_API_KEY |
clé TMDB v3 facultative : affiches et synopsis français (jamais pour la vidéo) | non définie |
LIBRARY_ROOTS |
racines absolues (séparées par :) sous lesquelles un dossier de bibliothèque peut être déclaré |
voir ARCHITECTURE.md |
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 |
SPTV_ALLOW_PRIVATE_HOSTS |
tests automatisés seulement : laisse le garde SSRF atteindre des cibles de bouclage ; refusé en production | désactivé |
Paramètres réglables depuis l'admin (table settings, valeurs par défaut)
| Paramètre | Défaut | Rôle |
|---|---|---|
sync_interval_hours |
24 | intervalle de synchronisation du catalogue |
check_enabled |
1 | surveillance de disponibilité active |
check_concurrency |
6 | tests simultanés au total |
check_host_delay_ms |
1500 | pause entre deux tests d'un même hôte |
check_timeout_ms |
10000 | délai d'expiration d'un test |
check_recheck_hours |
24 | nouveau test de l'ensemble du catalogue |
check_priority_hours |
6 | nouveau test des favoris et chaînes regardées |
epg_enabled |
1 | guide TV actif |
epg_interval_hours |
12 | intervalle de collecte du guide |
epg_countries |
CA,FR | pays couverts en priorité par le guide |
epg_max_channels |
250 | plafond de chaînes couvertes par le guide |
epg_days |
2 | jours de programmes collectés |
session_days |
60 | durée d'une session |
vod_interval_hours |
168 | import des films et séries libres |
library_interval_minutes |
15 | analyse de la bibliothèque |
transcode_cache_gb |
30 | taille maximale du cache de conversion |
sources_interval_hours |
24 | actualisation ARTE, NASA, Jellyfin, fournisseurs |
auto_resume, premium_filter |
1 | reprise automatique ; filtre des chaînes payantes présumées |
🧭 Pages de l'application
17 pages (page.tsx) : 16 derrière une session dans src/app/(tv)/, plus /connexion.
| Route | Page | Route | Page |
|---|---|---|---|
/ |
Accueil | /favoris |
Favoris et listes |
/chaines |
TV en direct | /continuer |
Continuer à regarder |
/sports |
Sports | /guide |
Guide TV |
/films |
Films | /playlists |
Playlists M3U personnelles |
/series |
Séries | /recherche |
Recherche unifiée |
/documentaires |
Documentaires | /parametres |
Paramètres |
/bibliotheque |
Ma bibliothèque | /admin |
Administration |
/catalogue |
Catalogue | /titre/[id] |
Fiche d'un titre |
/connexion |
Connexion |
Hors pages : /m3u/<jeton>.m3u et /m3u/<jeton>.xml (playlist et guide XMLTV d'une playlist personnelle),
/manifest.webmanifest, /sw.js.
🔌 API REST
Un petit routeur maison (src/server/api/core.ts) sert 71 routes sous /api. Les routes sont privées par
défaut ; toute requête non-GET doit porter l'en-tête Origin de l'application ; les corps sont validés par zod.
| Module | Routes | Contenu |
|---|---|---|
auth.ts |
10 | connexion, déconnexion, clés d'accès, mot de passe, sessions |
catalog.ts |
25 | santé, chaînes, accueil, favoris, listes, masquées, historique, guide, playlists |
vod.ts |
20 | titres, lecture, progression, « Ma liste », recherche, médias, bibliothèque |
admin.ts |
9 | aperçu, tâches, sources, guides, paramètres, journaux |
engine.ts |
7 | moteur de sources, redirections vers un fournisseur |
Routes publiques (sans session) : GET /api/health, POST /api/auth/login, POST /api/auth/passkey/options,
POST /api/auth/passkey/verify ; GET /api/provider/stream/:id et GET /api/provider/media/:id acceptent une session
ou un ticket signé de 12 heures propre au média.
Liste complète des 71 routes
Authentification (auth.ts)
| Méthode | Route |
|---|---|
| POST | /api/auth/login |
| POST | /api/auth/logout |
| POST | /api/auth/passkey/options |
| POST | /api/auth/passkey/verify |
| POST | /api/auth/passkey/register-options |
| POST | /api/auth/passkey/register |
| DELETE | /api/auth/passkey/:id |
| GET | /api/auth/security |
| POST | /api/auth/password |
| DELETE | /api/auth/sessions/:id |
Catalogue en direct (catalog.ts)
| Méthode | Route |
|---|---|
| GET | /api/health |
| GET | /api/channels |
| GET | /api/meta |
| GET | /api/home |
| GET | /api/channels/:id |
| POST | /api/channels/:id/check |
| POST | /api/channels/:id/played |
| POST | /api/favorites |
| POST | /api/hidden |
| GET | /api/lists |
| GET | /api/lists/:id |
| POST | /api/lists |
| PATCH | /api/lists/:id |
| DELETE | /api/lists/:id |
| PUT | /api/lists |
| GET | /api/now |
| GET | /api/history |
| DELETE | /api/history |
| GET | /api/guide |
| GET | /api/playlists |
| POST | /api/playlists/preview |
| POST | /api/playlists |
| PATCH | /api/playlists/:id |
| POST | /api/playlists/:id/rotate |
| DELETE | /api/playlists/:id |
Films, séries, bibliothèque (vod.ts)
| Méthode | Route |
|---|---|
| GET | /api/titles |
| GET | /api/titles/facets |
| GET | /api/titles/:id |
| GET | /api/play/:id |
| POST | /api/progress |
| POST | /api/watched |
| POST | /api/title-favs |
| GET | /api/title-favs |
| GET | /api/continue |
| GET | /api/vod/home |
| GET | /api/search |
| GET | /api/media/:id/file |
| GET | /api/media/:id/thumb |
| GET | /api/media/:id/hls/:file |
| GET | /api/media/:id/subs/:n |
| GET | /api/admin/vod |
| PATCH | /api/admin/vod-sources/:id |
| GET | /api/admin/library |
| POST | /api/admin/library |
| DELETE | /api/admin/library/:id |
Administration (admin.ts)
| Méthode | Route |
|---|---|
| GET | /api/admin/overview |
| POST | /api/admin/jobs |
| POST | /api/admin/sources |
| PATCH | /api/admin/sources/:id |
| DELETE | /api/admin/sources/:id |
| POST | /api/admin/epg-sources |
| DELETE | /api/admin/epg-sources/:id |
| PUT | /api/admin/settings |
| GET | /api/admin/logs |
Moteur de sources (engine.ts)
| Méthode | Route |
|---|---|
| GET | /api/admin/engine |
| POST | /api/admin/engine/test |
| POST | /api/admin/engine |
| PATCH | /api/admin/engine/:uid |
| DELETE | /api/admin/engine/:uid |
| GET | /api/provider/stream/:id |
| GET | /api/provider/media/:id |
🧩 Moteur universel de sources
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. src/server/engine.ts déclare 11 types de connecteurs (TYPES), auxquels s'ajoutent les listes intégrées :
| Type | Famille | Rôle | Ajoutable sans code |
|---|---|---|---|
m3u-url |
direct | playlist M3U / M3U8 publiée à une adresse, relue à chaque synchronisation | oui |
m3u-file |
direct | contenu d'un fichier .m3u importé, conservé dans la base |
oui |
stream |
direct | une seule adresse HLS ou MPEG-DASH non protégée, ajoutée comme chaîne | oui |
xtream |
direct | fournisseur IPTV auquel on est abonné (API compatible Xtream) : chaînes, films, séries, guide | oui |
xmltv |
guide | fichier XMLTV (.xml ou .xml.gz) |
oui |
jellyfin |
films et séries | bibliothèque d'un serveur Jellyfin que l'on exploite | oui |
wikidata |
films et séries | œuvres libres (Wikidata × Internet Archive / Commons) | intégré |
onf |
films et séries | Office national du film du Canada, lecteur officiel intégré | intégré |
arte |
films et séries | ARTE, lecteur officiel intégré, droits datés | intégré |
nasa |
films et séries | bibliothèque vidéo de la NASA (MP4 directs) | intégré |
folder |
bibliothèque | dossier local ou NAS monté (onglet Bibliothèque) | oui |
| listes intégrées | direct | playlists livrées avec l'application (dont sources/official-verified.m3u, 112 flux) |
intégré |
Mesure de l'apport d'une source : 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.
Un flux de fournisseur ou un média Jellyfin est stocké comme une référence opaque (provider://…) : l'adresse réelle,
qui contient souvent les identifiants, n'est reconstruite que sur le serveur au moment de lire, et envoyée au lecteur
comme une redirection.
🗄 Modèle de données
SQLite ($DATA_DIR/sp-tv.db, WAL) — 28 tables créées par 6 migrations (MIGRATIONS dans src/server/db.ts,
appliquées seules au démarrage via PRAGMA user_version).
| Groupe | Tables |
|---|---|
| Catalogue en direct | sources, streams, channels, categories, countries, languages, guides |
| Guide TV | programs, epg_state, epg_sources |
| État utilisateur (jamais touché par une synchronisation) | lists, list_items, hidden, history, settings, playlists |
| Films, séries, bibliothèque | titles, episodes, media, progress, title_favs, vod_sources, library_dirs |
| Accès | sessions, passkeys, login_attempts |
| Exploitation | jobs, logs |
erDiagram
sources ||--o{ streams : fournit
channels ||--o{ streams : regroupe
lists ||--o{ list_items : contient
titles ||--o{ episodes : contient
titles ||--o{ media : "lu par"
episodes ||--o{ media : "lu par"
media ||--o| progress : reprise
titles ||--o| title_favs : "Ma liste"
Le diagramme ne montre que les clés étrangères déclarées dans le schéma ; les autres liens (favoris, masquées, historique, programmes → chaîne) se font par l'identifiant de chaîne, sans contrainte, pour que l'état utilisateur survive aux synchronisations.
| Migration | Apport |
|---|---|
| 1 | catalogue en direct, guide, état utilisateur, sessions, clés d'accès, tâches, journal |
| 2 | films, séries, bibliothèque personnelle, progression de lecture |
| 3 | identifiant brut de playlist de chaque flux (rattachement d'un guide XMLTV propre à une playlist) |
| 4 | playlists M3U personnelles, chacune à son adresse secrète |
| 5 | moteur universel de sources : configuration par source, identifiants chiffrés, playlists importées, priorité de lecture, droits datés (ARTE) |
| 6 | suivi de l'enrichissement TMDB |
⏱ Worker et tâches planifiées
src/worker/index.ts fait tourner quatre boucles : deux files de tâches (sync/epg/library et vod/sources), un
planificateur (toutes les 30 s) et la surveillance continue de disponibilité.
| Tâche | Fréquence par défaut | Rôle |
|---|---|---|
sync |
24 h (et au premier démarrage) | synchronisation du catalogue de chaînes |
epg |
12 h | collecte du guide TV ; redemandé dans l'heure si un fichier a échoué |
vod |
168 h | import des films et séries libres |
sources |
24 h | ARTE (droits tournants), NASA, Jellyfin, fournisseurs |
library |
15 min | analyse légère des dossiers de la bibliothèque |
| surveillance | en continu, par lots de 400 flux | tests de disponibilité polis |
| expiration | toutes les 30 s | retrait des titres dont les droits sont échus |
| purge du journal | toutes les 30 s | suppression des entrées de plus de 30 jours |
Le planificateur écrit un battement (worker_heartbeat) : l'admin affiche « Le worker ne répond pas » s'il s'arrête.
✅ Tests et qualité
pnpm typecheck # tsc --noEmit
pnpm test # Vitest
node_modules/.bin/playwright install chromium firefox webkit # une fois
SPTV_URL=https://tv.spboucher.ai SPTV_PASSWORD='…' node_modules/.bin/playwright test| Suite | Fichiers | Cas déclarés | Portée |
|---|---|---|---|
Vitest (tests/unit) |
5 | 64 | analyseur M3U (9), catalogue et recherche (19), moteur de sources (10), sécurité (7), films et bibliothèque (19) |
Playwright (tests/e2e) |
3 | 23 | application (10), films et séries (8), moteur de sources (5) |
Les tests de bout en bout visent une instance réelle (production ou build local) et tournent sur 4 profils :
chromium-desktop, firefox-desktop, webkit-iphone (iPhone 15), webkit-ipad (iPad Pro 11) — soit 92 exécutions.
La 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.
Résultats mesurés, plateformes réellement testées et limites : TESTING.md.
🚢 Déploiement (MacLustr, mld)
SP TV est déployée par mld (maclustr-dispatch) comme les autres applications du cluster.
| Élément | Valeur |
|---|---|
| URL | https://tv.spboucher.ai |
App mld |
sp-tv |
| Nœud | m4mn (Mac mini M4 Pro, épinglé), dossier ~/apps/sp-tv = clone git, origin = spbgit sp-tv.git |
| Port | 8670 (HTTP ; seul le tunnel y accède de l'extérieur) |
| Reverse proxy HTTPS | Caddy sur la passerelle du MacLustr Tunnel (certificat Let's Encrypt automatique, HTTP → HTTPS), trafic acheminé par WireGuard |
| Processus PM2 | sp-tv-web (next start), sp-tv-worker (tsx), sp-tv-backup (cron 03:50) |
| Données | ~/data/sp-tv/sp-tv.db (SQLite, WAL), epg-grabber/, epg/, transcode/ (borné à 30 Go par défaut), thumbs/ |
| Sauvegardes | ~/backups/sp-tv/sp-tv-AAAAMMJJ-HHMMSS.db.gz, 14 jours |
| Secrets | ~/apps/sp-tv/.env (mode 600), hors Git |
| Dépendances | Node.js ≥ 24, pnpm, pm2, git + npm (grabber EPG), /usr/bin/sqlite3 (sauvegarde), ffmpeg + ffprobe |
# Mise à jour « remote-first » : sur le nœud
cd ~/apps/sp-tv
pnpm install --frozen-lockfile
node_modules/.bin/next build
pm2 restart sp-tv-web sp-tv-worker
git add -A && git commit -m "…" && git push origin main
# Exploitation
mld status --live | grep sp-tv
mld logs sp-tv
curl -s https://tv.spboucher.ai/api/healthscripts/bootstrap.ts(crochet de déploiement, idempotent) crée la base et, s'il n'y en a pas, un mot de passe aléatoire écrit une seule fois dans$DATA_DIR/initial-password.txt(mode 600).scripts/backup.sh: copie cohérente à chaud (sqlite3 .backup), contrôle d'intégrité, gzip, purge après 14 jours.- La base ne suit pas l'application : ne pas faire
mld move sp-tvsans copiersp-tv.db. - Jellyfin (dépôt
jellyfin) n'a pas de domaine propre : SP TV le publie soushttps://tv.spboucher.ai/jellyfin/par une réécriture (JELLYFIN_PROXY), derrière sa session.
Procédures complètes (première installation, restauration, NAS, dépannage) : DEPLOYMENT.md.
🔒 Sécurité
| Sujet | Mesure |
|---|---|
| Mot de passe | scrypt (N = 2¹⁵, r = 8, p = 1, sel de 16 octets), comparaison à temps constant, 12 caractères minimum |
| Clés d'accès | WebAuthn, identifiants découvrables, défis signés (HMAC, 5 min) dans un cookie HttpOnly limité à /api/auth |
| Sessions | jeton aléatoire de 256 bits, seule l'empreinte SHA-256 est stockée ; cookie __Host-sptv HttpOnly, Secure, SameSite=Lax |
| Force brute | 5 échecs en 15 minutes bloquent l'adresse 15 minutes ; 30 échecs toutes adresses confondues bloquent toute connexion |
| 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 |
| CSRF | SameSite=Lax + en-tête Origin exigé sur toute requête non-GET |
| 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 |
| Identifiants de sources | AES-256-GCM, clé dérivée de APP_SECRET ; jamais renvoyés par l'API ni journalisés |
| 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 |
| 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 |
| 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 |
| 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 |
Limites connues : pas de second facteur distinct (la clé d'accès remplace le mot de passe), sauvegardes non chiffrées et
sur le même nœud, CSP avec 'unsafe-inline' pour les scripts. Détail : SECURITY.md.
⚠️ Limites à connaître (pas de simulation)
- SP TV ne relaie pas la vidéo : le navigateur lit chaque flux directement à sa source. Un flux en HTTP non chiffré est bloqué par les navigateurs sur une page HTTPS ; un flux sans en-têtes CORS n'est lisible que par le lecteur natif de 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.
- Le statut d'un flux est celui du dernier test fait par le serveur (depuis le réseau du cluster), pas une garantie.
- Films et séries : le statut « domaine public » vient de Wikidata et vaut le plus souvent pour les États-Unis ; chaque fiche l'indique. Les films hébergés en WebM par Wikimedia Commons ne se lisent pas sur les anciens Safari.
- Bibliothèque : un fichier converti à la volée n'est entièrement navigable qu'une fois sa conversion terminée.
- 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.
🗺 Historique des versions et état
| Version | Date | Apport principal |
|---|---|---|
| 1.0 | 2026-11-16 | TV en direct IPTV-org, guide, favoris, recherche, authentification, déploiement |
| 2.0 | 2026-11-16 | sources supplémentaires, films, séries, ONF, bibliothèque, lecteur à la demande, playlists M3U, nouvelle interface |
| 3.0 | 2026-11-17 | moteur universel de sources, ARTE, NASA, Jellyfin, fournisseurs à API compatible Xtream, MPEG-DASH |
Le champ version de package.json est resté à 1.0.0 ; les versions ci-dessus sont celles du
rapport avant / après, qui donne les chiffres mesurés en production pour chacune.
Non vérifié ou en attente (voir TESTING.md) : lecture depuis un vrai partage NAS, Safari sur un vrai iPhone / iPad et AirPlay réel, Chrome et Edge officiels, Android TV et navigateurs de Smart TV, PWA installée sur appareil, import dans une vraie application de téléviseur.
📚 Documentation
- RAPPORT-AVANT-APRES.md — ce que chaque version a réellement changé, chiffres mesurés.
- SOURCES.md — sources intégrées, désactivées, refusées, et règles de droits.
- ARCHITECTURE.md — composants, modèle de données, flux de synchronisation, lecteur.
- DEPLOYMENT.md — MacLustr (
mld), ports, services, journaux, sauvegarde, mise à jour, dépannage. - SECURITY.md — authentification, sessions, SSRF, en-têtes, secrets, respect des sources.
- TESTING.md — tests exécutés, résultats, plateformes réellement testées, limites connues.
- RECHERCHE-DEPOTS-IPTV.md, RECHERCHE-FLUX-OFFICIELS.md, RECHERCHE-CATALOGUES-VOD.md — recherches de sources ayant mené aux choix ci-dessus.
👤 Auteur et licence
Simon-Pierre Boucher — contact@spboucher.ai · forge : git.spboucher.ai
Tous droits réservés. Instance privée à utilisateur unique : qu'un flux soit publiquement accessible n'autorise pas sa redistribution.