Streaming Live Video with the Graph API

Facebook Live is a fun and powerful way to connect with your followers by creating rich stories on Facebook in real time. The Live API allows you to create stories on Facebook using live video content from a variety of sources. Go beyond mobile device cameras and bring in video from professional cameras, multi-camera setups and programmatic sources such as games or screencasts.

Before you begin, please read our platform policies. Note that Facebook's API should not be used to simultaneously stream content to other online services and that the API isn't intended for use with mobile phone cameras. Third-party ads should not be included in streams.

Device Registration and Pairing

NEW

Register the device, the encoder, to Go Live and the person using this device. Registering the encoder allows the Live API to automatically configure your encoder to the optimal settings for a Facebook Live broadcast. You no longer need to manually adjust the encoder settings to ensure the highest quality Live video. The Live API provides the ability to set preview, start, and stop modes for your encoder from the Facebook interface.

The encoder uses POST requests on /me/live_encoders that return the live_encoder_id. The live_encoder_id will then be used to perform POST requests. Register and associate an encoder with a user with these two steps.

  1. Pair a user and a device with a Facebook Oauth Access Token when a user logs into Facebook on their device
  2. Register and associate this encoder (device) with the user

The encoder only has to react and acknowledge these actions.


Device Pairing

Pre-requisites for the Encoder Developer:
  1. Create an App for your encoder in the App Dashboard.
  2. Add the Facebook Login product for Other platforms.
  3. Enable Login from Devices in Facebook Login > Settings.
  4. Get the App ID from the App Dashboard under Settings > Basic.
  5. Get the Client Token under Settings > Advanced.
On the Encoder:

The following steps must be taken if the device has never been paired, does not yet have an access token, or the access token has been rejected; expired, revoked, or the device has unpaired.

In the following requests ACCESS_TOKEN is APP_ID or CLIENT_TOKEN and the following required permissions are stored in SCOPE separated by commas:

  • publish_actions
  • publish_pages
  • manage_pages

STEP 1. The encoder sends a request to Facebook for a VERIFICATION_URI and a USER_CODE:

POST graph.facebook.com/device/login?access_token=ACCESS_TOKEN&scope=SCOPE 

The response from Facebook:

{
  "code": "92a2b2e351f2b0b3503b2de251132f47",
  "user_code": "A1NWZ9",
  "verification_uri": "https://www.facebook.com/device",
  "expires_in": 420,
  "interval": 5
}

STEP 2. The encoder displays the USER_CODE on its display and asks the user to enter it on a VERIFICATION_URI page.

The encoder polls the device every INTERVAL seconds, waiting for the user to enter the USER_CODE in Facebook.

POST graph.facebook.com/device/login_status?access_token=ACCESS_TOKEN&code=CODE,INTERVAL 

Facebook responds to the encoder polling on /device/login_status:

{
  "access_token": "ABCD...",
  "expires_in" : 5183996
}

Once the user has entered the USER_CODE, the encoder stores the ACCESS_TOKEN in a persistent file and is expected to renew the token before EXPIRES_IN seconds.


Encoder Registration

We now have a specific ACCESS_TOKEN and will use it in all the following API calls. Note, in the following example, the access_token and interval parameters will be ignored for the sake of simplicity.

STEP 1. The encoder generates and stores a random UUID to identify itself before being associated with a user. The UUID helps to not create multiple encoders for the same device. If the HTTP request fails it should retry and reuse the same UUID.

The encoder request:

POST graph.facebook.com/me/live_encoders 

Sample output using a Wowza ClearCaster:

{
  'name': 'encoder-1',
  'brand': 'Wowza',
  'model': 'ClearCaster',
  'version': '1.0',
  'device_id': UUID
}

STEP 2. The device_id does not exist, so Facebook creates a new Ent for it to get an FBID and stores the device_id.

Response to encoder:

{
'id': FBID
}

The encoder stores the FBID as live_encoder_id and can now do POST requests on /{live_encoder_id}.

Creating a Live Video

You can create a live video by making a POST request to the live_videos edge using the following paths:

  • /{user_id}/live_videos
  • /{page_id}/live_videos
  • /{group_id}/live_videos
  • /{event_id}/live_videos

If you're using the Graph API Explorer to make your POST requests, be sure to change your application name from Graph API Explorer to the name of your app.

Then check your access token to ensure you have requested either a user or page access token.

Next, make your POST request to the page, user, group, or event ID with the live_videos edge. This creates a live_video object which will return a video ID, an RTMP stream_url, and stream key. The server URL will be http://rtmp-api.facebook.com/rtmp/ and the stream key will be everything after it. Use both in order to push video frames through your streaming software.

POST /{page_id}/live_videos

Put the RTMP stream URL into your encoder of choice. The example below is using Open Broadcasting Software, OBS, which can be downloaded for free. For OBS-specific broadcasts, click Settings then Stream and paste in your RTMP stream URL and key. Click Ok.

Be sure that your video sources are properly setup before you click Start Streaming. This will begin pushing video frames to the RTMP stream URL, which will cause them to appear live on Facebook.

To ensure premium quality live streams, please follow our technical specifications and streaming recommendations below:

Video Format:

  • We accept video in maximum 1080p (1920x1080) resolution at 30 frames per second, with 1 key frame every 2 seconds.
  • You must send an I-frame (keyframe) at least once every two seconds throughout the stream.
  • Recommended max bit rate is 4 Mbps. Going above this maximum is possible but will make live streams highly unstable.
  • Titles must be less than 255 characters otherwise the stream will fail
  • The Live API accepts H264 encoded video and AAC encoded audio only

Video Length:

  • 4 hour maximum length for live stream.
  • 4 hour maximum length for preview streams (either through Live dialog or publisher tools). After 240 minutes, a new stream key must be generated.
  • RTMP stream URLs will expire 24 hours after they are created.

Advanced Audio Settings:

  • Audio Sample Rate: 48 KHz
  • Audio Bitrate: 128 Kbps mono
  • Audio Codec: AAC

Advanced Video Settings:

  • Pixel Aspect Ratio: Square
  • Frame Types: Progressive Scan
  • Bitrate Encoding: CBR
  • Video Codec: H264

Playback of live content will only work if the input broadcast has both an audio and a video track.

Broadcasting a Live Video

NEW

Developers can indicate the exact frame and moment to go live creating seamless broadcasts. One great use case for this is to implement a countdown clock that signals the broadcaster the exact moment when a stream is live.

The Workflow Overview

  • Encoder starts in status ready
  • Encoder queries live_encoder_id with status=ready
  • If there is nothing to do right now FB responds with action=none and interval=X
  • Encoder sleeps X seconds and queries live_encoders with status=ready again
  • Facebook decides the encoder should execute ACTION and responds with action=ACTION
  • Encoder executes action ACTION
  • Encoder acknowledges action ACTION by querying live_encoders with status=ACTION

STEP 1. The user creates a new broadcast and selects an available encoder.

STEP 2. The encoder is idle in its polling loop on the {live_encoder_id} node. The request:

{
'status': 'ready'
}

STEP 3. Facebook asks the encoder to start capturing content on its input source. The response:

{
'action': 'capture', 'polling_interval': POLLING_INTERVAL,
'broadcast_id': BROADCAST_ID
}

STEP 4. The encoder starts capturing some content and collects the characteristics of its input source. The encoder request:

{
'status': 'capture',
'broadcast_id': BROADCAST_ID,
'cap_streaming_protocols': PROTOCOL,
'cap_audio_codecs':AUDIO_CODEC,
'cap_video_codecs':VIDEO_CODEC,
'input_video_width': VIDEO_WIDTH,
'input_video_height': VIDEO_HEIGHT,
'input_video_framerate': FRAME_RATE_NUMERATOR/FRAME_RATE_DENOMINATOR,
'input_audio_samplerate': AUDIO_SAMPLE_RATE,
'input_audio_channels': NUM_CHANNELS
}

STEP 5. Facebook sends the encoder the streaming url and encoding_settings. The encoding settings depend on the input_format, the encoding capabilities, and what Facebook supports. The response if h264 video codec was chosen:

{
'action':'preview',
'polling_interval': POLLING_INTERVAL,
'broadcast_id': BROADCAST_ID,
'streaming_protocol': PROTOCOL,
'video_bitrate': BITRATE,
'video_codec': VIDEO_CODEC,
'video_width': VIDEO_WIDTH,
'video_height': VIDEO_HEIGHT,
'video_framerate': FRAME_RATE_NUMERATOR/FRAME_RATE_DENOMINATOR, 
'video_h264_profile': H264_PROFILE,
'video_h264_level': H264_LEVEL,
'audio_bitrate': BITRATE,
'audio_channels': CHANNELS,
'audio_codec': AUDIO_CODEC,
'audio_samplerate': AUDIO_SAMPLE_RATE,
'streaming_url': RTMP_URL
}

STEP 6. Facebook waits to receive the RTMP stream from the encoder to display the preview.

STEP 7. The Encoder notifies Facebook that it is in preview status. The request:

{
'status': 'preview',
'broadcast_id': BROADCAST_ID
}

STEP 8. Facebook waits for the user to go Live. The response:

{
'action': 'none'
} 

STEP 9. The user decides to go live. Facebook creates the post in the user's feed using the quick publish workflow.

The encoder request:

{
'status': 'preview',
'broadcast_id': BROADCAST_ID
}

The response:

{
'action': 'live',
'broadcast_id': BROADCAST_ID
} 

STEP 9A. The encoder displays the countdown The request:

{
'status': 'live',
'broadcast_id': BROADCAST_ID
}

The response:

{
'action': 'none'
}

STEP 9B. Immediately after the countdown Facebook expects to see an RTMP AMF0 data onGoLive message that contains the timestamp value of the video frame to be publicly visible. It is mandatory to send this message or no video will be posted. If the encoder does not care about the first publicly visible frame, this timestamp can be set to 0. A wireshark decomposition of an example message is below. AMF0 Data message with OnGoLive string followed by an ECMA array with string timestamp and number that is the video frame timestamp value.

    Real Time Messaging Protocol (AMF0 Data onGoLive())
RTMP Header
01.. .... = Format: 1
..00 0101 = Chunk Stream ID: 5
Timestamp delta: 10948
Timestamp: 62719680 (calculated)
Body size: 39
Type ID: AMF0 Data (0x12)
RTMP Body
String 'onGoLive'
AMF0 type: String (0x02)
String length: 8
String: onGoLive
ECMA array (1 items)
AMF0 type: ECMA array (0x08)
Array length: 0
Property 'timestamp' Number 90166
Name: timestamp
String length: 9
String: timestamp
Number 90166
AMF0 type: Number (0x00)
Number: 90166
End Of Object Marker

STEP 10. The user decides to end the live stream. The encoder request:

{
'status': 'live',
'broadcast_id': BROADCAST_ID
}

The response:

{
'action': 'ready'
}

STEP 11. The encoder stops the broadcast. The request:

{
'status': 'ready'
} 

The response:

{
'action': 'none'
}

Reading a Live Video

Live API Reference

Issue a GET request to get information about the live video object.

For instance, you may wish to populate a live dashboard with current viewer count and total unique viewers. This can be accomplished by calling either:

GET /{live_video_id}?fields=live_views,total_views  
GET /{page_id}?fields=live_videos{live_views,total_views}

Note: After the live broadcast has finished, querying live_views will return 0.

Actions and Statuses

The encoder starts in the ready status.

Live Encoder Status FieldsDescription

REGISTER

READY

The default status when it starts and is not doing anything

CAPTURE

The encoder is capturing content from its input (SDI / HDMI)

PREVIEW

The encoder is broadcasting its input to Facebook (eg: sending a RTMP stream to FB)

LIVE

Same as preview but knowing that on Facebook side it is LIVE to the audience

NONE

Facebook API ActionsDescription

capture

The device should start capturing video from its input

preview

The device should start streaming its input to Facebook live server

live

The device should go live (eg: display count down)

ready

The device should end whatever it is doing and go back to ready status

none

The device should do nothing (equivalent of NOOP). It is only useful in polling mode.

Encoding Settings Negotiation

On status=capture, the live encoder sends its capabilities and information about the source input. View the all source input parameters and return types.

CapabilitiesDescription

cap_streaming_protocols

Comma separated list of supported protocols

(e.g., rtmps)

cap_audio_codecs

Comma separated list of supported audio codecs

(e.g., aac)

cap_video_codecs

Comma separated list of supported video codec

(e.g., h264)

Updating a Live Video

Live API Reference

You can update the properties of a live video by making a POST request. This includes some properties that may have been set at creation such as description.

POST /{live_video_id}?description="Testing Live Video"

For instance, to trigger the end of a broadcast from the Graph API, rather than by sending an RTMP streamdelete message, you can update the POST request using the end_live_video parameter by setting it to true. This is only valid if the live video is still running.

POST /{live_video_id}?end_live_video=true

Deleting a Live Video

Live API Reference

You can delete a live video by making a DELETE request.

DELETE /{live_video_id}

This will delete the entire live_video object, including the recorded video on demand and associated story.

Telemetry

NEW

Telemetry enables you to send Facebook diagnostic data to enable us to continually improve Facebook Live.

The device is expected to report its telemetry by doing POST requests on the /live_encoder_id>/telemetry edge every 30 seconds when it is in capture, preview, or live state. Common parameters of a telemetry event are listed below. For a complete list, please visit the Live Encoder API Reference docs.

  • broadcast_id
  • cpu_usage
  • framerate
  • frames_dropped
  • memory_usage
  • status
  • timestamp
  • network_latency
  • network_rx_bandwidth
  • network_rx_packets_dropped
  • network_rx_packets_errors
  • network_tx_bandwidth
  • network_tx_packets_dropped
  • network_tx_packets_errors

Viewer Experience

Once a live_video object is created and the frames have been pushed through your streaming software, the viewer will begin to see a live stream. In the top left corner, they will see how many people are watching the broadcast as well as determine how long the broadcast has been playing regardless of when they started watching.

As soon as the live video begins streaming, the viewer will receive a notification indicating that a profile or page they're following has gone live.

The viewer has the opportunity to follow the profile or page from within the comment stream.

They'll have the option to comment during the live stream as well as like others' comments.

Once you decide to end the live stream, the viewer will be presented with a screen that allows them to follow future live broadcasts, which will notify them the next time the profile or page goes live. The live video will then appear on the profile or page.

App Review and Permission Requirements

If you intend to allow consumers to live stream from your app, your app will need to request approval for use of the Live Video API feature if it uses Facebook Login to go Live on behalf of other users with a programmatic integration. Learn more about our App Review Process.

However, please note that not every use of the Live API needs to undergo App Review. You do not need to request the Live Video API permission if you are:

  • Using the Go Live dialog
  • Posting to your own timeline, page, group, or event. All permissions including the Live Video API feature are granted by default to app admins. You may use the Graph API Explorer tool to retrieve a page or user token.
  • Testing live streaming to a page/profile from your app

In addition to the Live Video API feature, you should ensure that the following permissions have been granted by a user before making a POST request to the live_videos edge using that user's access token:

  • User: publish_actions
  • Page: manage_pages, publish_pages
  • Group: publish_actions, user_managed_groups
  • Event: publish_actions, user_events

Troubleshooting Permission Requests

Are you receiving a permission error? Be sure to use the drop down menu in the Graph API Explorer tool to request the proper permissions when making requests to the Graph API.