Streaming Media Broadcasts Guide

The Live API offers a robust suite of capabilities that can take live streams to the next level. With the introduction of features like frame accurate start times, preview and geo-targeting, this advanced guide will help you highly customize your live streams:

Be sure to check out our Quick Start Guide before incorporating the following features mentioned in this doc.

  1. Recommended Specs
  2. Creating a Stream
  3. Previewing a Stream
  4. Additional Stream Testing
  5. Updating a Stream
  6. Scheduling a Live Video
  7. Determining Audience
  8. Handling Copyright
  9. Branded Content
  10. Boosting Engagement
  11. Live Video Comments

If using the Live API appears too challenging, you can utilize our other live options or contact one of our Media Solutions Developer Partners to get setup.

Recommended Specs

It is important to note the following specs for Facebook's live video streaming product and API. This documentation will be actively updated to reflect developments of the product.

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.

For more information on how to get the best quality live stream, check out our Best Practices Guide.

Creating a Stream

After gaining access to the Live API via App Review and establishing the proper permissions, live video objects can be created from a user,page, group, or event. Send a POST request to the following endpoints to create a live video.

Please reference the Creating a Live Video section of our Quick Start guide for more information on how to create live video objects.

Previewing a Stream

Facebook Live API allows a broadcaster to preview his/her live content before going Live.

First, issue a POST request to create a live video with the status parameter set to UNPUBLISHED. The live video object will be created but will not post to your Facebook timeline or page.

Using the Graph API Explorer:

Or using curl:

curl -k -X POST https://graph.facebook.com/$your_userid_or_pageid/live_videos 
-F "access_token=$your_user_or_page_token" 
-F "status=UNPUBLISHED"
    

The server will return the following response:

{
"id":"10159725222100347",
"stream_url":"rtmp://rtmp-api-dev.facebook.com:80/rtmp/10159725222100347?ds=1&s_efg=eyJxZV9ncm91cHMiOnsiZmJsaXZlX3NlcnZlcl9leHBlcmltZW50Ijp7InNlcnZpY2VfcG9ydCI6IjE3MDAwIn19fQ\u00253D\u00253D&s_l=1&s_vt=dev&a=ATgBKpITJwJNJLhMBpo",
"secure_stream_url":"rtmps://rtmp-api-dev.facebook.com:443/rtmp/10159725222100347?ds=1&s_efg=eyJxZV9ncm91cHMiOnsiZmJsaXZlX3NlcnZlcl9leHBlcmltZW50Ijp7InNlcnZpY2VfcG9ydCI6IjE3MDAwIn19fQ\u00253D\u00253D&s_l=1&s_vt=dev&a=ATgBKpITJwJNJLhMBpo",
"stream_secondary_urls":[],
"secure_stream_secondary_urls":[]
}

After creating a live video in preview, you can query the live video node for the dash_preview_url. This url can be used in a third party DASH player to verify the broadcaster's video and audio content. Examples of third party DASH players include the DASH reference player or Shaka player.

It's important to note that the dash_preview_url can only be used for 4 hours and is limited to no more than 10 viewers.

Using the Graph API Explorer:

Or using curl:

curl -k -X POST https://graph.facebook.com/$video_id 
-F "access_token=$access_token" 
-F "fields=dash_preview_url"

where the $live_video_id is the id field from the POST query to me/live_videos to create the broadcast.

The above curl request will return the following server response:

{
"dash_preview_url":"https://video.xx.fbcdn.net/hvideo-prn1/v/rBeBxrcPzotQcbdREgZ2b/live-dash/dash-md/10159725222100347.mpd?lvp=1&_nc_log=1&_nc_rl=AfAuSO1ApY1JC5ff&oh=6e33dc60dcd618afbda9e5675ba89d25&oe=59B25609",
"id":"10159725222100347"
}

After getting the preview URL, access a test DASH player to view the preview.

After filling the player setting with the right value, you should be able to see your stream like this:

If you find anything wrong with your content, please make sure your encoder is adhering to our streaming specifications.

After you verify the video/audio, make another POST request to the Graph API and change the status parameter to LIVE_NOW in order to publish your live video to Facebook.

curl -k -X POST https://graph.facebook.com/$your_live_video_id 
-F "access_token=$your_user_or_page_token" 
-F "status=LIVE_NOW"

Additional Stream Testing

While previewing a live stream is one of the best ways to test your audio/video setup before going live, there are additional methods that you can use to test reliability of a live stream.

We recommend setting up an unpublished test page and streaming your live video content to it. You will need to be an admin or editor of the page in order to create live video content. Additionally you can set the privacy parameter to create streams visible to you. The following values are available when setting privacy:

  • EVERYONE
  • ALL_FRIENDS
  • FRIENDS_OF_FRIENDS
  • CUSTOM
  • SELF
POST /{page_id}/live_videos?privacy={"value":"SELF"}

Updating the Live Stream

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.

Deleting the Live Stream

You can delete a live video by making a DELETE request. This will delete the entire live_video object, including the recorded video on demand and associated story.

Scheduling a Live Video

Broadcasters can now schedule a live video in advance through the Graph API, providing the option for people to opt in to be notified, Get Reminder, when a live broadcast starts. This allows audiences to opt in to receive a reminder notification when a live broadcast starts, ensuring that they don't miss a second of a live broadcast! A scheduled live video will help broadcasters:

  • Build anticipation and buzz before a broadcast
  • Start a broadcast strong, without any dead time
  • Test recurring programmed content

You can read more about scheduled live through our media blog post and the detailed workflow:

Scheduled Live introduces a few new fields to the existing Live API. Before reading this guide, make sure you are familiar with the basics of working with the Live API.

Parameter Description

planned_start_time

A unix timestamp that determines the time you plan to begin a live video. This time will be displayed on the announcement post. You must go live within 10 minutes of the planned start time or the announcement post will expire and be deleted from your timeline.

scheduled_custom_profile_image

The custom image will be displayed on the announcement post. This image uploaded should have a square aspect ratio and be in a .jpg or .png file format. If no custom image is uploaded, the announcement post will default to the profile picture of the user or page.

scheduled_unpublished

If status=SCHEDULED_UNPUBLISHED, any video data you upload will be visible to the preview stream but not to your audience. You can query the live video node for the preview_url. Scheduled live videos will have this status upon creation.

scheduled_live

If status=scheduled_live, the preview stream will transition to the live stream and be made available to your audience immediately. Scheduled live videos will automatically transition to status=scheduled_live at the planned_start_time, so make sure your preview stream is running before the planned_start_time.

is_manual_mode

By default scheduled live videos automatically transition your preview stream to the live stream at the planned start time. However, there may be a time in which you want to manually start a scheduled live video. For example, you might want to start the stream before the planned start time or if you running a little late and wish to continue previewing the stream past the planned start time. Once you switch to manual, you will be responsible for sending a POST request with status=scheduled_live to transition the stream from preview to live. As soon as manual mode is enabled, you will not be able to switch back to automatically transitioning from preview to live.

Creating a Scheduled Live

You can create a scheduled 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

with the required post data planned_start_time and the optional post data scheduled_custom_profile_image.

curl -X POST 
-F "access_token={access_token}"
-F "planned_start_time={unix_timestamp}" 
-F "schedule_custom_profile_image=@//Users/name/image.png" 
https://graph.facebook.com/v2.8/me/live_videos

Remember to save the id and stream_url returned on creation. The id field will allow you to do reads, updates, and deletes on the live_video node. The stream_url will be plugged into your encoder of choice and be used to live stream at the planned_start_time.

Reading a Scheduled Live Video

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

curl https://graph.facebook.com/v2.8/{live_video_id}?access_token={access_token}&fields=planned_start_time,status,is_manual_mode,stream_url

If you scheduled your live video a couple days in advanced and forgot your stream key you can specify stream_url as a field.

Updating a Scheduled Live Video

The properties of a scheduled live video can be updated by making a POST request to the Live API. You can change the custom image, reschedule to a new time, switch to manual mode, or transition the preview stream to live manually.

Here is an example of how to update reschedule the live video to a new time and change the custom profile image. You might want to reschedule when you can't start within 10 minutes of planned start time to prevent the scheduled live from expiring and being deleted from your timeline.

Send a POST request with planned_start_time={new_unix_timestamp} and schedule_custom_profile_image={path_to_new_image}.

curl -X POST 
-F access_token={access_token} 
-F planned_start_time={new_unix_timestamp} 
-F "schedule_custom_profile_image=@//Users/name/new_image.png"
https://graph.facebook.com/v2.8/{live_video_id}

This is another update example, which shows how to switch the scheduled live to use manual mode and transition the preview stream to the live stream.

Enable manual mode by sending a POST with is_manual_mode=true.

curl -X POST 
-F access_token={access_token} 
-F is_manual_mode=true 
https://graph.facebook.com/v2.8/{live_video_id}

First, verify the preview stream is working. When you are ready to transition the preview stream to the live stream send a POST with status=scheduled_live.

curl -X POST 
-F access_token={access_token} 
-F status=scheduled_live 
https://graph.facebook.com/v2.8/{live_video_id}

Deleting a Scheduled Live Video

You can delete a scheduled live video by making a DELETE request the same you would delete a normal live video. We will notify users that are currently viewing the announcement post that the scheduled live has been canceled.

curl -X DELETE 
-F access_token={access_token} 
https://graph.facebook.com/v2.8/{live_video_id}

Determining Your Audience

Audience Restrictions are now available for the Live API so broadcasters can limit who sees content by location and demographic. You can limit who sees your live content by location (country, region, city, zip code), language, age and gender. These targeting rules will apply for both VOD and Live. Sharing the same codes means that once a new geo-gating rule is added (such as IP_COUNTRY), the VOD and Live will be upgraded simultaneously.

Please note that geo-gating options are only available for pages. You can not use the API to geo-gate live videos posted to your timeline.

Please review the targeting specs available through the Marketing API in order to better understand how to geo-target your live video audience.

In addition to being able to include certain languages and locations, you can now exclude by language and location. This allows you to easily determine certain territories or languages.

Our Rights Manager tools helps you easily upload and maintain a reference library of video content to monitor and protect, including live video streams. Our Rights Management API enables publishers to claim copyright ownership for videos and manage copyright matching rules. You can read and learn more about Rights Manager at rightsmanager.fb.com.

Additionally, your live video may be stopped if there is a copyright infringement detected. This can be prevented by ensuring all rights have been cleared for content that will be used in Live streams. Licensors must whitelist their pages as well. Content management technology is in place that will potentially flag, block, and remove content that is not cleared (such as a video containing unlicensed background music). If this is the case, we provide a way for you to check the error condition of the stream.

Branded Content

Verified pages (pages with a blue checkmark) can now share branded content through live videos! Branded Content is any content that features a third-party product, brand, or sponsor ("marketer"). For information about incorporating branded content with a live video, please see our documentation on creating branded content for live. Be sure to familiarize yourself with our branded content policy and ads policy before getting started.

Learn more about Branded Content in our media portal.

Boosting Engagement

As soon as a live video begins streaming, Profile and Page followers will receive a notification indicating that a profile or page they're following has gone live. Currently, the Live API does not offer control over sending specific follower's notifications. However, below are some tips to improve reach:

  1. Encourage users to Like or Follow your page
  2. Inform your followers to Subscribe to live videos. Everyone who subscribes to live notifications from a page should expect to receive a notifications once that page goes live.
  3. Share your live video on other related pages. For example, if you are live streaming an interview between two public figures, share the video from one page to the other page to engage followers of the second page.

Followers can go into their notifications settings and toggle between the following options:

  • New Live Posts - They will receive all live video notifications
  • Suggested - Suggested live video notifications for this page. These are based off of whether or not a follower has interacted with this Pages content, specifically live videos, in the past. Everyone who follows a page are defaulted into this option.
  • Off - No live video notifications are sent

Note: Continuous live posts do not send notifications, even to followers of a page. For more information on continuous live, please see our continuous live documentation.

Why didn't I receive a notification?

There are a few reasons why a you may not receive a live notification:

  1. You are not a fan of the page.
  2. You are a fan of the page but the post is from a brand page.
  3. You've received too many live notifications in the last 24 hours.

Live Video Comments

Interacting with a broadcaster is one of the best parts about using live video on Facebook. With Facebook Live, you can comment during a stream or after, creating an engaging experience that feels live even after a video is complete.

For VOD (Video On Demand) comments, each comment and reaction that is left while a viewer is watching live or in VOD gets marked with the current time in the video, and all future viewers will see the comments and reactions replayed at the time in the video they were originally left.

Comment Moderation

Currently, the live_filter parameter is used to moderate comments on a live video. The default value is filter_low_quality which determines whether low quality comments will be filtered out of the results. In all other circumstances, the parameter is ignored. Additional comment moderation is not available through the Live API.

Reading Comments and Reactions

You can read live video comments by polling the Live Video Comments edge. You can also read live video reactions by polling the Reactions edge.

Note:

Please make sure that you are polling the Live Video comments edge and not the Video Comments edge. Your app may be rate limited if the Video comments edge is used. For more about app rate limiting, see our rate limiting documentation.