libv4lconvert is not safe for using one convert instance as returned by
v4lconvert_create from multiple threads, if you want to use one v4lconvert
instance from multiple threads you must provide your own locking and make
sure no simultaneous calls are made.

libv4l1 and libv4l2 are safe for multithread use *under* *the* *following*
*conditions* :

* when using v4lx_fd_open, do not make any v4lx_ calls to the passed fd until
  v4lx_fd_open has completed

* all v4lx_ calls must be completed before calling v4lx_close

Introduction
------------

libv4l is a collection of libraries which adds a thin abstraction layer on
top of video4linux2 devices. The purpose of this (thin) layer is to make it
easy for application writers to support a wide variety of devices without
having to write separate code for different devices in the same class.

All libv4l components are licensed under the GNU Lesser General Public
License version 2 or (at your option) any later version.

libv4l consists of 3 different libraries:


libv4lconvert
-------------

libv4lconvert started as a library to convert from any (known) pixelformat to
V4l2_PIX_FMT_BGR24, RGB24, YUV420 or YVU420.

The list of know source formats is large and continually growing, so instead
of keeping an (almost always outdated) list here in the README, I refer you
to the source, see the list of defines at the top of
libv4lconvert/libv4lconvert.c for the full list.
For more details on the v4lconvert_ functions see libv4lconvert.h.

Later on libv4lconvert was expanded to also be able to do various video
processing functions to improve webcam video quality on a software basis. So
the name no longer 100% covers the functionality. The video processing is
split in to 2 parts, libv4lconvert/control and libv4lconvert/processing.

The control part is used to offer video controls which can be used to control
the video processing functions made available by libv4lconvert/processing.
These controls are stored application wide (until reboot) by using a
persistent shared memory object.

libv4lconvert/processing offers the actual video processing functionality.


libv4l1
-------

This offers functions like v4l1_open, v4l1_ioctl, etc. which can by used to
quickly make v4l1 applications work with v4l2 devices. These functions work
exactly like the normal open/close/etc, except that libv4l1 does full emulation
of the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will just
pass calls through. For more details on the v4l1_ functions see libv4l1.h .


libv4l2
-------

This offers functions like v4l2_open, v4l2_ioctl, etc. which can by used to
quickly make v4l2 applications work with v4l2 devices with weird formats.
libv4l2 mostly passes calls directly through to the v4l2 driver. When the
app does a TRY_FMT / S_FMT with a not supported format libv4l2 will get in
the middle and emulate the format (if an app wants to know which formats the
hardware can _really_ do it should use ENUM_FMT, not randomly try a bunch of
S_FMT's). For more details on the v4l2_ functions see libv4l2.h .


libdvbv5
--------

This library provides the DVBv5 API to userspace programs. It can be used to
open DVB adapters, tune transponders and read PES and other data streams.
There are as well several parsers for DVB, ATSC, ISBT formats.

The API is currently EXPERIMENTAL and likely to change.
Run configure with --enable-libdvbv5 in order to build a shared lib and
install the header files.


wrappers
--------

The functionality provided by libv4l1 for v4l1 apps and libv4l2 for v4l2 apps
can also be used by existing apps without modifying them. For this purpose
2 wrapper libraries are provided which can be preloaded before starting the
application using the LD_PRELOAD environment variable. These wrappers will
then intercept calls to open/close/ioctl/etc. and if these calls directed
towards a video device the wrapper will redirect the call to the libv4lX
counterparts.

The preloadable libv4l1 wrapper which adds v4l2 device compatibility to v4l1
applications is called v4l1compat.so. The preloadable libv4l2 wrapper which
adds support for various pixelformats to v4l2 applications is called
v4l2convert.so.

Example usage (after install in default location):
$ export LD_PRELOAD=/usr/local/lib/libv4l/v4l1compat.so
$ camorama


Prerequisites
-------------

libv4l requires shmem file system support in the kernel (CONFIG_SHMEM).


FAQ
---

Q: Why libv4l, whats wrong with directly accessing v4l2 devices ?
Q: Do we really need yet another library ?
A: Current webcam using applications like ekiga contain code to handle many
different specific pixelformats webcam's use, but that code only supports a
small subset of all native webcam (compressed) pixelformats. Other current
v4l2 applications do not support anything but rgb pixelformats (xawtv for
example) and this will not work with most webcams at all.

With gspca being ported to v4l2 and thus decoding to normal formats being
removed from the device driver as this really belongs in userspace, ekiga
would need to be extended with many more often chip dependent formats, like
the bayer compression used by the spca561 and the (different) compression used
by the pac207 and the (again different) compression used by the sn9c102. Adding
support for all these formats should not be done at the application level, as
then it needs to be written for each application separately. Licensing issues
with the decompressors will then also become a problem as just cut and pasting
from one application to another is bound to hit license incompatibilities.

So clearly this belongs in a library, and in a library with a license which
allows this code to be used from as many different applications as possible.
Hence libv4l was born.


Q: Under which license may I use and distribute libv4l?
A: The libv4l libraries are licensed under the GNU Library General Publishing
License version 2 or (at your option) any later version. See the included
COPYING.LIBV4L file. The decompression helpers are licensed under the GNU
Library Publishing License version 2 (as they are derived from kernel code)


Q: Okay so I get the use of having a libv4lconvert, but why libv4l1 ?
A: Many v4l2 drivers do not offer full v4l1 compatibility. They often do not
implemented the CGMBUF ioctl and v4l1 style mmap call. Adding support to all
these drivers for this is a lot of work and more importantly unnecessary
adds code to kernel space.

Also even if the CGMBUF ioctl and v4l1 style mmap are supported, then most
cams still deliver pixelformats which v4l1 applications do not understand.

This libv4l1 was born as an easy way to get v4l1 applications to work with
v4l2 devices without requiring full v4l1 emulation (including format
conversion) in the kernel, and without requiring major changes to the
applications.


Q: Why should I use libv4l2 in my app instead of direct device access
   combined with libv4lconvert?
A: libv4l2 is mainly meant for quickly and easily adding support for more
pixelformats to existing v4l2 applications. So if you feel better directly
accessing the device in combination with libv4lconvert that's fine too.

Notice that libv4l2 also does emulation of the read() call on devices which
do not support it in the driver. In the background this uses mmap buffers
(even on devices which do support the read call). This mmap gives libv4lconvert
zero-copy access to the captured frame, and then it can write the converted
data directly to the buffer the application provided to v4l2_read(). Thus
another reason to use libv4l2 is to get the no memcpy advantage of the mmap
capture method combined with the simplicity of making a simple read() call.


Q: Where to send bugreports / questions?
A: Please send libv4l questions / bugreports to the:
   Linux Media Mailing List <linux-media@vger.kernel.org>
   Subscription is not necessary to send mail to this list. If you're not
   subscribed please put yourself in the CC of your original mail so you
   will receive replies.

Q: How do I port my application to libv4l1?
A: Just replace the open call for your device by v4l1_open and all
   following calls concerning this device file descriptor by their
   counterpart v4l1_xxx (for a list see libv4l1.h).

Q: How do I port my application to libv4l2?
A: Just replace the open call for your device by v4l2_open and all
   following calls concerning this device file descriptor by their
   counterpart v4l2_xxx (for a list see libv4l2.h).

Q: I still need an example how to convert my application!
A: Check out the patches for the VLC media player:
   https://trac.videolan.org/vlc/attachment/ticket/1804/vlc-0.8.6-libv4l1.patch
   https://trac.videolan.org/vlc/attachment/ticket/1804/vlc-0.9.3-libv4l2.patch

# v4l-utils

Linux utilities and libraries to handle media devices (TV devices, capture
devices, radio devices, remote controllers).

You can always find the latest development v4l-utils in the git repo:
[http://git.linuxtv.org/v4l-utils.git](http://git.linuxtv.org/v4l-utils.git).

Those utilities follow the latest Linux Kernel media API, as documented at:
[http://linuxtv.org/downloads/v4l-dvb-apis/](http://linuxtv.org/downloads/v4l-dvb-apis/).

Any questions/remarks/patches can be sent to the linux-media mailinglist. See
[https://linuxtv.org/lists.php](https://linuxtv.org/lists.php) for more
information about the mailinglist.

There is also a wiki page for the v4l-utils:
[https://linuxtv.org/wiki/index.php/V4l-utils](https://linuxtv.org/wiki/index.php/V4l-utils).

## Building

v4l-utils uses the meson build system.

A number of packages is required to fully build v4l-utils. The first step is to
install those packages. The package names are different on each distro.

On Debian and derivated distributions, you need to install the following
packages with `apt-get` or `aptitude`:

```
debhelper doxygen gcc git graphviz libasound2-dev libjpeg-dev
libqt5opengl5-dev libudev-dev libx11-dev meson pkg-config
qtbase5-dev udev libsdl2-dev libbpf-dev llvm clang
```

On Fedora, the package list for a minimal install with `dnf` or `yum` is:

```
gcc gcc-c++ gettext-devel git meson perl which
```

(git is only requiried if you're cloning from the main git repository at
linuxtv.org).

And, to be able to compile it with all usual functionality with qt5, you'll need
also:

```
alsa-lib-devel doxygen libjpeg-turbo-devel qt5-qtbase-devel libudev-devel
mesa-libGLU-devel
```

The v4l2-tracer also needs the json-c library. On Debian: `libjson-c-dev' ; on
Fedora: `json-c-devel`.

After downloading and installing the needed packages on your distribution, you
should run:

```
meson build/
ninja -C build/
```

And, to install on your system:

```
sudo ninja -C build/ install
```

### Optional features

Please notice that there's an extra feature to add an extra table to decode
Japanese DVB tables via iconv. This is meant to be used when the iconv itself
doesn't come with the *ARIB-STD-B24* and *EN300-468-TAB00* tables.

gconv is an auto feature, so it will be auto-enabled in case the dependencies
are satisfied. However, the gconv feature can be forced to enabled by running
the following command during configuration step:

```
meson configure -Dgconv=enabled build/
```

## Versioning

The v4l-utils doesn't quite follow the release versioning defined at
[semver.org](https://semver.org/).

Instead, since version 1.0, it uses `MAJOR.MINOR.PATCH`. Where:

* `MINOR` - an odd number means a development version. When the development is
closed, we release an even numbered version and start a newer odd version;

* `MAJOR` - It is incremented when `MINOR` number starts to be too big. The last
change occurred from 0.9.x to 1.0.

* All numbers start with 0.

All versions have their own tags, except for the current development version
(with uses the master branch at the git tree).

The `PATCH` meaning actually depends if the version is stable or development.

* For even `MAJOR.MINOR` versions (1.0, 1.2, 1.4, 1.6, ...): `PATCH` is
incremented when just bug fixes are added;

* For odd `MAJOR.MINOR` versions (1.1, 1.3, 1.5, 1.7, ...): `PATCH` is
incremented for release candidate versions.

### API/ABI stability:

There should not have any API/ABI changes when `PATCH` is incremented.

When `MAJOR` and/or `MINOR` are incremented, the API/ABI for the libraries might
change, although we do all the efforts for not doing it, except when inevitable.

The `TODO` files should specify the events that will generate API/ABI breaks.

## Media libraries

There are currently three media libraries defined at `lib/` directory, meant to
be used internally and by other applications.

### libv4l

This library is meant to be used by applications that need to talk with V4L2
devices (webcams, analog TV, stream grabbers).

It can be found on the following directories:

```
lib/libv4l1/
lib/libv4l2/
lib/libv4l-mplane/
lib/libv4lconvert/
```

See `README.libv4l` for more information on libv4l.

The libv4l is released under the GNU Lesser General Public License.

### libdvbv5

This library is meant to be used by digital TV applications that need to talk
with media hardware.

Full documentation is provided via Doxygen. Building documentation is enabled
by the auto feature: `doxygen-doc`. If enabled, it will be built within the
project.

It is possible to generate documentation in html, man pages and pdf formats.

The documentation is also available via web, at:
[http://linuxtv.org/docs/libdvbv5/](http://linuxtv.org/docs/libdvbv5/).

It can be found on the following directory `lib/libdvbv5/`.

The libdvbv5 is released under GPL version 2.

### libv4l2rds

This library provides support for RDS radio applications.

It can be found on the following directory `lib/libv4l2rds/`.

The libv4l is released under the GNU Lesser General Public License.

## Utilities

The utilities are stored under `utils/` directory.

The (for now for v4l-utils private use only) libv4l2util library is released
under the GNU Lesser General Public License, all other code is released under
the GNU General Public License.

v4l-utils includes the following utilities:

### decode\_tm6000

Decodes tm6000 proprietary format streams.

Installed under `<prefix>/bin`.

### ir-keytable

Dump, Load or Modify ir receiver input tables. The ir tables for remotes which
are known by the kernel (and loaded by default depending on dvb card type) can
be found under `utils/keytable/keycodes`.

v4l-keytable does not get installed during the install step.

### ir-ctl

A swiss-knife tool to handle raw IR and to set lirc options.

### qv4l2

QT v4l2 control panel application.

Installed under `<prefix>/bin`.

### rds-saa6588

Poll i2c RDS receiver [Philips saa6588].

rds-saa6588 does not get installed during the install step.

### v4l2-compliance

Tool to test v4l2 API compliance of drivers.

Installed under `<prefix>/bin`.

### v4l2-ctl

Tool to control v4l2 controls from the cmdline.

Installed under `<prefix>/bin`.

### v4l2-dbg

Tool to directly get and set registers of v4l2 devices, this requires a
*kernel >= 2.6.29* with the `ADV_DEBUG` option enabled. This tool can only be
used by root and is meant for development purposes only!

Installed under `<prefix>/sbin`.

### v4l2-sysfs-path

*FIXME* add description.

Installed under `<prefix>/bin`.

### v4l2-tracer

Tool to trace, record and replay userspace applications that implement the v4l2
memory-to-memory stateless video decoder interface.

Installed by `make install` under `<prefix>/bin`.

### xc3028-firmware

Xceive XC2028/3028 tuner module firmware manipulation tool.

xc3028-firmware does not get installed during the install step.

## Syncing with Kernel

There are a number of files on this package that depends on the Linux Kernel.

In order to make easier to keep it in sync, there's a target on this package to
do the synchronism.

For the sync to work, you need to run it on with 64 bits userspace and be sure
that glibc has the development package for 32 bits.

For Fedora, this is provided via this package: *glibc-devel.i686*

There are some steps required:

1. At the Kernel git tree:

    We need to sanitize the headers to be installed. To do that, you should run:

    ```
    make headers_install INSTALL_HDR_PATH=usr/
    ```

    This will create the dir `usr/` inside the Kernel tree.

1. Be sure that you have installed both glibc development packages for 32 and 64
bits, as otherwise the next step will fail.

1. At v4l-utils tree:

    ```
    ./sync-with-kernel.sh location/of/the/kernel/tree
    ```

    Alternatively, steps 1 to 3 can be replaced with:

    ```
    KERNEL_DIR=location/of/the/kernel/tree && (cd $KERNEL_DIR && make headers_install INSTALL_HDR_PATH=usr/) && ./sync-with-kernel.sh $KERNEL_DIR
    ```

1. Remove the `usr/` from the Kernel tree.