Europa Specials EPG Mastermind — Build 1.10.37
← Retour à l'application

Comment fonctionne EPG Mastermind

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.

Sommaire

  1. Vue d'ensemble
  2. Les huit onglets
  3. Navigation et interface
  4. Comment un check fonctionne
  5. Comment l'ADN de la chaîne est calculé
  6. Mapping IAB : automatique, mots-clés, manuel
  7. Charge publicitaire et écart entre coupures
  8. Importer ses données : SCTE, as run, ordre à suivre
  9. Fuseaux horaires et conventions
  10. Conservation des données
  11. Comment l'Ad Server consulte ces données
  12. Référence des endpoints
  13. Le système tourne-t-il ?
  14. Notifications Slack

1. Vue d'ensemble

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.

Flux source (XML/JSON)→ Normalisation→ Diagnostic Doctor→ Persistance D1→ ADN de la chaîne→ Tags IAB→ API Ad Server

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.

2. Les huit onglets

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.

Analyse

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).

Programmes

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.

Stream

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.

Ads

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).

Monétisation

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é.

Users

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.

API & MCP

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.

4. Comment un check fonctionne

Un check accepte trois familles de format, détectées automatiquement — pas besoin de préciser lequel :

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.

5. Comment l'ADN de la chaîne est calculé

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.

6. Mapping IAB : automatique, mots-clés, manuel

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é :

  1. Mapping automatique par catégorie — la catégorie éditoriale du programme (déjà présente dans le flux source) est traduite vers un ou plusieurs codes IAB via une table de correspondance.
  2. Règles mots-clés — utilisées uniquement quand un titre n'a aucune catégorie éditoriale exploitable : un mot-clé cherché dans le titre ou le sous-titre du programme (insensible à la casse) déclenche un mapping vers un code IAB donné. Gérables directement depuis l'onglet Analyse.
  3. Ajustement manuel — un tag posé à la main sur un titre précis n'est jamais écrasé par un nouveau passage du mapping automatique.

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.

7. Charge publicitaire et écart entre coupures

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.

Graphique « coupures / heure »

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.

Écart entre coupures

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.

Autres vues

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.

Synchronisation depuis 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.

8. Importer ses données : SCTE, as run, ordre à suivre

Un seul bouton, Importer un rapport (CSV), dans l'onglet Ads de la chaîne. Le format est reconnu automatiquement à son en-tête :

Règles de l'import « as run »

Ordre à suivre pour l'historique d'une chaîne

  1. Importer le fichier SCTE complet. Les coupures antérieures au premier programme connu de la chaîne sont écartées (aucun programme à croiser) — c'est normal à ce stade.
  2. Importer l'« as run » : les programmes du passé arrivent et reculent le « premier programme connu ».
  3. Réimporter le fichier SCTE : cette fois toutes les coupures sont gardées. Un réimport remplace les coupures de la même période (marge de 3 heures de chaque côté), il ne les duplique pas.

9. Fuseaux horaires et conventions

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.

Cas limite : la nuit du retour à l'heure d'hiver (une fois par an, entre 2 h et 3 h), une même heure murale existe deux fois ; les coupures de cette heure précise sont comptées sur la seconde occurrence.

10. Conservation des données

11. Comment l'Ad Server consulte ces données

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.

ETag

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.

12. Référence des endpoints

EndpointUsage
POST /checkLance une analyse ponctuelle sur un flux (URL ou contenu collé).
POST /channel-refreshRelance le check d'une chaîne déjà mémorisée, sans resaisir l'URL.
GET /channel-historyHistorique de programmes pour une chaîne mémorisée et une plage donnée — alimente la Frise et la vue Semaine.
GET /channel-dnaADN agrégé de la chaîne sur une période (semaine, historique complet de 6 mois...).
GET /channel-heatmapHeatmap hebdomadaire densité/fraîcheur/qualité.
POST /channels-latest-epg-datesDate EPG maximale pour un lot de chaînes en une seule requête — alimente le bandeau latéral.
GET /channel-contentIntelligence par titre — exposition, rotation, contexte de programmation (onglet Programmes).
GET /channel-ad-loadProfil 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-importImport 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-importImport 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-heatmapTaux de remplissage Ad Server, heatmap hebdomadaire.
GET /channel-ad-epg-crossrefCroisement 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-checkLance 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-breaksCoupures 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-importImport d'un rapport de revenus partenaire (Excel) ; GET /channel-monetization en lit le calendrier, la tendance et la répartition.
GET /channel-ssai-heatmapPublicité réelle heure par heure du SSAI Broadpeak : insertions, impressions et impressions par coupure.
GET /admin/content-iab-tagsTags IAB par titre pour une chaîne, catégories non mappées.
GET /admin/usersComptes internes et leur accès par chaîne (onglet Users).
GET /v1/api/channels/contextSnapshot programmes + coupures + tags IAB pour l'Ad Server (clé API, scope channels:read).
GET /admin/api-keys/auditJournal unifié de tous les accès API/MCP — 48h de rétention, filtrable et paginé.
POST /mcpServeur 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-statsStatistiques de la base (volume, couverture d'identité des programmes).
GET /admin/cron-logHistorique des exécutions planifiées (rafraîchissement des chaînes, nettoyage de rétention).

API partenaire et MCP

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.

Documentation interactive complète (schémas de requête/réponse, tous les endpoints partenaires) : GET /v1/api/docs — accessible sans clé API.

13. Le système tourne-t-il ?

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.

14. Notifications Slack

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.

Règles communes à tous les messages

Les messages envoyés

MessageNiveauQuandContenu
channel.runway_lowAvertissementUne 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_recoveredSuccèsCes chaînes repassent au-dessus de 24 h.Chaînes concernées et nouvelle date de fin d'EPG.
fetch.failedErreurUne 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.recoveredSuccèsUne source en alerte fonctionne de nouveau.Nom de la source.
cron.failedErreurUne 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.stuckErreurUne 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.staleAvertissementUne 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_recoveredSuccèsCes chaînes sont de nouveau actualisées.Chaînes concernées.
d1.size_highAvertissement puis erreurLa base D1 atteint 70 % puis 90 % de la limite configurée (D1_LIMIT_MB).Taille en Mo et limite.
d1.size_okSuccèsLa base repasse sous 70 %.Taille en Mo.
stream.downErreurLa 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.recoveredSuccèsLe flux d'une chaîne en panne est de nouveau lisible.Chaîne et heure de début de la panne.
okast.adbreaks_sync_failedAvertissementLa 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_recoveredSuccèsLa synchro de ces chaînes refonctionne.Chaînes concernées.
auth.loginInfoUn 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.impersonationAvertissementLa 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.deletedInfo / AvertissementCréation ou suppression d'un compte.Nom du compte.
user.admin_granted / user.admin_revokedAvertissement / InfoDroit admin accordé ou retiré.Nom du compte.
user.deactivated / user.reactivatedInfoCompte désactivé ou réactivé.Nom du compte.
user.token_regeneratedInfoJeton d'un utilisateur régénéré.Nom du compte, jamais le jeton.
digest.dailyInfo ou avertissementChaque 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.

D'où viennent ces messages

Réglages (wrangler.toml)

Ce qui n'est pas surveillé : la qualité des chaînes (pas de seuil défini), les coupures sans marqueur SCTE, le taux de remplissage publicitaire et l'intégration avec l'Ad Server. Une panne de Slack lui-même n'est pas signalée.