ライブ配信

ライブ動画を配信するには、まずLiveVideoオブジェクトを作成する必要があります。LiveVideoはライブ配信を表すオブジェクトであり、このオブジェクトのプロパティを操作することにより、ライブ配信の設定を管理できます。このAPIを作成すると、LiveVideoオブジェクトのIDとストリーミングURLが返されます。それらをエンコーダーに渡して、データをLiveVideoオブジェクトにストリーミングするために使うことができます。

ユーザーにライブ配信する

Userオブジェクトでライブ配信するには、publish_videoアクセス許可を付与されているユーザーアクセストークンを取得して、次の宛先にリクエストを送信します。

POST /<USER_ID>/live_videos?status=LIVE_NOW

タイトルや説明文など、ライブ配信を説明するために含めることができる追加のクエリ文字列パラメーターについては、/live_videosエッジのリファレンスをご覧ください。

成功すると、APIによりそのユーザーに関するLiveVideoオブジェクトが作成され、secure_stream_urlとLiveVideoオブジェクトのidが返されます。データが安全なストリーミング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とLiveVideoオブジェクトのidが返されます。データが安全なストリーミング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秒ごとに更新されるため、クエリは最大でも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>" 
}

応答のプロパティ

ライブ配信を終了する

ライブ配信を終了するには、エンコーダーからストリームURLへ渡されるライブ動画データのストリーミングを停止するか、次の宛先にリクエストを送信します。

POST /<LIVE_VIDEO_ID>?end_live_video=true

これにより、LiveVideoオブジェクトのステータスがVODに設定され、後で視聴できるようにビデオオンデマンド(VOD)として保存されます。

成功すると、APIからLiveVideoオブジェクトのIDが返されます。

リクエストの例

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

応答の例

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

GET操作をLiveVideo IDに対して実行すると、そのステータスが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フィールドをリクエストします。

secure_stream_url.inband_go_live(require_inband_signal)

これで、LiveVideoオブジェクトにおける正確なフレームでのライブ配信開始が可能になり、APIは新しいセキュアストリーミングURLで応答してストリーミングできるようになります。LiveVideoオブジェクトを最初に作成したときに送信された最初のセキュアストリーミングURLは無視してかまいません。

ライブ配信が開始され、視聴者に表示されるのは、(1) (Graph API呼び出しにより、またはユーザーによるLive Producerからの公開により)ライブ配信ステータスがLIVEに設定され、(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オブジェクトのセキュアストリームURLの例です。

{
  "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のリファレンス