RPi VideoConference Demo OS

VideoConference DEMO OS for Raspberry Pi 2 and 3 (except 3B+ atm)

Below is a link to a minimal, ready-to-use Raspbian-based image made for DEMO purposes to show some of the potential of UV4L and WebRTC and allows your Raspberry Pi and other participants (PCs, tablets, smartphones and other Raspberry Pi’s) to create or join an audio-video conference room over the web.

With this OS you can make your Raspberry Pi play the double role of relying media server (thanks to the pre-installed Janus Gateway) and/or client at the same time. In other words, it hosts a video conference room that all participants can join at any moment. The Raspberry Pi itself can then optionally join the same room on localhost or another room on a different server instance in the cloud.

While participants like PCs, smartphones and tablets need a browser (with no additional plug-in) to optionally share their camera and microphone and see the other participants in the same web page, the Raspberry Pi does not need this, as UV4L makes native use of all the available hardware (camera, microphone, display and speakers) to capture and render the streams and can be optionally controlled through the web interface.

To install and use the OS, just flash the image file onto a fresh SD card and boot it; thereafter open your preferred browser (e.g. from a smartphone or PC) and visit the homepage at http://<your_rpi_address> (where <your_rpi_address> will have to be replaced with the real address of your Raspberry Pi in your network). From this page it is possible to make your (headless) Raspberry Pi join or leave a self-hosted room or a room hosted by another machine (e.g. another Raspberry Pi, but not necessarily) in the same network or even in a public room on the internet cloud. At the same time, any visitor of this same page is allowed to participate to the conference and share their camera or microphone through the standard features of the browser in use. The snapshot below taken from the homepage lists all the possibilities.

Download it now!

The OS has been preconfigured to work out-of-the-box with both standard USB webcams and the official Raspberry Pi cameras, so the only requirement is that your Raspberry Pi has at least one of such cameras connected to it. Nevertheless, any (virtual) video device supported by UV4L would work (e.g. X screens for desktop sharing, remote MJPEG streams from IP cameras, etc…), provided that you are ready to read through the relevant manuals or tutorials so to properly tweak the configurations files by yourself. With regard to audio input, the USB microphone is optional and automatically detected. If an HDMI screen or a touchscreen is attached to the Raspberry Pi, then up to 3 participants are automatically rendered onto different windows on the screen (the default size and position of each window have been calibrated for the official Rpi 7” touchscreen). Audio output will be played back through the speakers, of course. Note that each camera is served by one independent instance of the Streaming Server. In particular, each time you attach or detach an USB webcam, the corresponding server instance is automatically created or destroyed respectively.

First-use recommendations: HTTPS, Wi-Fi, NAT traversal etc…

After you have booted the OS for the first time, you may need to limit the access by untrusted users. The first thing to do is to login with the default user and password pi/pi and change the password itself:

pi@raspberrypi-b827eb91dc83:~$ passwd
Changing password for pi.
(current) UNIX password: 
Enter new UNIX password: 
Retype new UNIX password: 
passwd: password updated successfully
pi@raspberrypi-b827eb91dc83:~$ exit

In general it’s better to keep UV4L updated to the latest version available for download. Login again and type:

pi@raspberrypi-b827eb91dc83:~$ sudo apt-get update
pi@raspberrypi-b827eb91dc83:~$ sudo apt-get install "uv4l*" --only-upgrade

Beware that during the upgrade you might be asked whether you want to overwrite the existing configuration files with those from the updated packages: unless you know what you are doing, choose not to overwrite the current configuration files.

Although during a conference any media stream between the peers is guaranteed to be encrypted by the WebRTC protocol, you may want to also enable secure HTTPS instead of HTTP as default protocol for the meta informations exchanged through the web interface. We will see how to do this with a self-signed certificate.

Generate a password-less private key and a valid certificate with the following command:

pi@raspberrypi-b827eb91dc83:~$ sudo bash -c "openssl genrsa -out /etc/ssl/private/selfsign.key 2048 && openssl req -new -x509 -key /etc/ssl/private/selfsign.key -out /etc/ssl/private/selfsign.crt -sha256"
[sudo] password for pi:
Generating RSA private key, 2048 bit long modulus
e is 65537 (0x10001)
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.

Now we will instruct the Web servers to make use of the previously generated certificate by modifying the configuration file specific to the hardware in use.

For the official Raspberry Pi Camera Modules, the file in question is /etc/uv4l/uv4l-raspicam.conf. Edit it (you can use nano editor) and search for each of the following lines in the text, make sure they are uncommented (by eventually removing the # character at the beginning of each line) and set them as below:

server-option = --use-ssl=yes
server-option = --ssl-private-key-file=/etc/ssl/private/selfsign.key
server-option = --ssl-certificate-file=/etc/ssl/private/selfsign.crt
server-option = --www-port=443
server-option = --www-use-ssl=yes
server-option = --www-ssl-private-key-file=/etc/ssl/private/selfsign.key
server-option = --www-ssl-certificate-file=/etc/ssl/private/selfsign.crt

Comment out the option below (by adding a # at the beginning of the line) if you want to forbid any changes to the configuration file from the web interface, otherwise choose a proper password (see the uv4l-server manual for more details about this option):

# server-option = --config-password=<choose_a_password>

Reboot the system or restart the uv4l_raspicam service for the above changes to take effect:

pi@raspberrypi-b827eb91dc83:~$ sudo service uv4l_raspicam restart

If you want to enable the wireless network interfaces wlan0, install the missing firmwares and reboot:

pi@raspberrypi-b827eb91dc83:~$ sudo apt-get install firmware-brcm80211 wireless-tools

To finalize the Wi-Fi connection setup add your network details according to these instructions.

Now it’s the time to install all the required certificates in your browser’s trusted certificate store. There are formal ways to do this from within the browser, but perhaps the most practical way is the following. Open the browser and visit the following three URL‘s one at a time, in this exact order: https://<your_rpi_address>:8889 (blank page), https://<your_rpi_address>:8080 and https://<your_rpi_address>. For each of the three contacted HTTPS servers above the browser will ask you to add a security exception to the self-signed SSL server’s certificate, so that it can whitelist them once for any future use. You must accept the certificates before doing anything else.

If your Raspberry Pi in your LAN is behind a NAT and you want it to be reachable from a different network (e.g. Internet), you will very likely need to configure the Janus Gateway to use a given STUN server in order to get the IP address of the Raspberry Pi as seen from the other network. Please refer to the documentation in the configuration file /usr/local/etc/janus/janus.cfg for more details about all the possible options. Usually, if you are exposing the Raspberry Pi to the Internet, specifying the following options in the configuration file should be enough:

stun_server = stun.l.google.com
stun_port = 19302

Note that at the moment if Janus fails to contact the given STUN server for some reasons (e.g. because of bad address or way to resolve the URL), it deliberately terminates with an error (future releases will be more tolerant).

That’s it. From now on https://<your_rpi_address> will be your default page from which it will be possible to join or create a video conference room. For more options such as basic HTTPS authentication please refer to the manuals.

Are you a developer?

Since the 7th of October 2016, UV4L has been supporting a RESTful API over HTTP(S) for the developers who want to implement their custom Janus client. The API allows to create and have a very fine-grained control over the whole Janus session. For example, at the moment of writing, the audio and video recording feature is only available through this API.

The system comes along with a post-processing tool that allows to convert any source that has been recorded on-the-fly during a conference into a standard container, such as opus, wav, webm, mp4, srt. This tool requires some libraries to work, which are not installed by default. You must do it manually, if you want to use this tool:

~$ sudo apt-get install libavutil54 libavcodec56 libavformat56
~$ /usr/local/bin/janus-pp-rec -h
Usage: /usr/local/bin/janus-pp-rec source.mjr destination.[opus|wav|webm|mp4|srt]
       /usr/local/bin/janus-pp-rec --header source.mjr (only parse header)
       /usr/local/bin/janus-pp-rec --parse source.mjr (only parse and re-order packets)