Programmable Media

Live streaming WebRTC (Beta)

Last updated: Jul-11-2023

Cloudinary's WebRTC live streaming functionality provides end-to-end streaming with on-the-fly video effects and transformations via a dedicated JavaScript library.

Important
WebRTC live streaming is currently in Beta and available for accounts that use the default US-based data center. 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.

This guide describes cloudinary-js-streaming version 1.3.0.

The WebRTC live streaming workflow using Cloudinary is:

  1. The video is streamed from the user's device camera.
  2. The video is up-streamed through Cloudinary (including any pre-configured transformations and effects), providing the streaming user with a Cloudinary public ID and resource URL.
  3. The stream is now publicly available through that URL (a single bitrate HLS stream) and can be fed into any streaming-supported video player.

Take a look at our live streaming demo to try it out for yourself.

Installation

Install the library using npm:

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 Cloudinary Console, in the Storage and Access section of the Edit upload preset page, by turning on Live broadcast.

Caution
Adding transformations that affect video duration will cause errors with your live streaming.

You can also configure your upload preset to use a streaming profile. You can use a streaming profile to define your adaptive bitrate streaming settings for your users.

2. Import the library

Alternatively, if you didn't install with NPM, you can include the file in your HTML page and then load it in your JavaScript. For example:

In your HTML:

In your JavaScript:

3. Set Cloudinary configuration parameters

To initialize live streaming you need to include at least your cloud name and the upload preset you configured for live broadcast. You can define these as constants and include them in your initLiveStream request.

Initializing live streaming

Use the initLiveStream(options) method to initialize live streaming in your app.

Options

Required parameters

Param Type Description
cloudName String The cloud name for your Cloudinary product environment.
uploadPreset String A "live broadcast" enabled upload preset. See setup for more information.

Optional parameters

Param Type Description
stream MediaStream object The MediaStream to use as the streaming source. Required only if you obtain a MediaStream object yourself with a getUserMedia request or the getStream helper function, rather than have the library get a stream from the default device by itself.
debug String or Array The Log level (disabled by default). A string or array of strings listing the type of messages to print.

Possible values: trace, debug, vdebug, log, warn, error, all.

bandwidth String The streaming bandwidth, in bits. Default: 1 Mbit/s (1024 * 1024).
hlsTarget Boolean Whether to live stream using the hls protocol.
fileTarget Boolean Whether to save an mp4 file in your Cloudinary storage.
facebookUri String (URI) The Facebook streaming URI used to direct the stream to facebook. Supplied by Facebook when configuring Facebook streaming.
youtubeUri String (URI) The Youtube streaming URI used to direct the stream to Youtube. Supplied by Youtube when configuring Youtube streaming.
events Callback Callback for events, supporting the following functions:
start: Called when the streaming starts. Includes the recording Id.
stop: Called when the streaming stops. Includes the recording Id.
error: Called when the library encounters an error. The error message is included in the callback.
local_stream: Called when the stream is available locally (stream is provided in the callback). This can be used to display to the user his own streaming as it up-streams.

Example

The example below shows a simple initialization:

Response

The response includes the new live streaming instance. You should store this in order to attach, start and stop your live stream. You can use a promise to do this, for example:

The result itself includes a response object that contains information about the initialized live stream. This includes the public_id which you need to use when starting the live stream.

Here's an example of the response object:

Instance methods

Once you have an instance of live streaming initialized you can make use of the instance methods to control your live streaming:

Attach

attach()

Attach your live stream to a video element to show the local stream to the user that is streaming. You can use the local_stream event when initializing your stream to trigger this, for example:

Start

start(publicID)

Start your live streaming using the start method. The method takes a single publicId string argument. This is the public ID of the video stream returned by the initialize request.

For example:

This will start live streaming from the device that calls this method.

Stop

stop()

Stop live streaming using the stop method. This will end live streaming and if fileTarget was set to true, your video will be saved in your Cloudinary product environment.

For example:

Selecting the device to stream from

You can choose which device to stream from, rather than use the default device.

Import the necessary functions/constants from the library:

Then get the relevant stream:

Or:

Or:

Once you've got the stream, pass it to initLiveStream(), for example:

Streaming Devices

The live streaming SDK contains some convenient helper functions and constants:

  • listDevices(): gets a list of streaming devices.
  • getStream(): gets the stream from a device.
  • FRONT_CAMERA: pass this to getStream() in order to get stream from the front camera.
  • REAR_CAMERA: pass this to getStream() in order to get stream from the rear camera.

Controlling the camera

In addition to the standard live streaming functions, you can also make use of some convenient camera functions to enable the user to preview their device camera before initializing a live stream.

attachCamera

attachCamera(<video-element>, facingMode)

Shows the camera in an HTML video element.

detachCamera

detachCamera(<video-element>, stopStream): Removes the camera from an HTML element.

  • <video-element>: The HTML <video> element to detach the camera from. Required.
  • stopStream: Whether to stop the camera stream as well as detaching from the video element. Optional. Default: true.

Here's a simple example of how to use the attachCamera and detachCamera functions to show or hide the camera preview to the user:

Streamer

A convenient wrapper for camera and streaming functions, it exposes functions for showing, hiding and streaming from a camera.

The Streamer wrapper makes it easier to use both camera and live streaming functions together. Here's an example of how to use the Streamer wrapper:

Streaming to other media platforms

Cloudinary's live streaming can also be streamed using other platforms such as Facebook or Youtube.

To stream to other platforms, you need to include the streaming URI retrieved from the relevant platforms, using the facebookUri and youtubeUri parameters when initializing your live stream.

Code explorer: Live Streaming Example

Here's a simple HTML, JavaScript and CSS example of how to add live streaming to your website or application.

  • The HTML includes buttons to select and show/hide the camera, initialize the stream, and to start and stop live streaming. It also displays some of the response elements from the initialization, such as the file and stream URL as well as the public ID.
  • The JavaScript is where you can add your configuration options and controls the logic of the live streaming.
  • The CSS adds some basic styling to the page.

This code is also available in GitHub.

Notes
  • The maximum duration for a live stream is one hour. Streaming will end after an hour and you'll need to initialize a new live stream.
  • 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, only the video streamed up to the point where you exceeded the limits will be stored in your Cloudiinary product environment.

✔️ Feedback sent!

Rate this page: