XonaPlayXonaPlay
Ver MarkdownAbrir no ClaudeAbrir no ChatGPT

Reprodução

Uma única regra: ninguém monta URLs de vídeo na mão. Você pede GET /v1/videos/{id}/playback e passa hls_url para o seu player. Nosso próprio dashboard funciona do mesmo jeito.

Quando chamar

Chame /playback quando o player abrir, nunca antes. No Strict, um link tem dez minutos para começar; um link preparado com antecedência pode já estar morto quando o espectador apertar play.

Você chama a partir de Use para
Sua página web ou app, sem key Vídeos públicos em Open ou Protected
Seu backend, com a secret key Vídeos privados e workspaces em Strict

Parâmetros de query opcionais:

  • viewer_id: um id opaco seu (o id do seu usuário, uma vaga de curso). Ele viaja dentro do link e chega aos nossos logs, então um link vazado pode ser rastreado até quem o recebeu.

O que você recebe

Campo O que é
hls_url Playlist mestre. Passe para o player. null se renderiza ou é original.
original_url O original intacto. Mesma expiração e segurança do hls_url.
poster_url Imagem fixa para o poster do player, ou null.
thumbnails_url Sprite WebVTT para as prévias de seek, ou null.
embed_url Nosso player hospedado (iframe). No Strict só funciona com esta URL exata.
expires_at Quando o link para de funcionar (ISO 8601), ou null no Open.
security O nível aplicado: open, protected, strict ou maximum.
delivery hls ou original. Veja abaixo.
duration_sec Duração do vídeo em segundos.

O token vive no path (/hls/t/{token}/…) porque o AVPlayer, o Chromecast e os apps nativos não conseguem enviar headers. Todo playlist e segmento sob esse path já está assinado; você nunca assina nada por conta própria.

Original ou HLS

Todo vídeo guarda o arquivo original exatamente como você o enviou ou importou. Nunca transcodificamos o original. Você escolhe um delivery ao enviar ou importar:

  • hls (padrão): a XonaPlay renderiza HLS adaptativo a partir do original. Reproduza hls_url.
  • original: nenhuma transcodificação. O original é o que você reproduz e baixa. Use original_url.

Enquanto o HLS ainda está sendo renderizado, hls_url é null e original_url já funciona. original_url aceita requisições por byte-range. Com original, hls_url é sempre null.

A XonaPlay garante hls_url em todos os dispositivos. Quais players conseguem reproduzir original_url depende do formato: mp4 com H.264 funciona em quase todos; mkv e HEVC podem não funcionar. Essa escolha é sua.

Sem HLS, poster_url e thumbnails_url são null, a menos que o dono do vídeo tenha definido um poster próprio.

Vídeos guardados no seu próprio servidor (BYO) retornam original_url: null.

Para passar um vídeo enviado com original para HLS, envie PATCH /v1/videos/{id} com "delivery": "hls". A mudança só vai em um sentido, e o original_url continua funcionando nesse meio-tempo.

Expiração

Nível O link funciona por
Open Para sempre
Protected Duração do vídeo + 1 hora (2 a 24 horas)
Strict 10 minutos para começar, depois duração do vídeo + 30 minutos (1 a 24 horas)

Uma aba pausada pode durar mais que o seu link. Isso é esperado: o player se recupera.

Regra do "Recarregar"

Toda receita nestes docs segue os mesmos quatro passos:

  1. Diante de qualquer erro fatal do player (um 403 em um segmento, um erro de rede, um erro de decodificação), chame /playback de novo — no máximo uma vez por minuto — e retome no mesmo segundo.
  2. Se a resposta trouxer hls_url, carregue-a e dê seek de volta.
  3. Se a resposta for um erro, mostre sua message. Ofereça o botão Recarregar só quando o code for reexecutável (veja a tabela abaixo).
  4. Se o player falhar de novo dentro de 60 segundos, não chame nada: mostre Recarregar, que volta ao passo 1.

A decisão vem do JSON de /playback, que qualquer cliente HTTP consegue ler. Não dependa de headers HTTP do host do vídeo: o AVPlayer não consegue lê-los.

Erros

Os erros usam o mesmo envelope do resto da API:

json
{ "status": "error", "code": "KEY_REQUIRED", "message": "This video needs a secret key." }
code HTTP Tentar de novo?
NOT_FOUND 404 Não
KEY_REQUIRED 401 Não. Chame pelo seu backend com a key.
INVALID_KEY 401 Não
DOMAIN_NOT_ALLOWED 403 Não
WORKSPACE_UNAVAILABLE 403 Não
ACCESS_DENIED 403 Não
VIDEO_NOT_READY 409 Sim, mais tarde
LIVE_NOT_ACTIVE 409 Sim, mais tarde
RATE_LIMITED 429 Sim, após Retry-After
5xx ou uma resposta sem JSON — Sim

O host do vídeo (não o /playback) responde a um link morto com um 401/403/503 simples e um header X-Xona-Error — TOKEN_EXPIRED, TOKEN_REVOKED, NETWORK_CHANGED, MAXIMUM_UNAVAILABLE… Ele existe para depuração; seu player só precisa seguir a regra de recarregar, e MAXIMUM_UNAVAILABLE (503) é reexecutável como os demais.

Ao vivo

As transmissões ao vivo usam o mesmo contrato:

bash
curl https://api.xonaplay.com/v1/live/{STREAM_ID}/playback

LIVE_NOT_ACTIVE significa que a transmissão ainda não entrou no ar. Tente de novo mais tarde ou mostre uma contagem regressiva.