Live streaming WebRTC (Beta)

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

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.

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

Optional parameters

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:

• Start
• Stop
• Attach

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.

• <video-element>: The HTML <video> element to attach the camera to. Required.
• facingMode: The mode or camera to use. Used to constrain the user to a specific camera on mobile devices. For example to constrain the user to only use the front-facing camera: { exact: "user"}. See https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/facingMode for more information. Optional.

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.