uv4l core – (advanced) Projects

NAME

uv4l – User space Video4Linux (core module)

SYNOPSIS

uv4l [-kfsg] [–auto-video_nr] [-d|–driver drvname1 drvname2 …] [drvopts] […]
uv4l [-kfsg] [-M maj] [-m min] [-n devname] [-d|–driver drvname1 drvname2 …] [drvopts] […]
uv4l [-t]
uv4l [-h|–help] [-i|–info] [[-d|–driver drvname1 drvname2 …] –driver-help]]

DESCRIPTION

UV4L is a modular collection of Video4Linux2-compliant, cross-platform, user space drivers for real or virtual video input devices and other pluggable back-ends or front-ends. The ‘uv4l’ core daemon loads a given driver module passed as argument via command line and creates one device node file under /dev for the applications to access the device. From the application’s perspective, there is no real difference from when a kernel driver is being used to control the device. You can run uv4l as many times as the number of the devices you want to handle (one process per device).

While the Read-Write I/O interface is embedded in the core, the UV4L framework comes with an optional extension library, libuv4lext, which enables the Streaming I/O interface as described by the Video4Linux2 specifications. Most of the Video4Linux2 applications only support the Streaming I/O method.

For an application to profit by this extension, the library must be pre-loaded by setting the standard LD_PRELOAD environmental variable before running the Video4Linux application. The library is usually located in an architecture-dependent directory under /usr/lib/uv4l/uv4lext/

For example:

$ locate libuv4lext.so /usr/lib/uv4l/uv4lext/x86_64/libuv4lext.so
$ LD_PRELOAD=/usr/lib/uv4l/uv4lext/x86_64/libuv4lext.so qv4l2 -r /dev/video0

If you don’t want to set LD_PRELOAD each time, you can write the path to the library into /etc/ld.so.preload. There are other ways to automatically set the variable, read the ‘man ld.so’ for more informations.

NOTE: Once LD_PRELOAD is properly set, the driver is usually able to detect the presence of the pre-loaded extension library while the application is running. However, under some circumstances, this is not possible; in these cases, try to load the driver with the ‘–extension-presence=1’ command option.

Some of the features are:

fully user space core module and drivers;
no kernel/system crashes since drivers run in user space;
transparent device node creation and dynamically loadable drivers;
embedded support for the Read-Write I/O Video4Linux2 API;
optional support for the Streaming I/O API via extension library;
multithread safe;
one system process for each handled device;
can run in foreground or background as a daemon;
optional real time scheduling and no memory paging;
no need for root priviligies;
multilevel logger that can send messages to a (remote) syslog daemon;
no dependency on any third-party library other than the basic system libraries

OPTIONS

-h –help
Print a help message and exit.

–video_nr number
device-node minor number as specified by the Video4Linux2 API. If given, this option will force –device-major 0 (auto), –device-minor video_nr and –device-name videovideo_nr. Note that If a Video4Linux2 kernel driver is present and a new device is attached and recognized by that driver, the device name assigned to it may overridde the device name specified by this option, so the registration will fail (use –auto-video_nr in case).

–auto-video_nr [yes|no]
When this option is enabled, if –video_nr has been specified, then automatically increase its argument until a free device node file is available. If –video_nr is not specified, –video_nr 0 will be implicitly assumed. Default is no.

-n –device-name filename
filename of the device node to create under /dev. Default is /dev/uv4l.

–extension-presence 0|1|2
detect the pre-loaded (via LD_PRELOAD) extension library presence in the client processes. 0 forces no presence, 1 forces presence, 2 means but auto-detection fails, try 1. Default is 2.

–frame-timeout number
frame timeout in ms for a single read, after which an error occurr. 0 for no timeout. Default is 5000 ms.

–frame-buffers number
number of queued frame buffers. Try to increase this value if you notice frame loss. (min. is 2). Default is 5.

–drop-bad-frames [yes|no]
drop bad frames. Default is yes.

–relaxed-ownership [yes|no]
f true, allow to change the format from different processes Default yes.

–sched-rr [prority]
try to set scheduling policy to SCHED_RR (real-time) with the given priority. 0 for highest priority. If no priority is given, highest priority is assumed.
See sched_setscheduler(2) for details.

–mem-lock [yes|no]
lock the memory after each allocation to avoid paging. You must run the program with enough priviligies for this option to be effective, otherwise you will get a warning (see rlimit).

-t –list-drivers
print the list of internal drivers and exit.

-l –libdir
directory containing the drivers to load. Default is built-in plus $LD_LIBRARY_PATH.

-d –driver drivername1 [ drivername2 … ]
list of drivers to load for the device detection

–driver-help
print driver help messages from all the driver modules found or from those specified by –driver only

–external-driver
an external driver will create or has created the passed –device-name. Do not use this option with –driver.

-i –program-info
print some program informations (version, author, etc…) and exit

-v –verbosity number
verbosity level (same as SYSLOG level RFC 3164), -1 to disable log

–syslog-host [hostname|ip]
attempt to add a specified SYSLOG server host as logging back-end. If no host is given, assume localhost.

–syslog-port [number]
SYSLOG server port to connect to. If no port is given, assume 514.

-k –load-cuse
try to load the ‘cuse’ kernel module.

-M –device-major [number]
device-node major number. Auto if no number is given.

-m –device-minor [number]
device-node minor number. Auto if no number is given.

-f –foreground
foreground operation

-s –single-thread
disable multi-threaded operation

–config-file
path to configuration file containing program options for uv4l. Options specified via command line have higher priority.

EXAMPLES

To print help messages from the ‘uvc’ driver modules, type:

uv4l --driver uvc --driver-help

To detect an UVC-based device, specify its ids (or, alternatively, its path), the device will be registered as /dev/uv4l:

uv4l --syslog-host localhost --driver uvc --device-id 04f2:a13d

To run ‘uv4l’ with a real-time scheduling policy (you may need root priviligies). The device will be registered as the first free /dev/videoX node:

uv4l --auto-video_nr --sched-rr --mem-lock --driver uvc --device-path 005:001

To see the images from a device you can use VLC (http://www.videolan.org). For example:

vlc v4l2:///dev/video0

SUPPORTED APPLICATIONS (INCOMPLETE LIST)

You can transparently use any Video4Linux2 compliant application. For example:

qv4l2 Video4linux2 Test Application;

VLC – http://www.videolan.org:

$ vlc v4l2:///dev/uv4l

XawTv:

$ xawtv -c /dev/uv4l

GStreamer – http://gstreamer.freedesktop.org/

$ gst-launch v4l2src device=/dev/uv4l ! 'video/x-raw-yuv,width=640,height=480' ! xvimagesink

Camorama;

ttv – watch tv on a ascii terminal using aalib;

fswebcam;

vgrabbj – http://vgrabbj.gecius.de/

$ vgrabbj -d /dev/video0 > image.jpg

Furthermore, the following applications are also known to work when the UV4L extension module (libuv4lext.so) is in pre-loaded:

motion – http://www.lavrsen.dk/foswiki/bin/view/Motion/WebHome

Jitsi – https://jitsi.org/Main/HomePage
Note: load the driver with ‘–extension-presence=1’ command option

qv4l2
$ qv4l2 -r /dev/video0

luvcview;

guvcview;

mplayer:

$ mplayer tv:// -tv driver=v4l2:width=352:height=288:device=/dev/video0

linphone – http://www.linphone.org/
Note: load the driver with ‘–extension-presence=1’ command option

VLC;