Fork me on GitHub
JavaScript API

The gateway exposes, assuming the HTTP transport has been compiled, a pseudo-RESTful interface, and optionally also WebSocket/RabbitMQ/MQTT/UnixSockets interfaces as well, all of which based on JSON messages. These interfaces are described in more detail in the Plain HTTP REST Interface WebSockets Interface RabbitMQ interface MQTT interface and UnixSockets interface documentation respectively, and all allow clients to take advantage of the features provided by Janus and the functionality made available by its plugins. Considering most clients will be web browsers, a common choice will be to rely on either the REST or the WebSockets interface for the purpose. To make things easier for web developers, a JavaScript library (janus.js) is available that can make use of both interfaces using exactly the same API. This library eases the task of creating sessions with the gateway, attaching WebRTC users to plugins, send and receive requests and events to the plugins themselves and so on. For real examples of how this library can be used, check the demos in the html folder of this package. Notice that the janus.js library makes use of the features made available by the webrtc-adapter shim, which means that your web application should always include it as a dependency. For instance, all the demos link to it externally via cdnjs.com.

Note
The current janus.js library makes use of jQuery (http://jquery.com/) as a support. A version without that dependency is available as janus.nojquery.js in the same folder, so you can use that one instead if required by your web application: all the documentation related to janus.js applies to janus.nojquery.js as well (including the dependency on the webrtc-adapter shim).

In general, when using the gateway features, you would normally do the following:

  1. include the Janus JavaScript library in your web page;
  2. initialize the Janus JavaScript library;
  3. connect to the gateway and create a session;
  4. create one or more handles to attach to a plugin (e.g., echo test and/or streaming);
  5. interact with the plugin (sending/receiving messages, negotiating a PeerConnection);
  6. eventually, close all the handles and shutdown the related PeerConnections;
  7. destroy the session.

The above steps will be presented in order, describing how you can use the low level API to accomplish them. Consider that in the future we might provide higher level wrappers to this API to address specific needs, e.g., a higher level API for each plugin: this would make it even easier to use the gateway features, as a high level API for the streaming plugin, for instance, may just ask you to provide the server address and the ID of the <video> element to display the stream in, and would take care of all the above mentioned steps on your behalf. Needless to say, you're very welcome to provide wrapper APIs yourself, if you feel a sudden urge to do so! :-)


As a first step, you should include the janus.js library in your project:

<script type="text/javascript" src="janus.js" ></script>

The core of the JavaScript API is the Janus object. This object needs to be initialized the first time it is used in a page. This can be done using the static init method of the object, which accepts the following options:

Here's an example:

Janus.init({
   debug: true,
   callback: function() {
           // Done!
   });

Once the library has been initialized, you can start creating sessions. Normally, each browser tab will need a single session with the gateway: in fact, each gateway session can contain several different plugin handles at the same time, meaning you can start several different WebRTC sessions with the same or different plugins for the same user using the same gateway session. That said, you're free to set up different gateway sessions in the same page, should you prefer so.

Creating a session is quite easy. You just need to use the new constructor to create a new Janus object that will handle your interaction with the gateway. Considering the dynamic and asynchronous nature of Janus sessions (events may occur at any time), there are several properties and callbacks you can configure when creating a session:

These properties and callbacks are passed to the method as properties of a single parameter object: that is, the Janus constructor takes a single parameter, which although acts as a container for all the available options. The success callback is where you tipically start your application logic, e.g., attaching the peer to a plugin and start a media session.

Here's an example:

var janus = new Janus(
        {
                server: 'http://yourserver:8088/janus',
                success: function() {
                        // Done! attach to plugin XYZ
                },
                error: function(cause) {
                        // Error, can't go on...
                },
                destroyed: function() {
                        // I should get rid of this
                }
        });

As anticipated, the server may be a specific address, e.g.:

var janus = new Janus(
        {
                server: 'http://yourserver:8088/janus',
                                // or
                server: 'ws://yourserver:8188/',
                [..]

or an array of addresses. Such an array can be especially useful if you want the library to first check if the WebSockets server is reachable and, if not, fallback to plain HTTP, or just to provide a link multiple instances to try for failover. This is an example of how to pass a 'try websockets and fallback to HTTP' array:

var janus = new Janus(
        {
                server: ['ws://yourserver:8188/','http://yourserver:8088/janus'],
                [..]

Once created, this object represents your session with the gateway. you can interact with a Janus object in several different ways. In particular, the following properties and methods are defined:

The most important property is obviously the attach() method, as it's what will allow you to exploit the features of a plugin to manipulate the media sent and/or received by a PeerConnection in your web page. This method will create a plugin handle you can use for the purpose, for which you can configure properties and callbacks when calling the attach() method itself. As for the Janus constructor, the attach() method takes a single parameter that can contain any of the following properties and callbacks:

Here's an example:

// Attach to echo test plugin, using the previously created janus instance
janus.attach(
        {
                plugin: "janus.plugin.echotest",
                success: function(pluginHandle) {
                        // Plugin attached! 'pluginHandle' is our handle
                },
                error: function(cause) {
                        // Couldn't attach to the plugin
                },
                consentDialog: function(on) {
                        // e.g., Darken the screen if on=true (getUserMedia incoming), restore it otherwise
                },
                onmessage: function(msg, jsep) {
                        // We got a message/event (msg) from the plugin
                        // If jsep is not null, this involves a WebRTC negotiation
                },
                onlocalstream: function(stream) {
                        // We have a local stream (getUserMedia worked!) to display
                },
                onremotestream: function(stream) {
                        // We have a remote stream (working PeerConnection!) to display
                },
                oncleanup: function() {
                        // PeerConnection with the plugin closed, clean the UI
                        // The plugin handle is still valid so we can create a new one
                },
                detached: function() {
                        // Connection with the plugin closed, get rid of its features
                        // The plugin handle is not valid anymore
                }
        });

So the attach() method allows you to attach to a plugin, and specify the callbacks to invoke when anything relevant happens in this interaction. To actively interact with the plugin, you can use the Handle object that is returned by the success callback (pluginHandle in the example).

This Handle object has several methods you can use to interact with the plugin or check the state of the session handle:

While the Handle API may look complex, it's actually quite straightforward once you get the concept. The only step that may require a little more effort to understand is the PeerConnection negotiation, but again, if you're familiar with the WebRTC API, the Handle actually makes it a lot easier.

The idea behind it's usage is the following:

  1. you use attach() to create a Handle object;
  2. in the success callback, your application logic can kick in: you may want to send a message to the plugin (send({msg})), negotiate a PeerConnection with the plugin right away ( createOffer followed by a send({msg, jsep})) or wait for something to happen to do anything;
  3. the onmessage callback tells you when you've got messages from the plugin; if the jsep parameter is not null, just pass it to the library, which will take care of it for you; if it's an OFFER use createAnswer (followed by a send({msg, jsep}) to close the loop with the plugin), otherwise use handleRemoteJsep ;
  4. whether you took the initiative to set up a PeerConnection or the plugin did, the onlocalstream and/or the onremotestream callbacks will provide you with a stream you can display in your page;
  5. each plugin may allow you to manipulate what should flow through the PeerConnection channel: the send method and onmessage callback will allow you to handle this interaction (e.g., to tell the plugin to mute your stream, or to be notified about someone joining a virtual room), while the ondata callback is triggered whenever data is received on the Data Channel, if available (and the ondataopen callback will tell you when a Data Channel is actually available).

The following paragraphs will delve a bit deeper in the negotiation mechanism provided by the Handle API, in particular describing the properties and callbacks that may be involved. To follow the approach outlined by the W3C WebRTC API, this negotiation mechanism is heavily based on asynchronous methods as well.

Whether you use createOffer or createAnswer depending on the scenario, you should end up with a valid jsep object returned in the success callback. You can attach this jsep object to a message in a send request to pass it to the plugin, and have the gateway negotiate a PeerConnection with your application.

Here's an example of how to use createOffer, taken from the Echo Test demo page:

// Attach to echo test plugin
janus.attach(
        {
                plugin: "janus.plugin.echotest",
                success: function(pluginHandle) {
                        // Negotiate WebRTC
                        echotest = pluginHandle;
                        var body = { "audio": true, "video": true };
                        echotest.send({"message": body});
                        echotest.createOffer(
                                {
                                        // No media property provided: by default,
                                                // it's sendrecv for audio and video
                                        success: function(jsep) {
                                                // Got our SDP! Send our OFFER to the plugin
                                                echotest.send({"message": body, "jsep": jsep});
                                        },
                                        error: function(error) {
                                                // An error occurred...
                                        }
                                });
                },
                [..]
                onmessage: function(msg, jsep) {
                        // Handle msg, if needed, and check jsep
                        if(jsep !== undefined && jsep !== null) {
                                // We have the ANSWER from the plugin
                                echotest.handleRemoteJsep({jsep: jsep});
                        }
                },
                [..]
                onlocalstream: function(stream) {
                        // Invoked after createOffer
                        // This is our video
                },
                onremotestream: function(stream) {
                        // Invoked after handleRemoteJsep has got us a PeerConnection
                        // This is the remote video
                },
                [..]

This, instead, is an example of how to use createAnswer, taken from the Streaming demo page:

// Attach to echo test plugin
janus.attach(
        {
                plugin: "janus.plugin.streaming",
                success: function(pluginHandle) {
                        // Handle created
                        streaming = pluginHandle;
                        [..]
                },
                [..]
                onmessage: function(msg, jsep) {
                        // Handle msg, if needed, and check jsep
                        if(jsep !== undefined && jsep !== null) {
                                // We have an OFFER from the plugin
                                streaming.createAnswer(
                                        {
                                                // We attach the remote OFFER
                                                jsep: jsep,
                                                // We want recvonly audio/video
                                                media: { audioSend: false, videoSend: false },
                                                success: function(ourjsep) {
                                                        // Got our SDP! Send our ANSWER to the plugin
                                                        var body = { "request": "start" };
                                                        streaming.send({"message": body, "jsep": ourjsep});
                                                },
                                                error: function(error) {
                                                        // An error occurred...
                                                }
                                        });
                        }
                },
                [..]
                onlocalstream: function(stream) {
                        // This will NOT be invoked, we chose recvonly
                },
                onremotestream: function(stream) {
                        // Invoked after send has got us a PeerConnection
                        // This is the remote video
                },
                [..]

Of course, these are just a couple of examples where the scenarios assumed that one plugin would only receive (Echo Test) or generate (Streaming) offers. A more complex example (e.g., a Video Call plugin) would involve both, allowing you to either send offers to a plugin, or receive some from them. Handling this is just a matter of checking the type of the jsep object and reacting accordingly.


This is it! For more information about the API, have a look at the demo pages that are available in the html folder in this package.