Fork me on GitHub
JavaScript API

Janus exposes, assuming the HTTP transport has been compiled, a pseudo-RESTful interface, and optionally also WebSocket/RabbitMQ/MQTT/Nanomsg/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 Nanomsg 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 Janus core, 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 allows you to provide custom implementations of certain dependencies, in order to make it easier to integrate with other JavaScript libraries and frameworks. Using this feature you can ensure janus.js does not (implicitly) depend on certain global variables. Two implementations are included in janus.js itself:
  1. Janus.useDefaultDependencies which relies on native browser APIs, which in turn require somewhat more modern browsers
  2. Janus.useOldDependencies which uses jQuery (http://jquery.com/) instead, and should provide equivalent behaviour to previous versions of janus.js

By default Janus.useDefaultDependencies will be used, but you can override this when initialising the Janus library and pass a custom dependencies object instead. For details, refer to: Working with custom janus.js dependencies

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

  1. include the Janus JavaScript library in your web page;
  2. initialize the Janus JavaScript library and (optionally) passing its dependencies;
  3. connect to the server 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 server 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! :-)

Using janus.js

As a first step, you should include the Janus library in your project. Depending on your needs you can either use janus.js or one of the generated JavaScript module variants of it. For available module syntaxes and how to build the corresponding variants, see: Using janus.js as JavaScript module

<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,
   dependencies: Janus.useDefaultDependencies(), // or: Janus.useOldDependencies() to get the behaviour of previous Janus versions
   callback: function() {
           // Done!
   });
Note
When using one of the JavaScript module variants of janus.js, you will need to import the Janus symbol from the module first. See also: Using janus.js as JavaScript module For example, using the ECMAScript module variant, the above example should be altered to:
import * as Janus from './janus.es.js'

Janus.init({
   debug: true,
   dependencies: Janus.useDefaultDependencies(), // or: Janus.useOldDependencies() to get the behaviour of previous Janus versions
   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 server: in fact, each Janus 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 Janus session. That said, you're free to set up different Janus 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 server. 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 server. 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. Notice that the following paragraphs address the first negotiation step, that is the one to create a new PeerConnection from scratch: to know how to originate or handle a renegotiation instead (e.g., to add/remove/replace a media source, or force an ICE restart) check the Updating an existing PeerConnection (renegotiations) section instead.

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 Janus 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...
                                        },
                                        customizeSdp: function(jsep) {
                                                // if you want to modify the original sdp, do as the following
                                                // oldSdp = jsep.sdp;
                                                // jsep.sdp = yourNewSdp;
                                        }
                                });
                },
                [..]
                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.

Updating an existing PeerConnection (renegotiations)

While the JavaScript APIs described above will suffice for most of the common scenarios, there are cases when updates on a PeerConnection may be needed. This can happen whenever, for instance, you want to add a new media source (e.g., add video to an audio only call), replace an existing one (e.g., switch from capturing the camera to sharing your screen), or trigger an ICE restart because of a network change. All these actions require a renegotiation to occur, which means a new SDP offer/answer round to update the existing PeerConnection.

Since version 0.2.6, renegotiations are indeed supported by Janus, and the janus.js library exposes ways to easily handle the process of updating a media session. More specifically, there are additional properties you can pass to createOffer and createAnswer for the purpose: most of the properties introduced in the previous section will still be usable, as it will be clearer in the next paragraphs.

The new properties you can pass to media in createOffer and createAnswer are the following:

Notice that these properties are only processed when you're trying a renegotiation, and will be ignored when creating a new PeerConnection.

These properties don't replace the existing media properties, but go along with them. For instance, when adding a new video stream, or replacing an existing one, you can still use the video related properties as before, e.g., to pass a specific device ID or asking for a screenshare instead of a camera. Besides, notice that you'll currently have to pass info on the streams you want to keep as well, or they might be removed: this means that, if for instance you want to replace the video source, but want to keep the audio as it is, passing audio:false to the new createOffer will potentially disable audio.

It's important to point out that, as for negotiations that result in the creation of a new PeerConnection in the first place, how to perform a renegotiation in practice will typically vary depending on the plugin that you're trying to do it for. Some plugins may allow you to offer a renegotiation, others may require you to send a different request instead in order to trigger a renegotiation from the plugin. As it will be clearer later, this is especially true for ICE restarts. As such, apart from the generic and core-related definitions introduced in this section, please refer to the documentation for each individual plugin for more information about how to perform renegotiations in specific use cases.

Here's a simple example of how you can use removeVideo to remove the local video capture in a session, e.g., in the EchoTest demo:

// Remove local video
echotest.createOffer(
    {
        media: { removeVideo: true },
        success: function(jsep) {
            Janus.debug(jsep);
            echotest.send({message: {audio: true, video: true}, "jsep": jsep});
        },
        error: function(error) {
            bootbox.alert("WebRTC error... " + JSON.stringify(error));
        }
    });

This other example shows how you can add a new video stream to an-audio only PeerConnection instead:

// Add local video
echotest.createOffer(
    {
        media: { addVideo: true },
        success: function(jsep) {
            Janus.debug(jsep);
            echotest.send({message: {audio: true, video: true}, "jsep": jsep});
        },
        error: function(error) {
            bootbox.alert("WebRTC error... " + JSON.stringify(error));
        }
    });

Finally, this example shows how you can replace the video track, by also showing how you can combine this with one of the properties we already met in the previous section:

// Replace local video
echotest.createOffer(
    {
        media: {
            video: {
                deviceId: "44f4740bee234ce6ddcfea8e59e8ed7505054f75edf27e3a12294686b37ff6a7"
            },
            replaceVideo: true
        },
        success: function(jsep) {
            Janus.debug(jsep);
            echotest.send({message: {audio: true, video: true}, "jsep": jsep});
        },
        error: function(error) {
            bootbox.alert("WebRTC error... " + JSON.stringify(error));
        }
    });

Notice that renegotiations involving media changes (both local and remote) will likely result in new calls to the onlocalstream and onremotestream application callbacks: as such, be prepared to see those callbacks called for the same PeerConnection more than once during the course of a media session.

ICE restarts

While ICE restarts can be achieved with a renegotiation, they're complex enough to deserve a specific subsection. In fact, ICE restarts don't address changes in the media, but in the underlying transport itself. They're used, for instance, when there's a network change (e.g., the IP address changed, or the user switched from WiFi to 4G). In order for this to work, new candidates must be exchanged, and connectivity checks must be restarted in order to find the new optimal path.

With janus.js, you can only force an ICE restart when sending a new offer. In order to do so, all you need to do is add iceRestart:true to your createOffer call, and an ICE restart will be requested. The following example shows how this can be done with the EchoTest:

echotest.createOffer({
    iceRestart: true,
    media: { data: true },
    success: function(jsep) {
        echotest.send({message: {audio: true, video: true}, jsep: jsep});
        }
});

In this particular example, we're not asking for any change on the media streams, but just an ICE restart. If successful, as soon as the answer is received, the client and Janus will restart the ICE process and find a new path for the media packets.

Notice that, with Janus and its plugins, you won't always be able to force an ICE restart by sending a new SDP offer yourself: some plugins, like the Streaming plugin for instance, will want to always send an offer themselves, which means they'll be the ones actually forcing the ICE restart from a negotiation perspective. In order to still allow users to actually originate the process, all the stock Janus plugins that assume they'll be sending offers for some or all of their media streams also expose APIs to force an ICE restart from the server side. You can learn more about this on a plugin level basis here and here. Besides, make sure you read the documentation for each of the plugins you're interested in using ICE restarts for, as the details for how to perform it properly are typically provided there.

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.

Last updated on Sat May 30 2020 — Janus WebRTC Server © Meetecho 2014-2020