Como reconhecer a falha CORS
| Verificar | Sintoma | Significado |
|---|---|---|
| Manifesto bloqueado | A solicitação .m3u8 falha antes do início da reprodução. | A origem precisa de Access-Control-Allow-Origin ou o jogador precisa de um proxy. |
| Chave bloqueada | O manifesto é carregado, mas a reprodução criptografada falha. | A chave AES-128 URL também deve permitir CORS ou rotear através do mesmo proxy. |
| Segmentos bloqueados | A reprodução é iniciada e, em seguida, armazenada em buffer ou parada. | Cada solicitação de segmento .ts ou .m4s precisa do mesmo caminho CORS. |
| VLC funciona, o navegador falha | A reprodução na área de trabalho funciona, mas a reprodução na web não. | Isso geralmente confirma um problema CORS do navegador, não um fluxo quebrado. |
| Falha na simulação | Cabeçalhos personalizados acionam uma solicitação OPTIONS que a origem rejeita. | Evite cabeçalhos desnecessários ou configure o proxy/Origem para lidar com OPTIONS. |
Como corrigir ou testar um erro HLS CORS
- 1
Verifique se o manifesto carrega
Abra o M3U8 URL ou cole-o no player. Se a solicitação de manifesto for bloqueada por CORS, a reprodução não poderá sequer ser iniciada.
- 2
Compare com VLC
Se VLC puder reproduzir o mesmo URL, mas o navegador não puder, o stream provavelmente está acessível e a falha é o controle de acesso do navegador.
- 3
Habilite o proxy CORS inteligente
Ative o proxy para que manifestos, chaves de criptografia e segmentos de mídia percorram uma resposta que o navegador possa ler.
- 4
Execute o relatório de saúde
Use o validador através do proxy para verificar se os segmentos estão realmente ativos em vez de apenas bloqueados por CORS.
- 5
Adicione Referer somente quando necessário
Se a origem usar proteção de hotlink, defina a página original URL como Referer. Não adicione cabeçalhos personalizados, a menos que a origem exija.
Por que HLS precisa de CORS em mais de um URL
Um jogador HLS não busca apenas um arquivo. Ele busca um manifesto mestre, uma ou mais listas de reprodução de mídia, chaves de criptografia para fluxos AES-128 e muitos segmentos URLs. Um único cabeçalho CORS ausente em qualquer um desses recursos pode interromper a reprodução, portanto, testar apenas a primeira resposta .m3u8 não é suficiente.
O que Access-Control-Allow-Origin deve fazer
Para streams públicos, a origem pode enviar Access-Control-Allow-Origin para o site que hospeda o player ou usar um curinga quando as credenciais não estiverem envolvidas. Para streams privados, mantenha a origem bloqueada e use um endpoint de proxy controlado para teste. Evite misturar URL diretos e proxy na mesma sessão HLS.
Por que um proxy é útil para depuração
Um proxy permite que o navegador solicite HLS ativos de sua própria origem permitida, enquanto o proxy busca o manifesto real, a chave e o segmento URLs. Isso torna possível saber se um fluxo está interrompido ou apenas bloqueado pela política do navegador. Também oferece um local para adicionar Referer ou User-Agent quando a origem exigir.
Ferramentas de depuração de fluxo relacionadas
- M3U8 solução de problemas de links cobre CORS, Referer, segmentos mortos, limites de codec e DRM.
- Jogador Referer M3U8 personalizado explica fluxos protegidos por hotlink que precisam de cabeçalhos encaminhados.
Perguntas frequentes
O que causa um erro HLS CORS?
Um erro HLS CORS ocorre quando o navegador não consegue ler o manifesto M3U8, a chave de criptografia ou os segmentos de mídia porque a origem não permitiu acesso entre origens. VLC ainda pode reproduzir o stream porque CORS é aplicado pelos navegadores.
Por que meu stream M3U8 é reproduzido no VLC, mas não no Chrome?
VLC não é restrito pelas verificações CORS do navegador. Se VLC funcionar e o Chrome falhar, o fluxo geralmente estará acessível, mas o navegador não poderá ler uma ou mais solicitações HLS sem cabeçalhos CORS ou um proxy.
Um proxy CORS pode corrigir a reprodução de M3U8?
Sim, para teste e depuração. O proxy deve rotear o manifesto, as listas de reprodução de mídia, as chaves e os segmentos para que cada solicitação HLS venha de uma origem que o navegador possa ler.
Os segmentos HLS precisam de cabeçalhos CORS?
Sim. O manifesto, as playlists secundárias, as chaves e todos os segmentos de mídia precisam ser legíveis pelo navegador. Um fluxo pode falhar mesmo se o arquivo .m3u8 de nível superior tiver cabeçalhos CORS corretos.
Isso é o mesmo que proteção de hotlink?
Não. CORS é uma regra de acesso do navegador. A proteção de hotlink é uma regra de origem que pode exigir um Referer ou User-Agent específico. Alguns fluxos têm ambos os problemas, então você pode precisar de um proxy mais um Referer correspondente.