Un guide de référence sur ce que fait ce système, ce que montre chaque onglet, comment les mécanismes clés fonctionnent, et où trouver chaque endpoint.
EPG Mastermind lit un flux de programmation (EPG) — XML ou JSON, publié par un fournisseur de contenu — le normalise vers un format pivot commun, le diagnostique (titres manquants, horaires invalides, chevauchements...), puis conserve chaque relevé en base pour construire, dans le temps, une vraie vue analytique de la chaîne : tendances de programmation, taux de répétition, mix de catégories, charge publicitaire. Cette même donnée, une fois enrichie de tags IAB, est ensuite exposée à l'Ad Server via une API dédiée pour éclairer sa décision publicitaire.
Chaque étape est indépendante et consultable séparément — un check ponctuel n'exige pas d'avoir mémorisé la chaîne au préalable, et l'historique en base reste consultable même longtemps après le dernier check.
Analyse ponctuelle d'un flux — URL ou contenu collé directement. Normalise, diagnostique, affiche le rapport complet (validité, complétude des métadonnées, problèmes détectés, moteur de règles qualité). Le point d'entrée pour toute nouvelle chaîne.
L'ADN de la chaîne — tendances sur plusieurs semaines, pas juste le dernier relevé : format & rythme, rotation, daypart, répartition thématique, franchises, programmes les plus rediffusés. Trois vues complémentaires : Frise (un jour, linéaire, détaillée), Semaine (grille calendrier 7 jours × heures avec les vrais titres) et Heatmap (7 jours, densité/fraîcheur/qualité agrégées). Mapping IAB automatique et récapitulatif persistant. Le passé de l'EPG peut être reconstitué par l'import d'un rapport « as run » du playout (section 8).
Intelligence par titre — exposition (diffusions, temps d'antenne, part de la chaîne), rotation (intervalle de rediffusion), contexte de programmation (voisins habituels), environnement publicitaire, tags IAB par titre.
Analyse technique du flux HLS de la chaîne : ladder de qualité, conformité de la playlist, vérification réelle des segments (codecs, durée mesurée contre durée déclarée) et lecture des marqueurs SCTE-35 sur un échantillon de segments.
Profil de charge publicitaire à partir des coupures importées : charge par jour et par heure (graphique en barres, navigation par semaine), écart entre coupures par rapport à la cible des plateformes, heatmaps, taux de remplissage Ad Server, croisement EPG × charge publicitaire et pistes calculées automatiquement (observations à seuils, jamais un jugement). C'est aussi ici que s'importent les fichiers de coupures SCTE et le rapport « as run » (sections 7 et 8).
Revenus publicitaires réellement générés, rapportés par un partenaire de distribution (import d'un fichier Excel par plateforme : Rakuten, Xiaomi, TCL...) : calendrier de revenus, tendance, répartition par device. Y figure aussi la publicité réelle heure par heure vue par le SSAI Broadpeak (insertions, impressions, impressions par coupure), pour les chaînes dont le serviceId est renseigné. À distinguer de l'onglet Ads, qui décrit l'inventaire programmé, pas l'argent gagné.
Gestion des comptes internes et de leur accès par chaîne — qui peut voir/analyser quoi. Présence en ligne visible pour les utilisateurs actifs.
Clés d'accès partenaire (REST + MCP, dissociées), documentation API interactive, collection Postman, et le journal d'audit unifié de tous les accès programmatiques.
Au-delà de 3 chaînes mémorisées, la grille horizontale de sélection laisse place à un bandeau latéral fixe (défilement sticky) — logo, nom, date de dernière analyse et date EPG maximale disponible pour chaque chaîne d'un coup d'œil. Une chaîne pas rafraîchie depuis plus de 24h est marquée d'une bordure orange à gauche ; la chaîne actuellement sélectionnée, d'une ligne or en bas. En dessous ou égal à 3 chaînes, la grille classique reste inchangée.
Le cartouche de chaîne (nom, fournisseur, lecteur vidéo) et la barre d'onglets restent visibles en sticky en haut de la page pendant le défilement d'un panneau long (Analyse notamment) — jamais besoin de remonter pour changer d'onglet ou vérifier quelle chaîne est affichée.
Sélecteur de langue (FR/EN) et bascule thème clair/sombre dans l'en-tête, appliqués immédiatement sans rechargement pour les parties déjà traduites de l'interface — ce chantier avance par tranches successives, certaines zones restent en français le temps d'être couvertes.
Un check accepte trois familles de format, détectées automatiquement — pas besoin de préciser lequel :
<subtitle> (sans tiret) plutôt que <sub-title>.Une fois normalisé vers un pivot commun, Doctor applique ses règles de qualité (titre manquant, horaire invalide, durée nulle, chevauchements) et calcule un rapport complet. Chaque programme de ce check est ensuite conservé en base — en ajout uniquement, jamais de mise à jour : un flux réanalysé plusieurs fois ne fusionne pas avec ses relevés précédents, ce qui rend possible de comparer deux relevés dans le temps pour détecter un vrai changement.
Contrairement à un check ponctuel (une seule capture instantanée), l'ADN de la chaîne agrège l'historique conservé en base sur la fenêtre demandée. La bonne compréhension de ce mécanisme repose sur un point technique important : la base étant en ajout uniquement, un même programme réel peut avoir plusieurs lignes au fil des checks successifs — notamment quand son horaire est corrigé de quelques minutes entre deux relevés, ce qui arrive couramment sur un flux réel.
Pour ne jamais confondre une correction d'horaire avec un nouveau programme, chaque programme reçoit une identité persistante (un identifiant interne, tolérant à ce type de dérive) dès qu'il est vu pour la première fois. La lecture agrégée s'appuie sur cette identité en priorité — la version la plus récemment vérifiée de chaque programme, peu importe l'horaire exact où elle est tombée — avec un repli sur l'horaire exact pour les rares programmes dont l'identité n'a pas pu être résolue.
Chaque titre diffusé peut recevoir un ou plusieurs tags IAB (taxonomie IAB Content Taxonomy 3.1), utilisés par l'Ad Server pour contextualiser sa décision publicitaire. Trois mécanismes, dans l'ordre de priorité :
L'onglet Analyse affiche un récapitulatif persistant (titres tagués, sans tag, catégories non mappées avec leur nombre de titres concernés) et un panneau de complétion manuelle pour traiter les titres restants directement, sans devoir les chercher un par un dans l'onglet Programmes.
L'onglet Ads décrit l'inventaire programmé : combien de coupures publicitaires la chaîne place, à quelle heure, pour quelle durée. Ce n'est pas de la publicité vendue ni diffusée — le fichier source ne dit rien du remplissage ni des revenus. Les chiffres sont calculés à partir des coupures importées (section 8) : par jour, par heure et en détail pour chaque coupure.
Un histogramme en barres verticales, une barre par heure (ou par jour si seules des données quotidiennes existent). La ligne pointillée marque la moyenne de la période ; les barres sous la moyenne sont atténuées ; la valeur du pic est inscrite au-dessus de sa barre. En vue horaire, la navigation se fait semaine par semaine ; le survol donne la date, le nombre de coupures et l'écart à la moyenne.
Les plateformes attendent en moyenne une coupure toutes les 12 minutes — c'est la cible par défaut, réglable entre 1 et 60 minutes. L'indicateur mesure le contenu vu entre deux pauses (de la fin d'une coupure au début de la suivante) ; l'écart début → début est affiché à côté, dans le tableau et sous la moyenne. Il distingue :
Les trous de plus de 3 heures (donnée manquante) sont exclus des moyennes. La carte offre aussi un histogramme des écarts, une bande horaire montrant à quelles heures les écarts courts se concentrent (heure UTC), et un tableau des pires intervalles par nature.
La heatmap horaire montre la charge par jour et par heure ; la heatmap de remplissage confronte les coupures programmées aux décisions réelles de l'Ad Server ; le croisement EPG × charge relie chaque jour aux programmes diffusés. L'import n'est proposé que pour les chaînes produites par OKAST.
Plus besoin d'importer un fichier à la main : si la chaîne a un identifiant FAST OKAST et sa clé API OKAST (onglet Check, réglages de la chaîne, réservé aux admins ; chaque chaîne a la sienne, car elles dépendent de plateformes OKAST différentes), l'application lit la grille de diffusion chez OKAST chaque jour à 04:00 UTC — les 3 derniers jours et les 30 prochains — et met à jour les coupures. Le bouton Synchroniser depuis OKAST de l'onglet Ads fait la même chose tout de suite.
OKAST_API_KEY sert de repli (chaînes Europa Specials) ; sans clé du tout, la chaîne est ignorée. En cas d'échec, un message Slack part (okast.adbreaks_sync_failed).Un seul bouton, Importer un rapport (CSV), dans l'onglet Ads de la chaîne. Le format est reconnu automatiquement à son en-tête :
date, adbreak_name, start_time, duration_s. Depuis la 1.9.101, les heures du fichier sont lues en UTC (export SCTE désormais en UTC) ; un ancien export en heure de Paris s'importe avec le paramètre timezone: Europe/Paris (conversion en UTC, heure d'été et d'hiver comprises).day, title, custom_id, start_time, end_time, duration (sec), cuepoints, number_of_ad_breaks. Il sert à reconstituer l'EPG du passé, là où aucun fichier XML n'existe (les XML ne couvrent que le futur).custom_id et même début) sont ignorés — plus de la moitié des lignes d'un export réel peuvent être des répétitions.since de l'API).number_of_ad_breaks est ignorée (elle vaut 0 partout dans les exports observés). Le temps de pub se déduit de l'écart entre la durée réelle et duration (sec), qui ne mesure que le contenu.Affichage des heures. Le cadran de la barre des chaînes (au-dessus du lecteur) affiche l'heure et son menu choisit le fuseau des heures affichées dans toute l'application : UTC, heure locale de votre navigateur, ou n'importe quel autre fuseau (heure d'été comprise). Le choix est mémorisé. Les jours purs (sélecteurs de semaine, courbes par jour) restent des jours UTC.
Tout est stocké et calculé en UTC : l'EPG XML, l'« as run » et les coupures SCTE (exports désormais en UTC). Un ancien export SCTE en heure de Paris reste importable : le paramètre timezone de l'import (défaut UTC, ou Europe/Paris) convertit alors à l'import, heure d'été et d'hiver comprises. Les graphiques d'heures de l'onglet Ads sont donc en heure UTC.
/admin/cleanup-duplicate-programs, /admin/collapse-redundant-programs).L'endpoint GET /v1/api/channels/context est le point de rencontre entre EPG Mastermind et l'Ad Server — un snapshot des programmes, coupures publicitaires et tags IAB sur une fenêtre demandée, préchargé à l'avance par l'Ad Server, jamais appelé pendant une requête publicitaire en direct.
La réponse porte un ETag réel (calculé sur le contenu effectif — jamais sur l'heure de génération). Un appel suivant avec le même If-None-Match reçoit un 304 Not Modified si rien n'a changé — ce comportement est normal et attendu, pas une anomalie ; le journal d'audit (onglet API & MCP) permet de comparer directement les deux valeurs si un doute existe sur la fraîcheur d'une réponse.
L'authentification se fait par clé API dédiée (scope channels:read), gérée depuis l'onglet API & MCP — distincte des comptes internes utilisés pour se connecter à l'application elle-même.
Le journal d'audit lui-même (rétention 48h) se filtre par canal (REST/MCP), par statut (succès/erreur) et par recherche libre sur l'endpoint, avec une pagination par curseur — chaque page suivante repart du dernier horodatage affiché, jamais un simple décalage numérique qui pourrait sauter ou répéter des lignes sur une table alimentée en continu.
| Endpoint | Usage |
|---|---|
POST /check | Lance une analyse ponctuelle sur un flux (URL ou contenu collé). |
POST /channel-refresh | Relance le check d'une chaîne déjà mémorisée, sans resaisir l'URL. |
GET /channel-history | Historique de programmes pour une chaîne mémorisée et une plage donnée — alimente la Frise et la vue Semaine. |
GET /channel-dna | ADN agrégé de la chaîne sur une période (semaine, historique complet de 6 mois...). |
GET /channel-heatmap | Heatmap hebdomadaire densité/fraîcheur/qualité. |
POST /channels-latest-epg-dates | Date EPG maximale pour un lot de chaînes en une seule requête — alimente le bandeau latéral. |
GET /channel-content | Intelligence par titre — exposition, rotation, contexte de programmation (onglet Programmes). |
GET /channel-ad-load | Profil de charge publicitaire — coupures, taux de charge théorique, écart entre coupures (onglet Ads). Paramètre optionnel target_minutes (cible d'écart, 1 à 60). |
POST /channel-asrun-import | Import d'un rapport « as run » du playout (CSV) : reconstitue l'EPG du passé, avant la première EPG réelle de la chaîne. Paramètres : channel_id, csv, since (optionnel, défaut 2026-06-01). |
POST /channel-ad-load-import | Import unifié (CSV) : agrégat quotidien, horaire, coupures détaillées ou « as run », reconnu automatiquement. Paramètres optionnels : timezone (coupures détaillées), since (as run). |
GET /channel-ad-fill-heatmap | Taux de remplissage Ad Server, heatmap hebdomadaire. |
GET /channel-ad-epg-crossref | Croisement EPG × charge publicitaire, jour par jour. |
GET /channel-dna-trend | Évolution de l'ADN de la chaîne dans le temps. |
GET /channel-content-trend | Évolution de l'exposition par titre (onglet Programmes). |
POST /channel-stream-check | Lance une vérification technique du flux HLS (onglet Stream) ; GET /channel-stream-latest, /channel-stream-history et /channel-stream-manifest en relisent le résultat. |
GET /channel-ad-load-breaks | Coupures détaillées d'une chaîne sur une plage ; POST /channel-ad-load-breaks et /channel-ad-load-hourly sont les imports spécialisés, remplacés par l'import unifié. |
POST /channel-monetization-import | Import d'un rapport de revenus partenaire (Excel) ; GET /channel-monetization en lit le calendrier, la tendance et la répartition. |
GET /channel-ssai-heatmap | Publicité réelle heure par heure du SSAI Broadpeak : insertions, impressions et impressions par coupure. |
GET /admin/content-iab-tags | Tags IAB par titre pour une chaîne, catégories non mappées. |
GET /admin/users | Comptes internes et leur accès par chaîne (onglet Users). |
GET /v1/api/channels/context | Snapshot programmes + coupures + tags IAB pour l'Ad Server (clé API, scope channels:read). |
GET /admin/api-keys/audit | Journal unifié de tous les accès API/MCP — 48h de rétention, filtrable et paginé. |
POST /mcp | Serveur MCP (JSON-RPC) — même système de clés que la REST API, mode d'accès vérifié séparément. |
GET /admin/db-stats | Statistiques de la base (volume, couverture d'identité des programmes). |
GET /admin/cron-log | Historique des exécutions planifiées (rafraîchissement des chaînes, nettoyage de rétention). |
Les clés partenaires donnent accès, selon leurs scopes, à : GET /v1/api/channels, /channels/programs, /channels/quality, /channels/heatmap, /channels/ad-load (avec target_minutes), /channels/ad-fill-rate, /channels/monetization, /channels/ssai-heatmap, /channels/context et POST /channels/refresh. Le serveur MCP (POST /mcp) expose les mêmes données sous forme d'outils : list_channels, get_channel_programs, refresh_channel, get_channel_quality, get_channel_heatmap, get_channel_ad_load, get_channel_ad_fill_rate, get_channel_monetization et get_channel_ssai_heatmap.
GET /v1/api/docs — accessible sans clé API.GET /admin/cron-log (clé maître) montre l'historique des rafraîchissements planifiés et du nettoyage de rétention. GET /admin/db-stats donne une vue d'ensemble de la base — volume, canaux distincts, bornes temporelles, couverture d'identité des programmes.
EPG Mastermind prévient l'équipe dans Slack, canal #europa-epgdoctor, quand quelque chose demande un coup d'œil. L'application ne parle jamais à Slack directement : elle passe par le Worker es-slack (liaison de service SLACK), qui choisit le canal et met le message en forme. Aucun jeton ni webhook Slack n'est stocké ici.
es-slack ne répond pas, l'action en cours (actualisation, connexion, gestion des comptes) se déroule normalement et l'incident est seulement écrit dans les journaux du Worker (notifySlack failed).| Message | Niveau | Quand | Contenu |
|---|---|---|---|
channel.runway_low | Avertissement | Une ou plusieurs chaînes passent sous 24 h d'EPG à venir (changement d'état, au passage du cron de 04:00 UTC). | Liste des chaînes avec la date de leur dernier programme. |
channel.runway_recovered | Succès | Ces chaînes repassent au-dessus de 24 h. | Chaînes concernées et nouvelle date de fin d'EPG. |
fetch.failed | Erreur | Une source EPG échoue 2 actualisations quotidiennes de suite. | Nom de la source, raison (flux invalide ou requête en échec), nombre d'échecs. Jamais l'URL. |
fetch.recovered | Succès | Une source en alerte fonctionne de nouveau. | Nom de la source. |
cron.failed | Erreur | Une tâche planifiée (nettoyage, actualisation) s'arrête sur une erreur. | Nom de la tâche et message d'erreur tronqué à 300 caractères. |
cron.stuck | Erreur | Une tâche est « démarrée » sans « terminée » depuis plus d'une heure (arrêt probable par la limite de CPU). | Tâche et heure de démarrage. |
channel.stale | Avertissement | Une chaîne n'a pas été vérifiée depuis plus de 36 h (ou jamais). | Chaîne et date de dernière vérification. |
channel.stale_recovered | Succès | Ces chaînes sont de nouveau actualisées. | Chaînes concernées. |
d1.size_high | Avertissement puis erreur | La base D1 atteint 70 % puis 90 % de la limite configurée (D1_LIMIT_MB). | Taille en Mo et limite. |
d1.size_ok | Succès | La base repasse sous 70 %. | Taille en Mo. |
stream.down | Erreur | La sonde (toutes les 5 min) échoue 2 fois de suite sur le flux d'une chaîne. | Chaîne et raison : HTTP en erreur, playlist vide, terminée ou figée, délai dépassé, serveur injoignable. |
stream.recovered | Succès | Le flux d'une chaîne en panne est de nouveau lisible. | Chaîne et heure de début de la panne. |
okast.adbreaks_sync_failed | Avertissement | La synchro quotidienne des ad breaks OKAST (04:00 UTC) échoue pour une chaîne (clé refusée, identifiant FAST inconnu, OKAST injoignable…). | Chaînes et raison. Un seul message par incident, jamais de clé. |
okast.adbreaks_sync_recovered | Succès | La synchro de ces chaînes refonctionne. | Chaînes concernées. |
auth.login | Info | Un utilisateur se connecte avec son e-mail et son mot de passe (ou choisit son mot de passe pour la première fois). Pas de message pour un échec ni pour une connexion par clé. | Nom de l'utilisateur et son droit (admin ou standard). Jamais l'e-mail ni le jeton. |
auth.impersonation | Avertissement | La clé maître ouvre une session « en tant que » un utilisateur. | Nom de l'utilisateur et durée de la session (8 h). |
user.created / user.deleted | Info / Avertissement | Création ou suppression d'un compte. | Nom du compte. |
user.admin_granted / user.admin_revoked | Avertissement / Info | Droit admin accordé ou retiré. | Nom du compte. |
user.deactivated / user.reactivated | Info | Compte désactivé ou réactivé. | Nom du compte. |
user.token_regenerated | Info | Jeton d'un utilisateur régénéré. | Nom du compte, jamais le jeton. |
digest.daily | Info ou avertissement | Chaque matin vers 6 h UTC, seulement s'il y a un point ouvert ou une session Stream sur 24 h. | Points ouverts, dernière actualisation, sessions et temps de lecture Stream, arrêts, taille D1, nombre de chaînes. |
wrangler.toml)D1_LIMIT_MB : limite de la base pour l'alerte de taille (500 sur le plan gratuit, 10000 sur le plan payant).DIGEST_UTC_HOUR : heure UTC du résumé quotidien (6 = 8 h 30 à Paris l'été, 7 h 30 l'hiver).STREAM_PROBE_ENABLED : "0" désactive la sonde de flux.OKAST_API_KEY (secret, facultatif) : clé OKAST de repli pour une chaîne qui n'a pas la sienne (section 7).SLACK_NOTIFY_SECRET (secret, facultatif) : à poser uniquement si es-slack exige un secret.