EPG para middleware OTT

O guia de programação da base de dados EPG é fornecido a sistemas externos — set-top boxes, aplicativos e OTT middleware — de duas formas: como documento XMLTV completo, por um servidor EPG dedicado, e como programação diária de um canal em JSON, pela API HTTP do nó.

Fornecimento de XMLTV

O XMLTV é distribuído por um servidor EPG integrado separado. Ele é ativado na tela «Servidor EPG» (Servidor EPG): «Ativar servidor EPG», a porta HTTP (43973 por padrão), se necessário HTTPS com certificado (porta 43983 por padrão) e o «Nome do anfitrião». A ativação e a desativação têm efeito imediato, sem reiniciar o serviço; um servidor desativado não abre nem a porta HTTP nem a HTTPS.

O acesso é feito por contas (aba «Contas» da tela «Configurações EPG», Configurações EPG): login e senha, «Conjunto de canais», «Data de fim» de validade, «IP permitido» e o indicador «Suspenso». A composição do fornecimento é determinada pelo conjunto de canais:

  • os conjuntos são criados na aba «Conjuntos de canais»;

  • os canais são incluídos nos conjuntos na base de dados EPG (Base de dados EPG); um canal pode pertencer a vários conjuntos;

  • a cada conta é atribuído um único conjunto — sem ele o fornecimento fica vazio;

  • um conjunto atribuído a uma conta não pode ser excluído; ao excluir um conjunto, o seu conteúdo também é excluído.

O documento está disponível no caminho /xmltv (e /xmltv.gz — arquivo compactado); a autorização é feita por HTTP Digest ou por parâmetros da requisição. As horas dos programas são fornecidas com o fuso horário do canal; apenas os eventos atuais e futuros são incluídos no documento. Se o mesmo identificador de canal tiver chegado de fontes diferentes, o canal é fornecido uma única vez, e a omissão é registrada no log. Desde a versão 2.0.2.418, junto com o canal também são omitidos os seus programas; antes, eles entravam no documento com o identificador do canal fornecido, ao lado dos programas dele, e um programa podia se repetir.

Exportação completa com dados de vinculação

Desde a versão 2.0.2.418, o servidor EPG também fornece uma exportação XMLTV completa para vincular os canais transmitidos ao guia de programação: o caminho /xmltv-src (e /xmltv-src.gz — arquivo compactado). Diferentemente de /xmltv, ela inclui os canais de todas as fontes (ou das selecionadas), com os dados pelos quais um canal é vinculado à sua fonte:

  • o identificador do canal na exportação é <fonte>:<canal>; ele é único mesmo que o mesmo canal exista em várias fontes;

  • cada canal traz o número e o nome da fonte (src-id, src-name), o identificador próprio do canal no arquivo XMLTV (channel-id, a chave de vinculação), o identificador adicional (channel-id2), se definido, o fuso horário (time-zone) e a hora de término do último programa (last-stop);

  • todos os nomes e ícones do canal; o canal é fornecido mesmo sem programas, e um canal sem nome recebe um nome igual ao seu identificador;

  • as horas dos programas estão em UTC (+0000): o fuso horário do canal não é aplicado e é transmitido como atributo; cada programa traz todos os seus títulos, descrições, gêneros e classificações etárias. Desde a versão 2.0.2.419, o subtítulo do programa (por exemplo, o título do episódio) é fornecido em um elemento <sub-title> separado, e <title> vem sem ele; qual subtítulo é separado está descrito abaixo, em Programação diária em JSON.

Parâmetros da requisição:

  • src — all (padrão) ou números de fontes separados por vírgula; 0 é a fonte integrada «importação de fluxos». Fontes desativadas e números desconhecidos são ignorados;

  • programmes — 1 (padrão) fornece canais e programas; 0, apenas o catálogo de canais;

  • days-back — 0 (padrão) fornece os programas atuais e futuros, como /xmltv; N, a partir da meia-noite UTC de N dias atrás, mas não além do prazo de retenção do histórico («Manter histórico, dias», Configuração das fontes).

Um valor de parâmetro inválido é rejeitado com o código 400. O acesso é por contas do servidor EPG, como em /xmltv: uma conta com o indicador all-channels (no arquivo de configuração ou pela API; desde a versão 2.0.2.419, a chave «Todos os canais em /xmltv-src», Configurações EPG) recebe todos os canais das fontes selecionadas; as demais, apenas os canais do seu conjunto. Uma requisição do próprio nó (de um endereço local) recebe todos os canais sem conta — somente neste caminho.

A exportação é montada no servidor e fica em cache até que mudem os dados das suas fontes ou as configurações, mas não por mais de 5 minutos. Uma requisição repetida do mesmo conteúdo com o cabeçalho If-None-Match recebe a resposta 304. Uma exportação grande com dias passados leva minutos para ser montada; apenas uma exportação com programas é montada por vez, e as demais aguardam. Se não for possível montar a exportação agora (o serviço está parando, uma fonte está sendo excluída, a fila está ocupada), o servidor responde 503 com o cabeçalho Retry-After: 30. O formato de /xmltv não muda.

Programação diária em JSON

Para as interfaces de middleware, o nó devolve a programação de um canal para um dia em uma única requisição à API HTTP em formato JSON (a autorização é a mesma das demais requisições da API):

GET /data/epg/channel?src=<fonte>&ch=<canal>&lang=<idioma>&t=<hora>

É devolvida a lista dos eventos do dia (em UTC) em que cai a hora t: início, fim, título e descrição de cada programa no idioma solicitado; se não houver tradução, é usado o idioma padrão e, em seguida, qualquer um disponível. Desde a versão 2.0.2.418, um programa com classificação etária também a traz, como objeto rating: age (a idade em anos, 16 para a classificação 16+, 0 para 0+) e system (o sistema de classificação do arquivo XMLTV ou o código de país DVB, se conhecido). A classificação vem do elemento <rating> do arquivo XMLTV ou da classificação parental do DVB EIT; se um programa tiver várias, é fornecida a maior idade. Um programa sem classificação não tem esse objeto.

Desde a versão 2.0.2.419, o subtítulo do programa (o elemento <sub-title> do arquivo XMLTV, por exemplo o título do episódio) é fornecido em um campo sub separado, no idioma do título, e title já não inclui o subtítulo. Até a versão 2.0.2.418, inclusive, o subtítulo era acrescentado ao título: Notícias. Episódio 1. Um programa sem subtítulo não tem o campo sub.

Só é fornecido separadamente o subtítulo no idioma do título ou sem idioma indicado. Um subtítulo em outro idioma (por exemplo, um em inglês sob um título em russo) continua sendo acrescentado ao título e não tem campo próprio. Se um programa tiver dois subtítulos — um no idioma do título e, em seguida, um estrangeiro —, o campo separado contém os dois, unidos por um ponto: A. B.

O fornecimento normal /xmltv, a EIT de saída e a interface web continuam mostrando o título junto com o subtítulo. Após a atualização do nó, a base de dados EPG é complementada no próprio local, sem perda de dados; os subtítulos aparecem após a próxima atualização de cada fonte.

Um dia sem eventos é uma lista vazia válida. As respostas ficam em cache no servidor e são atualizadas automaticamente quando chegam novos dados EPG.

O cache integrado está dimensionado para cerca de mil clientes simultâneos; em instalações maiores, recomenda-se colocar tanto o fornecimento em XMLTV quanto o fornecimento em JSON atrás de um proxy reverso com cache ou de uma CDN.

A reprodução do arquivo DVR por evento do guia de programação (o parâmetro epg na URL de reprodução) está descrita em Reprodução do arquivo (VOD).