EPG pour middleware OTT

Le programme des émissions issu de la base de données EPG est fourni aux systèmes externes — boîtiers décodeurs, applications et middleware OTT — de deux manières : sous forme de document XMLTV complet via le serveur EPG dédié, et sous forme de programme quotidien d’une chaîne en JSON via l’API HTTP du nœud.

Distribution XMLTV

XMLTV est distribué par un serveur EPG intégré distinct. Il s’active sur l’écran « Serveur EPG » (Serveur EPG) : « Activer le serveur EPG », le port HTTP (43973 par défaut), le cas échéant HTTPS avec un certificat (port 43983 par défaut) et le « Nom d’hôte ». L’activation et la désactivation agissent immédiatement, sans redémarrer le service ; un serveur désactivé n’ouvre ni le port HTTP ni le port HTTPS.

L’accès s’effectue par comptes (onglet « Comptes » de l’écran « Paramètres EPG », Paramètres EPG) : identifiant et mot de passe, « Ensemble de chaînes », « Date d’expiration », « IP autorisée » et l’indicateur « En pause ». Le contenu distribué est déterminé par l’ensemble de chaînes :

  • les ensembles sont créés dans l’onglet « Ensembles de chaînes » ;

  • les chaînes sont incluses dans les ensembles depuis la base de données EPG (Base de données EPG) ; une chaîne peut appartenir à plusieurs ensembles ;

  • un seul ensemble est attribué à un compte — sans ensemble, la distribution est vide ;

  • un ensemble attribué à un compte ne peut pas être supprimé ; la suppression d’un ensemble supprime aussi son contenu.

Le document est accessible au chemin /xmltv (et /xmltv.gz — le fichier compressé) ; l’autorisation s’effectue par HTTP Digest ou via les paramètres de requête. Les heures des émissions sont fournies avec le fuseau horaire de la chaîne ; seuls les événements en cours et à venir figurent dans le document. Si un même identifiant de chaîne provient de sources différentes, la chaîne n’est fournie qu’une seule fois et l’omission est signalée dans le journal. Depuis la version 2.0.2.418, les émissions de la chaîne sont omises avec elle ; auparavant, elles figuraient dans le document sous l’identifiant de la chaîne fournie, à côté de ses propres émissions, et une émission pouvait se répéter.

Export complet avec les données d’association

Depuis la version 2.0.2.418, le serveur EPG fournit aussi un export XMLTV complet pour associer les chaînes diffusées au programme des émissions : le chemin /xmltv-src (et /xmltv-src.gz — le fichier compressé). Contrairement à /xmltv, il comprend les chaînes de toutes les sources (ou des sources choisies), avec les données qui permettent de relier une chaîne à sa source :

  • l’identifiant de la chaîne dans l’export est <source>:<chaîne> ; il est unique même si la même chaîne figure dans plusieurs sources ;

  • chaque chaîne porte le numéro et le nom de la source (src-id, src-name), l’identifiant propre de la chaîne dans le fichier XMLTV (channel-id, la clé d’association), l’identifiant supplémentaire (channel-id2) s’il est défini, le fuseau horaire (time-zone) et l’heure de fin de la dernière émission (last-stop) ;

  • tous les noms et logos de la chaîne ; une chaîne est fournie même si elle n’a aucune émission, et une chaîne sans nom reçoit un nom égal à son identifiant ;

  • les heures des émissions sont en UTC (+0000) : le fuseau horaire de la chaîne n’est pas appliqué et il est transmis en attribut ; chaque émission comporte tous ses titres, descriptions, genres et classifications par âge. Depuis la version 2.0.2.419, le sous-titre de l’émission (par exemple, le titre de l’épisode) est fourni dans un élément <sub-title> distinct, et <title> ne le contient plus ; le sous-titre ainsi séparé est précisé plus bas, dans Programme quotidien en JSON.

Paramètres de la requête :

  • src — all (par défaut) ou des numéros de sources séparés par des virgules ; 0 désigne la source intégrée « flux-import ». Les sources désactivées et les numéros inconnus sont ignorés ;

  • programmes — 1 (par défaut) fournit les chaînes et les émissions, 0 uniquement le catalogue des chaînes ;

  • days-back — 0 (par défaut) fournit les émissions en cours et à venir, comme /xmltv ; N commence à minuit UTC N jours en arrière, mais pas au-delà de la durée de conservation de l’historique (« Conserver l’historique, jours », Configuration des sources).

Une valeur de paramètre incorrecte est rejetée avec le code 400. L’accès s’effectue par les comptes du serveur EPG, comme pour /xmltv : un compte doté de l’indicateur all-channels (dans le fichier de configuration ou via l’API ; depuis la version 2.0.2.419, l’interrupteur « Toutes les chaînes sur /xmltv-src », Paramètres EPG) reçoit toutes les chaînes des sources choisies, les autres uniquement les chaînes de leur ensemble. Une requête provenant du nœud lui-même (d’une adresse locale) reçoit toutes les chaînes sans compte — sur ce chemin seulement.

L’export est constitué sur le serveur et mis en cache jusqu’à ce que les données de ses sources ou les paramètres changent, mais pas plus de 5 minutes. Une nouvelle requête du même contenu avec l’en-tête If-None-Match reçoit la réponse 304. Un gros export incluant des jours passés prend plusieurs minutes ; un seul export avec émissions est constitué à la fois, les autres attendent. Si l’export ne peut pas être constitué tout de suite (le service s’arrête, une source est en cours de suppression, la file d’attente est occupée), le serveur répond 503 avec l’en-tête Retry-After: 30. Le format de /xmltv ne change pas.

Programme quotidien en JSON

Pour les interfaces middleware, le nœud fournit le programme d’une chaîne pour une journée par une seule requête à l’API HTTP au format JSON (l’autorisation est la même que pour les autres requêtes de l’API):

GET /data/epg/channel?src=<source>&ch=<chaîne>&lang=<langue>&t=<heure>

La réponse est la liste des événements de la journée (en UTC) qui contient l’heure t : début, fin, titre et description de chaque émission dans la langue demandée ; si la traduction est absente, la langue par défaut est utilisée, puis toute langue disponible. Depuis la version 2.0.2.418, une émission dotée d’une classification par âge la comporte aussi, sous forme d’objet rating : age (l’âge en années, 16 pour la classification 16+, 0 pour 0+) et system (le système de classification du fichier XMLTV ou le code de pays DVB, s’il est connu). La classification provient de l’élément <rating> du fichier XMLTV ou de la classification parentale DVB EIT ; si une émission en a plusieurs, l’âge le plus élevé est fourni. Une émission sans classification n’a pas cet objet.

Depuis la version 2.0.2.419, le sous-titre de l’émission (l’élément <sub-title> du fichier XMLTV, par exemple le titre de l’épisode) est fourni dans un champ sub distinct, dans la langue du titre, et title ne contient plus le sous-titre. Jusqu’à la version 2.0.2.418 incluse, le sous-titre était ajouté au titre : Journal. Épisode 1. Une émission sans sous-titre n’a pas de champ sub.

Seul un sous-titre dans la langue du titre ou sans langue indiquée est fourni séparément. Un sous-titre dans une autre langue (par exemple, un sous-titre anglais sous un titre russe) est toujours ajouté au titre et n’a pas de champ propre. Si une émission a deux sous-titres — l’un dans la langue du titre, suivi d’un sous-titre étranger —, le champ distinct contient les deux, séparés par un point : A. B.

La distribution habituelle /xmltv, l’EIT en sortie et l’interface web affichent toujours le titre avec le sous-titre. Après la mise à jour du nœud, la base EPG est complétée sur place, sans perte de données ; les sous-titres apparaissent après la prochaine mise à jour de chaque source.

Une journée vide constitue une liste vide valide. Les réponses sont mises en cache par le serveur et actualisées automatiquement à l’arrivée de nouvelles données EPG.

Le cache intégré est prévu pour environ un millier de clients simultanés ; pour les installations plus importantes, il est recommandé de placer aussi bien la distribution XMLTV que la distribution JSON derrière un proxy inverse à cache ou un CDN.

La lecture de l’archive DVR à partir d’un événement du programme des émissions (paramètre epg dans l’URL de lecture) est décrite dans Lecture de l’archive (VOD).