Configuração
Estrutura de um arquivo M3U: anatomia de uma lista IPTV
Entenda a estrutura de um arquivo M3U/M3U8: #EXTM3U, #EXTINF, títulos de grupo e logos. A anatomia de uma lista IPTV explicada de forma simples.
Entender a estrutura interna de um arquivo M3U ajuda a diagnosticar problemas de exibição, como um logo que não aparece ou um canal na categoria errada, e a perceber o que o aplicativo faz quando “carrega” uma lista. Este guia explica cada linha, sem exigir conhecimento técnico prévio.
O que é exatamente um arquivo M3U?
Um arquivo M3U é um arquivo de texto simples, não um vídeo, que faz referência a uma série de streams ou arquivos de mídia. O formato existe desde o início do MP3 e foi depois adotado para a transmissão de vídeo; continua sendo um dos formatos de lista de reprodução mais suportados pelos players de mídia atuais, conforme documentado na Wikipédia. Quando um aplicativo “abre” um URL M3U, ele baixa esse arquivo de texto e interpreta cada linha para montar a lista de canais exibida na tela, como mostra o diagrama acima.
O que é o cabeçalho #EXTM3U?
O cabeçalho #EXTM3U é a primeira linha de toda lista M3U estendida e avisa ao player que o arquivo aceita metadados como nome, logo e categoria. Ele ocupa sempre a primeira posição do arquivo:
#EXTM3U
O cabeçalho avisa ao player que se trata de um arquivo M3U estendido, um formato que aceita os metadados adicionais descritos abaixo. Um arquivo M3U básico, sem esse cabeçalho, fica limitado a uma lista simples de URLs, sem nomes nem logos.
Para que serve a linha #EXTINF?
A linha #EXTINF precede cada canal e reúne as informações descritivas dele: a duração, os atributos opcionais (identificador, logo e categoria) e o nome exibido. Esta é a estrutura típica:
#EXTINF:-1 tvg-id="canal1" tvg-logo="https://exemplo.com/logo.png" group-title="Esportes",Nome do canal
https://servidor-exemplo.com/live/canal1/index.m3u8
Três elementos compõem essa linha:
- A duração (
-1para uma transmissão ao vivo, sem duração definida; um valor positivo indicaria a duração em segundos para conteúdos sob demanda). - Os atributos opcionais:
tvg-id(identificador usado para associar um guia de programação),tvg-logo(URL da imagem do logo) egroup-title(categoria exibida, por exemplo, “Esportes” ou “Filmes”). - O nome exibido, colocado depois da vírgula final.
A linha seguinte contém o URL do próprio stream: é esse o endereço que o player usa para iniciar a reprodução quando o canal é selecionado.
Para que serve o título de grupo (group-title)?
O atributo group-title determina a categoria em que um canal aparece nos aplicativos que o utilizam. Sem esse atributo, ou se o player não o suportar, todos os canais costumam aparecer em uma lista única, sem categorias. Por isso, a mesma lista M3U pode parecer mais bem organizada em um aplicativo do que em outro: a organização depende de como cada player interpreta o atributo, não da lista de reprodução em si.
M3U ou M3U8: qual é a diferença?
A diferença entre as duas extensões está apenas na codificação de caracteres. Um arquivo .m3u8 usa UTF-8, necessário para exibir corretamente acentos e caracteres não latinos nos nomes dos canais. O formato M3U8 estendido também é usado pela transmissão adaptativa HLS, ou transmissão ao vivo por HTTP, na qual cada lista de reprodução aponta para segmentos de vídeo sucessivos, em vez de um único fluxo contínuo, como descrito na Wikipédia. No uso comum de IPTV, essa distinção é transparente: quase todos os aplicativos atuais aceitam as duas extensões sem distinção.
Como um player abre um URL M3U?
Alguns aplicativos, como o VLC, conseguem abrir um URL M3U direto pelo menu de reprodução em rede, sem uma tela de login dedicada à IPTV, uma abordagem documentada na documentação oficial do VideoLAN. Outros aplicativos de IPTV, como o IPTV Smarters Pro, têm uma tela específica para colar o URL M3U e acrescentam a própria interface à estrutura descrita aqui.
Como diagnosticar um problema pela estrutura?
Conhecer essa estrutura ajuda a entender a origem de certos problemas de exibição:
- Logo ausente: o URL informado em
tvg-logoestá indisponível ou inacessível a partir da sua rede. - Canal na categoria errada ou sem categoria: falta o atributo
group-titlena linha#EXTINFou o player não o utiliza. - A lista não carrega: o problema costuma estar no URL principal ou na conexão, não na estrutura interna do arquivo. Veja nosso guia caso a lista M3U não carregue.
Depois de entender a estrutura, nosso artigo sobre gerenciar uma lista M3U explica como organizar, atualizar e manter a lista legível ao longo do tempo.
Em resumo
Um arquivo M3U é um arquivo de texto com uma estrutura simples: um cabeçalho, seguido de pares de linhas #EXTINF/URL que descrevem cada canal. Entender essa anatomia ajuda a interpretar o comportamento do aplicativo e a distinguir um problema da lista de reprodução de um problema de rede. Para escolher entre esse método e uma conexão Xtream Codes, veja nosso artigo sobre códigos M3U ou Xtream.
Perguntas frequentes
Qual é a diferença entre .m3u e .m3u8?
Os dois seguem a mesma estrutura. A extensão .m3u8 indica apenas que o arquivo usa a codificação UTF-8, necessária para exibir corretamente acentos e caracteres especiais, por exemplo em nomes de canais de vários idiomas. A maioria dos aplicativos de IPTV atuais aceita os dois formatos sem distinção.
Para que serve a linha #EXTM3U no início do arquivo?
É o cabeçalho obrigatório que identifica o arquivo como uma lista M3U estendida. Sem essa linha na primeira posição, a maioria dos players não reconhece o arquivo como uma lista de reprodução válida.
O que significa o título de grupo em uma linha #EXTINF?
É um atributo opcional que indica a categoria de um canal (por exemplo, “Esportes”, “Filmes” ou “Notícias”). Os aplicativos compatíveis usam esse atributo para organizar a lista por temas automaticamente, em vez de mostrar todos os canais juntos.
Por que alguns logos de canais não aparecem?
O logo vem de um URL informado no atributo tvg-logo da linha #EXTINF. Se esse URL estiver ausente, expirado ou bloqueado pela rede, o player mostra um ícone padrão no lugar do logo.
É possível abrir e reproduzir um arquivo M3U em um editor de texto simples?
Dá para abrir, mas não para reproduzir. Um arquivo M3U é texto simples e pode ser inspecionado em qualquer editor; só um aplicativo compatível (VLC, TiviMate, IPTV Smarters Pro, etc.) consegue reproduzir os streams a que o arquivo faz referência.
O arquivo M3U contém o vídeo diretamente?
Não. Ele contém apenas endereços (URLs) que apontam para streams de vídeo hospedados em um servidor remoto, além de metadados (nome, logo e categoria). O arquivo em si ocupa apenas alguns quilobytes, independentemente do tamanho do catálogo referenciado.
