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:

b
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

Sample response

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