直播

若要直播視像，您必須先建立 LiveVideo 物件。LiveVideo 物件表示直播，您可操控此物件的屬性以控制直播設定。建立後，此 API 將傳回 LiveVideo 物件的編號和串流網址，您可以將它們傳遞到您的編碼器並用於將數據串流到 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 物件，並將狀態設為「預覽」。建立後，查詢 LiveVideo 物件並要求獲得包含以下巢狀欄位的 secure_stream_url field：

secure_stream_url.inband_go_live(require_inband_signal)

這將在 LiveVideo 物件啟用畫面精準直播，且 API 會回應並顯示一個用於接收串流數據的新安全串流網址。您可以略過一開始建立 LiveVideo 物件時系統傳送給您的初始安全串流網址。

在 (1) 直播狀態設為「直播」（透過 Graph API 呼叫或用戶使用「直播管理工具」發佈）以及 (2) 編碼器傳送直播 RTMP 訊息後，直播內容將開始並向受眾展示。

直播 RTMP 訊息結構

AMF0 數據封包（0x12 類型），當中包含：

• onGoLive 字串
• ECMA 陣列（0x08 類型），當中包含一組鍵／值配對：

  • 鍵：timestamp 字串（0x02 類型）
  • 值：數字（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 參考資料