Live streaming

Overview

Cloudinary's live video streaming API initiates an RTMP input URI for use with dedicated streaming software and hardware to stream your own video to your users via various output platforms. Your live streams can be stored in your Cloudinary product environment to be viewed at a later date.

View the Live Streaming API reference for full details on endpoints and parameters.

Create a live stream

To create a new live stream, make a POST request to the /live_streams endpoint with the relevant parameters in the request body. It must include the input parameter with type "rtmp", and in most cases will at least include a name.

You can also define optional timing options. For all options, see Create a new live stream in the Live Streaming API reference.

The new stream will be created in an idle state. To activate it, start streaming to the input uri or manually activate.

Example Request

Example Response

The response includes details about the input and outputs. The output includes details of the hls output that you can use to stream to your users via a relevant video player, such as the Cloudinary Video Player as well as an additional archive output that gets stored as a standard video asset in your Cloudinary product environment.

Start streaming

To start streaming to a live stream, you need to use an RTMP client such as OBS and stream to the input.uri provided in the live stream response. The input.stream_key can be used as the stream key for the RTMP client. Once you begin streaming to the input URI, the live stream will be activated and the output.

Manually activate a live stream

In some cases, you may want to manually activate a live stream before starting to stream to it. This can be useful if you want to ensure that the stream is ready to receive data before actually starting the stream.

To manually activate a live stream, make a POST request to the /live_streams/{liveStreamId}/activate endpoint.

Example Request

Example Response

Stop streaming

To stop streaming, simply stop the RTMP client from sending data. The live stream will automatically idle after the configured idle_timeout_sec.

You can also manually idle the live stream by making a POST request to the /live_streams/{liveStreamId}/idle endpoint.

Example Request

Delete a live stream

To delete a live stream, make a DELETE request to the /live_streams/{liveStreamId} endpoint.

Example Request

Define or update outputs

Different outputs can be used to stream your live video to various platforms or to create archives of the stream.

An hls and an archive output are automatically defined when you create a live stream. After you've created the stream and before activating it, you can modify the auto-generated values for those outputs or create additional outputs.

• To update the hls or archive outputs, make a PATCH request to /live_streams/{liveStreamId}/outputs/{liveStreamOutputId}
• To define new outputs for a live stream, make a POST request to /live_streams/{liveStreamId}/outputs

Supported output types:

• hls: You can use the hls output to deliver your stream via a relevant video player, such as the Cloudinary Video Player. Only one HLS output can be defined per stream. PATCH update the hls output if you want to modify the default definition that was set during the stream creation.
• archive: Archive outputs are stored as standard video assets in your Cloudinary product environment with the specified public ID. Only one archive output can be defined per stream. PATCH update the archive output if you want to modify the default definition that was set during the stream creation.
• simulcast: Simulcast outputs are not generated by default when creating a stream, but you can optionally create multiple simulcast outputs, each with a unique URI. Use simulcasts when you want to forward your stream to another streaming platform such as Youtube.

Example Request