This page contains a list of FAQ as gathered on the meetecho-janus Google group and the Issues page on GitHub. It obviously also includes things we're being asked all the time in general! If your question is not listed here or not available anywhere in this documentation, feel free to refer to the group for generic help, or to the Issues page for bugs in the implementation.
- What is Janus?
Janus is an open source WebRTC gateway and server written by Meetecho, conceived as modular and, as much as possible, general purpose. It acts as a WebRTC endpoint browsers can interact with, and different modules can determine what should be done with the media. This means that you can do SIP, videoconferencing, streaming and tons of other stuff using the same box! And if what you need is not there, you can always write your own module and expand Janus.
- What is Meetecho?
Meetecho is a company founded by a few researchers, post-docs and Ph.Ds coming from the Universty of Napoli Federico II. We've been working on real-time multimedia applications over the Internet for years, and at one point we decided to try and make products out of our research efforts. Our web conferencing platform and Janus are part of those efforts.
- Now that we're at it, how is Meetecho pronounced??
We're being asked that a lot! We've heard so many variants and different pronounciations of the name that we could make a book out of it! When we chose the name, we wanted it to sound like this, which means awesome! in Italian. The extra H was a mistake on our side, as obviously echo is pronouced differently than eco! Long story short, it doesn't really matter how you pronounce it: just do it and help us be famous! :-)
- I just started with Janus and am overwhelmed by the amount of info, documentation, etc... any easy way to dive in?
Fair point! Janus and its concepts/APIs can be a lot to digest in a short time... An easy way to start is watching one of the several presentations we've done on Janus these last months. Most if not all of them try to provide a complete introduction to the context Janus was built in, how it was born, the architecture we chose for it and so on. As such, it should be a useful starting point for whoever is interested in learning what Janus can do and how to use it.
There are several videos available that you can find online, here are some of them as quick pointers:
- Why is Janus called like that?
Quoting Wikipedia: "In ancient Roman religion and myth, Janus (Latin: Ianus, pronounced [ˈiaː.nus]) is the god of beginnings and transitions, and thereby of gates, doors, passages, endings and time. He is usually depicted as having two faces, since he looks to the future and to the past." Considering the general purpose nature of our gateway, where one face always looks at the future (WebRTC) and the other at the past (whatever the modules allows you to do, be it legacy stuff or not), Janus looked like the perfect name for it! And besides, we're Italian, Ancient Rome was awesome and mythology rules... ;-)
- Is the license AGPLv3 or GPLv3? Do you provide alternative license mechanisms as well?
Janus is licensend under the GPLv3 licence. At the very beginning we chose AGPLv3 for a simple reason: we wanted our work to be open source, and we wanted interested people to play with it and contribute back whatever improvement they could provide to the core. This is not always the case with open source software, which is sometimes just seen as free stuff you can exploit without helping back, and AGPLv3 looked like the easiest way to do that. That said, we were almost immediately made aware that this license mechanism is not very appreciated around, especially because of some interpretations about it that could affect the way proprietary stuff is deployed. We obviously cared about these concerns, and that's what eventually lead us to pick GPLv3 as a license, which should make it easier for Janus to be integrated in heterogeneous scenarios.
Anyway, if for some reason you're not comfortable with GPLv3 for your needs, we have a commercial license offering as well.
- On what OS can I install Janus?
At the moment only Linux is officially supported. Anyway, Janus does compile on Mac OS as well, thanks to contributions from the community, and so should work fine there as well. Windows support is also provided as a pull request by a Janus contributor: anyway, please beware that Windows support is behind the current version of development.
- Are Data Channels supported?
Yes they are! Starting from version
0.0.3 of Janus, we added a first experimental support to Data Channels, that can as such be used in plugins that choose to support them. Right now, they are handled in several plugins like the Echo Test, VideoCall, VideoRoom and TextRoom plugins.
Please notice that right now we only support text data: hopefully support for binary streams will be available soon as well. Until that happens, you'll have to resort to text-based encodings like Base64 to share binary data through Janus.
- I don't care about Data Channels, do I have to compile usrsctp anyway?
Support for Data Channels is optional, so if you didn't install the library the configure script will go around them and compile Janus without Data Channels support. If you did install the library and don't care about Data Channels, but only about audio and/or video, pass the
–disable-data-channels option to the configure script to explicitly disable them. If you're updating an existing install, issue a
clean before compiling again, or you might encounter issues with pre-existing symbols.
- I can't install usrsctp, I'm getting errors about dereferencing pointers?
Apparently recent compilers are stricter with respect to some code syntaxes, and this seems to be affecting the way
usrsctp is written as of now. Some users managed to fix this issue by passing an export before the
configure steps in the
export CFLAGS="-fno-strict-aliasing" ./boostrap
export CFLAGS="-fno-strict-aliasing" ./configure --prefix=/usr
make && make install
Another solution seems to be removing all the
-O2 occurrences in the generated
- Can I use Janus as a gateway to my Freeswitch/Kamailio/Asterisk/other SIP infrastructure?
Of course! One of the modules we provide out of the box is a SIP gateway plugin based on the Sofia-SIP library stack. These plugin allows a web user to register at a SIP proxy/server either as an authenticated user or as a guest, and start or receive calls from other SIP users, including other web users exploiting the same plugin. Janus will take care of all the WebRTC-related stuff (ICE, DTLS, SRTP), which means that on the SIP side it will be plain RTP only, much easier and lighter to handle for legacy implementations. SDES-SRTP is also supported on the SIP side in case it is required.
- Can I use existing SIP stacks (e.g., JsSIP) with Janus?
- Does Janus support transcoding?
Janus is a simple intermediary between WebRTC users and server-side plugins providing application logic, so no, it doesn't provide any transcoding functionality per-se. If transcoding is needed, this is supposed to be implemented within plugins themselves. That said, apart from the AudioBridge plugin which acts as an audio MCU, none of the plugins we provide out-of the box does transcoding, since we wanted the implementation to be lightweight and besides there are several existing tools and third-party implementations that could be leveraged for the purpose.
- Does Janus support recording?
Yep! The Janus core provides an integrated way of recording all the media streams that go through it, whether it's audio, video or data, and almost all stock plugins do exploit it one way or another. Recording is implemented as a structured dump of all RTP and data files exactly as they were transmitted or sent: as such, no manipulation is done while recording, and all post-processing is demanded to an external tool. For more information on this, check the documentation.
- Can I use WebSockets instead of plain HTTP to interact with Janus?
0.0.4, you can! At first we chose a REST-based plain HTTP communication for a simple reason: we noticed that there were some scenarios (e.g., client firewalls) where websockets wouldn't work, even though WebRTC did. To improve the chances of success in the communication, we then chose this simpler approach with respect to signalling. Besides, plain HTTP is much easier to proxy and/or place behind frontends like Apache HTTPD or nginx than WebSockets, another aspect that played a decisive role in our decision, as we were also very interested in making the integration of Janus in heterogeneous environments as easy as possible. That said, WebSockets also provide substantial benefits when compared to plain HTTP, and definitely make life easier to server side integrators as well, e.g., in terms of overhead and use of resources. For more information, check the WebSockets Interface page.
- Can I use RabbitMQ instead of HTTP/WebSockets to interact with Janus?
0.0.6, you can! This is a feature that several developers asked for, especially those that are interested in wrapping the Janus API on the server side, and implement the communication on the client side their own way. Specificaly, Janus now supports RabbitMQ based messaging as an alternative "transport" for API requests, responses and notifications, meaning it can be used with or without HTTP and WebSockets, depending on your requirements. For more information, check the RabbitMQ interface page.
- Can I use Unix Sockets instead of HTTP/WebSockets/RabbitMQ to interact with Janus?
0.2.1, you can! More specifically, you can use a
SOCK_SEQPACKET or a
SOCK_DGRAM socket to control a Janus instance. Notice that this feature is only available when installing Janus on a Linux machine. For more information, check the UnixSockets interface page.
- Can I use MQTT instead of HTTP/WebSockets/RabbitMQ/Unix Sockets to interact with Janus?
0.2.1, you can! This was a very welcome contribution by a Janus user, as it makes it even easier to have Janus interact with IoT deployments. For more information, check the MQTT interface page.
- What about <my favourite control protocol> instead?
0.1.0, the transports for the Janus API have been made modular. This means that, assuming a transport plugin implementing support for your favourite protocol has been made available, you can just add it to the Janus transport modules folder and it should work. If no plugin has been implemented, you may even want to do so yourself, or ask for ours or others help.
- I've launched Janus, how do I try the demos?
The demos are available in the
html folder in the project. That said, the integrated web server in Janus does not serve static files as well, so you'll have to make them available using a different webserver. Details about how to deploy Janus are provided in Deploying Janus.
- I'm trying the demos, but I get "Janus down" or certificate errors!
Again, make sure you've read and are following the instructions on how to effectively deploy Janus in Deploying Janus. Most likely you're either trying to open the WebRTC demos using HTTP instead of HTTPS (something that browsers will not allow, if not on localhost for testing), trying to contact Janus via an insecure protocol through a secure page, or using an insecure certificate for Janus itself. All of these problems are explained and solved easily in the Deploying Janus documentation.
- Can I use Janus with node.js or other frameworks?
Not natively, but since interaction with Janus is demanded to a JSON based communication transported on a network protocol (HTTP, WebSockets, RabbitMQ and others), this can be abstracted quite easily in several different ways. A common approach is implementing the Janus API in a server-side application, so that you handle users your own way and with your own API, while controlling Janus as a media server yourself by wrapping its API. Check the Resources documentation page for a list of Janus API wrappers in different programming languages that ou can use within your application to control a Janus instance from there instead of the browser. Should you decide to write your own Janus API wrapper, don't hesitate to let us know so that we can advertise yours there too!
- How do I monitor/manage my Janus instance?
0.2.2 there are a couple of different ways you can do that. The first and most immediate one is making use of the Admin API, which you can find documented in the Admin/Monitor API page. It is a request/response protocol that can be used to poll information on existing sessions and handles, and which also provides a lot of useful WebRTC-related information on PeerConnections Janus is managing. You can also find a very useful blog post where we describe in detail how the Admin API can be used to investigate issues.
A more recent, and potentially much more powerful, addition to Janus are the Event Handlers. Unlike the Admin API, which is query-based, Event Handlers provide a mechanism to dynamically feed you with real-time and live data on whatever is happening within Janus, whether it's the core or any of the plugins. You can find more information, along with an example of how to receive such events, in the pull request page from where this effort was merged. More guidelines and implementations will definitely follow.
- I want to write my own plugin, where do I start?
Great! Depending on the kind of plugin you want to implement (application plugin, transport plugin, event handler plugin), some of the details may change, but the concept is typically the same. There are APIs you can refer to, documented in Plugin API , Transport API and Event Handler API. The existing plugins are also an excellent way to start to get comfortable with the API: a good starting point may be the Echo Test plugin, which is a very simple and barebone implementation that simply bounces back whatever it is sent, and also involves some rough application logic to determine its behaviour (e.g., messages coming from web users that selectively enable or disable video). You may want to check third-party plugins as well in the Resources as well, as they'll give you an idea of how other users did the same. If you need any help with this, feel free to ask for help on the Google group: we're always excited whenever new Janus plugins are realized!
- I'm using the VideoRoom plugin and, when several users are handled, I get a "Too many open files" errors and Janus crashes
As all applications on Linux environments, Janus is bound to the constraints imposed by the OS and/or the user. One of these constraints is related to how many file descriptors the application, or all the applications, can open. On several distributions this number is, by default, quite low, which can cause the issue you experienced. This value, together with others, can be modified, per-user or for all users, using the
ulimit application. For a simple and quick way to handle this refer to the guide provided by the MongoDB developers: http://docs.mongodb.org/manual/reference/ulimit/
- When I enable the HTTPS web server in Janus, the CPU goes crazy
As discussed in a recent post on our Google group, this is caused by an occasional problem within libmicrohttpd, the library we use to implement an embedded web server in Janus. This is not deterministic, as the high CPU usage does happen on some distributions (e.g., Ubuntu 12.04), while it doesn't on others (e.g., Ubuntu 14.04). Anyway, this only can happen if you enable HTTPS support within Janus itself: you can still have a safe HTTPS usage with Janus if you deploy it behind a frontend (e.g., Apache HTTPD) that takes care of this on its behalf. Refer to the Deploying Janus section for more details about this.
- I enabled TURN in the Janus configuration, but my clients behind a firewall can't connect
As explained in the
janus.cfg documentation, the TURN settings you configure there refer to Janus itself, not the clients that make use of its services. This means that, whether you configure a static TURN server and the related credentials, or the REST API client stack to retrieve them dynamically, you're asking Janus to gather relay candidates for ITSELF. This is only useful if you know that your Janus instance will not be deployed on a public address (as it usually will) but will instead potentially sit behind a restrictive component like a firewall, or if you simply want to limit the number of open ports and so force all media traffic to go through the TURN server port alone.
echotest.js code, which has a commented portion that explains how to provide one or more TURN servers to make use of. If you're handling the WebRTC-related stuff on your own and are contacting Janus some other way, please refer to the related way of specifying STUN and TURN servers instead.
- Is there any benchmark on Janus performances?
Benchmarking Janus is not an easy task, especially if we consider its general purpose nature. In fact, Janus by itself does not much more than negotiating WebRTC PeerConnections and relaying frames around, while most of the application login is in the modules. As you can imagine, different modules may have very different requirements and impact on the performances. For instance, the Echo Test is probably much lighter than the Video MCU, even if they're handling the same number of users. This means that such a benchmarking does not have much sense unless you contextualise the scenarios.
You can find some results on tests we made ourselves in a couple of publications we wrote and available here. One of those introduces a WebRTC stress testing tool we implemented called Jattack, for which a video of the presentation is available. You can find some more details and considerations in an older post on our Google group too.
- How do I scale Janus?
This question is way too generic to answer here. As explained in the previous point, Janus is not an easily measurable entity, as it very much depends on which of the plugins you're involving in the scenarios that interest you and how. The same considerations also apply to scaling the scenario you implemented, as different plugins may require different approaches to do that.
In general, Janus does not have any built-in multi-tenant support. Each Janus instance is conceived to be standalone, and works by itself. That said, there are different ways in which you can implement scalability in your service. One of them is implementing a wrapper/controller application that is in charge of multiple Janus instances, so that it can distribute the load depending on the requests. If the scenario allows for it, you can also mix concepts from different plugins on different Janus instances (e.g., use the RTP forwardiing feature of the VideoRoom plugin to make the same VideoRoom publisher available as a Streaming mountpoint on other Janus machines). Anyway, as explained each application may have very different requirements when it comes to scalability.
Should you be interested in implementing scalability in your application and need help, contact us.
- Can you implement a feature/plugin/application I want?
We're constantly working on new features and on improving what's already there, and we do love feedback from users. That said, we're a small team and we do have to pay our bills, so we always have to reserve our resources wisely. If there's a feature you'd like to see implemented, tell us on our Google group, and discuss it with other users: it may be on our schedule, or someone else may be already working on it to contribute it back to the project. You may even want to try and build it yourself and help us make Janus even better!
If you really need something that isn't there, you may also want to consider contacting us for a sponsored development or consulting.
- I want to learn more on Janus!
That's great! The first obvious suggestion is of course to carefully read the documentation here: we worked hard on it and are constantly expanding it, so it should always be the first source of information whenever in doubt. We have a great Google group as well where the community shares questions, data and more everyday, so make sure you join too!
We also provide training on Janus and WebRTC in general, so if interested just contact us.