openvidu-hello-world

Check it on GitHub

This is the simplest demo you can try to get started with OpenVidu. It has the minimum set of features to make a group video-call. You will only need a few minutes to get your first application working!

Running this tutorial

1) Clone the repo:

git clone https://github.com/OpenVidu/openvidu-tutorials.git

2) You will need an http web server installed in your development computer to execute the tutorial. If you have node.js installed, you can use http-server to serve application files. It can be installed with:

npm install -g http-server

3) Run the tutorial:

http-server openvidu-tutorials/openvidu-hello-world/web

4) openvidu-server and Kurento Media Server must be up and running in your development machine. The easiest way is running this Docker container which wraps both of them (you will need Docker CE):

docker run -p 4443:4443 --rm -e openvidu.secret=MY_SECRET openvidu/openvidu-server-kms

5) Go to localhost:8080 to test the app once the server is running. The first time you use the docker container, an alert message will suggest you accept the self-signed certificate of openvidu-server when you first try to join a video-call.


If you are using Windows, read this FAQ to properly run the tutorial

To learn some tips to develop with OpenVidu, check this FAQ

Understanding the code

This application is very simple. It has only 4 files:

  • openvidu-browser-VERSION.js: openvidu-browser library. You don't have to manipulate this file.
  • app.js: sample application main JavaScritp file, which makes use of openvidu-browser-VERSION.js.
  • style.css: some CSS classes to style index.html.
  • index.html: HTML code for the form to connect to a video-call and for the video-call itself. It has two links to both JavaScript files:
  <script src="openvidu-browser-VERSION.js"></script>
<script src="app.js"></script>

Let's see how app.js uses openvidu-browser-VERSION.js:


First lines declare the variables that will be needed in different points along the code

var OV;
var session;

OV will be our OpenVidu object (entrypoint to the libray). session will be the video-call we will connect to. As first sentence in the joinSession() method, we initialize the variable that will identify our video-call retrieving the value from the HTML input.

var mySessionId = document.getElementById("sessionId").value;

Initialize a new session and its events

OV = new OpenVidu();
session = OV.initSession();

session.on('streamCreated', function (event) {
  session.subscribe(event.stream, 'subscriber');
});

As you can see in the code, the process is very simple: get an OpenVidu object and initialize a Session object with it.

Then you can subscribe to all the events you want for your session. In this case we just want to subscribe to every stream that is being created in the session: on streamCreated we subscribe to the specific stream, available at event.stream property.

You can take a look at all the events in the Reference Documentation


Get a token from OpenVidu Server

WARNING: This is why this tutorial is an insecure application. We need to ask OpenVidu Server for a user token in order to connect to our session. This process should entirely take place in our server-side, not in our client-side. But due to the lack of an application backend in this tutorial, the JavaScript code itself will perform the POST operations to OpenVidu Server
getToken(mySessionId).then(token => {
    // See next point to see how to connect to the session using 'token'
});

Now we need a token from OpenVidu Server. In a production environment we would perform this operations in our application backend, by making use of the API REST, OpenVidu Java Client or OpenVidu Node Client. Here we have implemented the POST requests to OpenVidu Server in a mehtod getToken() that returns a Promise with the token. Without going into too much detail, this method performs two ajax requests to OpenVidu Server, passing OpenVidu Server secret to authenticate them:

  • First ajax request performs a POST to /api/sessions (we send a customSessionId field to name the session with our mySessionId value retrieved from HTML input)
  • Second ajax request performas a POST to /api/tokens (we send a sessionId field to assign the token to this same session)

You can inspect this method in detail in the GitHub repo.


Connect to the session using the token

getToken(mySessionId).then(token => {

  session.connect(token)
    .then(() => {
      document.getElementById("session-header").innerText = mySessionId;
      document.getElementById("join").style.display = "none";
      document.getElementById("session").style.display = "block";

      var publisher = OV.initPublisher("publisher");
      session.publish(publisher);
    })
    .catch(error => {
      console.log("There was an error connecting to the session:", error.code, error.message);
    });
});

We simply need to call session.connect passing the recently retrieved token from OpenVidu Server. This method returns a Promise to which you can subscribe to.

In case of success we first set the view to the active video session. Then we proceed to publish our webcam. To do so we just get a publisher using OpenVidu.initPublisher method, and a new HTML video showing our webcam will be appended to the page inside element with id "publisher".

Last but not least, we publish this publisher object thanks to session.publish. At this point the rest of users connected to this session will trigger their own streamCreated event and can start watching our webcam.


Leaving the session:

session.disconnect();

Whenever we want a user to leave the session, we just need to call session.disconnect method. Here it will be called inside leaveSession function, triggered when the user clicks on "LEAVE" button. This function also returns the page to the "Join session" view.