Main Menu
Make donations with PayPal!
Donat-o-Meter Stats
November's Goal: $150.00
Due Date: Nov 30
Gross Amount: $25.00
Net Balance: $23.72
Left to go: $126.28

Use cases about the V4L2 driver for the Raspberry Pi Camera Module

First of all, if you have not installed UV4L on Raspbian 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.

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
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/ 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 ; 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/ ./mjpg_streamer -i " -d /dev/video0 -r 320x240 -f 30" -o " -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: 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 adt-get install opencv-dev
raspberrypi ~ $ wget
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

This may be useful for doing video-conferencing from your PC using the camera installed on your Raspberry Pi. 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/?action=stream
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/ jitsi
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

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

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
server ~ $ ffserver -f ./ffserver.conf
Feed the server from your RaspberryPi:
raspberrypi ~ $ export LD_PRELOAD=/usr/lib/uv4l/uv4lext/armv6l/
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 , 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:
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: Object Detection and Object Tracking

Object Detection and Object Tracking can be optionally turned on and off at any time. These features work with the following video encodings: yuv420, h264, mjpeg.

The following example is reasonably efficient for face detection with a ~15fps video at 320x240 resolution:
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 Streaming Server with the native uv4l-server module

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

It offers a Web Page from which it's possible to watch the video stream and a Control Page allowing you to fully control the camera settings while streaming with any Video4Linux application. 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.

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).

If you want to directly get the HTTP/MJPEG (Video) stream from the server, e.g. with VLC, type from the client:
client ~ $ cvlc http://raspberrypi:8080/stream/video.mjpeg
If you want to get the HTTP/raw H264 stream from the server, type:
client ~ $ cvlc http://raspberrypi:8080/stream/video.h264 --demux h264
If you want to get the HTTP/JPEG stream (as continuous Stills) from the server, type:
client ~ $ cvlc http://raspberrypi:8080/stream/video.jpeg
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!'

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


Lost Password?

Register now!