直播

如要直播视频，您必须先创建一个 LiveVideo 对象。LiveVideo 对象表示直播，您可以操控该对象的属性，从而控制该直播的设置。创建 LiveVideo 对象后，API 将返回该对象的编号和直播网址，您之后可将这些返回内容传递到编码器并用于向 LiveVideo 对象流式传输数据。

在“用户”页面上直播

如要在 User 对象上进行直播，请获取具备 publish_video 权限的用户访问口令，并发送请求至：

POST /<USER_ID>/live_videos?status=LIVE_NOW

请参阅 /live_videos 连线参考文档，了解您可以添加的用于描述该直播的其他查询字符串参数，如标题和描述。

若请求成功，API 将在“用户”界面上创建一个 LiveVideo 对象，并返回 secure_stream_url 和该 LiveVideo 对象的 id。向安全直播网址发送数据后，直播视频将立即出现在“用户”个人主页的帖子中。您可以查询该 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 和该 LiveVideo 对象的 id。向安全直播网址发送数据后，直播将立即出现在公共主页的一个帖子中。您可以查询该 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 对象，以获取直播视频的预览网址以及直播状态数据，如比特率和帧率。直播状态数据每 2 秒刷新一次，因此请将查询频次限制为仅每 2 秒 1 次。在未收到任何数据的 4 秒后，系统将检测到投射超时并予以报告。

如要读取 LiveVideo 对象，请获取具备 publish_video 权限的相应用户访问口令或公共主页访问口令，然后发送查询至：

GET /<LIVE_VIDEO_ID>?fields=<COMMA_SEPARATED_LIST_OF_FIELDS>

使用 {fields} 参数指定您希望返回的 LiveVideo 对象字段。以下示例展示如何请求获取 LiveVideo 对象上的 ingest_streams，其中包含直播状态数据：

请求示例

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

响应属性

结束直播

如要结束直播，请停止向直播网址流式传输编码器中的直播视频数据，或发送请求至：

POST /<LIVE_VIDEO_ID>?end_live_video=true

这会将 LiveVideo 对象的状态设置为 VOD，并将其另存为点播视频 (VOD)，以供日后观看。

若请求成功，API 将返回 LiveVideo 对象的编号。

请求示例

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

响应示例

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

您可以对 LiveVideo 编号执行 GET 操作，确认其状态已设置为 VOD：

GET /<LIVE_VIDEO_ID>?fields=status

响应示例

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

删除直播

如要删除已结束的直播并将其另存为 VOD，请发送请求至：

DELETE /<LIVE_VIDEO_ID>

请求示例

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

响应示例

{
  success: true
}

帧定位直播

在某个直播开始之前，当我们解码该直播的初始直播数据并处理任何相关 API 请求时，可能会稍有延迟。这会使直播人员很难准确知道直播何时开始。为避免这一问题，LiveVideo 对象可以设置为：接受直播数据，但直到在直播数据本身中检测到直播 RTMP 消息，才向观众直播。此举可让能预览直播的任何人都可以看到直播，同时让直播编码器可以精确控制向某个观众开始直播的时间和该观众看到的第一帧。

如要启用帧定位直播，首先照常创建一个 LiveVideo 对象，并将其状态设置为 PREVIEW。创建该对象后，查询该对象并请求包含以下嵌套字段的 secure_stream_url 字段：

secure_stream_url.inband_go_live(require_inband_signal)

这将在 LiveVideo 对象上启用帧定位直播功能，并且 API 返回的响应中将包含一个新安全直播网址，然后您便可将数据流式传输至此网址。您可以忽略您首次创建 LiveVideo 对象时发送给您的初始安全直播网址。

直播将在以下情况下开始并显示：(1) 直播状态设置为 LIVE（通过图谱 API 调用或通过从直播管理工具发布直播的用户）之后；以及 (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..."

响应示例

已启用帧定位直播功能的 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}"
}

常见直播视频 API 错误代码

权限错误代码

另请参阅

• 访问口令
• LiveVideo 参考文档
• Page 参考文档
• PageLiveVideos 参考文档
• 权限参考文档
• User 参考文档
• UserLiveVideos 参考文档