Трансляция

Для трансляции видео сначала необходимо создать объект LiveVideo. Объект LiveVideo представляет трансляцию. Его свойства позволяют управлять настройками трансляции. API возвращает ID созданного объекта LiveVideo и URL трансляции, который можно передать кодировщику и использовать для потоковой передачи данных в объект LiveVideo.

Трансляция в профиле пользователя

Для трансляции в объекте User получите маркер доступа пользователя с разрешением publish_video и отправьте такой запрос:

POST /<USER_ID>/live_videos?status=LIVE_NOW

Список дополнительных параметров, которые можно включить в строку запроса, таких как название и описание трансляции, см. в справке по границе контекста /live_videos.

В случае успеха API создаст объект LiveVideo в профиле пользователя и вернет secure_stream_url и id объекта LiveVideo. Трансляция появится в публикации в профиле пользователя, как только вы начнете отправлять данные на защищенный URL трансляции. Для отслеживания состояния трансляции и ее завершения можно отправлять запросы к объекту LiveVideo.

Пример запроса

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

Пример ответа

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

Трансляция на Странице

Для проведения прямого эфира в объекте Page получите маркер доступа к Странице, принадлежащий ее администратору, и разрешения pages_read_engagement и pages_manage_posts, а затем отправьте такой запрос:

POST /<PAGE_ID>/live_videos?status=LIVE_NOW

Список дополнительных параметров, которые можно включить в строку запроса, таких как название и описание трансляции, см. в справке по границе контекста /live_videos.

В случае успеха API создаст объект LiveVideo на Странице и вернет secure_stream_url и id объекта LiveVideo. Трансляция появится в публикации на Странице, как только вы начнете отправлять данные на защищенный URL трансляции. Для отслеживания состояния трансляции и ее завершения можно отправлять запросы к объекту LiveVideo.

Пример запроса

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"

Пример ответа

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

Получение потоковых данных трансляции

Из объекта LiveVideo можно получить URL предварительного просмотра трансляции и данные о ее состоянии, такие как скорость передачи и частота кадров. Данные о состоянии обновляются каждые 2 секунды, поэтому отправлять запросы чаще не следует. Если данные не будут получены в течение четырех секунд, произойдет тайм-аут.

Чтобы прочитать объект LiveVideo, получите соответствующий маркер доступа пользователя или маркер доступа к Странице с разрешением publish_video и отправьте такой запрос:

GET /<LIVE_VIDEO_ID>?fields=<COMMA_SEPARATED_LIST_OF_FIELDS>

В параметре {fields} укажите поля объекта LiveVideo, которые нужно получить. Например, получить поле ingest_streams объекта LiveVideo с данными о состоянии трансляции можно так:

Пример запроса

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

Пример ответа

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

Свойства ответа

Завершение трансляции

Чтобы завершить трансляцию, прекратите передачу данных из кодировщика на URL трансляции или отправьте такой запрос:

POST /<LIVE_VIDEO_ID>?end_live_video=true

Объект LiveVideo перейдет в статус VOD и сохранится как видео по запросу (VOD), так что его можно будет посмотреть позже.

В случае успеха API вернет ID объекта LiveVideo.

Пример запроса

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

Пример ответа

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

Чтобы проверить, получил ли объект LiveVideo статус VOD, выполните такой запрос GET:

GET /<LIVE_VIDEO_ID>?fields=status

Пример ответа

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

Удаление трансляции

Чтобы удалить заершенную трансляцию, сохраненную как видео по запросу, отправьте такой запрос:

DELETE /<LIVE_VIDEO_ID>

Пример запроса

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

Пример ответа

{
  success: true
}

Запуск с точностью до кадра

Перед запуском трансляции возможна небольшая задержка, связанная с декодированием ее исходных потоковых данных и обработкой всех связанных запросов API. Это может затруднить определение точного времени начала трансляции для артистов, работающих в эфире. Чтобы избежать этой проблемы, объекты LiveVideo можно настроить так, чтобы они принимали потоковые данные, но не отображались для аудиторий до тех пор, пока в самих потоковых данных не будет обнаружено сообщение RTMP о запуске. Это позволит любому, кто может предварительно просматривать трансляцию, увидеть ее, в то же время позволяя потоковому кодировщику точно контролировать как время запуска трансляции для аудитории, так и первый кадр, который она увидит.

Чтобы включить запуск с точностью до кадра, сначала, как обычно, создайте объект LiveVideo и установите для него статус PREVIEW. После создания запросите объект LiveVideo, а затем поле secure_stream_url со следующими вложенными полями:

secure_stream_url.inband_go_live(require_inband_signal)

Это включит для объекта LiveVideo запуск с точностью до кадра. API вернет новый безопасный URL, на который можно будет выполнять трансляцию. Исходный безопасный URL трансляции, который был отправлен при создании объекта LiveVideo, можно игнорировать.

Трансляция будет запущена и станет видимой для аудитории, после того как (1) для ее статуса будет установлено значение LIVE (посредством вызова API Graph или публикации пользователя из Live Producer) и (2) кодировщик отправит сообщение RTMP о запуске.

Структура сообщения RTMP о запуске

Пакет AMF0 (типа 0x12), содержащий следующее:

• строку onGoLive;
• массив ECMA (типа 0x08), содержащий одну пару "ключ-значение":

  • ключ — строка (типа 0x02) timestamp;
  • значение — число (типа 0x00), метка времени первого видеокадра, который будет виден всем.

Подробнее см. в спецификациях RTMP и AMF0.

Пример запроса

Пример запроса для включения запуска с точностью до кадра для объекта 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..."

Пример ответа

Безопасный URL трансляции для объекта LiveVideo с включенным запуском с точностью до кадра.

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

Получение информации об ошибках

Чтобы получить информацию об ошибках, связанных с трансляцией, отправьте такой запрос:

GET /<LIVE_VIDEO_ID>?fields=errors

API вернет значения error code, type, message и timestamp.

Пример ответа

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

Пример ответа

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

Коды распространенных ошибок Live Video API

Коды ошибок, связанные с разрешениями

См. также

• Маркеры доступа
• Справка по объекту LiveVideo
• Справка по объекту Page
• Справка по объекту PageLiveVideos
• Справка по разрешениям
• Справка по объекту User
• Справка по объекту UserLiveVideos