Transmisión

Para transmitir un video en vivo, debes crear primero un objeto LiveVideo. El objeto LiveVideo representa la transmisión, y puedes manipular las propiedades del objeto a fin de controlar la configuración de la transmisión. Una vez creado, la API devolverá el identificador del objeto LiveVideo y una URL del stream, que puedes pasar a tu codificador y utilizar para hacer stream de datos al objeto LiveVideo.

Transmitir en un usuario

Para transmitir en un objeto User, obtén un token de acceso de usuario con el permiso publish_video y envía una solicitud a:

POST /<USER_ID>/live_videos?status=LIVE_NOW

Consulta la referencia del perímetro /live_videos para ver los parámetros de cadena de consulta adicionales que puedes incluir para describir la transmisión, como un título y una descripción.

Si la operación se realiza correctamente, la API creará un objeto LiveVideo en el usuario y devolverá una secure_stream_url y el id del objeto LiveVideo. La transmisión aparecerá en una publicación en el perfil del usuario apenas envíes datos a la URL segura del stream. Puedes consultar el objeto LiveVideo a fin de supervisar el estado de la transmisión y finalizarla.

Ejemplo de solicitud

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."

Ejemplo de respuesta

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

Transmitir en una página

Para transmitir un video en vivo en una Page, obtén un token de acceso a la página del administrador de la página con los permisos pages_read_engagement y pages_manage_posts; luego, envía una solicitud a:

POST /<PAGE_ID>/live_videos?status=LIVE_NOW

Consulta la referencia del perímetro /live_videos para ver los parámetros de cadena de consulta adicionales que puedes incluir para describir la transmisión, como un título y una descripción.

Si la operación se realiza correctamente, la API creará un objeto LiveVideo en la página y devolverá una secure_stream_url y el id del objeto LiveVideo. La transmisión aparecerá en una publicación en la página apenas envíes datos a la URL segura del stream. Puedes consultar el objeto LiveVideo a fin de supervisar el estado de la transmisión y finalizarla.

Ejemplo de solicitud

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"

Ejemplo de respuesta

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

Obtener datos de streaming de la transmisión

Puedes leer un objeto LiveVideo a fin de obtener las URL de la vista previa del stream de transmisión y los datos sobre el estado del stream, como la velocidad de los bits y la velocidad de los fotogramas. Los datos del estado del stream se actualizan cada dos segundos, de modo que no realices más de una consulta cada dos segundos. Se detectará e informará un tiempo de espera del stream después de cuatro segundos en que no se reciban datos.

Para leer un objeto LiveVideo, obtén un token de acceso de usuario o página adecuado con el permiso publish_video, y, luego, envía una consulta a:

GET /<LIVE_VIDEO_ID>?fields=<COMMA_SEPARATED_LIST_OF_FIELDS>

Utiliza el parámetro {fields} para especificar los campos del objeto LiveVideo que quieres que se devuelvan. Por ejemplo, esta es una solicitud para obtener ingest_streams del objeto LiveVideo, que incluye datos sobre el estado del stream:

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  "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>" 
}

Propiedades de la respuesta

Finalizar una transmisión

Para finalizar una transmisión, detén el streaming de datos de video en vivo del codificador a la URL del stream o envía una solicitud a:

POST /<LIVE_VIDEO_ID>?end_live_video=true

Esto configura el estado del objeto LiveVideo en VOD y lo guarda como un video a petición (VOD) para que se pueda ver más tarde.

Si la operación se realiza correctamente, devolverá el identificador del objeto LiveVideo.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Puedes realizar una operación GET en el identificador del video en vivo a fin de confirmar que su estado se configuró en VOD:

GET /<LIVE_VIDEO_ID>?fields=status

Ejemplo de respuesta

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

Eliminar una transmisión

Para eliminar una transmisión que terminó y se guardó como un VOD, envía una solicitud a:

DELETE /<LIVE_VIDEO_ID>

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  success: true
}

Transmisión en vivo con precisión de fotograma

Existe la posibilidad de que haya una leve demora antes de realizar la transmisión en vivo mientras se decodifican los datos iniciales del stream y se procesan las solicitudes de la API vinculadas. Esta situación puede dificultar que las personas al aire sepan exactamente cuándo comenzó la transmisión. Para evitar este problema, los objetos del video en vivo pueden configurarse para que acepten datos del stream, pero que no se transmitan en vivo al público hasta detectarse un mensaje RTMP de comenzar la transmisión dentro de los propios datos del stream. Esta opción permite que todas las personas que pueden obtener una vista previa de la transmisión la vean. A su vez, permite que el codificador del stream controle con precisión tanto el momento en que comienza la transmisión en vivo al público, como el primer cuadro que alcanza a ver dicho público.

Para habilitar la transmisión en vivo con precisión de fotograma, primero crea un objeto de video en vivo de forma normal y configura su estado como "PREVIEW". Una vez que lo hayas creado, consulta el objeto de video en vivo y solicita el campo "secure_stream_url" con los siguientes campos anidados:

secure_stream_url.inband_go_live(require_inband_signal)

De esta manera, se habilitará la transmisión en vivo con precisión de fotograma en el objeto de video en vivo. A su vez, la API responderá con una nueva URL de stream seguro donde podrás realizar la transmisión. Puedes omitir la URL de stream seguro inicial que recibiste cuando creaste por primera vez el objeto de video en vivo.

La transmisión comenzará en vivo y estará visible al público una vez que (1) el estado de la transmisión se configure en "LIVE" (mediante una llamada a la API Graph o una publicación de usuario desde Live Producer) y (2) el codificador envíe el mensaje RTMP para comenzar la transmisión.

Estructura del mensaje RTMP para comenzar la transmisión

Un paquete AMF0 (tipo 0x12) que contenga lo siguiente:

• La cadena onGoLive
• Una matriz ECMA (tipo 0x08) que contenga un solo par clave-valor:

  • Clave: cadena (tipo 0x02) timestamp
  • Valor: número (tipo 0x00): la marca de tiempo del primer fotograma de video que estará visible públicamente

Para obtener más información, consulta las especificaciones de RTMP y AMF0.

Ejemplo de solicitud

Un ejemplo de solicitud para habilitar una transmisión en vivo con precisión de fotograma en un video en vivo.

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..."

Ejemplo de respuesta

URL de stream seguro para un objeto de video en vivo con la función de transmisión en vivo con precisión de fotograma habilitada.

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

Obtener datos de un código de error

Para obtener datos de un código de error asociados con una transmisión, envía una solicitud a:

GET /<LIVE_VIDEO_ID>?fields=errors

La API responderá con error code, type, message y timestamp.

Ejemplo de respuesta

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

Ejemplo de respuesta

{
  "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 error comunes de la API de video en vivo

Códigos de error de los permisos

Consulta también:

• Tokens de acceso
• Referencia LiveVideo
• Referencia Page
• Referencia PageLiveVideos
• Referencia de permisos
• Referencia User
• Referencia UserLiveVideos