Janus Gateway

Webinars and Video Conferences in Full HD with the Janus WebRTC Gateway

Please keep an eye on this tutorial as it will be being kept updated frequently whenever any new functionalities are added.

The Janus WebRTC Gateway is a general purpose lightweight server implementing the means to set up WebRTC media communications between peers. In many ways, Janus is similar to Jitsi (as examined in the previous example). Janus is so light that can easily scale to a Raspberry Pi! For the incredulous reader, here is a ready-to-use OS image for Raspberry Pi based on Janus and UV4L that you can flash to a SD card and immediately try out to entirely host or join video conferences elsewhere over the web.

Janus is also extremely powerful in that it is highly customizable and offers some unique features like video room recording & playback, codec & bitrate selection, live data, audio and video, stream forwarding to a RTP server, and so on…

What follows is meant for final users. For the developers who want to easily write their native applications and use UV4L as back-end for creating and driving a Janus session with greater detail, please refer to the RESTful API documentation.

We will not see how to build, install and configure Janus in this tutorial, as this is well explained in the official Janus documentation, so from now on we’ll be assuming that there exists one instance of Janus already deployed somewhere (there is indeed one public video room available here, which may be useful for testing purposes).

In the WebRTC world a peer is usually a browser, but not necessarily, as in this case. In facts, with UV4L it’s possible to turn a Raspberry Pi optionally equipped with camera, microphone, speakers and display into a full WebRTC-compliant peer able to connect to a given Janus Gateway and create or join a given video room “on the cloud” for publishing your own live feed and/or subscribing to audio, video and data live feeds from any participants in the room (of course, any other participant in the room is free to use a Raspberry Pi rather than a browser). This publish/subscribe model allows the realization of several different scenarios, ranging from a simple webinar (one speaker, several listeners) to a fully meshed video conference (each peer sending and receiving to and from all the others)! Again, there is no need of any browser installed on the Raspberry Pi. There is also no need of a X server or GUI to display the video from the other participants.

Before proceeding, it’s necessary to install the required packages, which are: uv4l, uv4l-server, uv4l-webrtc, and one video driver (e.g. uv4l-raspicam, uv4l-uvc, etc…). Please refer to these installation instructions for more details.

To start and stop streaming to a particular room, it’s enough to invoke the corresponding commands by means of the UV4L Streaming Server installed on the Raspberry Pi. This can be done in two ways.

The first convenient way is through a browser (e.g. on a PC or smartphone) by using the Janus control page available at the URL where the Streaming Server itself is running (e.g. http://myraspberrypi:8080). In this web page it’s possible to insert all the mandatory informations (i.e. gateway URL, room, pin, and username) required to establish a connection and to start or stop a session in order to join or leave the specified room respectively. The page should look similar to this:
Unless it is specified otherwise, all the mandatory fields in the page (except username and few others probably) are filled automatically with some default values which allow you to quickly join the the public video room mentioned in the introduction of this example.

The second way is to invoke the start/stop commands via HTTP/GET requests sent to the Streaming Server from command line. For example, to start a session by joining the default video room at the public Janus DEMO instance, type (in one line):

curl -s 'http://raspberrypi:port/janus?gateway_url=https://janus.conf.meetecho.com&gateway_root=/janus&room=1234&room_pin=&username=test&proxy_host=&proxy_port=80&proxy_password=&proxy_bypass=&token=&publish=1&subscribe=0&hw_vcodec=0&vformat=60&reconnect=1&action=Start' > /dev/null

where raspberrypi will have to be replaced with the real hostname of your Raspberry Pi in your network (it can be localhost if you are executing the command from within your Raspberry Pi) and port will have to be replaced with the real port number the Streaming Server is listening to (8080 is the default).

This is a list of the parameters that can appear in the URL (those in bold are mandatory):

gateway_url: URL of the Janus Geteway;
gateway_root: root on the gateway, /janus if you do not know;
room: room number to join or create if it does not exist;
username: you preferred name in the room
room_pin: PIN if the room is protected;
token: authentication token to be used for all the requests sent to the Janus Geteway;
publish: 1 if you want to broadcast your own audio/video to the room, 0 otherwise;
subscribe: 1 if you want to subscribe for other’s audio/video feeds, 0 otherwise;
hw_vcodec: 1 if you want to make use of the hardware codecs on the device (if supported);
vformat: code for video resolution and frame rate (see the manual);
reconnect: 1 to try to reconnect on unexpected disconnections, 0 otherwise;
proxy_host: optional HTTP proxy to use for the all requests to the Janus Gateway;
action: Start or Stop to commit the parameters and to start or gracefully stop the session.

Please read the uv4l-server manual for more informations on all the parameters that you are allowed to specify in the URL or in the UV4L configuration file (as default values). In the manual you will also find many others non Janus-specific options which can affect the streaming (one is example is the default video codec to use between VP8, VP9, hardware-encoded H264)

Similarly, to terminate a session in progress and leave the video room:

curl -s 'http://raspberrypi:8080/janus?action=Stop' > /dev/null

If you are protecting the UV4L Streaming Server with a password, then the above URL will not work. In this case, you must specify user and password in the URL as in the below example:

curl -s 'http://user:myp4ssw0rd@raspberrypi:8080/janus? [etc...]'

If the UV4L Streaming Server is providing HTTPS instead of HTTP, you will have to specify ‘https://[…]’ in the URLs and may also want to add the –insecure option to curlĀ  to turn off the verification of the server’s certificate (see curl manual for more details).