Lista M3U e XMLTV¶

Nem todo assinante assiste na vitrine: alguns preferem o próprio reprodutor no computador, no set-top box ou no celular. Para eles a Catena entrega a mesma coisa em dois arquivos — a lista de canais em M3U e o guia de programação em XMLTV.

Os dois arquivos contêm exatamente os canais que este assinante pode assistir pela fórmula de acesso. Um canal sem stream atribuído fica de fora: não há o que reproduzir nele.

Endereços¶

Os endereços são relativos à raiz da instalação: se a vitrine abre em https://tv.example.com/tv/, a lista fica em https://tv.example.com/playback/tv/playlist.m3u8.

Qualquer um dos dois tokens serve:

• o token de reprodução do assinante — aquele que o operador vê na ficha dele, campo Token de reprodução;
• um token de dispositivo obtido ao entrar na vitrine.

A diferença está só na revogação: ao revogar um dispositivo, o link dele também se apaga, enquanto o token de reprodução vive com o próprio assinante.

O que há dentro da lista¶

Uma linha de canal fica assim:

#EXTINF:-1 tvg-id="ch_992YXaVtjYS" tvg-chno="1",News 24
/playback/tv/channels/ch_992YXaVtjYS/play?token=<token>

• tvg-id é o identificador do canal na Catena. Esse mesmo identificador está no XMLTV, então o reprodutor casa sozinho a programação com o canal.
• tvg-chno é o número do canal: com ele o reprodutor monta a ordem à qual o assinante está acostumado.

O endereço é escrito relativo à raiz do servidor, e o reprodutor o completa a partir do endereço de onde baixou a lista.

Esse endereço é um link de emissão, não uma URL de fluxo pronta. Ao abri-lo, o reprodutor recebe um redirecionamento para a reprodução com uma permissão recém-emitida. A razão são os tempos de vida: o arquivo baixado vive semanas com o assinante e uma permissão de reprodução vive horas, de modo que uma lista com a permissão embutida pararia de funcionar na mesma noite.

Daí uma consequência: o reprodutor precisa seguir redirecionamentos. Todos os comuns seguem.

O que há dentro do XMLTV¶

O arquivo traz as declarações de canais e seus programas. A janela padrão é de um dia para trás e seis para frente: o dia passado é o que o catch-up precisa, e seis dias é o próprio limite do guia.

A janela pode ser definida com os parâmetros from e to — momentos no formato RFC 3339, por exemplo ?from=2026-08-20T00:00:00Z&to=2026-08-22T00:00:00Z.

Os horários dos programas são sempre convertidos para UTC e escritos na forma XMLTV YYYYMMDDHHMMSS +0000. Um programa cujos limites não podem ser lidos é ignorado: uma única data quebrada faz o reprodutor desenhar o arquivo inteiro como uma grade vazia, e não apenas aquela linha.

A programação vem do guia de programação. Se ele estiver vazio, o XMLTV chega com as declarações de canais e sem programas — e isso se resolve na fonte, não na exportação.

Limites¶

• O limite de telas vale aqui também. Uma reprodução num reprodutor externo ocupa uma tela igual a uma na vitrine; ao bater no limite, o reprodutor recebe uma recusa (Quantas telas ao mesmo tempo).
• O catch-up é montado pelo próprio reprodutor, com os limites do programa que vêm no XMLTV. O que está gravado é decidido pelo arquivo do stream: além dele não há o que reproduzir.
• O arquivo não se atualiza sozinho. Surgiu um canal novo na assinatura, o assinante baixa a lista de novo.

Cenário: entregar ao assinante o link da lista¶

1. Abra a ficha do assinante e copie o campo Token de reprodução.
2. Monte o endereço: https://<endereço da instalação>/playback/tv/playlist.m3u8?token=<token>.
3. Confira no navegador: deve baixar um arquivo de texto começando com #EXTM3U.
4. Monte com o mesmo par o endereço do XMLTV e entregue ao assinante os dois links — o reprodutor precisa dos dois.

Se o arquivo vier vazio (só #EXTM3U), o assinante não tem nenhum canal com stream atribuído: veja o bloco Canais disponíveis na ficha dele.

O que vem a seguir¶

• Vitrine — a mesma coisa dentro do aplicativo do espectador.
• Guia de programação — de onde vem a programação do XMLTV.
• Assinantes — o token de reprodução e os canais disponíveis.