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 habitual fica em https://tv.example.com/playback/tv/playlist.m3u8, e a IPTV em https://tv.example.com/playback/tv/iptv.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.

Lista para reprodutores IPTV¶

A lista habitual é para reprodutores que aceitam um endereço relativo e seguem redirecionamentos. Alguns reprodutores IPTV, ao importar um M3U, ficam só com endereços absolutos http:// e https:// e esperam de imediato um HLS ao vivo na forma /{stream}/index.m3u8. Um link de emissão eles não contam como canal — a lista chega vazia.

Para eles a Catena entrega um segundo arquivo em /playback/tv/iptv.m3u8. É um formato de lista compatível com o Flussonic: qualquer reprodutor que funcionasse com o esquema do Flussonic continuará a funcionar com iptv.m3u8. Os mesmos canais, outras linhas:

#EXTINF:-1 tvg-id="ch_992YXaVtjYS" tvg-name="News 24" tvg-chno="1",News 24
http://tv.example.com/news/index.m3u8?token=<permissão>

• O endereço é absoluto: o reprodutor vê um canal sem completar o caminho.
• A cauda é HLS ao vivo index.m3u8. A Catena aceita esse caminho e redireciona para a reprodução.
• Na URL vai uma permissão de reprodução, não o token do assinante: o arquivo vive horas, não semanas. Quando os links deixam de reproduzir, o assinante baixa a lista de novo.
• Se o stream tiver arquivo, a entrada traz catchup="fs" e catchup-days — o reprodutor monta a janela de catch-up a partir do endereço ao vivo. Sem arquivo esses atributos não aparecem.

O guia de programação é o mesmo para as duas listas: o mesmo XMLTV.

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 na lista habitual é montado pelo próprio reprodutor, com os limites do programa que vêm no XMLTV. Na lista IPTV a janela é declarada na entrada se o stream tiver arquivo. 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. A lista IPTV também se baixa de novo quando a permissão dos links acaba.

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.

Cenário: o reprodutor baixou a lista, mas não mostra canais¶

1. Com o mesmo token, monte o endereço IPTV: https://<endereço da instalação>/playback/tv/iptv.m3u8?token=<token>.
2. Confira no navegador: o arquivo deve conter endereços absolutos http://…/index.m3u8.
3. O XMLTV não muda — o assinante continua precisando do mesmo link do guia de programação.

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.