Getting Started

Overview

elasticRTC makes it easy to deploy scalable WebRTC media infrastructures in Amazon Web Services (AWS). You can forget about the infrastructure and focus on building great apps. Just use the elasticRTC APIs and integrate advanced video and audio communications in your Web and mobile applications without headaches.

_images/elasticrtc-diagram.png

General features

  • WebRTC compatible, including simulcast and multi-stream.
  • Group communications.
  • Media broadcasting.
  • Media recording and playing (S3, HTTP, RTSP).
  • Transcoding.
  • Autoscaling.
  • Control APIs and SDKs.

What do you need?

  • A webcam and a microphone.

  • A WebRTC browser, such as Chrome or Firefox.

  • Some basic tools for deploying the cluster:

  • An AWS account. If it’s the first time you are setting your account, make sure you store the AWS Access Key ID and AWS Access Secret Key, as you’ll need them later on.

  • Java or Node.js web server. You can find some ideas here.

5 minutes to being elastic

That’s enough yada yada. Let’s get to business! Here’s what you need to start your own elasticRTC cluster.

Fire up the cloud

The first thing we are going to do is start the elasticRTC cluster. We’ll use elasticrtc-tools for that. Change directory to elasticrtc-tools/tools and deploy a cluster with a single command:

./elasticrtc create --region eu-west-1 --stack-name mycluster

where

--region AWS region where cluster is deployed.
--stack-name Cluster name. It must start with letter, contain only alphanumeric characters and be unique in selected region. White spaces are not allowed.
The first time you execute the command, you might be prompted for your AWS Access Key ID and AWS Access Secret Key in order to continue. Click on the arrow to see the complete message. Pay attention to the highlighted lines!
====================================
AWS credentials not configured. Access and secret keys must be
provided in order to allow elasticRTC to access AWS APIs.
If you're the account administrator execute following procedure:
  1 - Navigate to https://console.aws.amazon.com/iam/home?#security_credential
  2 - Open section Access Keys (Access Key ID and Secret Access Key)
  3 - Press button Create New Access Key
If you're not the account administrator you still can generate credentials
with following procedure
  1 - Navigate to https://myaccount.signin.aws.amazon.com/console. Your AWS
      administrator will provide you the value for myaccount
  2 - Login to AWS console with you IAM user and password. Ask your AWS
      administrator if you don't have an IAM user
  3 - Navigate to IAM home https://console.aws.amazon.com/iam/home#home
  4 - Open section 'Rotate your access keys' and click 'Manage User Access Key'
  5 - Go to section 'Security Credentials' and click 'Create Access Key'
====================================
Enter AWS Access Key ID:AKIAIOSFODNN7EXAMPLE
Enter AWS Secret Access Key:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
After a successful run, you will see some logs with relevant information about the cluster. Click on the arrow for a sample output.
elasticRTC: Found AWS profile: default
elasticRTC: Build CloudFormation template
elasticRTC: Get Kurento Media Server AMI for region: eu-west-1
elasticRTC: Start CloudFormation stack: mycluster
Creating cluster..............................................[OK]

====================================
elasticRTC Cluster: mycluster
     Status:
          CREATE_COMPLETE
     Version:
          |CLIENT_VERSION|
     Cluster URL
          ws://myclusterKurentoLoadBalancer-559451190.eu-west-1.elb.amazonaws.com/kurento
     Cluster Instances : 1
          i-37dcdbbc : m3.medium - 10.0.237.125/52.48.35.246
     APP:
          none
     Build parameters:
          api-key                 : kurento
          api-origin              : 0.0.0.0/0
          aws-app-instance-type   : m3.medium
          aws-instance-tenancy    : default
          aws-instance-type       : m3.medium
          aws-key-name            : aws_key
          aws-s3-bucket-name      : eu-west-1-mycluster
          control-origin          : 0.0.0.0/0
          desired-capacity        : 1
          elasticsearch-password  :
          elasticsearch-ssl       :
          elasticsearch-transport :
          elasticsearch-user      :
          hosted-zone-id          :
          inspector-pass          :
          inspector-user          :
          log-storage             : cloudwatch
          max-capacity            : 1
          min-capacity            : 1
          ssl-cert                :
          ssl-key                 :
          version                 : |CLIENT_VERSION|
====================================

Get the libraries

elasticRTC is fully compatible with Kurento‘s’ API and uses the same libraries. You can develop your applications in three flavors: Java, JavaScript and Node.js. Each language has a different way of managing dependencies.

For Java developers.

We recommend that you use a build tool that supports dependency management such as Maven. elasticRTC is compatible with Apache Maven 3.2 or above. If you don’t already have Maven installed, you can follow the instructions at maven.apache.org.

Add following code to your pom.xml file:

<dependencies>
    <dependency>
      <groupId>org.kurento</groupId>
      <artifactId>kurento-client</artifactId>
      <version>6.5.0</version>
    </dependency>
</dependencies>

If you prefer not to use Maven, you can still download them from the Maven repository, and place the appropriate kurento-\*.jar files on your classpath.

For JavaScript browser developers.

The recommended way of managing dependencies in your JavaScript projects is through bower. First, you’ll need to include the dependency in your bower.json project file, along with your other dependencies:

"dependencies": {
  "kurento-client": "6.5.0"
}

That will put the kurento-client.js in your bower_componets folder. In order to use that script file in the application, you’ll need to import it in your html file with the following line:

<script src="bower_components/kurento-client/js/kurento-client.js"></script>
For Node.js developers.

It is recommended to manage your dependencies through npm. You can run the following command in your Node.js project, to have the dependency installed and added to your package.json file. If you don’t already have npm installed, you can follow the instructions provided in the npm installation guide:

$ npm install kurento-client@6.5.0 --save --save-exact

This is a server-side dependency that can be imported with function require() in any file where is needed:

var kurento = require('kurento-client')

Build your first app!

We’ll start with a simple loopback application that lets you test your deployment. The loopback is one of the simplest application you can create, where the local stream is sent to the elasticRTC, which sends it back to the client without modifications.

Loopback pipeline

WebRTC endpoint connected in loopback

The application consists of a single page with two HTML5 <video> tags: one showing the local stream (as captured by the webcam) and the other showing the remote stream.

Leaving aside the page layout, we’ll focus on how to get the elements to achieve the loopback. On the client side (i.e. the browser), we’ll be using a wrapper of the RTCPeerConnection object called WebRtcPeer, which is provided by the kurento-utils library. For this reason, we need to import this library in our HTML source:

<script src="./js/kurento-utils.js"></script>

And then create a WebRtcPeer instance in the browser side. Notice that <video> tags for local and remote displays are provided in the constructor.

1
2
3
4
5
6
7
var options = {
  localVideo: document.getElementById('localVideo'),
  remoteVideo: document.getElementById('remoteVideo'),
  onicecandidate : onBrowserIceCandidate,
};

webRtcPeer = kurentoUtils.WebRtcPeer.WebRtcPeerSendrecv(options, creationCallback);

Now we need to create the WebRtcEndpoint in the elasticRTC side. kurento-client is the library that controls the cluster, so just have to add following code to your HTML page:

<script src="./js/kurento-client.js"></script>

And connect to elasticRTC:

elasticRtcClient(wsUri, function(error, client) {
  // We'll add some code here later
}

Parameter wsUri is the API endpoint’s URL where elasticRTC listens for control commands. The callback will return a client which will allow us to: create, connect and destroy media elements, amongst other things. These elements are created in elasticRTC, but can be controlled through proxy objects provided by the kurento-client. Let’s see how we can create the pipeline:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
elasticRtcClient(wsUri, function(error, client) {
  client.create("MediaPipeline", function(error, pipeline) {
    pipeline.create("WebRtcEndpoint", function(error, webRtcEndpoint) {
      webRtcEndpoint.on('OnIceCandidate', onServerIceCandidate);
      webRtcEndpoint.connect(webRtcEndpoint, function(error) {
        console.log("Loopback established");
      });
    });
  });
});

Note

All error management code has been removed for clarity.

We have first created the MediaPipeline (line 2), and afterwards the WebRtcEndpoint (line 3). The endpoint is then connected with itself to build the loopback (line 9), so whatever comes in, is sent back. Since we are going to use Trickle ICE, we are also subscribing to the OnIceCandidate event (line 4), so the RTCPeerConnection in the browser can process those.

Note

If you are new to WebRTC, please consider reading the WebRTC fundamentals and the Streaming with WebRTC guides.

Now, we can initiate the negotiation as described here

1
2
3
4
5
6
7
8
9
function negotiateBrowserWithElasticRtc(error) {
  if (error) return onError(error);
  webRtcPeer.generateOffer(function(error, sdpOffer) {
    webRtcEndpoint.processOffer(sdpOffer, function(error, sdpAnswer) {
      webRtcPeer.processAnswer(sdpAnswer, onError);
    });
    webRtcEndpoint.gatherCandidates(onError);
  });
}

First we have the browser object - webRtcPeer - generating an offer (line 3). This offer is passed to the proxy object that represents the server’s peer: the webRtcEndpoint (line 4). Once the server has processed the offer, it will send back an answer for the browser (line 5). Last, we signal the server to start gathering candidates.

Once you get everything together, here’s how it will look like. You can see the different pieces of the application right away!

You can find other sample projects in elasticRTC Tutorials.

Note

If you are looking for the real deal, you might want to check the Room Application to be deployed along with your elasticRTC cluster.