Loading...
Searching...
No Matches
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.
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: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:
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! :-)
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:
debug: whether debug should be enabled on the JavaScript console, and what levelstrue or "all": all debuggers enabled (Janus.trace, Janus.debug, Janus.log, Janus.warn, Janus.error)["trace", "warn"]): only enable selected debuggers (allowed tokens: trace, debug, log, warn, error)false: disable all debuggerscallback: a user provided function that is invoked when the initialization is completedependencies: a user provided implementation of Janus library dependenciesHere's an example:
Janus.init({
debug: true,
dependencies: Janus.useDefaultDependencies(), // or: Janus.useOldDependencies() to get the behaviour of previous Janus versions
callback: function() {
// Done!
}
});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:
server: the address of the server as a specific address (e.g., http://yourserver:8088/janus to use the plain HTTP API or ws://yourserver:8188/ for WebSockets) or as an array of addresses to try sequentially to allow automatic for fallback/failover during setup;iceServers: a list of STUN/TURN servers to use (a default STUN server will be used if you skip this property);ipv6: whether IPv6 candidates should be gathered or not;withCredentials: whether the withCredentials property of XHR requests should be enabled or not (false by default, and only valid when using HTTP as a transport, ignored for WebSockets);max_poll_events: the number of events that should be returned when polling; the default is 1 (polling returns an object), passing a higher number will have the backend return an array of objects instead (again, only valid for HTTP usage as this is strictly related to long polling, ignored for WebSockets);destroyOnUnload: whether we should destroy automatically try and destroy this session via Janus API when onbeforeunload is called (true by default);token , apisecret: optional parameters only needed in case you're Authenticating the Janus API ;success: the session was successfully created and is ready to be used;error: the session was NOT successfully created;destroyed: the session was destroyed and can't be used any more.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 typically 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:
getServer(): returns the address of the server;isConnected(): returns true if the Janus instance is connected to the server, false otherwise;getSessionId(): returns the unique Janus session identifier;attach(parameters): attaches the session to a plugin, creating a handle; more handles to the same or different plugins can be created at the same time;destroy(parameters): destroys the session with the server, and closes all the handles (and related PeerConnections) the session may have with any plugin as well.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:
plugin: the unique package name of the plugin (e.g., janus.plugin.echotest );opaqueId: an optional opaque string meaningful to your application (e.g., to map all the handles of the same user);success: the handle was successfully created and is ready to be used;error: the handle was NOT successfully created;consentDialog: this callback is triggered just before getUserMedia is called (parameter=true) and after it is completed (parameter=false); this means it can be used to modify the UI accordingly, e.g., to prompt the user about the need to accept the device access consent requests;webrtcState: this callback is triggered with a true value when the PeerConnection associated to a handle becomes active (so ICE, DTLS and everything else succeeded) from the Janus perspective, while false is triggered when the PeerConnection goes down instead; useful to figure out when WebRTC is actually up and running between you and Janus (e.g., to notify a user they're actually now active in a conference); notice that in case of false a reason string may be present as an optional parameter;connectionState: this callback is triggered when the connection state for the PeerConnection associated to the handle changes: the argument of the callback is the new state as a string (e.g., "connected" or "failed");iceState: this callback is triggered when the ICE state for the PeerConnection associated to the handle changes: the argument of the callback is the new state as a string (e.g., "connected" or "failed");mediaState: this callback is triggered when Janus starts or stops receiving your media: for instance, a mediaState with type=audio and on=true means Janus started receiving your audio stream (or started getting them again after a pause of more than a second); a mediaState with type=video and on=false means Janus hasn't received any video from you in the last second, after a start was detected before; useful to figure out when Janus actually started handling your media, or to detect problems on the media path (e.g., media never started, or stopped at some time);slowLink: this callback is triggered when Janus reports trouble either sending or receiving media on the specified PeerConnection, typically as a consequence of too lost packets detected to/from the user in the last second: for instance, a slowLink with uplink=true means you notified several missing packets from Janus, while uplink=false means Janus is not receiving all your packets; useful to figure out when there are problems on the media path (e.g., excessive loss), in order to possibly react accordingly (e.g., decrease the bitrate if most of our packets are getting lost);onmessage: a message/event has been received from the plugin;onlocalstream: a local MediaStream is available and ready to be displayed;onremotestream: a remote MediaStream is available and ready to be displayed;ondataopen: a Data Channel is available and ready to be used;ondata: data has been received through the Data Channel;oncleanup: the WebRTC PeerConnection with the plugin was closed;detached: the plugin handle has been detached by the plugin itself, and so should not be used anymore.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:
getId(): returns the unique handle identifier;getPlugin(): returns the unique package name of the attached plugin;send(parameters): sends a message (with or without a jsep to negotiate a PeerConnection) to the plugin;createOffer(callbacks): asks the library to create a WebRTC compliant OFFER;createAnswer(callbacks): asks the library to create a WebRTC compliant ANSWER;handleRemoteJsep(callbacks): asks the library to handle an incoming WebRTC compliant session description;dtmf(parameters): sends a DTMF tone on the PeerConnection;data(parameters): sends data through the Data Channel, if available;getBitrate(): gets a verbose description of the currently received stream bitrate;hangup(sendRequest): tells the library to close the PeerConnection; if the optional sendRequest argument is set to true, then a hangup Janus API request is sent to Janus as well (disabled by default, Janus can usually figure this out via DTLS alerts and the like but it may be useful to enable it sometimes);detach(parameters): detaches from the plugin and destroys the handle, tearing down the related PeerConnection if it exists.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:
attach() to create a Handle object;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;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 ;onlocalstream and/or the onremotestream callbacks will provide you with a stream you can display in your page;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.
createOffer takes a single parameter, that can contain any of the following properties and callbacks:media: you can use this property to tell the library which media (audio/video/data) you're interested in, and whether you're going to send and/or receive any of them; by default audio and video are enabled in both directions, while the Data Channels are disabled; this option is an object that can take any of the following properties:audioSend: true/false (do or do not send audio);audioRecv: true/false (do or do not receive audio);audio: true/false (do or do not send and receive audio, takes precedence on the above);audio: object with deviceId property (specify ID of audio device to capture, takes precedence on the above; devices list can be accessed with Janus.listDevices(callback) );videoSend: true/false (do or do not send video);videoRecv: true/false (do or do not receive video);video: true/false (do or do not send and receive video, takes precedence on the above);video: "lowres"/"lowres-16:9"/"stdres"/"stdres-16:9"/"hires"/"hires-16:9" (send a 320x240/320x180/640x480/640x360/1280x720 video, takes precedence on the above; default is "stdres" ) this property will affect the resulting getUserMedia that the library will issue; please notice that Firefox doesn't support the "16:9" variants, which will fallback to the ones; besides, "hires" and "hires-16:9" are currently synonymous, as there's no 4:3 high resolution constraint as of now;video: "screen" (use screensharing for video, disables audio, takes precedence on both audio and video);video: object with deviceId , width and/or height properties (specify ID of video device to capture and optionally resolution to use, takes precedence on the above; devices list can be accessed with Janus.listDevices(callback) );data: true/false (do or do not use Data Channels, default is false)failIfNoAudio: true/false (whether a getUserMedia should fail if audio send is asked, but no audio device is available, default is false)failIfNoVideo: true/false (whether a getUserMedia should fail if video send is asked, but no video device is available, default is false)screenshareFrameRate: in case you're sharing a screen/application, allows you to specify the framerate (default=3);trickle: true/false, to tell the library whether you want Trickle ICE to be used (true, the default) or not (false);stream: optional, only to be passed in case you obtained a MediaStream object yourself with a getUserMedia request, and that you want the library to use instead of having it get one by itself (makes the media property useless, as it won't be read for accessing any device);success: the session description was created (attached as a parameter) and is ready to be sent to the plugin;error: the session description was NOT successfully created;customizeSdp: you can modify the sdp generated by the webrtc engine if you need;createAnswer takes the same options as createOffer, but requires an additional one as part of the single parameter argument:jsep: the session description sent by the plugin (e.g., as received in an onmessage callback) as its OFFER.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.
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:
addAudio: if set, start capturing audio if you weren't (will fail if you're sending audio already);addVideo: if set, start capturing video if you weren't (will fail if you're sending video already);addData: if set, negotiate a datachannel if it didn't exist (is actually just a synonym for data:true );removeAudio: if set, stop capturing audio and remove the local audio track;removeVideo: if set, stop capturing video and remove the local video track;replaceAudio: if set, stop capturing the current audio (remove the local audio track), and capture a new audio source;replaceVideo: if set, stop capturing the current video (remove the local video track), and capture a new video source.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.
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.