Live API: RTMP Outputs

This topic explains how you can output RTMP using the Live API. RTMP outputs are useful when you will be streaming to a platform that does not support HLS live streams.

General information

To use RTMP outputs, please be aware of the following

You must have purchased event hours, or any Digital Marketing package
RTMP output hours will be billed against event hours
They are limited to 5 outputs per live job
You can define a label where the label can choose one of the output renditions selected for the stream. If the label is not set then the output will default to the input source.
They can be used with standard jobs and recurring events (SEP).
They can be used for events or 24/7 streams.
They can be started and stopped independently from any live stream.
For SEP jobs that were created before the RTMP output feature was implemented, the feature will not work entirely: on the API it will show a failure even though the RTMP output is actually created. For best results, create a new SEP job to use the RTMP output feature.
When using a RTMP output with a standard job (non-SEP) the RTMP output stream will end when the job ends.
RTMP Outputs do support rtmps urls, and we recommend using them if the social media platform supports them. Also note that as of 1 May 2019, Facebook will only allow RTMPS.
The only format current supported for RTMP URLs is rtmps://host:port/application/streamName.

Notifications

You can set up notifications for rtmp_output_state_changed events. Notifications will be sent for the following states:

RTMP Output States
RTMP Output States	(reported for `rtmp_output_state_changed` notifications as `state`)
`starting`	The stream is starting.
`connected`	The encoder has connected.
`Disconnected`	The encoder has disconnected.
`error`	The stream failed to connect.
`pending_deactivation`	The entry point has been queued for cleanup from the streaming worker.
`deactivation_in_progress`	The entry point is disconnecting from the streaming worker.
`cancelled`	The entry point has been cancelled.
`finished`	The entry point has completed successfully.

Notifications for RTMP outputs must be set at the job level when you create the live job.

To see the different state values reported for RTMP outputs, see Live Notifications.

Creating RTMP outputs

You will first need to create a live job as you normally do, and then make an additional request to create the RTMP endpoint(s).

Note: it is possible under certain situations like activating/deactivating the job that this API call will return an error, if that happens please retry after a pause.

Endpoint

	https://api.bcovlive.io/v1/jobs/{jobId}/rtmpouts

Method

POST

Request body

	{
		"url": "rtmps://host:port/application/streamName",
		"output_label": "480p"
	}

Request Body Fields
Field Name	Required	Type	Description
`url`	yes	string	The URL for the RTMP output - example `rtmp://live-api-s.facebook.com:80/rtmp/my_stream`
`output_label`	no	string	The label of the job output to use as the source for the RTMP output. Omit this parameter to simply use the RTMP input instead.

Sample response

	{
		"host": "live-api-s.facebook.com",
		"port": 80,
		"application": "rtmp",
		"streamName": "my_stream",
		"rtmp_out_id": "asdfg-lkjh"
	}

Get RTMP outputs

Endpoint

	https://api.bcovlive.io/v1/jobs/{jobId}/rtmpouts

Method

GET

Sample response

	[
		{
			"rtmp_out_id": "asdfg-lkjh",
			"stream_start": 1538746255247,
			"connection_info": {
				"host": "a.rtmp.youtube.com",
				"port": 1935,
				"application": "live2",
				"streamName": "my_stream",
				"sessionStatus": "Active"
			}
		}
	]

Stop an RTMP output

Endpoint

	https://api.bcovlive.io/v1/jobs/{jobId}/rtmpouts/{rtmp_out_id}/stop

Method

PUT

Note that the job needs to be started at least once to get the job_id.

Sample response

	{
		"message": "RTMP out asdfg-lkjh deleted successfully"
	}