방송

라이브 동영상을 방송하려면 먼저 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(video-on-demand)로 저장됩니다.

성공 시 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>
}

LiveVideo ID에서 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로 설정합니다. LiveVideo 개체를 만든 후 쿼리하고, 다음 중첩 필드를 포함하여 secure_stream_url 필드를 요청합니다.

secure_stream_url.inband_go_live(require_inband_signal)

이렇게 하면 LiveVideo 개체에서 프레임 동기화 라이브 방송이 활성화되고 API가 새로운 보안 스트림 URL로 응답합니다. 그런 다음 스트리밍을 시작하면 됩니다. LiveVideo 개체를 처음 만들었을 때 전송된 첫 보안 스트림 URL은 무시해도 됩니다.

라이브 방송은 (1) 방송 상태가 LIVE로 설정되고(그래프 API 호출 또는 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..."

응답 샘플

프레임 동기화 라이브 방송을 활성화한 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 참고 자료