Tutorial 1: broadcasting video with APIDEO

>Level: beginner

In this first tutorial, we will see how Apideo is easy to use. We will go through a simple sample where you are streaming your image from one computer and viewing your image on another computer.

The goal of this tutorial is to develop 2 web pages. One web page will be used by Alice to broadcast her image from a webcam. The other page will be used by Bob to receive Alice's picture.

In order to go through this tutorial, we assume that you have a web server set-up, and that you are familiar with the basic concepts of HTML and Javascript.

We also assume that you already have your Apideo key, that you have downloaded the API and installed it on your server.

In this tutorial, we assume that the API is installed in your server, in the directory [webroot]/apideo, where [webroot] is the root of your website.

Broadcast page

We will first create the broadcaster page.

It is actually very simple.

broadcaster.html

<html>
    <head>
        <script src="[path to apideo]/apideo/apideo.js"></script>
        <script type="text/javascript">
            function init() {
                myConnection = Apideo.connect("112233445566778899")
                myRoom = myConnection.joinRoom("myroom")
                myRoom.startCamera("cameraDiv","mystream", {width:320, height:240})
            }
        </script>				
    </head>
    <body onload="init()">
        <div id="cameraDiv"></div>
    </body>
</html>

That's it!

Ok, this is very basic. As you can see, there is a really simple HTML page with a <div> whose id is "cameraDiv". The script tag is loading the Apideo library. Of course, you need to replace [path to apideo] with your web path to the Apideo library. And then, there are those 3 lines of Javascript code that gets executed when the page starts. Let's have a closer look at those.

myConnection = Apideo.connect("112233445566778899")

The first line invokes the Apideo.connect function that will connect you to Apideo. As you might already have guessed, you will need to replace the 1234457890ABCDEF00 part of the code with your Apideo key. Otherwise, you will get an error. This function returns an ApideoConnection object. This object is used to perform basic tasks in Apideo.

myRoom = myConnection.joinRoom("myroom")

In Apideo, people meet in "rooms". Rooms are virtual places where people get together. So if you want 2 persons to see each other, the first step is to let those persons join the same room. This is exactly what the ApideoConnection.joinRoom function does. In Apideo, you do not need to "create" a room. Instead, you just "join" the room. When you join the room, if the room does not exist, it is automatically created. Furthermore, when the last user quits the room, the room is automatically destroyed.

myRoom.startCamera("cameraDiv","mystream", {width:320, height:240})

Finally, using the myRoom object returned by the joinRoom function, you can start broadcasting your image using the ApideoRoom.startCamera function. The ApideoRoom.startCamera function takes 3 parameters:

The first parameter is the id of the div that will be the target for the camera.

The second parameter is the name of the stream. When you are streaming a video in a room, you must give it a name. This name will be used by the viewers to see your stream.

The last parameter is the JSON object containing parameters regarding the size and quality of the stream. Here, we only specify the width and the height of the camera. Many other parameters can be viewed here.

Using only those 3 lines of code, we managed to connect to Apideo and to broadcast our image on the web.

Please note that you need to deploy the HTML page on a web-server. Due to security restrictions, most browsers will prevent you from running the Apideo API by double clicking on the HTML file directly from you operating system. You need to go through a proper web-server (like Apache, IIS, are the web-server your hosting company provides to you.

Now, let's see what to do to receive this image in another page.

Receiver page

receiver.html

<html>
    <head>
        <script src="[path to apideo]/apideo/apideo.js"></script>
        <script type="text/javascript">
            function init() {
                myConnection = Apideo.connect("112233445566778899")
                myRoom = myConnection.joinRoom("myroom")
                myRoom.playStream("playerDiv","mystream", {width:320, height:240})
            }
        </script>				
    </head>
    <body onload="init()">
        <div id="playerDiv"></div>
    </body>
</html>

That's it!

If you have a close look at the receiver's code, you will certainly notice that the code is quite close to the code of the broadcaster. This is actually normal. Just like the broadcaster, we are first connecting to Apideo, and then, we are joining the room whose id is "myroom".

The difference is in the last line of code:

myRoom.playStream("playerDiv","mystream", {width:320, height:240})

This ApideoRoom.playStream function will simply get the stream whose id is "mystream" and will display it in the <div> element whose id is "playerDiv". The third parameter is the size of the video.

A note about concurrent connections

Depending on your Apideo account, you can stream a limited number of concurrent streams. If you are using a standard free account, you are limited to 2 streams in upload and 2 streams in download. In this tutorial, this means that you only 2 users can open the receiver.html page at the same time.

If a third user tries to open the receiver.html page, it will be notified by an error message.

All error messages can be intercepted and customized by the developer. You can learn more about errors handling in this section.

Where to go from here?

We just performed our first steps with Apideo. Now that we know how to stream some content from one page to another, establishing a 2 ways conversation is trivial.

We just need to broadcast a "aliceStream" stream from alice.html to bob.html and broadcast a "bobStream" stream from bob.html to alice.html

We have our video discussion, but this requires our users to have a webcam. Although webcams are pretty common these days, there are still computers without any. We have to provide a fallback mechanism for those users.

In the next tutorial, we will see how to develop a chat application by sending and receiving events.

This will require a bit more Javascript, but nothing to hard to understand.

Javascript Gurus, stay tuned, there are more hard-core tutorial for you later!