Stream to Facebook Live using the Wowza Streaming Engine REST API

The Stream Targets feature in Wowza Streaming Engine™ media server software allows you to send live streams to widely distributed destinations. For example, you can send a live stream from Wowza Streaming Engine to Facebook Live.

This article explains how Facebook app developers can use Wowza Streaming Engine REST API to send a single live stream to the Facebook Live network for distributed delivery. The process will be similar to what's documented here, but see Facebook's documentation if you need help with configuring its service to ingest live streams.

Notes:
  • Wowza Streaming Engine 4.5 or later and a Facebook account are required.
  • To stream to Facebook groups, Wowza Streaming Engine 4.7.6 or later is required.
  • All Facebook accounts (personal profiles and commercial Pages) are supported.
  • You can also use Wowza Streaming Engine Manager to send a stream to Facebook. See Stream to Facebook Live using Wowza Streaming Engine.

Requirements


Facebook has the following requirements for live streams:
 
  • The maximum resolution is 720p (720 x 1280), at 30 frames per second.
     
  • You must send a keyframe (I-frame) at least once every two seconds throughout the stream.
     
  • The recommended maximum video bitrate is 4 Mbps.
  • The audio bitrate must be 128 Kbps mono.
  • The audio sample rate must be 44.1 KHz.
  • The maximum length is 4 hours.
  • The recommended projection format for 360 (spherical) video is equirectangular.
Notes:
  • If your live stream exceeds the maximum length, Facebook terminates the post and saves the video. Wowza Streaming Engine automatically creates a new Facebook post with the same settings and continues the live stream.
     
  • Facebook may change their live stream requirements at any time. For more information, see their Live API Best Practices.
  • Facebook policy prohibits you from simultaneously streaming to Facebook Live and other online services. You can, however, broadcast to Facebook and your own website. For more information, see “Can I simulcast?” in the Facebook Live API FAQ

Acquire a Facebook access token 


When using the REST API to configure Wowza Streaming Engine to send a stream to Facebook Live, you must first use an external Facebook application that you're developing to acquire a Facebook access token. Note the following requirements for the external Facebook application:

  • The app must have the required user and account permissions to post live videos to Facebook Live.
  • The app's Require App Secret option must be disabled.  

Create a live application in Wowza Streaming Engine


Use the Wowza Streaming Engine REST API to configure the live application that ships with Wowza Streaming Engine to ingest a source stream (publisher).

Wowza Streaming Engine stream source (publisher) parameters

Parameter Data Type Description
publisherName String A descriptive name for the publisher, for example, MyRTMPencoder.

Example request and response

Note: Wowza Streaming Engine REST API requests must include three headers: Accept:application/json, Content-Type:application/json, and charset=utf-8. For more information, see How to query the Wowza Streaming Engine REST API.

Create a source (publisher) for the live application on a local instance of Wowza Streaming Engine. This example uses an RTMP encoder as the source:

curl -X POST --header "Accept:application/json" --header "charset=utf-8" --header "Content-Type:application/json" "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost/applications/live/publishers/myRTMPencoder" -d '{
  "publisherName": "myRTMPencoder"
}'

The command creates the publisher and returns a response that looks something like this:

{
  "success": true,
  "message": "",
  "data": null
}

Related requests

Get a list of applications:

curl -X GET --header "Accept:application/json" --header "charset=utf-8" --header "Content-Type:application/json" "http://localhost:8087/v2/servers/[serverName]/vhosts/[vhostName]/applications"

View the details of an application:

curl -X GET --header "Accept:application/json" --header "charset=utf-8" --header "Content-Type:application/json" "http://localhost:8087/v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]"

View a list of stream sources (publishers) connected to an application:

curl -X GET --header "Accept:application/json" --header "charset=utf-8" --header "Content-Type:application/json" "http://localhost:8087/v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]/publishers"

Create a stream target in Wowza Streaming Engine 


Note: If you create a Facebook stream target with the Wowza Streaming Engine REST API, make sure you don't later try to edit it via Wowza Streaming Engine Manager. This can break the stream target.

Still in the Wowza Streaming Engine REST API, use your Facebook access token to create a stream target for the live application. 

Wowza Streaming Engine mapentries parameters

Parameter Data Type Description
application String The Wowza Streaming Engine application name. For example, live.
enabled Boolean Specify true so that the target is ready to run as soon as you create it. If you don't include this parameter, you'll need a separate API request to enable the stream target.
entryName String A descriptive name for the map entry, for example, facebook_timeline_target.
facebook.accessToken String The access token acquired from your external Facebook app.
facebook.description String (Optional) Specify a description that will accompany the live video post on Facebook.
facebook.destId String Specify the destination ID. You can find this information in the URL for your Facebook timeline, page, or group.
facebook.destName String (Optional) Specify the name of the Facebook destination: My Timeline, Page, or Group. This name is only used by Wowza Streaming Engine Manager.
facebook.destType String Specify the type of Facebook destination:  timeline, page, or group.
facebook.privacy Integer Specify the desired privacy level, noting that it can't exceed the app-level privacy settings: onlyMe, friends, friendsOfFriends, or public.
Note: The specified privacy setting is only applicable to Timeline posts, but a value is required for all Facebook stream targets regardless of destType.
facebook.title String (Optional) Specify a title for the live video post on Facebook.
profile String Specify rtmp-facebook.
sourceStreamName String The name of the incoming stream for the live application, for example, myStream.

Example request and response

curl -X POST --header 'Accept:application/json' --header 'charset=utf-8' --header 'Content-Type:application/json; http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/pushpublish/mapentries/wowza_streaming_cloud_ull_target' -d '{
  "application": "live",
  "enabled": true,
  "entryName": "facebook_timeline_target",
  "facebook.accessToken": "hsf87634rfohg73q4htoeytf94ur9reygoq34iuty9hf9437t9w8eht4378htwe87f9248hf2387TH...",
  "facebook.description": "This is a stream from Wowza Streaming Engine.",
  "facebook.destId": "12345678",
  "facebook.destName": "My Timeline",
  "facebook.destType": "timeline",
  "facebook.privacy": "onlyMe",
  "facebook.title": "Live Test",
  "profile": "rtmp-facebook",
  "sourceStreamName": "myStream",
}
'

The command creates the target (map entry) and returns a response that looks something like this:

{
  "success": true,
  "message": "Entry (facebook_timeline_target) saved successfully",
  "data": null
}

Related request

Enable a single stream target (push publishing map entry):

curl -X PUT --header "Accept:application/json" --header "charset=utf-8" --header "Content-Type:application/json" "http://localhost:8087/v2/servers/[server_name]/vhosts/[vhostName]/applications/[appname]/pushpublish/mapentries/[entryname]/actions/enable"

Enable the Wowza Streaming Engine stream targets feature 


Note: The stream target feature can't be enabled with the REST API. Instead, you must use the Wowza Streaming Engine Manager instructions provided below or see How to use CDNs and services to distribute live streams (push publishing) for information about manually configuring the Application.xml file.

Before you stream, you must enable the Stream Targets feature for the Wowza Streaming Engine application and the stream target you created.

If you don't see a checkmark next to Stream Targets in the contents panel of the application, click Stream Targets in the contents panel and then click Enable Stream Targets. When prompted, click Restart Now so your change takes effect. When Stream Targets is enabled, a checkmark appears next to Stream Targets in the contents panel and the Stream Targets page shows Status is Enabled.

If the Status of an individual stream target is Disabled, click the Enable icon for the stream in the Actions column.




When a stream target is enabled, its status on the Stream Targets page is one of the following:
 
  • Waiting. The target is enabled but isn't pushing the stream to the Facebook destination yet because it's waiting for the source stream to connect to the Wowza Streaming Engine instance.
     
  • Active. The Wowza Streaming Engine instance successfully connected to the Facebook destination and is actively pushing the stream.
     
    Notes:
    • The live video post is automatically published to the Facebook destination when the stream target's status becomes Active.
       
    • When logged into Facebook you, as the publisher of the live stream, may see the label Published with Wowza Streaming Engine in the post. This label isn't visible to viewers; it's only visible to the account used to publish the stream.
  • Error. The Wowza Streaming Engine instance tried to connect to the Facebook destination but was unsuccessful. Make sure that the target's configured source stream is connected to the Wowza Streaming Engine input and that the target is configured correctly.

    An error can also occur if the Facebook user access token in the target has become invalid. This can happen if the token expires, when you change the password on the associated Facebook account, or if you manually remove permissions from the Wowza Streaming Engine application on Facebook. If the access token becomes invalid, a statement similar to the following is recorded in the Wowza Streaming Engine error log file ([install-dir]/logs/wowzastreamingengine_error.log):
     
    2016-06-23 10:42:56 MDT comment server WARN 200 - PushPublishFacebookTokenInfo.log: token is invalid

    To fix this issue, edit the Facebook stream target in Wowza Streaming Engine Manager, log in to the appropriate Facebook account, and then save the stream target again.
     
    Note: To enable this error to be logged, you must enable the Debug Log option on the Advanced tab for the stream target in Wowza Streaming Engine Manager. To do this:
     
    1. Click the Edit icon for the stream target.
       
    2. On the Advanced tab, click Edit. Access to the Advanced tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
       
    3. Set Debug Log to true, and then click Save.
The status of each stream target updates automatically if your Wowza Streaming Engine application has fewer than 100 stream targets. If your application has more than 100 stream targets, you can click Refresh to update the status.

Test the connection



Configure your encoder and then test the live stream.
 
  1. Start the stream in the H.264 camera or encoder that's sending the stream to the live application in Wowza Streaming Engine. The live application ingests the live stream and sends it to Facebook.
     
  2. In Wowza Streaming Engine Manager, verify that the stream is working:
     
    • Click Incoming Streams in the contents panel and then click the stream name. The stream detail page displays the Status of the stream (Active) as well as details about connections, uptime, and throughput for the live stream.
       
    • Click Stream Targets in the contents panel. The Status of the target should be Active.
  3. Verify that Facebook is receiving the stream. Check that the live video was posted to your Facebook destination.
     
  4. Stop the stream in the source camera or encoder to end your test connection. 

About Facebook Live video posts


After the Facebook stream target initiates a live video post, the video post in Facebook is labeled LIVE. If the live source stream is disconnected, Facebook puts the video post into a "waiting" state. If the live stream is reconnected quickly, the video post resumes after a short recovery period.

However, if it takes more than a few minutes for the live source stream to reconnect, Facebook will automatically "close" the live video post and start converting it to an on-demand video file. If the live source stream then reconnects to the stream target, a new live video post is generated with the same Title, Description, Video Destination, and Privacy settings.

The following actions performed in Wowza Streaming Engine can also cause Facebook to close an active live video post and generate a new one for a Facebook stream target:
 
  • Restarting the media server, the virtual host (VHost), or the live application that has the Facebook stream target.
     
  • Disabling, deleting, restarting, or editing and saving the Facebook stream target

Troubleshoot a Facebook Live stream target 


If you encounter problems sending your live stream to Facebook, a timeout issue may be the cause. Increasing the timeout may fix it. 

  1. In Wowza Streaming Engine Manager, click the Applications tab and select your application in the contents panel.
  2. In the contents panel, click Stream Targets and then click on your Facebook stream target. 
  3. In the details page, click the Custom tab, and then click Edit.
  4. Click Add Custom Property, specify the following settings in the Add Custom Property dialog box, and then click Add:
    • Name - Enter facebook.readWriteTimeout.
    • Type - Select Integer.
    • Value - Enter 15000 milliseconds. (The default value is 3000 milliseconds.)
  5. Click Save, and then restart the application when prompted to apply the changes.