Como fazer uma transmissão

Para transmitir um vídeo ao vivo, você deve primeiro criar um objeto LiveVideo. O objeto LiveVideo representa a transmissão. É possível gerenciar as propriedades do objeto para controlar as configurações da transmissão. Após a criação, a API retornará o ID do objeto LiveVideo e uma URL de stream, que pode ser enviada ao codificador e usada para transmitir dados ao objeto LiveVideo.

Transmitir em um usuário

Para fazer uma transmissão em um objeto User, obtenha um token de acesso do usuário com a permissão publish_video e envie uma solicitação para:

POST /<USER_ID>/live_videos?status=LIVE_NOW

Consulte a referência da borda /live_videos e veja parâmetros adicionais da string de consulta que você pode incluir para descrever a transmissão, como um título e uma descrição.

Em caso de sucesso, a API criará um objeto LiveVideo no usuário e retornará uma secure_stream_url, além do id do objeto LiveVideo. A transmissão será exibida em uma publicação no perfil do usuário assim que você enviar dados para a URL de stream segura. É possível consultar o objeto LiveVideo para monitorar a integridade da transmissão e encerrá-la.

Exemplo de solicitação

curl -i -X POST \
 "https://graph.facebook.com/v21.0/<USER_ID>/live_videos
   ?status=LIVE_NOW
   &title=Today%27s%20Live%20Video
   &description=This%20is%20the%20live%20video%20for%20today."

Exemplo de resposta

{
  "id": "1953020644813104",      //<LIVE_VIDEO_ID>
  "stream_url": "rtmp://rtmp-api.facebook...",
  "secure_stream_url":"rtmps://rtmp-api.facebook..."
}

Transmitir em uma Página

Para transmitir um vídeo ao vivo em uma Page, obtenha um token de acesso à Página de um administrador com as permissões pages_read_engagement e pages_manage_posts. Depois, envie uma solicitação para:

POST /<PAGE_ID>/live_videos?status=LIVE_NOW

Consulte a referência da borda /live_videos e veja parâmetros adicionais da string de consulta que você pode incluir para descrever a transmissão, como um título e uma descrição.

Em caso de sucesso, a API criará um objeto LiveVideo na Página e retornará uma secure_stream_url, além do id do objeto LiveVideo. A transmissão será exibida em uma publicação na Página assim que você enviar dados para a URL de stream segura. É possível consultar o objeto LiveVideo para monitorar a integridade da transmissão e encerrá-la.

Exemplo de solicitação

curl -i -X POST \
  "https://graph.facebook.com/v21.0/<PAGE_ID>/live_videos
    ?status=LIVE_NOW
    &title=Today%27s%20Page%20Live%20Video
    &description=This%20is%20the%20live%20video%20for%20the%20Page%20for%20today"

Exemplo de resposta

{
  "id": "1953020644813108",     //<LIVE_VIDEO_ID>
  "stream_url": "rtmp://rtmp-api.facebook...",
  "secure_stream_url":"rtmps://rtmp-api.facebook..."
}

Obter dados do stream da transmissão

É possível ler um objeto LiveVideo para obter as URLs de prévia do stream da transmissão e dados sobre a integridade do streaming, como taxas de bits e de quadros. Os dados de integridade do stream são atualizados a cada 2 segundos. Por isso, não exceda essa frequência ao fazer consultas. Um tempo-limite de stream será detectado e registrado após 4 segundos sem recebimento de dados.

Para ler um objeto LiveVideo, obtenha um token de acesso adequado de usuário ou Página com a permissão publish_video. Depois, envie uma consulta para:

GET /<LIVE_VIDEO_ID>?fields=<COMMA_SEPARATED_LIST_OF_FIELDS>

Use o parâmetro {fields} para especificar os campos do objeto LiveVideo que você quer retornar. Por exemplo, veja uma solicitação para receber o ingest_streams no objeto LiveVideo, que inclui dados sobre a integridade do stream:

Exemplo de solicitação

curl -i -X GET \
  "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>?fields=ingest_streams"

Exemplo de resposta

{
  "ingest_streams": [
    {
      "stream_id": "0",
      "stream_url": "rtmp://rtmp-api.facebook...",
      "secure_stream_url": "rtmps://rtmp-api.facebook...",
      "is_master": true,
      "stream_health": {
        "video_bitrate": 4024116,
        "video_framerate": 60,
        "video_gop_size": 2000,
        "video_height": 720,
        "video_width": 1280,
        "audio_bitrate": 128745.4921875
      },
      "id": "1914910145231512"  // <INGEST_STREAM_ID>
    }
  ],
  "id": "<LIVE_VIDEO_ID>" 
}

Propriedades da resposta

Encerrar uma transmissão

Para encerrar uma transmissão, interrompa o streaming dos dados do vídeo ao vivo do seu codificador para a URL de stream ou envie uma solicitação para:

POST /<LIVE_VIDEO_ID>?end_live_video=true

Isso definirá o status do objeto LiveVideo como VOD e o salvará como um vídeo sob demanda (VOD, pelas iniciais em inglês) para que ele possa ser assistido mais tarde.

Em caso de sucesso, a API retornará o ID do objeto LiveVideo.

Exemplo de solicitação

curl -i -X POST \
  "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>?end_live_video=true"

Exemplo de resposta

{
  "id": "10213570560993813"  //<LIVE_VIDEO_ID>
}

É possível realizar uma operação GET no ID do LiveVideo para confirmar que o status dele foi definido como VOD:

GET /<LIVE_VIDEO_ID>?fields=status

Exemplo de resposta

{
  "status": "VOD",  // Broadcast ended, saved as VOD
  "id": "10213570560993813"    //<LIVE_VIDEO_ID>
}

Excluir uma transmissão

Para excluir uma transmissão que foi encerrada e salva como VOD, envie uma solicitação para:

DELETE /<LIVE_VIDEO_ID>

Exemplo de solicitação

curl -i -X DELETE \
 "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>"

Exemplo de resposta

{
  success: true
}

Transmissão ao vivo com precisão de quadro

Pode haver um pequeno atraso antes que uma transmissão ao vivo seja iniciada enquanto decodificamos os dados de streaming iniciais e processamos as solicitações de API associadas. Por isso, pode ser difícil que os apresentadores no ar saibam exatamente quando a transmissão foi iniciada. Para evitar esse problema, os objetos LiveVideo poderão ser configurados para aceitar dados de streaming, mas não serem transmitidos ao vivo para o público até que uma mensagem RTMP de transmissão seja detectada nos dados. Isso possibilita que qualquer pessoa capaz de obter uma prévia veja a transmissão, ao mesmo tempo em que permite que o codificador de streaming controle com precisão o horário em que a transmissão vai ao ar para o público e o primeiro quadro que o público vê.

Para habilitar a transmissão ao vivo com precisão de quadro, primeiro crie um objeto LiveVideo como você faria normalmente e defina o status como PREVIEW. Depois de criado, consulte o objeto LiveVideo e solicite o campo secure_stream_url com os seguintes campos aninhados:

secure_stream_url.inband_go_live(require_inband_signal)

Isso habilitará a transmissão ao vivo com precisão de quadro no objeto LiveVideo. Além disso, a API responderá com uma nova URL de stream segura que poderá ser usada para transmissão. Você pode desconsiderar a URL de stream segura inicial que foi enviada na criação do objeto LiveVideo.

A transmissão entrará no ar e ficará visível para o público após (1) o status dela ser definido como LIVE (por meio de uma chamada da Graph API ou de uma publicação do usuário no Live Producer) e (2) o codificador enviar a mensagem RTMP ao vivo.

Estrutura da mensagem RTMP ao vivo

Um pacote AMF0 (tipo 0x12) que inclui o seguinte:

• A string onGoLive
• Uma matriz ECMA (tipo 0x08) contendo um único par de chave-valor:

  • Chave: string (tipo 0x02) timestamp
  • Valor: número (tipo 0x00), o registro de data e hora do primeiro quadro de vídeo que ficará visível publicamente

Para saber mais, consulte as especificações de RTMP e AMF0.

Exemplo de solicitação

Exemplo de solicitação para habilitar a transmissão ao vivo com precisão de quadro em um LiveVideo.

curl -i -X GET \
   "https://graph.facebook.com/v21.0/LIVE_VIDEO_ID?fields=secure_stream_url.inband_go_live(require_inband_signal)&access_token=12345..."

Exemplo de resposta

URL de stream segura para um objeto LiveVideo com a transmissão ao vivo com precisão de quadro habilitada.

{
  "secure_stream_url": "rtmps://rtmp-pc.facebook.com:443/rtmp/LIVE_VIDEO_ID?s_bl=1&s_gl=1&...",
  "id": "LIVE_VIDEO_ID"
}

Obter dados de código de erro

Para obter dados de código de erro associados a uma transmissão, envie uma solicitação para:

GET /<LIVE_VIDEO_ID>?fields=errors

A API responderá com o error code, o type, a message e um timestamp.

Exemplo de resposta

curl -i -X GET \
 "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>?fields=errors"

Exemplo de resposta

{
  "errors": {
    "data": [
      {
        "error_code": 1969004,
        "error_type": "stream",
        "error_message": "Video signal lost",
        "creation_time": "2018-12-05T23:58:52+0000"
      },
      {
        "error_code": 1969004,
        "error_type": "stream",
        "error_message": "Video signal lost",
        "creation_time": "2018-12-05T23:58:52+0000"
      },
      {
        "error_code": 0,
        "error_type": "info",
        "error_message": "Live Service received the video signal",
        "creation_time": "2018-12-05T23:58:02+0000"
      },
      {
        "error_code": 0,
        "error_type": "info",
        "error_message": "Live Service received the video signal",
        "creation_time": "2018-12-05T23:58:02+0000"
      }
    ]
  },
  "id": "{your-live-video-id}"
}

Códigos de erro comuns da API de Vídeo ao Vivo

Códigos de erro de permissão

Veja também

• Tokens de acesso
• Referência de LiveVideo
• Referência de Page
• Referência de PageLiveVideos
• Referência da permissão
• Referência de User
• Referência de UserLiveVideos