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.
• 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 8 hours.
• The recommended projection format for 360 (spherical) video is equirectangular.

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

---

Wowza Streaming Engine stream source (publisher) parameters

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 your application on a local instance of Wowza Streaming Engine. This example uses an RTMP encoder as the source:

curl -X POST \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "Content-Type:application/json" \
"http://localhost:8087/v2/servers/(serverName}/vhosts/{vhostName}/applications/{appName}/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 \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "Content-Type:application/json" \
"http://localhost:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications"

View the details of an application:

curl -X GET \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "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 \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "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 testlive application. 

Wowza Streaming Engine mapentries parameters

Example request and response

curl -X POST \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
http://localhost:8087/v2/servers/(serverName)/vhosts/(vhostName)/applications/{appName)/pushpublish/mapentries/facebook_timeline_target \
-d '{
  "application": "appName",
  "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",
  "facebook.useAppSecret": "false",
  "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 \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "Content-Type:application/json" \
"http://localhost:8087/v2/servers/(servverName)/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 or the individual stream target you created.

1. In the contents panel of your application, if you don't see a checkmark next to Stream Targets, click Stream Targets in the contents panel and then click Enable Stream Targets.

   

   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.

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

   
    

3. When prompted, click Restart Now so your change takes effect.

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 your application in Wowza Streaming Engine. The 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 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 6000 milliseconds.)
5. Click Save, and then restart the application when prompted to apply the changes.