Mostrar a câmera ao vivo

O caminho inteiro tem duas chamadas: descobrir a câmera e pedir o endereço do vídeo. O resto é o player.

Liste as câmeras da conta

curl -s -H "Authorization: Bearer $PICTOR_KEY" \
  "$PICTOR_API/api/devices?limit=100"

Guarde o device_id de cada uma — é o identificador que todas as outras rotas aceitam.

Peça o endereço do vídeo, no momento de exibir

curl -s -H "Authorization: Bearer $PICTOR_KEY" \
  "$PICTOR_API/api/devices/CAM-001/media-url"

{
  "device_id": "CAM-001",
  "device_uuid": "0b8f…",
  "whep_url": "https://app.pictor.cloud/media/s1/api/webrtc?src=CAM-001&exp=…&t=…",
  "hls_url":  "https://app.pictor.cloud/media/s1/api/stream.m3u8?src=CAM-001&exp=…&t=…",
  "expires_in": 600
}

Toque

whep_url é WebRTC (sub-segundo). hls_url é o plano B, e você vai precisar dele — veja o orçamento de 5 segundos, abaixo.

As duas URLs vêm absolutas e completas. Use-as como vieram: não junte com o endereço da API e não reescreva o host. O vídeo é servido por um endereço diferente do da API, e a assinatura é calculada sobre a URL inteira.

O player, inteiro

WHEP é WebRTC com uma única troca HTTP: você faz POST da sua oferta SDP no whep_url, recebe a resposta SDP no corpo, e o vídeo começa. Não precisa de biblioteca. Este é o mesmo caminho que o console do Pictor usa em produção — inclusive as duas decisões que não são óbvias e estão comentadas abaixo.

<video id="cam" autoplay muted playsinline controls></video>

<script>
// O console do Pictor usa 5 s. Passado esse tempo sem PRIMEIRO QUADRO, ele
// desiste do WebRTC e vai para o HLS.
const ORCAMENTO_MS = 5000;

async function abrir(deviceId) {
  // O endereço vem do SEU backend, nunca do navegador: a chave de API não pode
  // ir para o cliente. Veja "Onde a chave mora", abaixo.
  const r = await fetch(`/minha-api/cameras/${deviceId}/url`);
  if (!r.ok) return mostrarFalha(await r.json());
  const { whep_url, hls_url } = await r.json();

  try {
    await tocarWhep(whep_url);
  } catch (motivo) {
    console.warn('WebRTC não rendeu:', motivo, '— caindo para HLS');
    await tocarHls(hls_url);
  }
}

function tocarWhep(url) {
  return new Promise((ok, falhou) => {
    const video = document.getElementById('cam');
    const pc = new RTCPeerConnection();
    let relogio;

    const desistir = (motivo) => {
      clearTimeout(relogio);
      pc.close();
      falhou(motivo);
    };

    // PRIMEIRO QUADRO é a única definição honesta de "funcionou".
    // `connectionState: 'connected'` NÃO garante imagem: a conexão sobe, o
    // vídeo não decodifica, e o operador fica olhando um retângulo preto com o
    // status verde. Quem resolve o timer é o evento `playing`.
    video.addEventListener('playing', () => { clearTimeout(relogio); ok(pc); }, { once: true });

    pc.addTransceiver('video', { direction: 'recvonly' });
    pc.addTransceiver('audio', { direction: 'recvonly' });
    pc.ontrack = (ev) => {
      if (!video.srcObject) {
        video.srcObject = ev.streams[0];
        video.play().catch(() => {});
      }
    };
    pc.onconnectionstatechange = () => {
      if (pc.connectionState === 'failed' || pc.connectionState === 'closed') {
        desistir('peer_failed');
      }
    };

    (async () => {
      // Manda a oferta SEM esperar o ICE terminar. Os candidatos continuam
      // chegando depois da resposta; esperar aqui só adia o primeiro quadro.
      const oferta = await pc.createOffer();
      await pc.setLocalDescription(oferta);

      const resp = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/sdp' },
        body: pc.localDescription.sdp ?? '',
      });
      if (!resp.ok) return desistir(`whep_http_${resp.status}`);

      await pc.setRemoteDescription({ type: 'answer', sdp: await resp.text() });
      relogio = setTimeout(() => desistir('sem_primeiro_quadro'), ORCAMENTO_MS);
    })().catch(() => desistir('negociacao'));
  });
}

async function tocarHls(url) {
  const v = document.getElementById('cam');
  // Safari e iOS tocam HLS nativo; o resto precisa de hls.js.
  if (v.canPlayType('application/vnd.apple.mpegurl')) { v.src = url; return; }
  const { default: Hls } = await import('https://cdn.jsdelivr.net/npm/hls.js@1/+esm');
  const hls = new Hls({ lowLatencyMode: true });
  hls.loadSource(url);
  hls.attachMedia(v);
}
</script>

O orçamento de 5 segundos, e por que o HLS não é opcional

Trate o HLS como caminho de produção, não como remendo. Numa portaria com dezenas de câmeras de fabricantes diferentes, uma parte delas não vai render por WebRTC — e o sintoma, quando você não tem o plano B pronto, é o operador esperando cinco segundos por tile.

O motivo é o perfil de vídeo. O WebRTC negocia o formato antes de o vídeo começar, e o que o decodificador de hardware do dispositivo aceita não é o mesmo em toda câmera. Quando a negociação fecha num formato que aquele aparelho não decodifica, a conexão sobe e a imagem não vem — que é exatamente o caso em que connectionState mente e só o primeiro quadro conta. Consequências práticas para o seu código:

Meça o primeiro quadro, não a conexão. É o número que diz se a portaria está usável.
Tenha o hls_url em mão antes de tentar o WHEP. Ele vem na mesma resposta — não custa uma segunda chamada.
Não faça retry de WHEP. Se não rendeu, não vai render nesta câmera neste aparelho: vá para o HLS e fique nele.

Onde a chave mora

A chave de API nunca vai para o navegador. Ela é uma credencial de conta: quem a tem lê o inventário inteiro, o diagnóstico e o vídeo.

O desenho é sempre este:

navegador  ──►  seu backend  ──►  Pictor Cloud
              (guarda a chave)     (devolve a URL assinada)

O endereço que o seu backend repassa ao navegador já é seguro de trafegar: ele carrega a própria assinatura e vence sozinho. É por isso que ele existe — para você entregar vídeo sem entregar credencial.

Quando não abre

A rota não devolve 200 com um endereço mudo. Quando não há como preparar a transmissão, ela responde 502 com a causa nomeada:

{
  "detail": "Não foi possível determinar de onde puxar a imagem desta câmera.",
  "code": "stream_unresolvable",
  "diagnostics_url": "/api/devices/CAM-001/diagnostics"
}

`code`	O que aconteceu	O que fazer
`stream_unresolvable`	não sabemos de onde puxar a imagem desta câmera	o cadastro está incompleto — siga o `diagnostics_url`
`stream_register_failed`	sabemos de onde puxar, e a preparação falhou	pode ser transitório; o diagnóstico diz em qual elo parou

function mostrarFalha(erro) {
  // `detail` é escrito para o operador ler. Mostre-o; não traduza.
  const acao = erro.diagnostics_url ? 'Ver diagnóstico' : 'Tentar novamente';
  render(erro.detail, acao);
}

Não faça retry em laço nesta rota. Ela tem teto próprio, bem abaixo do teto geral da chave, porque cada emissão acorda uma sessão de vídeo — e sessão de vídeo é CPU no servidor de mídia, contada em sessões simultâneas. Um laço aqui não degrada a API: apaga o vídeo da conta inteira. Falhou, vá para o diagnóstico.

O prazo

expires_in é o prazo da assinatura da URL, em segundos — não o prazo do vídeo. Passado ele, o endereço deixa de abrir e você pede outro. Peça a URL quando for exibir. Pedir em lote, para as 40 câmeras do condomínio, e guardar para quando o operador clicar, não economiza chamada nenhuma: entrega 39 endereços vencidos e queima o teto de mídia da conta.

Do zero ao vídeo na tela

Quando a câmera não abre

O que aconteceu

Montar a tela da portaria

O player, inteiro

O orçamento de 5 segundos, e por que o HLS não é opcional

Onde a chave mora

Quando não abre

O prazo

​O player, inteiro

​O orçamento de 5 segundos, e por que o HLS não é opcional

​Onde a chave mora

​Quando não abre

​O prazo

O player, inteiro

O orçamento de 5 segundos, e por que o HLS não é opcional

Onde a chave mora

Quando não abre

O prazo