Main Menu
Donations
Donate!
Make donations with PayPal!
Donat-o-Meter Stats
May's Goal: $150.00
Due Date: May 31
Gross Amount: $139.00
Net Balance: $131.13
Left to go: $18.87

Donations
Anonymous 
Anonymous 
Anonymous 
Anonymous 
Anonymous 
Anonymous 
Use cases about the V4L2 driver for the all the Raspberry Pi Camera Boards

First of all, if you have not installed UV4L on Raspbian or Jessie yet, do it by following these instructions.

Upgrade UV4L to the latest version:
raspberrypi ~ $ sudo apt-get update
raspberrypi ~ $ sudo apt-get upgrade
Below are some simple examples on how to use the driver in combination with some applications. To show you complete examples, I will suppose that you have not installed the recent uv4l-raspicam-extras optional package yet, which automatically loads the driver at boot. Remember that, in all the cases, to eventually "unload" the driver it's enough to kill the corresponding uv4l process. All the examples have been originally tested on the (old) Raspberry Pi 1. The Raspberry Pi 2 can do much better where the CPU would be a bottleneck.



List of examples:

1. Record an H264 video at full 1920x1080 resolution, 30 fps
2. Motion
3. HTTP Server with mjpg-streamer or vlc (obsolete, see example #11)
4. Capture and display with OpenCV
5. Use the Camera Board on the Rpi as a (virtual) camera plugged into another PC
6. Set up a RealTime Streaming Server (RTSP)
7. FFmpeg Server & avconv
8. Setup an RTMP Server (in H264 full res, 30fps) with crtmpserver and FFMpeg
9. Full fps, Live Text Overlay (over video)
10. Real-time Object Detection and Object Tracking
11. Real-time HTTP/HTTPS Streaming Server with the native uv4l-server module
12. Compute Module: stereoscopic vision
13. Compute Module: use Dual Cameras separately
14. Start or Join a Multi Peer-to-Peer Audio/Video Conference with WebRTC
15. Live Desktop & Audio Streaming to the browser with WebRTC
16. How to broadcast or have bidirectional live audio and video conferences to/in a Jitsi Meet Room over the Web
17. Webinars and Video Conferences in Full HD with the Janus WebRTC Gateway
18. UV4L for the Internet of Things with WebRTC Data Channels



Example 1: Record an H264 video at full 1920x1080 resolution, 30 fps

This is the simplest case, as no particular applications are needed to record a video in H264, the dd system command is enough for the job. For example:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --encoding h264 --width 1920 --height 1080
[notice] [core] Device detected!
[notice] [core] Registering device node /dev/video0
Alternatively, if the driver has been previously loaded with another initial configuration, change it on the fly:
raspberrypi ~ $ sudo apt-get install v4l-utils
raspberrypi ~ $ v4l2-ctl --set-fmt-video=width=1920,height=1080,pixelformat="H264" -d /dev/video0
Since, by default, the system read I/O interface on RPi is too slow for recording at full resolution without data loss, we will give the uv4l process a RealTime scheduling priority:
raspberrypi ~ $ sudo chrt -a -r -p 99 `pgrep uv4l`
Now we can record a 10s video:
raspberrypi ~ $ dd if=/dev/video0 of=video.h264 bs=1M & pid=$! ; sleep 10; kill $pid
The driver also supports the more efficient Video4Linux2 Streaming I/O API, but this will require a Video4Linux-complaiant application implementing the mentioned I/O method.

As an alternative to manually setting the RealTime scheduling priority to the uv4l process each time, you can run the driver with the --sched-rr option, which requires root priviligies by default:
raspberrypi ~ $ sudo uv4l --sched-rr --driver raspicam --auto-video_nr --encoding h264 --width 1920 --height 1080


Example 2: Motion

Install Motion from the official Raspbian repository:
raspberrypi ~ $ sudo apt-get install motion
To start with Motion, download and try the following configuration file, which you can change later according to your needs:
raspberrypi ~ $ wget http://linux-projects.org/downloads/examples/motion.conf
Now run the driver in background, for example:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr
[notice] [core] Device detected!
[notice] [core] Registering device node /dev/video0
Finally, run Motion:
raspberrypi ~ $ LD_PRELOAD=/usr/lib/uv4l/uv4lext/armv6l/libuv4lext.so motion -c ./motion.conf
If you run motion as daemon and the camera is not detected properly for some reasons, try to load the driver with the --extension-presence=1 option. Check if the Motion HTTP server is up and running on your Raspberry Pi. For example, from your PC with firefox:
mypc ~ $ firefox http://raspberrypi:8081/


Example 3: HTTP Server with mjpg-streamer or vlc (obsolete, see example #11)

There are two alternatives here: one is mjpg-streamer, the other one is vlc (high framerate, low resolution, DEPRECATED since v1.8).

mjpg-streamer is an HTTP Server, the source code can be downloaded from http://sourceforge.net/projects/mjpg-streamer/ ; once compiled, load the driver and run mjpg-streamer:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --width 640 --height 480
raspberrypi ~ $ cd mjpg-streamer
raspberrypi ~ $ export LD_LIBRARY_PATH="$(pwd)"
raspberrypi ~ $ LD_PRELOAD=/usr/lib/uv4l/uv4lext/armv6l/libuv4lext.so ./mjpg_streamer -i "input_uvc.so -d /dev/video0 -r 320x240 -f 30" -o "output_http.so -w ./www"
Now you can connect to the server and watch the output from the camera
mypc ~ $ firefox http://raspberrypi:8080/stream.html
Later we will see how to profit by this server for a video-conferincing solution.

VLC can be downloaded from the Raspbian repository:
raspberrypi ~ $ sudo apt-get install vlc
A good configuration for the server is 352x288 at 10fps:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --framerate 10
raspberrypi ~ $ cvlc v4l2:///dev/video0 --v4l2-width 352 --v4l2-height 288 --sout '#transcode{vcodec=MJPG,width=352,height=288,vb=1000}:duplicate{dst=std{access=http{mime=multipart/x-mixed-replace;boundary=--7b3cc56e5f51db803f790dad720ed50a},mux=mpjpeg,dst=:8080/video.mjpg}'
The server can now be reached at http://raspberrypi:8080/video.mjpg .


Example 4: Capture and display with OpenCV

Here is the source code of a simple program using the OpenCV libraries to continuosly capture and display video frames from the camera.

First we should make sure that the opencv libraries are installed, afterwards we need to download the source code and compile it:
raspberrypi ~ $ sudo apt-get install libopencv-dev
raspberrypi ~ $ wget http://linux-projects.org/downloads/examples/opencv_test.cpp
raspberrypi ~ $ g++ -lopencv_core -lopencv_highgui -L/usr/lib/uv4l/uv4lext/armv6l -luv4lext -Wl,-rpath,'/usr/lib/uv4l/uv4lext/armv6l' opencv_test.cpp -o opencv_test

The above command will also link libuv4lext to the executable directly so that it will not be necessary to set the LD_PRELOAD environment variable before executing the program.

Now we can run the driver and test the program. If you are on a remote host, to actually see the window showing the output from the camera, you might have to be logged via ssh -X to your raspberry:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --encoding yuv420 --width 320 --height 240
raspberrypi ~ $ ./opencv_test


Example 5: Use the Camera Board on the Rpi as a (virtual) camera plugged into another PC

Here we go:

Step 1. Install UV4L and the MJPEGStream driver on your PC (download the packages for Ubuntu, or a generic archive), then upgrade UV4L on the Rpi to the latest version.

Step 2. Follow the instructions given at the Example 11 to have an MJPEG Streaming Server running on your Rpi.

Step 3. Make a virtual Video4Linux2 device on your PC from the above stream with the following command:
mypc ~ $ uv4l --driver mjpegstream --auto-video_nr --uri http://raspberrypi:8080/stream/video.jpeg
Now you have a device registered as /dev/video0 (or higher) on your PC that you can use as you prefer, for example:
mypc ~ $ LD_PRELOAD=/usr/lib/uv4l/uv4lext/x86_64/libuv4lext.so jitsi
or
mypc ~ $ vlc v4l2:///dev/video0
The LD_PRELOAD environment variable has to be set for some applications. If you are in doubt, always specify it.
Jitsi is a video-conferencing tool which can be downloaded at https://jitsi.org/


Example 6: Set up a RealTime Streaming Server (RTSP) (see example #11 for HTTP server)

Install the required packages:
raspberrypi ~ $ sudo apt-get install vlc
Run UV4L with the raspicam driver:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --framerate 25
[core] Device detected!
[core] Registering device node /dev/video0
Give a RealTime scheduling policy to the driver process for better perfomance (which is the same as running uv4l with sudo uv4l --sched-rr):
raspberrypi ~ $ sudo chrt -a -r -p 99 `pgrep uv4l`
Run the RealTime Streaming Server on your Raspberry Pi with the preferred resolution:
raspberrypi ~ $ LD_PRELOAD='' cvlc v4l2:///dev/video0 --v4l2-width 640 --v4l2-height 480 --v4l2-chroma h264 --sout '#rtp{sdp=rtsp://:8554/}'
Now you can connect to your Raspberry Pi from the client, for example (don't forget the final slash):
mypc ~ $ vlc rtsp://raspberrypi:8554/
where raspberrypi is the host name or IP of your RaspberryPi.

You can set any image property on the fly (while the camera is streaming). For example, to list all the available controls and change the brightness:
raspberrypi ~ $ sudo apt-get install v4l-utils
raspberrypi ~ $ v4l2-ctl --list-ctrls --device /dev/video0


brightness (int) : min=0 max=100 step=1 default=50 value=50
contrast (int) : min=-100 max=100 step=1 default=0 value=0
saturation (int) : min=-100 max=100 step=1 default=0 value=0
iso (int) : min=0 max=1200 step=1 default=400 value=400
horizontal_mirror (bool) : default=0 value=0
vertical_mirror (bool) : default=0 value=0
sharpness (int) : min=-100 max=100 step=1 default=0 value=0


raspberrypi ~ $ v4l2-ctl --set-ctrl=brightness=50 --device=/dev/video0
A more user-friendly interface for changing the image properties while streaming with this/any method is the Conrol Panel web page coming along with the HTTP Sreaming Server plug-in for UV4L (see example #11 for more details)


Example 7: FFmpeg Server & avconv

Install avconv on raspbian and ffmpeg on the streaming server host. Run UV4L with the raspicam driver:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --framerate 25
[core] Device detected!
[core] Registering device node /dev/video0
Give a RealTime scheduling policy to the driver process for better perfomance (which is the same as running uv4l with sudo uv4l --sched-rr):
raspberrypi ~ $ sudo chrt -a -r -p 99 `pgrep uv4l`
Run the FFmpeg Streaming Server starting from the simple configuration file below:
server ~ $ wget http://linux-projects.org/downloads/examples/ffserver.conf
server ~ $ ffserver -f ./ffserver.conf
Feed the server from your RaspberryPi:
raspberrypi ~ $ export LD_PRELOAD=/usr/lib/uv4l/uv4lext/armv6l/libuv4lext.so
raspberrypi ~ $ avconv -r 25 -s 640x480 -f video4linux2 -i /dev/video0 http://server:8080/raspicam.ffm
where raspberrypi is the host name or IP of your RaspberryPi and server the host name of you streaming server (they can be the same hots).

Now you can get the video stream via VLC, for example:
mypc ~ $ vlc http://server:8080/raspicam.mjpeg
I think this will give you about ~15fps. If you know more efficient configurations with ffmpeg, let me know.


Example 8: Setup an RTMP Server (in H264 full res, 30fps) with crtmpserver and FFMpeg (see example #11 for HTTP server)

Get a recent version of FFMpeg from http://www.ffmpeg.org/ , compile the sources and install the binaries on your RaspberryPi. Do NOT use the default ffmpeg binary from the Raspbian repository, as it won't work.

Install crtmpserver on the Streaming Server machine and rtmpdump on the client. The server host can be your RaspberryPi itself or a different machine:
server ~ $ sudo apt-get install crtmpserver
Add the crtmpserver log directory:
server ~ $ sudo mkdir /var/log/crtmpserver
Find and change these values in /etc/crtmpserver/applications/flvplayback.lua:
validateHandshake=false,
keyframeSeek=false,
seekGranularity=0.1
clientSideBuffer=30
Restart crtmpserver:
server ~ $ sudo /etc/init.d/crtmpserver restart
Now load the raspicam driver with a RealTime priority, set the preferred resolution in H264 and run ffmpeg:
raspberrypi ~ $ sudo uv4l --sched-rr --driver raspicam --auto-video_nr
raspberrypi ~ $ v4l2-ctl --set-fmt-video=width=1280,height=720,pixelformat=H264 -d /dev/video0
raspberrypi ~ $ dd if=/dev/video0 bs=512K | ./ffmpeg_20130804/bin/ffmpeg -i - -vcodec copy -an -f flv -metadata streamName=myStream tcp://server:6666
Now you can dump the RTMP video on the client and see it:
mypc ~ $ rtmpdump -r "rtmp://server/flvplayback/myStream" --live -o foo.flv
mypc ~ $ vlc foo.flv
Or directly:
mypc ~ $ vlc "rtmp://server/flvplayback/myStream live=1"


Example 9: Full fps, Live Text Overlay (over video)

Text Overlay is a driver feature which allows you to put text lines onto video frames on-the-fly. Text Overlay works with almost all the video formats supported by the driver (mjpeg, h264, yuv420, bgr24, etc...). Drawing properties of each line such as position, color, font, thickness, scale and also the data itself are read from a JSON file specified via command line when the driver is loaded. If you load the driver with text overlay enabled but don't specify any file, the driver attempts to open a file from a default path (see the manual for more details). As an interesting note, the default file contains a special tag as metadata which instructs the driver to overlay the live framerate. The driver will parse the file when the camera is opened the first time or every time an explicit command is given (see below). A failure on validating the JSON file will not be considered a blocking error.

One full example of JSON file with comments can be found here, which results in something like this image. Comments are ignored.

Text overlay can be turned on and off at any time. By sending a standard Video4Linux2 command to the driver (see the example below), it is possible to instantaneously turn on text overlay (if not already on) and make the driver reparse the JSON file for any new text to be overlaied. If you plan to apply changes very frequently during streaming, it is suggested that you place the file in a ramdisk (i.e. under /tmp) for better performance.

It is required to specify the full path to the JSON file when loading the driver. This can be done with the --text-filename command line option. The path cannot be changed later. However, specifying the --text-overlay option makes the driver start with text overlay enabled, but it is not mandatory to do this when loading the driver, you can optionally enable it later.

For example:
raspberrypi ~ $ uv4l --driver raspicam --width 640 --height 480 --auto-video_nr --encoding h264 --text-overlay --text-filename=/tmp/text.json
To turn text overlay off, type:
raspberrypi ~ $ v4l2-ctl --set-ctrl=text_overlay=0
To turn text overlay on at any time:
raspberrypi ~ $ v4l2-ctl --set-ctrl=text_overlay=1
v4l2-ctl is a standard linux tool. As mentioned, the above command will also make the driver reparse the JSON file and immediately draw all the text lines described there onto the video stream.

NOTE 1: if you want to turn on text-overlay while the camera is in use by another application AND text-overlay was turned off when that application opened the Camera, you need to close that application first.

NOTE 2: when text-overlay is enabled, Image width and height should be multiple of 16.

To show what fancy things you can do with the Text Overlay feature, below we will see how to add a simple text animation to your video stream with the help of a very simple program called uv4l-overlay. The source code can be found here, while the binary can be found here. Run it as in the following example:
raspberrypi ~ $ ./uv4l-overlay /dev/video0 /tmp/text.json "Hello World, this is a simple text animation"
It's not necessary to run uv4l-overlay after you have started the capture with some application. Also, note that in this case the /tmp/text.json argument is exactly the path to the file (in memory) at which the driver is currently pointing.

The resulting effect is something like this!

If you notice glitches in the moving text, that's because the simple micro sleep's in the loop in the example program are not always accurate. Feel free to fix this flaw. In short, modify the few lines of source code above so that the effect can best fit your needs, recompile and... have fun!


Example 10: Real-time Object Detection and Object Tracking

Live Object Detection and Object Tracking can be optionally turned on and off at any time. These features work with the following video modes: yuv420, h264, mjpeg (video), jpeg (continuous stills or snapshots), webrtc.

The following example is reasonably efficient for face detection on a RaspberryPi 1 with a ~15fps video at 320x240 resolution, while the RaspberryPi 2 can easily do 640x480 at 30fps:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --object-detection --min-object-size 80 80 --main-classifier /usr/share/uv4l/raspicam/lbpcascade_frontalface.xml --object-detection-mode accurate_detection --width 320 --height 240 --framerate 15 --encoding h264
As you can see, you can specify the path to the preferred cascade classifier that the driver shall be using for object detection.

As another example, face tracking can be enabled in a similar way as detection, with the exception that you should also specify a secondary classifier specifically suited for the tracking algorithm:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --object-detection --min-object-size 80 80 --main-classifier /usr/share/uv4l/raspicam/lbpcascade_frontalface.xml --secondary-classifier /usr/share/uv4l/raspicam/lbpcascade_frontalface.xml --object-detection-mode accurate_tracking --width 320 --height 240 --framerate 15 --encoding h264
Whenever objects are detected on the image, they will be surrounded by white rectangles. Other classifiers are available from the OpenCV framework.

To turn off object detection/tracking on-the-fly, type:
raspberrypi ~ $ v4l2-ctl --set-ctrl=object_detection=0
To turn it on again:
raspberrypi ~ $ v4l2-ctl --set-ctrl=object_detection=1
NOTE: if you want to turn on obect detection while the camera is in use by another application AND object detection was turned off when that application opened the Camera, you might need to close that application first.


Example 11: Real-time HTTP/HTTPS Streaming Server with the native uv4l-server module

The uv4l-server module is a plug-in specific for UV4L which enables a per-camera Streaming Server that can be simultaneously accessed by any browser over HTTP or HTTPS protocols.

It offers a Web interface from which it's possible to see the video stream in various ways and a Control Page allowing to fully control the camera settings while streaming with any Video4Linux application. Other than secure HTTPS protocol, basic authentication for both the normal and admin users is also supported.

To install the module simply follows the instructions provided here. That's all. Next time you run uv4l, it will automatically load the plug-in and run the server.

All the URLs appearing in the below examples are based on the insecure HTTP protocol for simplicity, but the remember that the Streaming Server also supports secure HTTPS protocol if SSL is enabled (see the manual for more informations). In this case, to make the examples work it will be enough to replace http:// with https:// in the URLs.

By default the homepage of the server can be accessed at the following address: http://raspberrypi:8080 (where raspberrypi has to be replaced with the actual hostname or IP of the RaspberryPi in your network).

You do not necessarily need a browser to see the video streams. In the examples below we will be using VLC as an alternative application to display the video. From within VLC it's possible to see, transcode and record into a file - at the same time - almost any kind of stream formats over HTTP/HTTPS.

If you want to directly get the MJPEG (Video) stream over HTTP from the server, type from the client:
client ~ $ cvlc http://raspberrypi:8080/stream/video.mjpeg
If you want to get the raw H264 stream over HTTP from the server, type:
client ~ $ cvlc http://raspberrypi:8080/stream/video.h264 --demux h264
If you want to get the JPEG stream (as continuous Stills) over HTTP from the server, type:
client ~ $ cvlc http://raspberrypi:8080/stream/video.jpeg
If you want to get a single snapshot in JPEG after a given delay specified in the URL (5 seconds in this example) and record it to a file, type:
client ~ $ wget http://raspberrypi:8080/stream/snapshot.jpeg?delay_s=5 -O snapshot.jpeg
If you want to password protect any stream from unauthenticated users, you can use the --user-password server option, as in the following example:
raspberrypi ~ $ uv4l --auto-video_nr --driver raspicam --encoding h264 --server-option '--user-password=myp4ssw0rd'
A proper HTTP client should now be able to authenticate the user from a standard URL in the form:
client ~ $ cvlc http://user:myp4ssw0rd@raspberrypi:8080/stream/video.h264 --demux h264
In case you do not want, for some reasons, enable the server when uv4l is run, you will have to explicitly pass the --enable-server off command line option, for example:
raspberrypi ~ $ uv4l --auto-video_nr --driver raspicam --enable-server off
As another example, the following will make the server listen to port 9000 (instead of the default one) and prompt the user for the specified 'admin' password when accessing the Control Page:
raspberrypi ~ $ uv4l --auto-video_nr --driver raspicam --encoding mjpeg --server-option '--port=9000' --server-option '--admin-password=myp4ssw0rd'


Example 12: Compute Module: stereoscopic vision

Since stereoscopic vision is disabled by default, to enable it you must specify the --stereoscopic-mode option when loading the driver. Here is a basic example:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --stereoscopic-mode=side_by_side --encoding=mjpeg --width=2360 --height=720
With the stereoscopic mode specified above two 1280x720 image captures will be placed side by side in the final video frame; another mode is top_bottom. Other (not mandatory) options affecting stereoscopic vision are --decimate to enable frame decimation and --camera-number to set the primary and secondary camera ports (please refer to the manual for more details).


Example 13: Compute Module: use Dual Cameras separately

Instead of having the two camera images packed side by side or one above the other to form the final frame - as in a typical stereoscopic scenario - you may want to access, configure and stream from each camera separately, yet at the same time eventually. This can be simply done by running two instances of uv4l with the --camera-number command line option correctly specified (and no --stereoscopic-mode specified), thus one process per camera.

For example, we can create the first device node for the camera connected to the CAM1 port. Let's configure it as 1280x768, H264:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --encoding=h264 --width=1280 --height=768 --camera-number=0
[driver] Dual Raspicam Video4Linux2 Driver v1.9.24 built Dec 13 2014
[driver] Selected format: 1280x768, encoding: h264, H264 Video Compression
[core] Device detected!
[core] Registering device node /dev/video0
If the uv4l-server plugin has been already installed, the above command will also make the camera accessible from the network at the default HTTP port 8080.

Now let's create the second device node for the other camera connected to the CAM0 port, configured as 640x480, MJPEG this time, and have an associated HTTP Server listening to port 9000:
raspberrypi ~ $ uv4l --driver raspicam --auto-video_nr --encoding=mjpeg --width=640 --height=480 --camera-number=1 --server-option='--port=9000'
[driver] Dual Raspicam Video4Linux2 Driver v1.9.24 built Dec 13 2014
[driver] Selected format: 640x480, encoding: mjpeg, JPEG Video Capture
[core] Device detected!
[core] Registering device node /dev/video1
Okay. Now we have the two cameras registered as different device nodes. This means we can access them individually through /dev/video0 and /dev/video1 with any Video4Linux2-complaint application. Or, if you prefer, we can get the streams directly from the two embedded HTTP Streaming Servers:
client ~ $ cvlc http://raspberrypi:8080/stream/video.h264 --demux h264
client ~ $ cvlc http://raspberrypi:9000/stream/video.mjpeg


Example 14. Start or Join a Multi Peer-to-Peer Audio/Video Conference with WebRTC

It's possible to start a new conference or join an existing one from any browser (on PC, Smartphone, Tablet...). No configuration is required. The only requirement is that the peers support the WebRTC protocol. Almost all browsers support WebRTC nowadays. To also make your RaspberryPi 2 WebRTC-capable without the need of any browser, it's enough to install the UV4L Streaming Server and the WebRTC extension on it according to these instructions.

Once installed, to start a new conference simply connect to your RaspberryPi 2 at the (default) URL below. You can use your preferred browser from your PC or from the Raspberry Pi itself (iceweasel, in the latter case):
http://raspberrypi:8080/conference
(where raspberrypi has to be replaced with the real address of your RaspberryPi 2). If you are using iceaweasel on your Raspberry Pi and get sort of connection errors when audio is enabled (it is by default), consider installing pulseaudio, then reboot and retry.

A page similar to this example should appear. Now read the few notes at the beginning of the page and click Start New Conference when ready, then share the current link with the other participants and wait for them to join the conference.

NOTE: if the other participants are on a different network, you may want to copy and make the above example web page available on your web server somewhere on internet or just try it at that URL.

If you want to join an existing conference instead, simply ask the other partecipants for the URL where they can be reached at, open that URL in your preferred browser and press the Join button.

Note: the Signalling Server Address field present in the page should be automatically set to the address of the RaspberryPi 2 host in your network. Fix it if you have problems or think that is not correct.


Example 15. Live Desktop & Audio Streaming to the browser with WebRTC

Have you ever wanted to stream your Raspberry Pi 2 desktop to a Web page in your browser? Well, you can do this with UV4L. You just need to install or update the UV4L core module, the xscreen driver, the Streaming Server plug-in and the WebRTC extension according to these instructions.

Once done, make sure the X server is started whenever the system boots (raspi-config will tell you) and edit /boot/config.txt to set the screen resolution as follows:
framebuffer_width=640
framebuffer_height=480
framebuffer_depth=32
framebuffer_ignore_alpha=1
(this is the only supported resolution at the moment, others may be supported in the future). Save and reboot.

When ready, login into your Raspberry Pi 2 again and load the xscreen driver:
raspberrypi ~ $ uv4l --driver xscreen --auto-video_nr --display :0 --framerate 10 --server-option '--port=9000'

[core] Trying driver 'xscreen' from built-in drivers...
[core] Driver 'xscreen' not found
[core] Trying driver 'xscreen' from external plug-in's...
[driver] Opening display: :0
[driver] Display open, screen 0: 640x480, depth: 24, bpp: 32, big endian: false
[driver] Specified capturing rectangle: (xorigin 0, yorigin 0, width 640, height 480)
[core] Device detected!
[core] Trying to load the the Streaming Server plug-in...
[server] HTTP Streaming & WebRTC Signalling Server v1.1.18 built on Apr 22 2015
[core] Streaming Server loaded!
[core] Cannot create /dev/video0 because file already exists
[core] Registering device node /dev/video1
[server] Web Streaming Server listening on port 9000
Ignore the warning. In the above example, note that a new video device has been registered as /dev/video1. It's the node of a new virtual device representing your desktop. You can use this device with any Video4Linux2-compliant application! Also, note that /dev/video0 is busy. It is in use by something else: it may well be another intance of uv4l (and another Streaming Server) running the camera (e.g. as shown in example 14).

Okay, let's go ahead. Open your browser and type the URL pointing to the Streaming Server:
http://raspberrypi:9000/stream/webrtc
(where raspberrypi has to be replaced with the real address of your RPi)

A page similar to this should appear. Finally, press Start and watch the live stream from your desktop! If a michrophone is attached to your Raspberry Pi, you should be getting the audio stream too.

Another funny thing you may want to try is to share your desktop with other people in a audio/video conference (see example 14).


Example 16. How to broadcast or have bidirectional live audio and video conferences to/in a Jitsi Meet Room over the Web

If you do not already know what Jitsi Meet is, here is the official homepage. Jitsi Meet allows you to create and join video calls over the Web (even as a simple viewer). Some of its features are: encrypted by default, no account needed, invite by pretty URL https:// MySite.com/OurConf

Thanks to UV4L it is possible to create or join an existing room and broadcast live video and audio to all the participants or viewers in the room from a camera and a microphone connected to the Raspberry Pi. It's also possible to automatically hear and see other participants if you have speakers and display (HDMI, touchscreen, etc...) connected to the Raspberry Pi. Of course, other participants can be other Raspberry Pi's. The great news is that you do not need any browser installed on the Raspberry Pi to do this.

It's necessary to install the required packages before proceeding: uv4l, uv4l-server, uv4l-webrtc, uv4l-xmpp-bridge 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 Jitsi Meet server (called videobridge), 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 by using the Jitsi Meet control page available at the URL the Streaming Server itself is listening to (e.g. http://myraspberrypi:8080), from which it's possible to specify all the mandatory informations (i.e. XMPP and/or BOSH signalling server, chat room, your username and password) required to establish a connection and to click on start/stop buttons in order to join or leave the specified room respectively.

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 streaming to the videobridge which is at the base of the official, free-access Jitsi Meet service at meet.jit.si, type (in one line):
curl -s 'http://raspberrypi:port/xmpp?xmpp?server=meet.jit.si&port=5222&muc=conference.meet.jit.si&room=testroom&room_password=&username=tester&password=&bosh_enable=1&bosh_tls=1&bosh_server=meet.jit.si&bosh_port=443&bosh_hostname=meet.jit.si&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 8080 will have to be replaced with the real port number the Streaming Server is listening to (8080 is the default). The above command will make the Raspberry Pi create or join a conference at http://meet.jit.si/myroom .

Please note the parameters in the URL that you are allowed to specify:

- server (XMPP server hostname or ip address)
- port (port the XMPP server is listening to)
- muc (multiuser chat domain)
- room (desired room you want to join or create)
- room_password (room password, if the room is protected)
- username (desired username in the chat room)
- password (password if the server is password protected)
- reconnect (try to reconnect after disconnection)
- bosh_enable (1 if you want to use BOSH signalling, 0 otherwise)
- bosh_server (usually HTTP(S) server hostname for BOSH)
- bosh_tls (1 for HTTPS, 0 otherwise)
- bosh_port (typically 443 for HTTPS, 80 for HTTP)
- bosh_hostname (connection manager hostname, typically the same as bosh_server)
- action (Start or Stop streaming)

All the above settings can be optionally specified once for all in the UV4L configuration file (except action) (see the uv4l-webrtc manual for more details).

Similarly, to stop streaming:
curl -s 'http://raspberrypi:8080/xmpp?action=Stop' > /dev/null
If you are protectng 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/xmpp? [etc...]'




Example 17. 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 gateway 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 run on a Raspberry Pi! It's also extremely powerful in that it is highly customizable and offers some unique features like video room recording, codec & bitrate selection, live audio and video stream forwarding to a RTP server, and so on...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 one instance of Janus already deployed somewhere - and 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 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:8080/janus?gateway_url=http://janus.conf.meetecho.com:8088&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 8080 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;
- proxy_port
- proxy_password
- proxy_bypass
- 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 running on HTTPS instead, you want to add the -k option to curl and specify 'https://[...]' in the URL.


Example 18. UV4L the Internet of Things with WebRTC Data Channels
New releases of the WebRTC extension for UV4L support WebRTC data channels. To know how to install or update the UV4L suite, please read these instructions.

By means of UV4L, WebRTC data channels allow real-time, secure and full-duplex data exchange between a remote WebRTC-complaint peer (e.g. a browser) and a third-party application running on localhost. By default the data channel is bundled onto the same transport as audio and video tracks.

In other words, the data flow that is made possible by UV4L can be represented as follows:

your app <--(unix domain socket)--> UV4L <--(WebRTC data channel)--> remote peer

UV4L acts as bridge connecting two parties of a communication channel. It instantly relays any incoming or outgoing messages from one endpoint to the other. As UV4L and the application endpoint are two different processes running on the same host (thus, are "local" with respect to each other), the inter-process communication is best accomplished with a Unix Domain Socket of type SOCK_SEQPACKET (type SOCK_SEQPACKET is for a reliable connection-oriented socket that preserves message boundaries and delivers messages in the order that they were sent).

In order to communicate with UV4L, the only requirement of the local application is that it has to create the agreed unix domain socket, listen and accept incoming connections (from UV4L). In facts, after having created, offered and established the WebRTC data channel with the remote peer on one side, UV4L attempts to open the local socket on the other side. One attempt every second is automatically made until it gets connected or on possible connection failures. Once the local connection is ready, the local application can start to send or receive any messages to or from the remote peer transparently by simply writing or reading to or from the socket respectively. When the WebRTC connection with the remote peer terminates, UV4L closes the socket in turn, so to terminate the connection with the application.

For instance, all this can be extremely useful for remotely controlling the servo motors of a robot from a Web application with a few lines of Javascript code - using the standard WebRTC API supported by any modern browser - e.g. commands may be sent in form of messages from the user interface to the device, where the messages can be actuated by translating them into real OS commands. The opposite direction is also possible, e.g. the application could push messages representing data coming from various sensors mounted on the robot into the pipe, while the Web application, on the other end, can consume them as soon as they are received.

The uv4l-webrtc package comes with a simple echo server demonstrating the overall concept. Every time it receives a message, it sends the same message back to the sender. The source code is here. It can be invoked at any time as follows:
pi@raspberrypi:~ $ datachannel_server /tmp/uv4l.socket
To quickly test data channels through the Web interface, open the WebRTC Web page at the UV4L Streaming Server. There you will see a "Data Channel" section with an input and an output text fields inside. Start an audio/video call as usual. At this point the data channel should be open too, fill the input field with any message and click on the send button to send it to the echo server. You will immediately receive the same message back and have it displayed on the output field.

WebRTC data channels are enabled by default with /tmp/uv4l.socket as default path for the socket. The default values can be changed through the relevant options from command line or in the configuration file. Please refer to the uv4l-server manual for more details.

IMPORTANT: If you want to use WebRTC data channels with the Janus Gateway, make sure it is built with WebRTC data channel flag turned on, or the connection will be denied by Janus and will fail miserably.

Return to Sections Index Return to Sections Index
[ Back to UV4L, Userspace Video4Linux framework | Return to Sections Index | Printer Friendly Page]
Login
Username:

Password:


Lost Password?

Register now!