Live streaming RTMP (Beta)

Cloudinary's RTMP live video streaming can easily initiate an RTMP input URI for use with dedicated streaming software and hardware to stream your own video to your users via various platforms.

Important
RTMP Live Streaming is currently in BETA. There may be minor changes to parameter names or other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our support team.

The RTMP live streaming workflow using Cloudinary is:

  • Use an unsigned upload to upload a live streaming manifest using a live streaming upload preset.
  • Use the RTMP live output URI from the upload response to start streaming with dedicated streaming software.
  • Deliver an HLS live stream using the live output URI.

Setup

1. Create a new live streaming upload preset

Create a new unsigned upload preset or modify an existing one to enable live broadcast. You can do this either using the Admin API by setting the live parameter to true or via the management console, in the Storage and Access section of the Edit upload preset page, by turning on Live broadcast.

2. Create your live streaming manifest file

The live streaming manifest is a json file that contains the configuration for your live streaming, for example:

Copy to clipboard
{
  "input_type": "rtmp",
  "targets": [{"kind": "hls"}, {"kind": "file"}],
  "idle_timeout_sec": 120,
  "max_runtime_sec": 32000
}

The example above sets:

  • input_type to rtmp.
  • targets for the live stream to hls for adaptive streaming and file for saving the stream to your Cloudinary Media Library.
  • idle_timeout_sec to 120 seconds to end the stream when idle for the set period.
  • max_runtime_sec to 32000 seconds to end the stream after the set period has elapsed.

See the live streaming reference for all the available parameters.

Initializing a live stream

To initialize an RTMP live stream, upload the live streaming manifest file using the live streaming upload preset you created.

Here is a cURL example for the request:

Copy to clipboard
curl --request POST 'https://api.cloudinary.com/v1_1/<cloud name>/video/upload' \
--form 'file=@live_manifest.json' \
--form 'upload_preset=live_streaming'

Response

The JSON response from the upload contains the same parameters as an upload of media or raw files, with the addition of two parameters:

  • live_input_uri - This is the input uri and contains the server and stream key that need to be entered into your RTMP live streaming software.
    • The server part is everything up to and including your cloudname. e.g. rtmp://3.214.86.161:1935/<cloud_name>
    • The stream key is the string after your cloudname. e.g. dh8bxtg97t9cns4bddoa_56753701a34f46cdc6a094e7
  • live_output_uri - This is the output uri used to view the live stream and can be displayed using a video player such as the Cloudinary Video Player.

Below is an example response from initializing an RTMP live stream:

Copy to clipboard
{
    "asset_id": "809633ca0b93f4dfd63c10df415d5",
    "public_id": "dh7bxdk97ts7bdfoa",
    "version": 16008634678,
    "version_id": "b5a8e68265c27e2sdc0bd3a4b62126",
    "signature": "88b4cd2f7f3f97f0df74f4686357da196261",
    "format": "live",
    "resource_type": "video",
    "created_at": "2020-09-23T12:17:48Z",
    "tags": [],
    "bytes": 220,
    "type": "upload",
    "placeholder": false,
    "url": "http://res.cloudinary.com/<cloud_name>/video/upload/v1600863468/dh7bxdk97ts7bdfoa.live",
    "secure_url": "https://res.cloudinary.com/<cloud_name>/video/upload/v1600863468/dh7bxdk97ts7bdfoa.live",
    "live_input_uri": "rtmp://3.214.86.161:1935/<cloud_name>/dh8bxtg97t9cns4bddoa_56753701a34f46cdc6a094e7",
    "live_output_uri": "https://res.cloudinary.com/<cloud_name>/video/live/dh7bxdk97ts7bdfoa.m3u8",
    "access_mode": "public",
    "original_filename": "live_manifest",
    "original_extension": "json"
}

Terminating a live stream

A live stream is terminated automatically when either the configured max_runtime_sec or idle_timeout_sec have elapsed.

Live streaming reference

This reference lists the available parameters to be included in the streaming manifest json file for RTMP streaming.

Required parameters

Param Type Description
targets array An array of objects defining the output targets for the live stream. Each target is comprised of:
  • kind: Required. The type of output for the stream. Possible values: file, hls, facebook, youtube.
  • uri: Required when kind is set to facebook or youtube. The Facebook or Youtube streaming URI used to direct the stream to that platform. Supplied when configuring Facebook/Youtube streaming.
input_type string Required for RTMP. The live streaming protocol to use.

Possible values: rtmp, webrtc. Default: webrtc.

Optional parameters

Param Type Description
input_codec string The codec to use for input. Possible values: avc, mpeg2. Default: avc.
input_resolution string The resolution to use for input. Possible values: hd, sd. Default: hd.
input_max_bitrate integer (Mbps) The maximum bitrate to use for input in Mbps. Default: 10.
max_runtime_sec integer (seconds) The maximum run time for the stream in seconds before the stream is terminated. Default: 43200.
idle_timeout_sec integer (seconds) The length of time in seconds that the no input is detected before the stream is terminated. Default: 120.
input_loss_image string (url) An image URL (PNG or BMP only) to show when input is lost. Default: null.

Notes

  • The public ID for the stream will be assigned automatically, you can't manually set the public ID.
  • If the video from your live stream exceeds your storage limits, the video will not be stored in your account.

✔️ Feedback sent!