Getting Started with OpenTok: From 0 to simple group video chat

TokBox is the company that provides the video streaming API called OpenTok. This tutorial will be a walk through to creating a very simple group video chat application.

There are two flavors to the OpenTok API, OpenTok Flash that uses flash plugin and OpenTok WebRTC that uses the new and cool HTML 5 technology, and they are not interoperable.

WebRTC provides a much better video chat experience when it comes to quality but is currently only supported officially in Firefox and Chrome. Internet Explorer users must install Chrome Frame plugin.

Flash on the other hand, is supported in 99% of all browsers and allows the ability to record live video streams as they occur (archiving).

Fortunately, both flash and webrtc has a very similar interface so in most cases changing technology can be as simple as changing the javascript library.

To get started, you must first include our javascript library. In this example, we will use OpenTok WebRTC:

[html]<script type="text/javascript" src="http://static.opentok.com/webrtc/v2.0/js/TB.min.js"></script>[/html]

Now, you can create a publisher object in your javascript. Make sure you have a div element with id “myPublisherDiv” in your HTML so it can get replaced by your video feed.

[html]<div id="myPublisherDiv"></div>[/html]
[javascript]var publisher = TB.initPublisher(apiKey, ‘myPublisherDiv’);[/javascript]

Next, we need to create a session object with an OpenTok session Id. Think of sessionId as rooms. People connected to the same sessionId, or room id, will be able to publish and subscribe to each others’ video streams and hence see each other. You will need to generate sessionIds in your server with your Api key and secret. For your convenience, you can quickly generate one from your developer dashboard.

[javascript]var publisher = TB.initPublisher(apiKey, ‘myPublisherDiv’);
var session = TB.initSession(sessionId);[/javascript]

After creating a session object, we should connect to it. To connect to a session, we need a token. Think of token as the key to get into a room. Tokens are always generated for its respective sessionId. You will need to generate tokens in your server with your api key, secret, and the sessionId that you wish to connect to. For your convenience, you can quickly generate one from your developer dashboard.

[javascript]var session = TB.initSession(sessionId);
session.connect(apiKey, token);[/javascript]

Since session.connect is asynchronous because it needs to talk to OpenTok servers, we need to add an event listener to know when we have successfully connected to a session:

[javascript]var session = TB.initSession(sessionId);
session.addEventListener(‘sessionConnected’, function(e){
alert("we are connected!");
});
session.connect(apiKey, token);[/javascript]

When we are connected to the session, our event callback function will be called. Lets start publishing our video into the session by calling ‘session.publish’ so other people connected to that session can see us.

[javascript]var publisher = TB.initPublisher(apiKey, ‘myPublisherDiv’);
var session = TB.initSession(sessionId);
session.addEventListener(‘sessionConnected’, function(e){
session.publish( publisher );
});
session.connect( apiKey, token );[/javascript]

What if there were people already publishing into our session? When we are connected to the session, our event callback function will be called. This event callback will have an event parameter that contains users who is currently publishing video into the session (event.streams). To see them, all we have to do is to subscribe to their video streams. We will write a for loop and subscribe to all the video streams currently in that session.

[javascript]session.addEventListener(‘sessionConnected’, function(e){
session.publish( publisher );
for (var i = 0; i < e.streams.length; i++) {
session.subscribe(e.streams[i]);
}
}[/javascript]

If you subscribe to all video streams, we might accidentally subscribe to our own videos. To prevent this, we would need a quick check to make sure we do not subscribe to our own stream.

[javascript]session.addEventListener(‘sessionConnected’, function(e){
session.publish( publisher );
for (var i = 0; i < e.streams.length; i++) {
// Make sure we don’t subscribe to ourself
if (streams[i].connection.connectionId == session.connection.connectionId) {
return;
}
session.subscribe(e.streams[i]);
}
}[/javascript]

If you like control over where the subscribed video streams are located, its a good practice to create a new div element and replace that div with the newly subscribed streams.

[javascript]…
for (var i = 0; i < e.streams.length; i++) {

// Create the div to put the subscriber element in to
var div = document.createElement(‘div’);
div.setAttribute(‘id’, ‘stream’ + streams[i].streamId);
document.body.appendChild(div);

session.subscribe(streams[i], div.id);
}
…[/javascript]

What if users joins after you have already connected to your session? To complete our app, you would need to listen to streamCreated event in order to subscribe to people who started publishing after you have already connected to the session. When new streams are created, stream created event callback function will be called. This event callback will have an event parameter that contains an array of streams that just joined. To see them, all we have to do is to subscribe to each stream (credit tobi). We will write a for loop and subscribe to all the video streams from the stream created event. Make sure you dont subscribe to your own streams!

[javascript]session.addEventListener(‘sessionConnected’, …);
session.addEventListener(‘streamCreated’, function(e){
for (var i = 0; i < e.streams.length; i++) {
// Make sure we don’t subscribe to ourself
if (streams[i].connection.connectionId == session.connection.connectionId) {
return;
}
// Create the div to put the subscriber element in to
var div = document.createElement(‘div’);
div.setAttribute(‘id’, ‘stream’ + streams[i].streamId);
document.body.appendChild(div);
session.subscribe(streams[i], div.id);
}
});
session.connect( apiKey, token );[/javascript]

Congratulations! Now that you have completed our getting started tutorial, you can complete your lesson by going over how to create sessions and generate tokens from your server.

If you like to jump right into code, check out some of our getting started demo apps!