Transmissões ao vivo

O recurso de transmissão ao vivo da Video API da Vonage permite que você transmita uma sessão de vídeo para um grande público usando a transmissão ao vivo por HTTP (HLS) ou um fluxo RTMP.

Um fluxo HLS permite que mais clientes o assistam simultaneamente do que um sessão de vídeo interativa ao vivo. Por exemplo, você pode fornecer um stream HLS a um cliente se a sessão tiver atingido o limite de 15.000 conexões para transmissões interativas ao vivo. Os streams HLS suportam um número ilimitado de espectadores. Os streams RTMP são limitados pelo número de espectadores suportados pelo provedor RTMP.

Você pode usar o recurso de transmissão RTMP para enviar um fluxo de vídeo para uma plataforma compatível com transmissões RTMP, como o YouTube Live ou o Facebook.

Além disso, os clientes que não suportam WebRTC podem assistir à transmissão em HLS ou RTMP.

Uma transmissão pode incluir até 16 fluxos de vídeo da sessão (e até 50 fluxos de áudio). Se a sessão incluir mais de 16 fluxos de vídeo simultaneamente, os fluxos excedentes não serão incluídos na transmissão.

Um HLS apresenta um atraso de 15 a 20 segundos em relação às transmissões ao vivo da sessão. Durante o atraso inicial, a transmissão não está disponível. Não forneça a URL da transmissão aos clientes até que o fluxo HLS ou RTMP esteja disponível.

Para uma transmissão RTMP, a plataforma da Vonage apresenta uma latência de aproximadamente 5 segundos. No entanto, cada plataforma de transmissão RTMP (como o YouTube Live ou o Facebook) adicionará latência adicional, dependendo do processamento que realiza no vídeo antes de publicá-lo.

O recurso de streaming HLS e RTMP está disponível apenas para sessões roteadas (sessões que utilizam o Vonage Media Router). Para obter mais informações, consulte O Roteador de Mídia da Vonage e os Modos de Mídia.

A reprodução de HLS é suportada nativamente pela maioria dos navegadores modernos. Para ambientes que não oferecem suporte nativo, plug-ins como Flowplayer pode ser usado para garantir a compatibilidade entre navegadores.

As transmissões RTMP da Vonage apresentam as seguintes especificações:

Codec de vídeo H.264 baseline, nível 3.1
640 x 480 pixels (SD paisagem), 480 x 640 pixels (SD retrato), 1280 x 720 pixels (HD paisagem), 720 x 1280 pixels (HD retrato), 1920 x 1080 pixels (FHD paisagem) ou 1080 x 1920 pixels (FHD retrato), a 25 quadros por segundo
Taxa de bits constante (CBR) de 2 Mbps, com intervalo entre quadros-chave de 2 segundos
Áudio AAC de 1 canal a 128 Kbps e taxa de amostragem de 48 kHz As transmissões publicadas pelo Safari aparecem como “somente áudio” nas transmissões ao vivo.

Veja o Página de preços da Vonage para obter mais detalhes sobre os preços do streaming HLS e RTMP.

Iniciar e interromper transmissões ao vivo

Use o API REST de vídeo para iniciar e interromper a transmissão ao vivo de uma sessão e para verificar o status de uma transmissão ao vivo.

As transmissões HLS e RTMP são interrompidas automaticamente 60 segundos após o último cliente se desconectar da sessão. Além disso, há uma duração máxima padrão de 4 horas (14.400 segundos) para cada transmissão HLS e RTMP (a transmissão ao vivo é interrompida automaticamente quando essa duração é atingida). É possível alterar a duração máxima da transmissão definindo a propriedade `maxDuration` ao chamar o iniciar transmissão Método REST. É possível definir a duração máxima entre 60 segundos e 10 horas (36.000 segundos).

Observação: As transmissões ao vivo são interrompidas durante a rotação de servidores da sessão. É possível reiniciar uma transmissão em resposta a eventos de notificação de rotação de servidores. Consulte Rotação de servidores e migração de sessões.

Você pode limitar a taxa de bits máxima a ser usada na transmissão definindo o maxBitrate propriedade ao chamar o iniciar transmissão Método REST. É possível definir a taxa de bits máxima como um valor entre 100.000 e 6.000.000 de bits por segundo.

Configurando o layout de vídeo para as transmissões ao vivo

Ao usar o recurso de transmissão ao vivo, você pode personalizar o layout dos vídeos na transmissão HLS ou RTMP.

Por padrão, o recurso de transmissão ao vivo organiza os vídeos da sessão em um layout em mosaico no vídeo HLS ou RTMP composto. O layout é baseado no número de vídeos da sessão. Por exemplo, a ilustração a seguir mostra o layout quando há 1, 2, 4 ou 5 transmissões em uma sessão:

Vonage video API default layout 1

Esse layout é conhecido como “melhor ajuste”. Como alternativa, você pode escolher entre vários outros layouts predefinidos. Para os outros layouts, é preciso atribuir um nome de classe a cada fluxo de vídeo para determinar como ele aparecerá no layout. (Veja Tipos de layout predefinidos.)

Você também pode definir seus próprios layouts personalizados usando CSS. Consulte Definindo layouts personalizados.

Por padrão, o vídeo transmitido tem 640x480 pixels (SD na orientação horizontal, proporção 4:3). Os vídeos individuais são dispostos em retângulos contêineres dentro do vídeo composto. Por padrão, o vídeo é exibido com a propriedade CSS `object-fit` definida como `contain`. Por exemplo, a ilustração a seguir mostra um layout de melhor ajuste com dois vídeos SD na orientação paisagem (4:3) (1 e 4) e dois vídeos HD na orientação paisagem (16:9) (2 e 3):

Vonage Video API layout aspect ratios

Você pode modificar esse comportamento usando layouts personalizados.

Você também pode configurar uma transmissão para usar as resoluções 480x640 (SD retrato, proporção 3:4), 1280x720 (HD paisagem, proporção 16:9), 720x1280 (HD retrato, proporção de 9:16), 1920x1080 (FHD paisagem, proporção de 16:9) ou 1080x1920 (FHD retrato, proporção de 9:16) ao chamar o endpoint de início de transmissão do API REST da Vonage. Talvez seja recomendável usar a proporção retrato para transmissões que incluam fluxos de vídeo provenientes de dispositivos móveis (que geralmente utilizam essa proporção).

Especificação do tipo de layout inicial

Ao iniciar a transmissão ao vivo de uma sessão, usando o API REST, você pode, se desejar, especificar o tipo de layout inicial.

Defina o Content-Type para "application/json" e definir o tipo de layout como uma propriedade dos dados JSON enviados na solicitação POST.

{
  "sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
  "layout": {
    "type": "pip"
  }
}

Se você estiver usando um layout personalizado (consulte Definindo layouts personalizados), defina o type propriedade para "custom" e passar a folha de estilo como uma propriedade adicional — stylesheet:

{
  "sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
  "layout": {
    "type": "custom",
    "stylesheet": "stream.instructor {position: absolute; width: 100%;  height:50%;}"
  }
}

Você também pode especificar um tipo de layout a ser usado quando houver uma transmissão de compartilhamento de tela na sessão, definindo a propriedade `screenshareType` da propriedade `layout` (consulte formatos de compartilhamento de tela):

{
  "sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
  "layout": {
    "type": "bestFit",
    "screenshareType": "pip"
  },
  "name" : "archive_name",
  "outputMode" : "composed"
}

A solicitação retorna um código de resposta de erro 400 caso você especifique um tipo inválido.

Se você não especificar um tipo de layout inicial, o stream HLS ou RTMP utilizará o tipo de layout mais adequado. Se você especificar qualquer outro tipo de layout, certifique-se de aplicar as classes de layout apropriadas aos streams da sessão (consulte Atribuição de classes de layout a fluxos).

Veja Tipos de layout predefinidos.

Tipo de layout que muda dinamicamente

Alteração dinâmica do tipo de layout durante uma transmissão ao vivo É possível alterar dinamicamente o tipo de layout chamando a função /broadcast/layout Ponto de extremidade REST.

Defina o Content-Type para "application/json" e inclua o tipo de layout como uma propriedade dos dados JSON na solicitação PUT:

{
  "type": "pip"
}

Se você estiver usando um layout personalizado (consulte Definindo layouts personalizados) definir o type propriedade para "custom" e passar a folha de estilo como uma propriedade adicional — stylesheet:

{
  "type": "custom",
  "stylesheet": "stream.instructor {position: absolute; width: 100%;  height:50%;}"
}

Você também pode especificar um tipo de layout a ser usado quando houver uma transmissão de compartilhamento de tela na sessão, definindo a propriedade `screenshareType` (consulte formatos de compartilhamento de tela):

{
  "type": "bestFit",
  "screenshareType": "pip"
}

A solicitação retorna um código de resposta de erro 400 caso você especifique um tipo inválido.

Ao especificar um tipo de layout diferente do padrão “Best Fit”, certifique-se de aplicar as classes de layout adequadas aos fluxos da sessão (consulte Atribuição de classes de layout a fluxos).

Seleção dos streams a serem incluídos em uma transmissão ao vivo

Ao iniciar uma transmissão ao vivo, se você definir o streamMode para "manual", você pode escolher os streams a serem incluídos na transmissão. É possível adicionar e remover streams durante a transmissão. Além disso, você pode especificar se a transmissão incluirá o áudio ou o vídeo de um stream (ou ambos). Consulte o API REST de vídeo.

Ativação da funcionalidade de DVR em transmissões HLS

As transmissões da HLS oferecem suporte à funcionalidade de DVR, que permite aos usuários retroceder, pausar e retomar as transmissões (em reprodutores compatíveis com DVR). Você pode configurar o dvr opção de true ao iniciar uma transmissão ao vivo.

Com o DVR ativado, a URL do HLS incluirá um ?DVR sequência de consulta anexada ao final.

O recurso de DVR oferece um intervalo de duas horas para reproduzir o conteúdo transmitido. Enquanto a transmissão estiver em andamento, você pode reproduzir (e retroceder até) qualquer ponto da transmissão até duas horas antes do momento atual. A gravação do DVR fica indisponível duas horas após o término da transmissão.

Utilização de metadados de carimbo de data/hora do HLS para sincronizar eventos

O manifesto da transmissão ao vivo HTTP inclui um EXT-X-PROGRAM-DATE-TIME cabeçalho, que é definido com o carimbo de data e hora do início em tempo real da captura do segmento de streaming. Isso é definido no Especificação de transmissão ao vivo por HTTP. Isso está definido como um ISO 8601:2004 valor de data/hora, em UTC.

Por exemplo, o cabeçalho ficará assim:

#EXT-X-PROGRAM-DATE-TIME:2021-09-02T11:45:00.810+00:00

Esses carimbos de data e hora permitem sincronizar eventos em aplicativos clientes para compensar o atraso na transmissão HLS. Por exemplo, se você quiser enviar a um cliente um evento para exibir um emoji em um momento específico da transmissão de vídeo, o cliente pode usar o carimbo de data e hora para atrasar a exibição do emoji com base no atraso da transmissão recebida.

Transmissões HLS de baixa latência

Para configurar uma transmissão HLS para suportar o modo de baixa latência, defina o low-latency opção de true quando iniciar uma transmissão ao vivo.

Alguns reprodutores HLS não oferecem suporte ao modo de baixa latência.

Este recurso é incompatível com Transmissões HLS do DVR.

Transmissões simultâneas

Para iniciar simultaneamente várias transmissões ao vivo para a mesma sessão, defina o multiBroadcastTag opção ao iniciar cada transmissão ao vivo. É necessário definir isso como uma sequência de caracteres exclusiva para cada transmissão simultânea de uma sessão em andamento.

Embora seja possível especificar vários fluxos RTMP quando iniciar uma transmissão ao vivo, cada uma delas utilizará as mesmas opções (como os streams atribuídos e o layout). No entanto, ao iniciar transmissões simultâneas (chamando o método REST várias vezes, com o multiBroadcastTag (conjunto de opções), é possível usar layouts diferentes e atribuir fluxos distintos a cada transmissão simultânea.

Transmissões apenas de áudio e apenas de vídeo

Ao iniciar uma transmissão ao vivo usando o API REST do OpenTok, você pode especificar se ele incluirá áudio, vídeo ou ambos. (Consulte o hasAudio e hasVideo opções.) Por padrão, ambas são transmitidas.

Observação: As transmissões apenas de áudio incluirão vídeo com quadros pretos de 160x120 nos fluxos RTMP. Alguns destinos, como o YouTube e o Facebook, rejeitam fluxos RTMP apenas de áudio.

Como obter informações sobre transmissões ao vivo

Use o SDKs de servidor ou API REST para obter informações sobre uma transmissão ao vivo ou para listar transmissões ao vivo.

Monitoramento das alterações no status das transmissões ao vivo

Você pode registrar uma URL de retorno de chamada (webhook) para receber notificações sobre mudanças no status das transmissões ao vivo de um projeto. O status de uma transmissão ao vivo é definido como "started" ou "stopped".

Para registrar um callback de transmissão para um projeto:

Faça login na sua Account da Video API da Vonage.
No menu à esquerda, selecione a Account desejada (caso você tenha várias Accounts).
No menu à esquerda, selecione a aba “Applications” e, em seguida, o projeto para o qual você deseja registrar um callback seguro.
Role a página para baixo até Configurações do projeto. Clique no Editar ícone, ative o Retorno de chamada seguro botão deslizante, e clique no Salvar botão.

Atualmente, é necessário habilitar os callbacks seguros para definir um callback de monitoramento de transmissão. Se você desabilitar os callbacks seguros, qualquer callback de transmissão que você definir será desativado.

Localize o Monitoramento de transmissões seção e clique no Configurar botão.
Especifique a URL de retorno de chamada e (opcionalmente) um segredo de assinatura.

Para obter mais informações sobre callbacks seguros, consulte esta página.

Quando o status de uma transmissão é alterado, o servidor envia solicitações HTTP POST para a URL que você fornecer. O Content-Type da solicitação é application/json. Os dados da solicitação consistem em um objeto JSON no seguinte formato:

{
  "id": "1748b707-0a81-464c-9759-c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "applicationId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "event": "broadcast",
  "group": "status",
  "resolution": "640x480",
  "streamMode" : "auto",
  "streams" : [],
  "broadcastUrls": {
    "hls" : "http://server/fakepath/playlist.m3u8",
    "hlsStatus": "live",
    "rtmp": {
      "foo": {
        "serverUrl": "rtmps://myfooserver:443/myfooapp",
        "streamName": "myfoostream",
        "status": "live"
      },
      "bar": {
        "serverUrl": "rtmp://mybarserver:443/mybarapp",
        "streamName": "mybarstream",
        "status": "live"
      }
    }
  },
  "settings": {
    "hls": {
      "dvr": false,
      "lowLatency": false
    }
  },
  "status": "started"
}

O objeto JSON inclui as seguintes propriedades:

id — O ID exclusivo da transmissão.
sessionId — O ID da sessão da Video API.
applicationId — O ID do seu projeto da Video API.
group — Isso está definido para "broadcast".
event — Isso está definido para "status".
createdAt — O momento em que a transmissão começou, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC).
updatedAt — Para esse método GET, esse carimbo de data e hora corresponde ao carimbo de data e hora “createdAt”.
resolution — A resolução da transmissão (seja “640x480”, “1280x720”, “1920x1080”, “480x640”, “720x1280” ou “1080x1920”).
status - O status da transmissão: ou "started", "stopped", ou "failed". Para um "failed" status, verifique o reason propriedade do evento para obter mais detalhes.
reason - Para uma transmissão com o status definir como "failed", essa propriedade conterá "Internal server failure".
broadcastUrls — Detalhes sobre os fluxos de transmissão HLS e RTMP.

Para uma transmissão HLS, a URL é fornecida como o hls propriedade. Consulte o Guia do desenvolvedor para transmissão ao vivo da Vonage para obter mais informações sobre como usar essa URL. O hlsStatus a propriedade está definida como um dos seguintes valores:
- "connecting" — O servidor da Vonage está iniciando os transcodificadores. Este é o estado inicial.
- "ready" — O servidor da Vonage foi inicializado com sucesso, mas a CDN não está reproduzindo a mídia.
- "live" — O servidor da Vonage foi inicializado com sucesso e a CDN está reproduzindo o conteúdo multimídia.
- "ended" — A transmissão da fonte foi encerrada. Se o DVR estiver ativado e for solicitada uma gravação prévia, o status mudará para "live".
- "error" — Há um erro na plataforma da Vonage.
Para cada transmissão RTMP, são fornecidos a URL do servidor RTMP e o nome da transmissão, juntamente com o status da transmissão RTMP.
- status — O status do fluxo RTMP. Essa propriedade pode assumir um dos seguintes valores:
  - connecting — A plataforma Vonage está se conectando ao servidor RTMP remoto. Esse é o estado inicial e é o status exibido quando você inicia a sessão sem que haja transmissões publicadas. Ele muda para “ao vivo” quando há transmissões (ou muda para um dos outros estados).
  - live — A plataforma da Vonage se conectou com sucesso ao servidor RTMP remoto, e a transmissão de mídia está em andamento.
  - offline — A plataforma Vonage não conseguiu se conectar ao servidor RTMP remoto. Isso ocorre devido a um servidor inacessível ou a um erro no handshake RTMP. As causas incluem conexões RTMP rejeitadas, Applications RTMP inexistentes, nomes de stream rejeitados, erros de autenticação etc. Verifique se o servidor está online e se você forneceu a URL correta do servidor e o nome do stream.
  - error — Há um erro na plataforma da Vonage.
- serverUrl — A URL do servidor RTMP.
- streamName — O nome do fluxo RTMP.
settings — Mais detalhes sobre a transmissão em HLS. Isso properties O objeto inclui um hls propriedade com as seguintes características:
- dvr — Se Funcionalidade de DVR está ativado para esta transmissão.
- lowLatency — Se modo de baixa latência está ativado para a transmissão HLS.
multiBroadcastTag — A tag exclusiva para transmissões simultâneas (caso tenha sido definida).
streamMode — Se todas as transmissões estão incluídas na transmissão ("auto") ou você seleciona os streams a serem incluídos na transmissão ("manual"). Veja Seleção dos streams a serem incluídos em uma transmissão ao vivo.
streams — Uma matriz de objetos correspondentes às transmissões que estão no ar no momento. Esse valor só é definido para uma transmissão com o status definir como "started" e o streamMode definir como "manual". Cada objeto da matriz possui as seguintes propriedades:
- streamId — O ID da transmissão incluída na transmissão ao vivo.
- hasAudio — Se o áudio da transmissão está incluído na transmissão.
- hasVideo — Se o vídeo da transmissão está incluído na transmissão.

Problemas conhecidos com o recurso de transmissão ao vivo da Vonage

O recurso de transmissão ao vivo apresenta os seguintes problemas conhecidos:

Quando você interrompe uma transmissão ao vivo, os últimos 5 segundos (antes da interrupção) do conteúdo da sessão da Vonage são omitidos do fluxo de transmissão.